@cyanheads/openalex-mcp-server 0.7.14 → 0.7.16

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

@@ -16,9 +16,9 @@ const SAMPLE_MAX = 100;
  * alone, so every parameter named here is dropped on that path — by OpenAlex itself, which
  * answers an entity-by-ID URL identically whether or not search params ride along.
  *
- * Pagination (`per_page`, `cursor`) is deliberately absent: a singleton lookup is one record by
- * definition, and `per_page` always carries its schema default, so a caller's intent there
- * cannot be told apart from the absence of one. Naming it would be noise, not a warning.
+ * Pagination (`per_page`, `cursor`, `page`) is deliberately absent: a singleton lookup is one
+ * record by definition, and `per_page` always carries its schema default, so a caller's intent
+ * there cannot be told apart from the absence of one. Naming it would be noise, not a warning.
  */
 function searchOnlyParams(input) {
     const parts = [];
@@ -51,31 +51,16 @@ function buildSearchEcho(input) {
     return [...parts, ...searchOnlyParams(input).map((part) => part.rendered)].join(' | ');
 }
 /**
- * Reject list-query parameter combinations OpenAlex cannot serve. All three checks constrain a
- * *list* query. `id` takes the singleton path in `OpenAlexService.search()`, which reads only
- * `entity_type`, `id`, and `select` — so search_mode, per_page, cursor, sample, and seed are
- * unread there, and rejecting an ID lookup over how they relate to each other fails it on
- * constraints it never met. The handler's dropped-parameter notice reports them instead. The
- * `id` predicate is truthiness, not `!== undefined`, to match the service branch: an
- * empty-string `id` parses and lists.
+ * Is this call continuing a paginated traversal rather than opening one? A `cursor` is the
+ * keyword/exact signal — the schema rejects a blank one, so its presence is always a real
+ * continuation rather than a mistake OpenAlex answers with page 1; a `page` past the first is
+ * the semantic signal, and `page` only survives the handler's preconditions under semantic
+ * mode. Only on a continuing call does a page of
+ * zero results mean the traversal is finished — on a first call it means nothing matched, and
+ * the two want opposite advice.
  */
-function assertListQueryConstraints(input, ctx) {
-    if (input.id)
-        return;
-    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,
-        });
-    }
-    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 });
-    }
-    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 });
-    }
+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.',
@@ -88,12 +73,48 @@ export const searchEntitiesTool = tool('openalex_search_entities', {
             when: `A search (no \`id\`) set per_page above the semantic-search cap of ${SEMANTIC_PER_PAGE_CAP}.`,
             recovery: `Reduce per_page to ${SEMANTIC_PER_PAGE_CAP} or less, or switch search_mode to keyword.`,
         },
+        {
+            reason: 'semantic_without_query',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'A search set search_mode to "semantic" without supplying the `query` it embeds.',
+            recovery: 'Pass the text to match in `query`, or switch search_mode to keyword for a filter-only listing.',
+        },
+        {
+            reason: 'semantic_with_cursor',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'A search set search_mode to "semantic" and supplied `cursor`, which OpenAlex rejects on a semantic query.',
+            recovery: 'Drop `cursor` and walk semantic results with `page` (1-based), or switch search_mode to keyword or exact, which paginate by cursor.',
+        },
+        {
+            reason: 'page_without_semantic',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'A search supplied `page` under a search_mode other than "semantic".',
+            recovery: 'Drop `page` and paginate with `cursor`, or set search_mode to "semantic" — the only mode `page` applies to.',
+        },
         {
             reason: 'sample_with_cursor',
             code: JsonRpcErrorCode.ValidationError,
             when: 'A search (no `id`) provided both `sample` and `cursor`.',
             recovery: 'Sampling returns a single page only; remove `cursor` or remove `sample`.',
         },
+        {
+            reason: 'sample_with_page',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'A search (no `id`) provided both `sample` and `page`.',
+            recovery: 'Sampling returns a single page only; remove `page` or remove `sample`.',
+        },
+        {
+            reason: 'sample_with_semantic',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'A search (no `id`) provided `sample` with search_mode "semantic", which OpenAlex does not sample — it returns the same ranked candidates under every seed.',
+            recovery: 'Switch search_mode to keyword or exact to draw a random sample, or remove `sample` and walk the semantic candidates with `page`.',
+        },
+        {
+            reason: 'sample_with_sort',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'A search (no `id`) provided both `sample` and `sort`, which OpenAlex refuses together.',
+            recovery: 'A random sample has no order to sort by; remove `sort` or remove `sample`.',
+        },
         {
             reason: 'seed_without_sample',
             code: JsonRpcErrorCode.ValidationError,
@@ -105,6 +126,7 @@ export const searchEntitiesTool = tool('openalex_search_entities', {
             code: JsonRpcErrorCode.NotFound,
             when: 'Lookup by id matched no OpenAlex entity.',
             recovery: 'Verify the ID format or call openalex_resolve_name to find the correct ID.',
+            thrownBy: 'service',
         },
         {
             reason: 'rate_limited',
@@ -112,6 +134,7 @@ export const searchEntitiesTool = tool('openalex_search_entities', {
             when: 'OpenAlex throttled the request for exceeding its per-second ceiling (HTTP 429).',
             retryable: true,
             recovery: 'Wait several seconds and retry; consider lowering request frequency for this caller.',
+            thrownBy: 'service',
         },
         {
             reason: 'upstream_budget_exhausted',
@@ -119,6 +142,7 @@ export const searchEntitiesTool = tool('openalex_search_entities', {
             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.',
+            thrownBy: 'service',
         },
         {
             reason: 'upstream_timeout',
@@ -126,6 +150,7 @@ export const searchEntitiesTool = tool('openalex_search_entities', {
             when: 'OpenAlex did not respond within the request deadline.',
             retryable: true,
             recovery: 'Retry after a short delay; if timeouts persist, narrow the request with tighter filters to reduce upstream load.',
+            thrownBy: 'service',
         },
         {
             reason: 'upstream_unavailable',
@@ -133,54 +158,70 @@ export const searchEntitiesTool = tool('openalex_search_entities', {
             when: 'OpenAlex was unreachable or unusable — HTTP 503, a connection failure, or a body that was empty, HTML, or unparseable JSON.',
             retryable: true,
             recovery: 'Wait and retry; check https://openalex.org for service status if the outage persists.',
+            thrownBy: 'service',
         },
         {
             reason: 'upstream_unauthorized',
             code: JsonRpcErrorCode.Unauthorized,
             when: 'OpenAlex rejected the API key (HTTP 401).',
             recovery: 'Check that OPENALEX_API_KEY is set to a valid OpenAlex account API key (free from https://openalex.org/settings/api).',
+            thrownBy: 'service',
         },
         {
             reason: 'upstream_forbidden',
             code: JsonRpcErrorCode.Forbidden,
             when: 'OpenAlex denied access to the requested resource (HTTP 403).',
             recovery: 'Confirm the API key has access to this entity type or endpoint, then retry the request.',
+            thrownBy: 'service',
         },
         {
             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.',
+            thrownBy: 'service',
         },
         {
             reason: 'upstream_invalid_params',
             code: JsonRpcErrorCode.InvalidParams,
             when: 'OpenAlex rejected an invalid filter, select, or sort field name (HTTP 400).',
             recovery: 'The upstream message names the rejected field and suggests close matches. Use openalex_describe_fields(entity_type, context) to browse all valid fields for the given entity type and context.',
+            thrownBy: 'service',
         },
         {
             reason: 'upstream_invalid_id_value',
             code: JsonRpcErrorCode.InvalidParams,
             when: 'An entity-ID filter received a value that is not an OpenAlex ID — usually a name (HTTP 400).',
             recovery: 'Call openalex_resolve_name to turn the name into an OpenAlex ID, then filter by that ID. Entity filters such as authorships.author.id, primary_topic.id, and cites accept IDs only.',
+            thrownBy: 'service',
         },
         {
             reason: 'upstream_sort_requires_search',
             code: JsonRpcErrorCode.InvalidParams,
             when: 'sort=-relevance_score was used without an active search (HTTP 400).',
             recovery: 'Sorting by relevance_score requires an active search — add a `query` or a `*.search` filter (e.g. title.search), or choose a concrete sort field such as -cited_by_count or -publication_date.',
+            thrownBy: 'service',
+        },
+        {
+            reason: 'query_too_long',
+            code: JsonRpcErrorCode.InvalidParams,
+            when: 'OpenAlex rejected `query` as longer than the search length it accepts (HTTP 400).',
+            recovery: 'Shorten `query` to the character limit the upstream message names, or split the text into several shorter searches and merge their results.',
+            thrownBy: 'service',
         },
         {
             reason: 'upstream_invalid_params_other',
             code: JsonRpcErrorCode.InvalidParams,
             when: 'OpenAlex rejected the request (HTTP 400) for a reason other than an invalid field name.',
             recovery: 'Read the upstream message in the error above and adjust the request — check filter operators, value formats, and cursor/per_page bounds.',
+            thrownBy: 'service',
         },
         {
             reason: 'upstream_validation_failed',
             code: JsonRpcErrorCode.ValidationError,
             when: 'OpenAlex rejected the request as semantically invalid (HTTP 422).',
             recovery: 'Read the upstream message for the specific field, then adjust the request to satisfy validation.',
+            thrownBy: 'service',
         },
     ],
     inputAliases: { search: 'query', filter: 'filters' },
@@ -188,24 +229,26 @@ export const searchEntitiesTool = tool('openalex_search_entities', {
         entity_type: z.enum(ENTITY_TYPES).describe('Type of scholarly entity to search.'),
         id: z
             .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"). 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"), 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.'),
         query: z
             .string()
+            .min(1)
             .optional()
-            .describe('Text search query. Supports boolean operators (AND, OR, NOT), quoted phrases ("exact match"), wildcards (machin*), fuzzy matching (machin~1), and proximity ("climate change"~5). Omit for filter-only queries.'),
+            .describe('Text search query. Supports boolean operators (AND, OR, NOT), quoted phrases ("exact match"), wildcards (machin*), fuzzy matching (machin~1), and proximity ("climate change"~5). Omit for filter-only queries — an empty string is rejected, since a blank search is a mistake rather than a request for the whole catalog.'),
         search_mode: z
             .enum(['keyword', 'exact', 'semantic'])
             .default('keyword')
-            .describe('Search strategy. "keyword": stemmed full-text (default). "exact": no stemming, matches individual words (use quoted phrases for multi-word exact match). "semantic": AI embedding similarity (max 50 results, 1 req/sec).'),
+            .describe(`Search strategy. "keyword": stemmed full-text (default). "exact": no stemming, matches individual words (use quoted phrases for multi-word exact match). "semantic": AI embedding similarity over a query-dependent candidate set whose size \`meta.count\` reports, at ~1 req/sec, up to ${SEMANTIC_PER_PAGE_CAP} per page, and paginated with \`page\` rather than \`cursor\`.`),
         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. 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. 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()
-            .describe('Sort field. Prefix with "-" for descending. Comma-separate for a multi-key sort, applied left to right, with the "-" prefix set per key ("-publication_year,cited_by_count" sorts by year descending, then citations ascending). Common: "cited_by_count", "-publication_date", "-relevance_score" (default when query present). Note: when combined with a keyword query, an explicit sort overrides relevance ranking entirely — top results may be highly cited but only tangentially on-topic. Use "-relevance_score" or omit sort to keep the most relevant results first. "-relevance_score" requires an active search via "query" or a "filter:search" filter — passing it without one will fail.'),
+            .describe('Sort field. Prefix with "-" for descending. Comma-separate for a multi-key sort, applied left to right, with the "-" prefix set per key ("-publication_year,cited_by_count" sorts by year descending, then citations ascending). Common: "cited_by_count", "-publication_date", "-relevance_score" (default when query present). Note: when combined with a keyword query, an explicit sort overrides relevance ranking entirely — top results may be highly cited but only tangentially on-topic. Use "-relevance_score" or omit sort to keep the most relevant results first. "-relevance_score" requires an active search via "query" or a "filter:search" filter — passing it without one will fail. Not combinable with `sample` — a search passing both is rejected.'),
         select: z
             .array(z.string())
             .optional()
@@ -219,15 +262,22 @@ export const searchEntitiesTool = tool('openalex_search_entities', {
             .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.'),
         cursor: z
             .string()
+            .min(1)
+            .optional()
+            .describe('Pagination cursor from a previous response. Pass to get the next page. Omit it on the first call — an empty string is rejected, since a supplied-but-blank cursor is a caller mistake rather than a request for page 1. Keyword and exact modes only — semantic search walks its candidates with `page`, and a `cursor` sent with it is rejected.'),
+        page: z
+            .number()
+            .int()
+            .min(1)
             .optional()
-            .describe('Pagination cursor from a previous response. Pass to get the next page.'),
+            .describe('Page number (1-based) for semantic search, the one mode that paginates with `page` instead of `cursor`. Semantic search ranks a query-dependent candidate set whose size `meta.count` reports, so the last reachable page is ceil(meta.count / per_page) — e.g. page 14 for a count of 70 with per_page=5. Passing it under any other search_mode is rejected.'),
         sample: z
             .number()
             .int()
             .min(1)
             .max(SAMPLE_MAX)
             .optional()
-            .describe(`Return a random sample of this many entities matching the filters (1-${SAMPLE_MAX}). Single page only — pagination via \`cursor\` is not supported with sampling. Overrides \`per_page\`. Useful for unbiased exploration: spot-checking filter correctness, stratified review prompts, or generating exploration sets without bias toward most-cited.`),
+            .describe(`Return a random sample of this many entities matching the filters (1-${SAMPLE_MAX}). Single page only — neither \`cursor\` nor \`page\` pagination applies to sampling, and a search that passes either alongside it is rejected. Keyword and exact modes only: OpenAlex does not sample a semantic search, so \`sample\` with search_mode "semantic" is rejected. Cannot be combined with \`sort\` — a sample has no order, and a search passing both is rejected. Overrides \`per_page\`. Useful for unbiased exploration: spot-checking filter correctness, stratified review prompts, or generating exploration sets without bias toward most-cited.`),
         seed: z
             .string()
             .optional()
@@ -236,8 +286,12 @@ export const searchEntitiesTool = tool('openalex_search_entities', {
     output: z.object({
         meta: z
             .object({
-            count: z.number().describe('Total results matching the query/filters.'),
-            per_page: z.number().describe('Results on this page.'),
+            count: z
+                .number()
+                .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.'),
             next_cursor: z
                 .string()
                 .nullable()
@@ -255,7 +309,7 @@ export const searchEntitiesTool = tool('openalex_search_entities', {
         })
             .passthrough()
             .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 passed through unchanged. 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 — and an abstract arrives reconstructed as `abstract`. Additional fields depend on entity_type and select.'),
     }),
     // Agent-facing context for the success path — the query/filters as parsed, the
     // total match count, and recovery guidance for empty results. Populated via
@@ -268,7 +322,7 @@ export const searchEntitiesTool = tool('openalex_search_entities', {
         notice: z
             .string()
             .optional()
-            .describe('Guidance notice. Set when results are empty (echoes the criteria and suggests how to broaden) or when an `id` lookup was passed search criteria it does not apply (names them). 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), and on every semantic search to disclose that `meta.count` is a candidate total rather than a match total. Absent otherwise.'),
         budget: z
             .object({
             costUsd: z
@@ -292,7 +346,76 @@ export const searchEntitiesTool = tool('openalex_search_entities', {
         budget: { render: renderBudgetTrailer },
     },
     async handler(input, ctx) {
-        assertListQueryConstraints(input, ctx);
+        /**
+         * Reject list-query parameter combinations OpenAlex cannot serve. Every check here
+         * constrains a *list* query. `id` takes the singleton path in `OpenAlexService.search()`,
+         * which reads only `entity_type`, `id`, and `select` — so search_mode, per_page, cursor,
+         * page, sample, and seed are unread there, and rejecting an ID lookup over how they relate
+         * to each other fails it on constraints it never met. The dropped-parameter notice below
+         * reports them instead. The `id` predicate mirrors the service's own truthiness branch.
+         */
+        if (!input.id) {
+            // Semantic search matches an embedding of the query text, so with no query there is
+            // 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 });
+            }
+            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,
+                });
+            }
+            // 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,
+                });
+            }
+            // 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,
+                });
+            }
+            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 });
+            }
+            // 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 });
+            }
+            // 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,
+                });
+            }
+            // 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 });
+            }
+            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 });
+            }
+        }
         const service = getOpenAlexService();
         const result = await service.search({
             entityType: input.entity_type,
@@ -304,6 +427,7 @@ export const searchEntitiesTool = tool('openalex_search_entities', {
             select: input.select,
             perPage: input.per_page,
             cursor: input.cursor,
+            page: input.page,
             sample: input.sample,
             seed: input.seed,
         }, ctx);
@@ -316,17 +440,28 @@ export const searchEntitiesTool = tool('openalex_search_entities', {
         });
         const echo = buildSearchEcho(input);
         ctx.enrich({ echo, totalCount: result.meta.count });
+        const notices = [];
         // An `id` lookup always returns its one record or throws, so it never reaches the
         // empty-results notice — the two branches are exclusive, and the dropped-parameter
         // warning is the more useful of the two on that path.
         const ignored = input.id ? searchOnlyParams(input).map((part) => part.name) : [];
         if (ignored.length > 0) {
             const [verb, pronoun] = ignored.length === 1 ? ['was', 'it'] : ['were', 'them'];
-            ctx.enrich.notice(`\`id\` takes precedence — ${ignored.join(', ')} ${verb} not applied, and the record below is the entity at that ID regardless of ${pronoun}. Drop \`id\` to run ${pronoun} as a search.`);
+            notices.push(`\`id\` takes precedence — ${ignored.join(', ')} ${verb} not applied, and the record below is the entity at that ID regardless of ${pronoun}. Drop \`id\` to run ${pronoun} as a search.`);
         }
         else if (result.results.length === 0) {
-            ctx.enrich.notice(`No matches for ${echo}. Try broadening the query, removing filters, or switching search_mode.`);
+            notices.push(isContinuationPage(input)
+                ? `Pagination exhausted for ${echo} — the previous page was the last, so this one came back empty. Stop paging rather than broadening the search.`
+                : `No matches for ${echo}. Try broadening the query, removing filters, or switching search_mode.`);
+        }
+        // `meta.count` reports the ranked candidate set under semantic search, not the population
+        // matching the query. Its size is query-dependent (OpenAlex serves 70 for some queries,
+        // 50 for others), so the notice states the count it got rather than a fixed ceiling.
+        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,

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

@@ -1 +1 @@
-{"version":3,"file":"search-entities.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/search-entities.tool.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"search-entities.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/search-entities.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/escape-markdown.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @fileoverview Markdown escaping for provider text at the `content[]` boundary. Every `format()`
+ * that interpolates OpenAlex text routes it through `escapeMarkdown`, so the surfaces cannot
+ * drift. Escapes use backslashes, never HTML entities, and cover only what a CommonMark + GFM
+ * renderer would read as structure; a URL that GFM links cleanly renders byte-identical, as the
+ * autolink it is. `structuredContent` never passes through here — it carries the plain text.
+ * @module mcp-server/tools/escape-markdown
+ */
+/**
+ * Where the text lands. `inline` is mid-line (after a label, inside bold, in a list item);
+ * `line-start` begins a line, where block syntax (`#`, `- `, `1. `, `>`, `[label]:`) applies;
+ * `heading` follows `### `, where a trailing `#` run would close the heading.
+ */
+export type MarkdownPosition = 'inline' | 'line-start' | 'heading';
+/**
+ * Escape provider text for Markdown so a renderer shows exactly the characters it holds.
+ *
+ * Escaped everywhere: `*`, backticks, `~` (GFM strikethrough), `<` before a letter, `/`, `!`, or
+ * `?`, `_` unless it sits between two letters or digits, `&` when it starts a character reference
+ * a renderer would decode, a backslash before punctuation or at the end, a `<` that opens an
+ * email autolink, and any `[` ahead of a `](` pair (a link needs it to open its label) or never
+ * closed. Closed citation brackets with no `](` after them stay as they are. At a line start,
+ * also the block markers; in a heading, a trailing `#` run. Line breaks and tabs collapse to a
+ * space.
+ *
+ * A span GFM links as an autolink literal passes through untouched. When it cannot — trailing
+ * punctuation that needs an escape would join the link, an open `[` or an email literal holds
+ * it, or GFM would not link it at all — the `:` or `.` of its prefix is escaped instead, which
+ * reads the same but links nothing in any renderer, and the span is escaped like any other text.
+ */
+export declare function escapeMarkdown(text: string, position?: MarkdownPosition): string;
+//# sourceMappingURL=escape-markdown.d.ts.map

package/dist/mcp-server/tools/escape-markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape-markdown.d.ts","sourceRoot":"","sources":["../../../src/mcp-server/tools/escape-markdown.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,YAAY,GAAG,SAAS,CAAC;AAoQnE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,GAAE,gBAA2B,GAAG,MAAM,CA4F1F"}