@cyanheads/openalex-mcp-server 0.7.16 → 0.9.0

package/dist/mcp-server/tools/definitions/search-entities.tool.d.ts

@@ -30,6 +30,10 @@ export declare const searchEntitiesTool: import("@cyanheads/mcp-ts-core").ToolDe
     page: z.ZodOptional<z.ZodNumber>;
     sample: z.ZodOptional<z.ZodNumber>;
     seed: z.ZodOptional<z.ZodString>;
+    slice: z.ZodOptional<z.ZodObject<{
+        field: z.ZodString;
+        offset: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
 }, z.core.$strip>, z.ZodObject<{
     meta: z.ZodObject<{
         count: z.ZodNumber;
@@ -40,6 +44,26 @@ export declare const searchEntitiesTool: import("@cyanheads/mcp-ts-core").ToolDe
         id: z.ZodString;
         display_name: z.ZodNullable<z.ZodString>;
     }, z.core.$loose>>;
+    omitted: z.ZodOptional<z.ZodObject<{
+        ids: z.ZodArray<z.ZodString>;
+        next: z.ZodObject<{
+            tool: z.ZodLiteral<"openalex_search_entities">;
+            arguments: z.ZodObject<{}, z.core.$loose>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    windows: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        field: z.ZodString;
+        offset: z.ZodNumber;
+        shown: z.ZodNumber;
+        total: z.ZodNumber;
+        possibly_capped: z.ZodBoolean;
+        next: z.ZodNullable<z.ZodObject<{
+            tool: z.ZodLiteral<"openalex_search_entities">;
+            arguments: z.ZodObject<{}, z.core.$loose>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    over_budget: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>, readonly [{
     readonly reason: "semantic_per_page_cap";
     readonly code: JsonRpcErrorCode.ValidationError;
@@ -85,6 +109,28 @@ export declare const searchEntitiesTool: import("@cyanheads/mcp-ts-core").ToolDe
     readonly code: JsonRpcErrorCode.ValidationError;
     readonly when: "A search (no `id`) provided `seed` without `sample`.";
     readonly recovery: "Pass `sample` to enable random sampling, or remove `seed`.";
+}, {
+    readonly reason: "slice_without_id";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "A search passed `slice` without `id` — slice pages one array of one record.";
+    readonly recovery: "Pass the record's `id` alongside `slice`, or drop `slice` to run the search; a `windows` entry's `next` call carries both.";
+}, {
+    readonly reason: "slice_field_not_array";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "The `slice` field is `*`, or is not an array on the record at `id` — absent, null, a scalar, or an object.";
+    readonly recovery: "Name a top-level array field of that record, such as authorships, author_list, referenced_works, or locations; openalex_describe_fields(entity_type, \"select\") lists the field names.";
+}, {
+    readonly reason: "id_type_mismatch";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "`id` is a native OpenAlex ID whose letter names another entity type than `entity_type`, or a concept ID (C…), a type this server does not serve.";
+    readonly recovery: "Pass the entity_type the ID letter names — W works, A authors, S sources, I institutions, T topics, P publishers, F funders. A concept ID (C…) has no entity_type here; search topics for the concept by name with openalex_resolve_name instead.";
+    readonly thrownBy: "service";
+}, {
+    readonly reason: "id_dot_segment";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "`id` holds a `.` or `..` path segment, written plainly or percent-encoded.";
+    readonly recovery: "Pass the identifier itself — an OpenAlex ID, DOI, ORCID, ROR, PMID, or ISSN — with no relative path segments, or drop `id` and search with `query` or `filters`.";
+    readonly thrownBy: "service";
 }, {
     readonly reason: "entity_not_found";
     readonly code: JsonRpcErrorCode.NotFound;
@@ -103,7 +149,14 @@ export declare const searchEntitiesTool: import("@cyanheads/mcp-ts-core").ToolDe
     readonly code: JsonRpcErrorCode.RateLimited;
     readonly when: "The OpenAlex daily usage budget is spent (HTTP 429).";
     readonly retryable: false;
-    readonly recovery: "The daily budget refills at midnight UTC — retrying sooner will not succeed. Set OPENALEX_API_KEY to a free key (https://openalex.org/settings/api) for a larger daily budget than anonymous access, or wait for the reset.";
+    readonly recovery: "This server's daily OpenAlex budget is spent and refills at midnight UTC — retrying before then will not succeed.";
+    readonly thrownBy: "service";
+}, {
+    readonly reason: "upstream_plan_required";
+    readonly code: JsonRpcErrorCode.Forbidden;
+    readonly when: "A filter is one OpenAlex serves only on a paid plan — created_date, updated_date, or a from_/to_ form of either (HTTP 429 \"Plan upgrade required\").";
+    readonly retryable: false;
+    readonly recovery: "Drop the plan-gated filter and rerun; retrying it unchanged will not succeed. To bound works by date, filter on publication_date, from_publication_date, or to_publication_date, which need no paid plan.";
     readonly thrownBy: "service";
 }, {
     readonly reason: "upstream_timeout";
@@ -115,7 +168,7 @@ export declare const searchEntitiesTool: import("@cyanheads/mcp-ts-core").ToolDe
 }, {
     readonly reason: "upstream_unavailable";
     readonly code: JsonRpcErrorCode.ServiceUnavailable;
-    readonly when: "OpenAlex was unreachable or unusable — HTTP 503, a connection failure, or a body that was empty, HTML, or unparseable JSON.";
+    readonly when: "OpenAlex was unreachable or unusable — HTTP 503, a connection failure, a body that was empty, HTML, or unparseable JSON, or a semantic search whose query embedding failed upstream (HTTP 400 `Failed to embed query:`, or semantic search not configured).";
     readonly retryable: true;
     readonly recovery: "Wait and retry; check https://openalex.org for service status if the outage persists.";
     readonly thrownBy: "service";
@@ -134,8 +187,26 @@ export declare const searchEntitiesTool: import("@cyanheads/mcp-ts-core").ToolDe
 }, {
     readonly reason: "comma_in_filter_value";
     readonly code: JsonRpcErrorCode.InvalidParams;
-    readonly when: "A filter value contains a comma, which collides with the OpenAlex filter separator.";
-    readonly recovery: "Use `|` for OR within a filter value (e.g. \"2020|2021\"), or use a `.search` filter or the `query` parameter for free-text phrases that contain commas.";
+    readonly when: "A filter value contains a comma, which collides with the OpenAlex filter separator, on a field that takes no phrase. Free-text search filters (any `.search` key, such as title.search or abstract.search.exact) and fields matched as whole text (display_name, awards.funder_display_name, awards.funder_award_id, geo.city, geo.region, raw_affiliation_strings, block_key, parsed_longest_name, biblio fields) are exempt: a comma there is sent quoted, as part of the phrase.";
+    readonly recovery: "Use `|` for OR within a filter value (e.g. \"2020|2021\"), or move a phrase that contains commas into a free-text search filter such as title.search or raw_affiliation_strings.search, or into the `query` parameter.";
+    readonly thrownBy: "service";
+}, {
+    readonly reason: "invalid_country_code";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "A country filter (a key ending in country_code, country_codes, or countries) holds a segment that cannot be a country code, such as a misspelled name, an unassigned number, \"unknown\", or two codes joined by a space (\"DE US\").";
+    readonly recovery: "Pass the country as an ISO 3166-1 alpha-2 code such as DE, US, or GB (an alpha-3 code, numeric code, or English name is converted), or null for records with no country.";
+    readonly thrownBy: "service";
+}, {
+    readonly reason: "mixed_and_or_in_filter_value";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "A filter value puts \"|\" (OR) beside an AND operator — a \"+\", or a space on a field where words mean AND (on a country field a space is always part of a country name, and inside a language name it is part of the name). OpenAlex splits the value on \"|\" first and drops every alternative that ANDs more than one value, so no single value can carry both.";
+    readonly recovery: "Keep \"|\" and the AND operator in separate filter keys: OR the alternatives in this key and put the AND in a second key that reaches the same values — on works, {\"authorships.institutions.country_code\": \"DE|FR\", \"institutions.country_code\": \"US\"} matches (DE or FR) and US. The filters object holds each key once, so where no second key fits, run one call per alternative instead.";
+    readonly thrownBy: "service";
+}, {
+    readonly reason: "quote_in_filter_value";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "A filter value sent to OpenAlex double-quoted holds a double quote inside its outer pair — a value the server quotes (a multi-word value on a field matched as whole text, or a value holding a comma on such a field or on a free-text search filter), or one the caller wrapped in double quotes on any filter but a free-text search.";
+    readonly recovery: "Remove the double quote from the value; a phrase is matched without quoting its own text.";
     readonly thrownBy: "service";
 }, {
     readonly reason: "upstream_invalid_params";

package/dist/mcp-server/tools/definitions/search-entities.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search-entities.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/search-entities.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AA0EjE,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyiB7B,CAAC"}
+{"version":3,"file":"search-entities.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/search-entities.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AA2FjE,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqqB7B,CAAC"}

package/dist/mcp-server/tools/definitions/search-entities.tool.js

@@ -5,11 +5,14 @@
 import { tool, z } from '@cyanheads/mcp-ts-core';
 import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 import { renderBudgetTrailer } from '../render-budget.js';
-import { renderEntityRecord } from '../render-entity-record.js';
-import { getOpenAlexService } from '../../../services/openalex/openalex-service.js';
+import { fitRecordsToBudget, fitSliceToBudget, formatRecordPage, joinNotices, measurePageFrame, omittedOutputSchema, overBudgetOutputSchema, windowsOutputSchema, } from '../response-budget.js';
+import { quoteCallerText } from '../../../services/openalex/filter-values.js';
+import { getOpenAlexService, selectRecordKey } from '../../../services/openalex/openalex-service.js';
 import { ENTITY_TYPES } from '../../../services/openalex/types.js';
 const SEMANTIC_PER_PAGE_CAP = 50;
 const SAMPLE_MAX = 100;
+/** What `meta.count` counts, in the rendered header. */
+const RESULT_NOUN = 'result(s)';
 /**
  * The parameters that shape a *list* query, each paired with its echo rendering. Ground truth
  * is `OpenAlexService.search()`: its `id` branch requests `/{entity_type}/{id}` with `select`
@@ -23,7 +26,7 @@ const SAMPLE_MAX = 100;
 function searchOnlyParams(input) {
     const parts = [];
     if (input.query)
-        parts.push({ name: 'query', rendered: `query="${input.query}"` });
+        parts.push({ name: 'query', rendered: `query=${JSON.stringify(input.query)}` });
     if (input.search_mode && input.search_mode !== 'keyword') {
         parts.push({ name: 'search_mode', rendered: `search_mode=${input.search_mode}` });
     }
@@ -31,23 +34,25 @@ function searchOnlyParams(input) {
         parts.push({ name: 'filters', rendered: `filters=${JSON.stringify(input.filters)}` });
     }
     if (input.sort)
-        parts.push({ name: 'sort', rendered: `sort=${input.sort}` });
+        parts.push({ name: 'sort', rendered: `sort=${JSON.stringify(input.sort)}` });
     if (input.sample !== undefined) {
         parts.push({ name: 'sample', rendered: `sample=${input.sample}` });
     }
-    if (input.seed !== undefined)
-        parts.push({ name: 'seed', rendered: `seed=${input.seed}` });
+    if (input.seed !== undefined) {
+        parts.push({ name: 'seed', rendered: `seed=${JSON.stringify(input.seed)}` });
+    }
     return parts;
 }
 /**
  * Echo the criteria that actually ran. An `id` lookup echoes `entity_type` and `id` only —
  * echoing a filter the singleton path never applied reads as confirmation that it did, which
- * is the one thing this field exists not to do.
+ * is the one thing this field exists not to do. Caller text is JSON-encoded, so a line break in
+ * it cannot start a heading or end the line the echo renders on.
  */
 function buildSearchEcho(input) {
     const parts = [`entity_type=${input.entity_type}`];
     if (input.id)
-        return [...parts, `id=${input.id}`].join(' | ');
+        return [...parts, `id=${JSON.stringify(input.id)}`].join(' | ');
     return [...parts, ...searchOnlyParams(input).map((part) => part.rendered)].join(' | ');
 }
 /**
@@ -63,7 +68,7 @@ function isContinuationPage(input) {
     return input.cursor !== undefined || (input.page ?? 1) > 1;
 }
 export const searchEntitiesTool = tool('openalex_search_entities', {
-    description: 'Search, filter, sort, or retrieve by ID. Covers all OpenAlex entity types (works, authors, sources, institutions, topics, keywords, publishers, funders). Pass `id` to retrieve a single entity. Otherwise, use `query` and/or `filters` for discovery. Supports keyword search with boolean operators, exact phrase matching, and AI semantic search. Use openalex_resolve_name to resolve names to IDs before filtering. Searches and ID lookups return a curated set of fields by default; pass `select` to override with specific fields, or `["*"]` for the full record.',
+    description: 'Search, filter, sort, or retrieve by ID. Covers all OpenAlex entity types (works, authors, sources, institutions, topics, keywords, publishers, funders). Pass `id` to retrieve a single entity. Otherwise, use `query` and/or `filters` for discovery. Supports keyword search with boolean operators, exact phrase matching, and AI semantic search. Use openalex_resolve_name to resolve names to IDs before filtering. Searches and ID lookups return a curated set of fields by default; pass `select` to override with specific fields, or `["*"]` for the full record. Responses cap at 64,000 bytes per surface unless the least a call can return is larger (`over_budget`); `omitted` and `windows` give the calls that continue a cut, and `slice` pages a long array.',
     sourceUrl: 'https://github.com/cyanheads/openalex-mcp-server/blob/main/src/mcp-server/tools/definitions/search-entities.tool.ts',
     annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
     errors: [
@@ -121,6 +126,32 @@ export const searchEntitiesTool = tool('openalex_search_entities', {
             when: 'A search (no `id`) provided `seed` without `sample`.',
             recovery: 'Pass `sample` to enable random sampling, or remove `seed`.',
         },
+        {
+            reason: 'slice_without_id',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'A search passed `slice` without `id` — slice pages one array of one record.',
+            recovery: "Pass the record's `id` alongside `slice`, or drop `slice` to run the search; a `windows` entry's `next` call carries both.",
+        },
+        {
+            reason: 'slice_field_not_array',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'The `slice` field is `*`, or is not an array on the record at `id` — absent, null, a scalar, or an object.',
+            recovery: 'Name a top-level array field of that record, such as authorships, author_list, referenced_works, or locations; openalex_describe_fields(entity_type, "select") lists the field names.',
+        },
+        {
+            reason: 'id_type_mismatch',
+            code: JsonRpcErrorCode.ValidationError,
+            when: '`id` is a native OpenAlex ID whose letter names another entity type than `entity_type`, or a concept ID (C…), a type this server does not serve.',
+            recovery: 'Pass the entity_type the ID letter names — W works, A authors, S sources, I institutions, T topics, P publishers, F funders. A concept ID (C…) has no entity_type here; search topics for the concept by name with openalex_resolve_name instead.',
+            thrownBy: 'service',
+        },
+        {
+            reason: 'id_dot_segment',
+            code: JsonRpcErrorCode.ValidationError,
+            when: '`id` holds a `.` or `..` path segment, written plainly or percent-encoded.',
+            recovery: 'Pass the identifier itself — an OpenAlex ID, DOI, ORCID, ROR, PMID, or ISSN — with no relative path segments, or drop `id` and search with `query` or `filters`.',
+            thrownBy: 'service',
+        },
         {
             reason: 'entity_not_found',
             code: JsonRpcErrorCode.NotFound,
@@ -141,7 +172,15 @@ export const searchEntitiesTool = tool('openalex_search_entities', {
             code: JsonRpcErrorCode.RateLimited,
             when: 'The OpenAlex daily usage budget is spent (HTTP 429).',
             retryable: false,
-            recovery: 'The daily budget refills at midnight UTC — retrying sooner will not succeed. Set OPENALEX_API_KEY to a free key (https://openalex.org/settings/api) for a larger daily budget than anonymous access, or wait for the reset.',
+            recovery: "This server's daily OpenAlex budget is spent and refills at midnight UTC — retrying before then will not succeed.",
+            thrownBy: 'service',
+        },
+        {
+            reason: 'upstream_plan_required',
+            code: JsonRpcErrorCode.Forbidden,
+            when: 'A filter is one OpenAlex serves only on a paid plan — created_date, updated_date, or a from_/to_ form of either (HTTP 429 "Plan upgrade required").',
+            retryable: false,
+            recovery: 'Drop the plan-gated filter and rerun; retrying it unchanged will not succeed. To bound works by date, filter on publication_date, from_publication_date, or to_publication_date, which need no paid plan.',
             thrownBy: 'service',
         },
         {
@@ -155,7 +194,7 @@ export const searchEntitiesTool = tool('openalex_search_entities', {
         {
             reason: 'upstream_unavailable',
             code: JsonRpcErrorCode.ServiceUnavailable,
-            when: 'OpenAlex was unreachable or unusable — HTTP 503, a connection failure, or a body that was empty, HTML, or unparseable JSON.',
+            when: 'OpenAlex was unreachable or unusable — HTTP 503, a connection failure, a body that was empty, HTML, or unparseable JSON, or a semantic search whose query embedding failed upstream (HTTP 400 `Failed to embed query:`, or semantic search not configured).',
             retryable: true,
             recovery: 'Wait and retry; check https://openalex.org for service status if the outage persists.',
             thrownBy: 'service',
@@ -177,8 +216,29 @@ export const searchEntitiesTool = tool('openalex_search_entities', {
         {
             reason: 'comma_in_filter_value',
             code: JsonRpcErrorCode.InvalidParams,
-            when: 'A filter value contains a comma, which collides with the OpenAlex filter separator.',
-            recovery: 'Use `|` for OR within a filter value (e.g. "2020|2021"), or use a `.search` filter or the `query` parameter for free-text phrases that contain commas.',
+            when: 'A filter value contains a comma, which collides with the OpenAlex filter separator, on a field that takes no phrase. Free-text search filters (any `.search` key, such as title.search or abstract.search.exact) and fields matched as whole text (display_name, awards.funder_display_name, awards.funder_award_id, geo.city, geo.region, raw_affiliation_strings, block_key, parsed_longest_name, biblio fields) are exempt: a comma there is sent quoted, as part of the phrase.',
+            recovery: 'Use `|` for OR within a filter value (e.g. "2020|2021"), or move a phrase that contains commas into a free-text search filter such as title.search or raw_affiliation_strings.search, or into the `query` parameter.',
+            thrownBy: 'service',
+        },
+        {
+            reason: 'invalid_country_code',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'A country filter (a key ending in country_code, country_codes, or countries) holds a segment that cannot be a country code, such as a misspelled name, an unassigned number, "unknown", or two codes joined by a space ("DE US").',
+            recovery: 'Pass the country as an ISO 3166-1 alpha-2 code such as DE, US, or GB (an alpha-3 code, numeric code, or English name is converted), or null for records with no country.',
+            thrownBy: 'service',
+        },
+        {
+            reason: 'mixed_and_or_in_filter_value',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'A filter value puts "|" (OR) beside an AND operator — a "+", or a space on a field where words mean AND (on a country field a space is always part of a country name, and inside a language name it is part of the name). OpenAlex splits the value on "|" first and drops every alternative that ANDs more than one value, so no single value can carry both.',
+            recovery: 'Keep "|" and the AND operator in separate filter keys: OR the alternatives in this key and put the AND in a second key that reaches the same values — on works, {"authorships.institutions.country_code": "DE|FR", "institutions.country_code": "US"} matches (DE or FR) and US. The filters object holds each key once, so where no second key fits, run one call per alternative instead.',
+            thrownBy: 'service',
+        },
+        {
+            reason: 'quote_in_filter_value',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'A filter value sent to OpenAlex double-quoted holds a double quote inside its outer pair — a value the server quotes (a multi-word value on a field matched as whole text, or a value holding a comma on such a field or on a free-text search filter), or one the caller wrapped in double quotes on any filter but a free-text search.',
+            recovery: 'Remove the double quote from the value; a phrase is matched without quoting its own text.',
             thrownBy: 'service',
         },
         {
@@ -231,7 +291,7 @@ export const searchEntitiesTool = tool('openalex_search_entities', {
             .string()
             .min(1)
             .optional()
-            .describe('Retrieve a single entity by ID. Supports: OpenAlex ID ("W2741809807"), DOI ("10.1038/nature12373"), ORCID ("0000-0002-1825-0097"), ROR ("https://ror.org/00hx57361"), PMID ("12345678" or "https://pubmed.ncbi.nlm.nih.gov/12345678"), ISSN ("1234-5678"). Keywords are identified by slug rather than a native ID — pass either the slug ("groundwater") or the URL a search returns ("https://openalex.org/keywords/groundwater"). A PMCID is recognized too, bare ("PMC1234567") or as a PubMed Central URL, but OpenAlex indexes no PMCIDs, so it resolves nothing — pass the work\'s PMID or DOI instead. When provided, `query`, `search_mode`, `filters`, `sort`, `sample`, and `seed` are not applied — the returned record is the entity at that ID regardless of them, and the response `notice` names any you passed. `select` still applies: the curated per-entity-type default is returned unless you pass `select` (use `["*"]` for the complete record). To filter, drop `id` and search. Use openalex_resolve_name to find the ID if unknown.'),
+            .describe('Retrieve a single entity by ID. Supports: OpenAlex ID ("W2741809807", or its OpenAlex record-page or API URL such as "https://openalex.org/works/W2741809807" or "https://api.openalex.org/works/W2741809807"), whose letter must name `entity_type` — W works, A authors, S sources, I institutions, T topics, P publishers, F funders; DOI ("10.1038/nature12373"; under entity_type "funders", a funder\'s Crossref Funder Registry DOI such as "10.13039/100000001"), ORCID ("0000-0002-1825-0097"), ROR ("https://ror.org/00hx57361" — one ROR can name an institution, a funder, and a publisher, and `entity_type` picks which), PMID ("12345678" or "https://pubmed.ncbi.nlm.nih.gov/12345678"), ISSN ("1234-5678"). Keywords are identified by slug rather than a native ID — pass either the slug ("groundwater") or the URL a search returns ("https://openalex.org/keywords/groundwater"). A PMCID is recognized too, bare ("PMC1234567") or as a PubMed Central URL, but OpenAlex indexes no PMCIDs, so it resolves nothing — pass the work\'s PMID or DOI instead. When provided, `query`, `search_mode`, `filters`, `sort`, `sample`, and `seed` are not applied — the returned record is the entity at that ID regardless of them, and the response `notice` names any you passed. `select` still applies: the curated per-entity-type default is returned unless you pass `select` (use `["*"]` for the complete record). An array too long for the response budget comes back as a window (`windows`); page the rest with `slice`. To filter, drop `id` and search. Use openalex_resolve_name to find the ID if unknown.'),
         query: z
             .string()
             .min(1)
@@ -244,7 +304,7 @@ export const searchEntitiesTool = tool('openalex_search_entities', {
         filters: z
             .record(z.string(), z.string())
             .optional()
-            .describe('Filter criteria as field:value pairs. AND across fields (multiple keys). OR within field: pipe-separate ("us|gb"). NOT: prefix "!" ("!us"). Range: "2020-2024". Comparison: ">100", "<50". AND within same field: "+"-separate. Two keys that resolve to the same upstream field (an alias and its canonical name, e.g. `year` and `publication_year`) are both applied and AND\'d, so they narrow rather than override each other. Use OpenAlex IDs (not names) for entity filters — resolve names first. Common keys: `openalex` (filter by entity ID, e.g. {"openalex": "W123|W456"}), `cites` (works citing a given work), `publication_year` (range "2020-2024"), `authorships.author.id`, `type`, `is_oa`.'),
+            .describe('Filter criteria as field:value pairs. AND across fields (multiple keys). OR within field: pipe-separate ("us|gb"). NOT: prefix "!" ("!us"). Range: "2020-2024". Comparison: ">100", "<50". AND within same field: "+"-separate ("us+gb"); inside a `.search` value, a DOI, a date (a timestamp\'s "+00:00" offset), a URL field such as landing_page_url, an exactly matched name (display_name, awards.funder_display_name — "C++", "Erasmus+"), a biblio field (issue "1+2"), or awards.funder_award_id, "+" is a literal character. A value cannot mix "|" with an AND operator — a "+", or a space between values on an ID, code, or `language` key (a space inside a language name is part of the name, and a country field never reads a space as AND) — OpenAlex splits it on "|" first and drops every alternative that ANDs more than one value, so such a value is rejected; put the AND in a second key instead ("institutions.country_code": "US" beside "authorships.institutions.country_code": "DE|FR" on works). On a field matched as whole text (display_name, awards.funder_display_name, awards.funder_award_id, geo.city, geo.region, raw_affiliation_strings, block_key, biblio fields), a space is part of the value: "New York", "!New York", and "New York|Boston" match as written, but quotes around one "|" alternative make that alternative match nothing. A comma is part of such a value too ("University of California, Berkeley" on raw_affiliation_strings): a value holding one is sent as one quoted phrase, its "+" a literal character. A value sent as a quoted phrase cannot contain a double quote of its own. A multi-word value there cannot be ANDed with another ("New York+Boston" matches nothing); to require two funders or institutions, AND their IDs (awards.funder_id, authorships.institutions.id). Country fields (keys ending in country_code, country_codes, or countries) take ISO 3166-1 alpha-2 codes ("DE"): an alpha-3 code ("DEU"), numeric code ("276"), or English name ("Germany", "South Korea") is converted, "UK" becomes "GB", and a value that cannot be a country code is rejected. A space there is part of a name, never a separator: "South Korea|Japan" ORs two countries, and "DE US" is rejected. `language` takes ISO 639-1 codes ("en"): an ISO 639-2 code ("eng") or English name ("English") is converted. Two keys that resolve to the same upstream field (an alias and its canonical name, e.g. `year` and `publication_year`) are both applied and AND\'d, so they narrow rather than override each other. Use OpenAlex IDs (not names) for entity filters — resolve names first. Common keys: `openalex` (filter by entity ID, e.g. {"openalex": "W123|W456"}), `cites` (works citing a given work), `publication_year` (range "2020-2024"), `authorships.author.id`, `type`, `is_oa`.'),
         sort: z
             .string()
             .optional()
@@ -252,14 +312,14 @@ export const searchEntitiesTool = tool('openalex_search_entities', {
         select: z
             .array(z.string())
             .optional()
-            .describe('OpenAlex top-level field names to return. Always returned: `id`, `display_name` — additional fields you list are appended. A curated default per entity type applies to both searches and single-entity (`id`) lookups; pass field names to override it, or `["*"]` to retrieve the complete record (every field). Only top-level fields project, so a nested value is requested by its parent object: bibliometrics (`h_index`, `i10_index`, `2yr_mean_citedness`) live under `summary_stats` on authors, sources, institutions, publishers, and funders, and naming a leaf returns that object. Invalid field names produce an error identifying the rejected field. Example: ["doi", "authorships", "primary_topic"].'),
+            .describe('OpenAlex top-level field names to return. Always returned: `id`, `display_name` — additional fields you list are appended. A curated default per entity type applies to both searches and single-entity (`id`) lookups; pass field names to override it, or `["*"]` to retrieve the complete record (every field). Only top-level fields project, so a nested value is requested by its parent object: bibliometrics (`h_index`, `i10_index`, `2yr_mean_citedness`) live under `summary_stats` on authors, sources, institutions, publishers, and funders, and naming a leaf returns that object. On sources, `publisher` returns `host_organization_name`: the publisher of a journal, the hosting institution of a repository, and null on most sources. On works, `author_list` returns each author in authorship order as `{id, display_name, orcid}` (`orcid` null when absent), a compact alternative to `authorships`, which also carries institutions and affiliations; neither the default nor `["*"]` includes it. Invalid field names produce an error identifying the rejected field. Large projections may be cut to fit the response budget (`omitted`, `windows`). Not applied with `slice`. Example: ["doi", "author_list", "primary_topic"].'),
         per_page: z
             .number()
             .int()
             .min(1)
             .max(100)
             .default(25)
-            .describe('Results per page (1-100). Default 25. Semantic search caps at 50 — when search_mode="semantic", set per_page ≤ 50 (also subject to a 1 req/sec rate limit upstream). The cap applies to searches only; an `id` lookup returns its one record regardless of both.'),
+            .describe('Results per page (1-100). Default 25. Semantic search caps at 50 — when search_mode="semantic", set per_page ≤ 50 (also subject to a 1 req/sec rate limit upstream). The cap applies to searches only; an `id` lookup returns its one record regardless of both. A budget-cut page returns fewer (`omitted`).'),
         cursor: z
             .string()
             .min(1)
@@ -282,6 +342,20 @@ export const searchEntitiesTool = tool('openalex_search_entities', {
             .string()
             .optional()
             .describe('Deterministic seed for `sample`. Same seed + same filters = same results — pass when reproducibility matters. Has no effect without `sample`, and a search that passes it alone is rejected.'),
+        slice: z
+            .object({
+            field: z
+                .string()
+                .describe('Top-level array field to page, such as "authorships", "author_list", or "referenced_works". Leave it empty to skip slicing.'),
+            offset: z
+                .number()
+                .int()
+                .min(0)
+                .default(0)
+                .describe('0-based index of the first element to return.'),
+        })
+            .optional()
+            .describe('Page one array of the record at `id`: returns `id`, `display_name`, and `field` from `offset` onward, as many elements as fit the response budget (at least one), with the window and its `next` call in `windows`. Requires `id`; replaces `select`. An offset at or past the end returns an empty window. Walks any partial array, including a possibly capped 100-entry `authorships` or `author_list`.'),
     }),
     output: z.object({
         meta: z
@@ -291,25 +365,30 @@ export const searchEntitiesTool = tool('openalex_search_entities', {
                 .describe('Total results matching the query/filters. Under search_mode "semantic" it is instead the size of the ranked candidate set — the most results `page` can reach — not an exhaustive match total.'),
             per_page: z
                 .number()
-                .describe('Page size OpenAlex echoed for this request — the requested per_page, not the number of records returned. A short or exhausted page carries fewer records than this.'),
+                .describe('Page size OpenAlex echoed for this request — the requested per_page, not the number of records returned. A short or exhausted page carries fewer records than this, as does a page the response budget cut (`omitted`).'),
             next_cursor: z
                 .string()
                 .nullable()
-                .describe('Cursor for next page. null if no more results.'),
+                .describe('Cursor for next page. null if no more results. Continues after the full upstream page, `omitted` records included.'),
         })
             .describe('Result metadata including pagination.'),
         results: z
             .array(z
             .object({
-            id: z.string().describe('OpenAlex ID (e.g., "W2741809807", "A1234567890").'),
+            id: z
+                .string()
+                .describe('OpenAlex ID URL (e.g., "https://openalex.org/W2741809807"). `windows` and `omitted` name records by the bare ID ("W2741809807"); a keyword keeps its URL.'),
             display_name: z
                 .string()
                 .nullable()
                 .describe('Entity name or work title. null when OpenAlex holds no title for the record (paratext works and other untitled entries) — use `id` to identify it.'),
         })
-            .passthrough()
+            .loose()
             .describe('A single OpenAlex entity record. `id` is always present and `display_name` is always returned (though it may be null); additional fields vary by entity_type and `select`.'))
-            .describe('OpenAlex entity objects. Text values are plain text — HTML entities decoded, HTML/JATS/MathML markup removed — and an abstract arrives reconstructed as `abstract`. Additional fields depend on entity_type and select.'),
+            .describe('OpenAlex entity objects. Text values are plain text — HTML entities decoded, HTML/JATS/MathML markup removed — except identifier and URL fields such as `id`, `doi`, `ids`, and `*_url`, returned exactly as OpenAlex stores them; an abstract arrives reconstructed as `abstract`, and a selected `author_list` as one `{id, display_name, orcid}` entry per author. Additional fields depend on entity_type and select. Records cut by the response budget are in `omitted`; partial or possibly capped arrays are in `windows`.'),
+        omitted: omittedOutputSchema,
+        windows: windowsOutputSchema,
+        over_budget: overBudgetOutputSchema,
     }),
     // Agent-facing context for the success path — the query/filters as parsed, the
     // total match count, and recovery guidance for empty results. Populated via
@@ -322,12 +401,12 @@ export const searchEntitiesTool = tool('openalex_search_entities', {
         notice: z
             .string()
             .optional()
-            .describe('Guidance notice. Set when a first call returns no results (echoes the criteria and suggests how to broaden), when a paginated call ran past its last page (says the traversal is finished instead of advising a broader query), when an `id` lookup was passed search criteria it does not apply (names them), and on every semantic search to disclose that `meta.count` is a candidate total rather than a match total. Absent otherwise.'),
+            .describe('Guidance notice. Set when a first call returns no results (echoes the criteria and suggests how to broaden), when a paginated call ran past its last page (says the traversal is finished instead of advising a broader query), when an `id` lookup was passed search criteria it does not apply (names them), on every semantic search to disclose that `meta.count` is a candidate total rather than a match total, when the response budget cut records, windowed an array, or ran over, when a list record carries exactly 100 authorships or author_list entries (possibly capped), when a `slice` offset is past the end of its array, and when `slice` was passed with `select`, which it replaces. Absent otherwise.'),
         budget: z
             .object({
             costUsd: z
                 .number()
-                .describe('USD this call spent. 0 for an `id` lookup — OpenAlex does not bill single-entity fetches, so batching known IDs beats paging a filtered list.'),
+                .describe('USD this call spent. 0 for an `id` lookup by an OpenAlex ID, DOI, ORCID, ROR, PMID, or ISSN — OpenAlex does not bill those single-entity fetches, so batching known IDs beats paging a filtered list. OpenAlex bills like one list request a keyword looked up by its slug, an `id` carrying characters past the identifier itself (`W2741809807#x` still returns W2741809807), and a funder looked up by its Funder Registry DOI.'),
             remainingUsd: z.number().describe("USD left in today's OpenAlex budget after this call."),
             resetsInSeconds: z
                 .number()
@@ -346,6 +425,15 @@ export const searchEntitiesTool = tool('openalex_search_entities', {
         budget: { render: renderBudgetTrailer },
     },
     async handler(input, ctx) {
+        // A form client sends an empty `slice.field` for an unset slice; an empty field is no slice.
+        const slice = input.slice?.field ? input.slice : undefined;
+        if (slice && !input.id) {
+            throw ctx.fail('slice_without_id', '`slice` pages one array of the record at `id`, and no `id` was supplied.', { slice });
+        }
+        // `*` would fetch the full record only to find no field of that name; refuse it up front.
+        if (slice?.field === '*') {
+            throw ctx.fail('slice_field_not_array', '`slice.field` is `*`, which names every field rather than one array.', { field: slice.field, id: input.id });
+        }
         /**
          * Reject list-query parameter combinations OpenAlex cannot serve. Every check here
          * constrains a *list* query. `id` takes the singleton path in `OpenAlexService.search()`,
@@ -359,61 +447,44 @@ export const searchEntitiesTool = tool('openalex_search_entities', {
             // nothing to embed — the request silently degraded to a plain unfiltered listing whose
             // echo still advertised `search_mode=semantic`.
             if (input.search_mode === 'semantic' && !input.query) {
-                throw ctx.fail('semantic_without_query', 'Semantic search needs `query` text to embed — none was supplied.', { ...ctx.recoveryFor('semantic_without_query'), searchMode: input.search_mode });
+                throw ctx.fail('semantic_without_query', 'Semantic search needs `query` text to embed — none was supplied.', { searchMode: input.search_mode });
             }
             if (input.search_mode === 'semantic' && input.per_page > SEMANTIC_PER_PAGE_CAP) {
-                throw ctx.fail('semantic_per_page_cap', `Semantic search supports at most ${SEMANTIC_PER_PAGE_CAP} results per page. Reduce per_page or switch search_mode.`, {
-                    ...ctx.recoveryFor('semantic_per_page_cap'),
-                    searchMode: input.search_mode,
-                    perPage: input.per_page,
-                    cap: SEMANTIC_PER_PAGE_CAP,
-                });
+                throw ctx.fail('semantic_per_page_cap', `Semantic search supports at most ${SEMANTIC_PER_PAGE_CAP} results per page. Reduce per_page or switch search_mode.`, { searchMode: input.search_mode, perPage: input.per_page, cap: SEMANTIC_PER_PAGE_CAP });
             }
             // OpenAlex answers `search.semantic` plus a cursor with a 400 ("Cursor pagination is not
             // supported with semantic search"), so forwarding it spends a round trip to learn that.
             if (input.search_mode === 'semantic' && input.cursor !== undefined) {
-                throw ctx.fail('semantic_with_cursor', 'Semantic search does not accept `cursor` — walk its candidates with `page` (1-based) instead.', {
-                    ...ctx.recoveryFor('semantic_with_cursor'),
-                    searchMode: input.search_mode,
-                    cursor: input.cursor,
-                });
+                throw ctx.fail('semantic_with_cursor', 'Semantic search does not accept `cursor` — walk its candidates with `page` (1-based) instead.', { searchMode: input.search_mode, cursor: input.cursor });
             }
             // The inverse: `page` is the semantic-only knob, and OpenAlex ignores it on a cursor
             // traversal — silently returning page 1 again rather than the page that was asked for.
             if (input.page !== undefined && input.search_mode !== 'semantic') {
-                throw ctx.fail('page_without_semantic', `\`page\` applies to semantic search only — search_mode is "${input.search_mode}", which paginates with \`cursor\`.`, {
-                    ...ctx.recoveryFor('page_without_semantic'),
-                    searchMode: input.search_mode,
-                    page: input.page,
-                });
+                throw ctx.fail('page_without_semantic', `\`page\` applies to semantic search only — search_mode is "${input.search_mode}", which paginates with \`cursor\`.`, { searchMode: input.search_mode, page: input.page });
             }
             if (input.sample !== undefined && input.cursor !== undefined) {
-                throw ctx.fail('sample_with_cursor', 'Sampling returns one page only — `sample` cannot be combined with `cursor` pagination.', { ...ctx.recoveryFor('sample_with_cursor'), sample: input.sample, cursor: input.cursor });
+                throw ctx.fail('sample_with_cursor', 'Sampling returns one page only — `sample` cannot be combined with `cursor` pagination.', { sample: input.sample, cursor: input.cursor });
             }
             // Sampling pins `per_page` to `sample` and returns that one page, so there is no second
             // page for `page` to address — the same exclusion `cursor` has above. Reachable under
             // semantic mode alone; every other mode rejects `page` at the check before this one.
             if (input.sample !== undefined && input.page !== undefined) {
-                throw ctx.fail('sample_with_page', 'Sampling returns one page only — `sample` cannot be combined with `page` pagination.', { ...ctx.recoveryFor('sample_with_page'), sample: input.sample, page: input.page });
+                throw ctx.fail('sample_with_page', 'Sampling returns one page only — `sample` cannot be combined with `page` pagination.', { sample: input.sample, page: input.page });
             }
             // OpenAlex ignores `sample` and `seed` under `search.semantic` and returns the ranked page,
             // so forwarding the pair would label a relevance ranking as a random sample. The population
             // request would also carry `cursor=*` beside `search.semantic`, which upstream rejects.
             // Checked after `sample_with_page`, which is reachable under semantic mode alone.
             if (input.sample !== undefined && input.search_mode === 'semantic') {
-                throw ctx.fail('sample_with_semantic', 'Semantic search does not sample — OpenAlex returns the same ranked candidates under every seed.', {
-                    ...ctx.recoveryFor('sample_with_semantic'),
-                    sample: input.sample,
-                    searchMode: input.search_mode,
-                });
+                throw ctx.fail('sample_with_semantic', 'Semantic search does not sample — OpenAlex returns the same ranked candidates under every seed.', { sample: input.sample, searchMode: input.search_mode });
             }
             // OpenAlex answers any sort beside `sample` with a 400 ("sample does not work with sort").
             // A blank or whitespace-only sort is never sent upstream, so it is no conflict.
             if (input.sample !== undefined && input.sort?.trim()) {
-                throw ctx.fail('sample_with_sort', 'A random sample cannot be sorted — `sample` cannot be combined with `sort`.', { ...ctx.recoveryFor('sample_with_sort'), sample: input.sample, sort: input.sort });
+                throw ctx.fail('sample_with_sort', 'A random sample cannot be sorted — `sample` cannot be combined with `sort`.', { sample: input.sample, sort: input.sort });
             }
             if (input.seed !== undefined && input.sample === undefined) {
-                throw ctx.fail('seed_without_sample', '`seed` is only meaningful with `sample` — pass `sample` to enable random sampling.', { ...ctx.recoveryFor('seed_without_sample'), seed: input.seed });
+                throw ctx.fail('seed_without_sample', '`seed` is only meaningful with `sample` — pass `sample` to enable random sampling.', { seed: input.seed });
             }
         }
         const service = getOpenAlexService();
@@ -424,7 +495,7 @@ export const searchEntitiesTool = tool('openalex_search_entities', {
             searchMode: input.search_mode,
             filters: input.filters,
             sort: input.sort,
-            select: input.select,
+            select: slice ? [slice.field] : input.select,
             perPage: input.per_page,
             cursor: input.cursor,
             page: input.page,
@@ -460,31 +531,56 @@ export const searchEntitiesTool = tool('openalex_search_entities', {
         if (!input.id && input.search_mode === 'semantic') {
             notices.push(`Semantic search ranks a candidate set rather than every match, so \`meta.count\` (${result.meta.count}) is the number of candidates \`page\` can reach, not the total number of matching records. Reach the rest of the candidates with \`page\`.`);
         }
-        if (notices.length > 0)
-            ctx.enrich.notice(notices.join(' '));
-        return {
-            meta: {
-                count: result.meta.count,
-                per_page: result.meta.per_page,
-                next_cursor: result.meta.next_cursor,
-            },
-            results: result.results,
+        if (slice && input.select) {
+            notices.push('`slice` returns only `id`, `display_name`, and the sliced field, so `select` was not applied.');
+        }
+        const meta = {
+            count: result.meta.count,
+            per_page: result.meta.per_page,
+            next_cursor: result.meta.next_cursor,
         };
-    },
-    format: (result) => {
-        const lines = [];
-        const countLabel = `${result.meta.count} result(s) — ${result.meta.per_page} per page`;
-        const header = result.meta.next_cursor
-            ? `**${countLabel}** — next cursor: \`${result.meta.next_cursor}\``
-            : `**${countLabel}**`;
-        lines.push(header);
-        if (result.results.length === 0) {
-            return [{ type: 'text', text: lines.join('\n') }];
+        const measureFrame = (disclosure, budgetNotice) => measurePageFrame({ meta, results: [], ...disclosure }, RESULT_NOUN, {
+            echo,
+            totalCount: result.meta.count,
+            totalLabel: 'Total',
+            notice: joinNotices([...notices, budgetNotice]),
+        });
+        let page;
+        // A slice without an `id` was refused as `slice_without_id`, so `input.id` only narrows here.
+        if (slice && input.id) {
+            // The one-field projection lands under its record key — `authors` arrives as `authorships`,
+            // and `author_list` as itself.
+            const field = selectRecordKey(input.entity_type, slice.field);
+            const [record] = result.results;
+            const items = record?.[field];
+            if (!record || !Array.isArray(items)) {
+                throw ctx.fail('slice_field_not_array', `${quoteCallerText(slice.field)} is not an array on the record at ${quoteCallerText(input.id)}.`, { field: slice.field, id: input.id });
+            }
+            if (slice.offset > items.length) {
+                notices.push(`slice.offset ${slice.offset} is past the end of \`${field}\`, which holds ${items.length} element(s), so nothing follows.`);
+            }
+            page = fitSliceToBudget({
+                record,
+                field,
+                offset: slice.offset,
+                entityType: input.entity_type,
+                measureFrame,
+            });
         }
-        for (const record of result.results) {
-            lines.push(...renderEntityRecord(record));
+        else {
+            page = fitRecordsToBudget({
+                records: result.results,
+                entityType: input.entity_type,
+                path: input.id ? 'lookup' : 'list',
+                select: input.select,
+                measureFrame,
+            });
         }
-        return [{ type: 'text', text: lines.join('\n') }];
+        const notice = joinNotices([...notices, page.notice]);
+        if (notice)
+            ctx.enrich.notice(notice);
+        return { meta, results: page.results, ...page.disclosure };
     },
+    format: (result) => formatRecordPage(result, RESULT_NOUN),
 });
 //# sourceMappingURL=search-entities.tool.js.map