@cyanheads/openalex-mcp-server 0.7.14 → 0.7.16

package/AGENTS.md

@@ -1,8 +1,8 @@
 # Developer Protocol
 
 **Server:** openalex-mcp-server
-**Version:** 0.7.14
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.5`
+**Version:** 0.7.16
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.6`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/server` ^2.0.0
 **Zod:** ^4.6.5
@@ -168,7 +168,7 @@ Handlers receive a unified `ctx` object. Key properties:
 
 Handlers throw — the framework catches, classifies, and formats.
 
-**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` to receive a typed `ctx.fail(reason, …)` keyed by the declared reason union — `ctx.fail('typo')` is a TS error, `data.reason` is auto-populated, and the linter enforces conformance against the handler. The `recovery` field is required (≥5 words). Spread `ctx.recoveryFor('reason')` into `data` to opt the contract recovery onto the wire.
+**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, thrownBy? }]` on `tool()` to receive a typed `ctx.fail(reason, …)` keyed by the declared reason union — `ctx.fail('typo')` is a TS error, `data.reason` is auto-populated, and the linter enforces conformance against the handler. The `recovery` field is required (≥5 words). Spread `ctx.recoveryFor('reason')` into `data` to opt the contract recovery onto the wire; `error-contract-recovery-unforwarded` warns per `ctx.fail` site that forwards neither the resolver nor its own `recovery` key.
 
 ```ts
 import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
@@ -177,6 +177,10 @@ errors: [
   { reason: 'semantic_per_page_cap', code: JsonRpcErrorCode.ValidationError,
     when: 'per_page exceeds the semantic-search cap',
     recovery: 'Reduce per_page to 50 or less, or switch search_mode to keyword.' },
+  { reason: 'upstream_timeout', code: JsonRpcErrorCode.Timeout,
+    when: 'OpenAlex did not respond within the request deadline',
+    recovery: 'Retry after a short delay, or narrow the request with tighter filters.',
+    thrownBy: 'service' },
 ],
 async handler(input, ctx) {
   if (overCap) throw ctx.fail('semantic_per_page_cap', message, { ...ctx.recoveryFor('semantic_per_page_cap') });
@@ -185,7 +189,7 @@ async handler(input, ctx) {
 
 **Declare contracts inline on each tool, even when similar across tools.** The contract is part of the tool's documented public surface — reading one tool definition file should give the full picture. Don't extract a shared `errors[]` constant; per-tool repetition is the intended cost of locality.
 
-The OpenAlex service throws factory errors (`notFound`, `rateLimited`, etc.) based on upstream status codes, carrying the contract `reason` on `data.reason` and the recovery via `ctx.recoveryFor(reason)`; those bubble through and are auto-classified. Because most declared reasons are produced in the service, handler-local precondition throws (`semantic_per_page_cap`, `reserved_filter_key`, …) live in module-level helpers (`assertListQueryConstraints`, `assertNoReservedFilterKey`, `resolveSeedToWorkId`) rather than inline: `error-contract-unthrown` only scans handlers holding a literal `ctx.fail(`, and an inline one would flag every service-produced reason as dead. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely without needing to be declared on a contract.
+The OpenAlex service throws factory errors (`notFound`, `rateLimited`, etc.) based on upstream status codes, carrying the contract `reason` on `data.reason` and the recovery via `ctx.recoveryFor(reason)`; those bubble through and are auto-classified. Every such entry carries `thrownBy: 'service'` — lint-only metadata that tells `error-contract-unthrown`, whose scan reads the handler body alone, to skip a reason produced a layer below it. Handler-local precondition throws stay inline and unmarked so the rule keeps checking them: `semantic_without_query`, `semantic_per_page_cap`, `semantic_with_cursor`, `page_without_semantic`, `sample_with_cursor`, `sample_with_page`, `sample_with_semantic`, `sample_with_sort`, and `seed_without_sample` on `openalex_search_entities`; `reserved_filter_key` and the seed-lookup `entity_not_found` on `openalex_get_citation_graph`. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely without needing to be declared on a contract.
 
 **Fallback for ad-hoc throws:** error factories or plain `Error`.
 

package/CLAUDE.md

@@ -1,8 +1,8 @@
 # Developer Protocol
 
 **Server:** openalex-mcp-server
-**Version:** 0.7.14
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.5`
+**Version:** 0.7.16
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.6`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/server` ^2.0.0
 **Zod:** ^4.6.5
@@ -168,7 +168,7 @@ Handlers receive a unified `ctx` object. Key properties:
 
 Handlers throw — the framework catches, classifies, and formats.
 
-**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` to receive a typed `ctx.fail(reason, …)` keyed by the declared reason union — `ctx.fail('typo')` is a TS error, `data.reason` is auto-populated, and the linter enforces conformance against the handler. The `recovery` field is required (≥5 words). Spread `ctx.recoveryFor('reason')` into `data` to opt the contract recovery onto the wire.
+**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, thrownBy? }]` on `tool()` to receive a typed `ctx.fail(reason, …)` keyed by the declared reason union — `ctx.fail('typo')` is a TS error, `data.reason` is auto-populated, and the linter enforces conformance against the handler. The `recovery` field is required (≥5 words). Spread `ctx.recoveryFor('reason')` into `data` to opt the contract recovery onto the wire; `error-contract-recovery-unforwarded` warns per `ctx.fail` site that forwards neither the resolver nor its own `recovery` key.
 
 ```ts
 import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
@@ -177,6 +177,10 @@ errors: [
   { reason: 'semantic_per_page_cap', code: JsonRpcErrorCode.ValidationError,
     when: 'per_page exceeds the semantic-search cap',
     recovery: 'Reduce per_page to 50 or less, or switch search_mode to keyword.' },
+  { reason: 'upstream_timeout', code: JsonRpcErrorCode.Timeout,
+    when: 'OpenAlex did not respond within the request deadline',
+    recovery: 'Retry after a short delay, or narrow the request with tighter filters.',
+    thrownBy: 'service' },
 ],
 async handler(input, ctx) {
   if (overCap) throw ctx.fail('semantic_per_page_cap', message, { ...ctx.recoveryFor('semantic_per_page_cap') });
@@ -185,7 +189,7 @@ async handler(input, ctx) {
 
 **Declare contracts inline on each tool, even when similar across tools.** The contract is part of the tool's documented public surface — reading one tool definition file should give the full picture. Don't extract a shared `errors[]` constant; per-tool repetition is the intended cost of locality.
 
-The OpenAlex service throws factory errors (`notFound`, `rateLimited`, etc.) based on upstream status codes, carrying the contract `reason` on `data.reason` and the recovery via `ctx.recoveryFor(reason)`; those bubble through and are auto-classified. Because most declared reasons are produced in the service, handler-local precondition throws (`semantic_per_page_cap`, `reserved_filter_key`, …) live in module-level helpers (`assertListQueryConstraints`, `assertNoReservedFilterKey`, `resolveSeedToWorkId`) rather than inline: `error-contract-unthrown` only scans handlers holding a literal `ctx.fail(`, and an inline one would flag every service-produced reason as dead. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely without needing to be declared on a contract.
+The OpenAlex service throws factory errors (`notFound`, `rateLimited`, etc.) based on upstream status codes, carrying the contract `reason` on `data.reason` and the recovery via `ctx.recoveryFor(reason)`; those bubble through and are auto-classified. Every such entry carries `thrownBy: 'service'` — lint-only metadata that tells `error-contract-unthrown`, whose scan reads the handler body alone, to skip a reason produced a layer below it. Handler-local precondition throws stay inline and unmarked so the rule keeps checking them: `semantic_without_query`, `semantic_per_page_cap`, `semantic_with_cursor`, `page_without_semantic`, `sample_with_cursor`, `sample_with_page`, `sample_with_semantic`, `sample_with_sort`, and `seed_without_sample` on `openalex_search_entities`; `reserved_filter_key` and the seed-lookup `entity_not_found` on `openalex_get_citation_graph`. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely without needing to be declared on a contract.
 
 **Fallback for ad-hoc throws:** error factories or plain `Error`.
 

package/README.md

@@ -7,7 +7,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.7.14-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/openalex-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/openalex-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/openalex-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-0.7.16-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/openalex-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/openalex-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/openalex-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -52,11 +52,12 @@ Scholarly catalog data from [OpenAlex](https://openalex.org) — 270M+ works, 90
 
 ### `openalex_search_entities` <sub>tool</sub>
 
-- Retrieve a single entity by ID — OpenAlex ID, DOI, ORCID, ROR, PMID, ISSN, or PMCID (bare or URL form). `id` takes precedence: search parameters passed alongside it are dropped, and the response names which ones. A PMCID resolves nothing (OpenAlex indexes none) — use the work's PMID or DOI instead
-- Keyword search (boolean operators, quoted phrases, wildcards, fuzzy match) plus `exact` and `semantic` search modes — semantic caps at 50 results per page and ~1 req/sec
+- Retrieve a single entity by ID — OpenAlex ID, DOI, ORCID, ROR, PMID, ISSN, or PMCID (bare or URL form), or a keyword by its slug or keyword URL. `id` takes precedence: search parameters passed alongside it are dropped, and the response names which ones. A PMCID resolves nothing (OpenAlex indexes none) — use the work's PMID or DOI instead
+- Keyword search (boolean operators, quoted phrases, wildcards, fuzzy match) plus `exact` and `semantic` search modes — semantic ranks a query-dependent candidate set at ~1 req/sec (up to 50 per page), and its `meta.count` reports the candidate count rather than a match total
 - Rich filter syntax: AND across fields, OR within a field (`|`), NOT (`!`), ranges, comparisons; a comma inside a filter value is rejected (use `|`, or a `.search` filter for free text)
 - `select` returns a curated per-entity-type default unless overridden, or `["*"]` for the full record; invalid field names error with the valid set
-- Cursor pagination, up to 100 results per page (default 25); `sample` (up to 100, single page only, no `cursor`) plus a deterministic `seed` for reproducible random sampling
+- Cursor pagination for keyword and exact search, up to 100 results per page (default 25); semantic search walks its candidates with `page` (1-based) instead, and mixing either knob with the wrong `search_mode` is rejected before the upstream call
+- `sample` (up to 100, single page only — neither `cursor` nor `page` applies) plus a deterministic `seed` for reproducible random sampling; keyword and exact modes only, and never alongside `sort` — OpenAlex does not sample a semantic search and refuses a sorted sample, so both combinations are rejected before the upstream call
 - `display_name` is nullable for untitled records; every call reports OpenAlex daily-budget cost and remaining balance
 
 ---
@@ -65,8 +66,8 @@ Scholarly catalog data from [OpenAlex](https://openalex.org) — 270M+ works, 90
 
 - Group any supported field for trend, distribution, or comparative analysis; combine with `filters` to scope the population before aggregation
 - Up to 200 groups per page (default). `order: "count"` (default) returns the top-N by count with no further pages; `order: "key"` enumerates all distinct values key-ascending with cursor pagination
-- `include_unknown` (default `false`) adds a group for entities with no value for the grouped field
-- Not every field is groupable — raw date fields, `.search` operators, and `from_*`/`to_*` range modifiers are rejected; check with `openalex_describe_fields(entity_type, "group_by")`
+- `include_unknown` (default `false`) adds a group for entities with no value for the grouped field, flagged `is_unknown: true` and labeled as unknown in the text output. OpenAlex keys it `-111`/`-111.0` (numeric fields), `unknown` (text fields and `order: "key"`), or an ID ending in `/unknown`; the key is a sentinel, not a filter value. Boolean fields have no such group — a missing value counts as `false`
+- Not every field is groupable — raw date fields, `.search` operators, `from_*`/`to_*` range modifiers, decimal scores such as `fwci`, `display_name`, and external-ID fields such as `doi` are rejected; `openalex_describe_fields(entity_type, "group_by")` lists the fields that group
 - Reports OpenAlex daily-budget cost and remaining balance — aggregation is priced far below paging the same entities
 
 ---
@@ -74,8 +75,9 @@ Scholarly catalog data from [OpenAlex](https://openalex.org) — 270M+ works, 90
 ### `openalex_resolve_name` <sub>tool</sub>
 
 - A name or partial name runs an autocomplete search: up to 10 matches with disambiguation hints (last institution, host organization, place, etc.)
-- An identifier — OpenAlex ID, DOI, ORCID, ROR, PMID, or ISSN, bare or in URL form — resolves directly to the one record it addresses; no `entity_type` needed, since the identifier determines its own. A PMCID is recognized but resolves nothing — OpenAlex indexes none
+- An identifier — OpenAlex ID, DOI, ORCID, ROR, PMID, ISSN, or keyword URL, bare or in URL form — resolves directly to the one record it addresses; no `entity_type` needed, since the identifier determines its own. A PMCID is recognized but resolves nothing — OpenAlex indexes none
 - `filters` narrows autocomplete only; on an identifier lookup they're ignored and named in a notice
+- With `entity_type` set, OpenAlex autocomplete fails on a name over 1,000 characters; that failure is reported once as `query_too_long` with advice to shorten the name, not retried as an outage
 - Reports OpenAlex daily-budget cost and remaining balance
 
 ---
@@ -84,7 +86,7 @@ Scholarly catalog data from [OpenAlex](https://openalex.org) — 270M+ works, 90
 
 - `direction` sets the edge: `cites` (works citing the seed), `cited_by` (the seed's own reference list), `related_to` (OpenAlex's algorithmic related works, ~8-30 typical, may be empty)
 - `seed_id` accepts an OpenAlex ID, DOI, or PMID (PMCID recognized but resolves nothing); validated against a live lookup first, so a non-existent seed fails as `NotFound` rather than returning an empty graph
-- Stacks with `filters`/`sort`/`select` to narrow the graph; `filters` cannot set `cites`/`cited_by`/`related_to` directly — those are reserved for `direction`
+- Stacks with `filters`/`sort`/`select` to narrow the graph; `filters` cannot set `cites`/`cited_by`/`related_to`, nor an alias of one such as `cited_works` — those keys are reserved for `direction`
 - Cursor pagination, up to 100 results per page (default 25)
 - Reports OpenAlex daily-budget cost, covering both the seed-validation lookup and the graph page, plus remaining balance
 
@@ -93,7 +95,7 @@ Scholarly catalog data from [OpenAlex](https://openalex.org) — 270M+ works, 90
 ### `openalex_describe_fields` <sub>tool</sub>
 
 - Lists every valid field name for an entity type + context (`filter`, `group_by`, `select`) — the complete pool, never truncated
-- `group_by` is the filter set minus raw date fields, `.search`/`.search.exact` operators, and `from_*`/`to_*` range modifiers, which OpenAlex rejects as aggregation keys
+- `group_by` is the filter set minus what OpenAlex rejects as an aggregation key: raw date fields, `.search`/`.search.exact` operators, `from_*`/`to_*` range modifiers, and a per-entity-type set found by grouping every listed field against the live API — decimal scores such as `fwci`, several source year fields, `display_name`, and external-ID fields among them
 - Optional `query` reorders results by name similarity without dropping any field — a nested value's parent object stays reachable further down the list
 - Backed by a generated field catalog — no live API calls
 
@@ -130,6 +132,7 @@ Agent-friendly output:
 - Effective-query echo — search, trends, and citation-graph responses echo the criteria that actually ran, so an empty result is diagnosable without re-reading the request
 - Discriminated output contracts — typed error reasons (`entity_not_found`, `upstream_budget_exhausted`, `semantic_per_page_cap`, `reserved_filter_key`, and more) each carrying an explicit recovery hint
 - Response shaping — abstracts are reconstructed from OpenAlex's inverted-index encoding into plaintext, and `display_name` stays `null` for untitled or paratext records instead of being backfilled
+- Clean provider text — OpenAlex passes titles, abstracts, and names through unsanitized; HTML entities are decoded against the full WHATWG table, comments and HTML/JATS/MathML formatting tags are removed, and literal text such as `A < B` is kept. The text output escapes that text for Markdown, so a stray `*`, `<tag>`, or `[x](y)` renders as written; IDs, and URLs that render as links, stay byte-identical
 
 ## Getting started
 

package/changelog/0.7.x/0.7.15.md

@@ -0,0 +1,33 @@
+---
+summary: "Keyword identifiers, semantic-mode `page` pagination, AND'd filter aliases, and honest pagination/notice handling across the paginating tools."
+breaking: false
+security: false
+---
+
+# 0.7.15 — 2026-09-22
+
+## Added
+
+- **Keyword identifiers** resolve via their OpenAlex URL or bare slug (`https://openalex.org/keywords/groundwater` or `groundwater`) — keywords never had a native alphanumeric ID, so the removed `K`-prefixed routing arm 404'd. ([#68](https://github.com/cyanheads/openalex-mcp-server/issues/68))
+- **`page`** input on `openalex_search_entities` paginates semantic search (1-based), the one mode OpenAlex rejects `cursor` on. Combining `page`/`cursor`/`sample` with the wrong mode now throws `semantic_with_cursor`, `page_without_semantic`, or `sample_with_page`. ([#71](https://github.com/cyanheads/openalex-mcp-server/issues/71))
+- **`best_oa_location`** joins the default `works` projection, naming a green-OA work's readable copy (`pdf_url`, `license`, `version`, hosting source) instead of leaving only the closed publisher location. ([#79](https://github.com/cyanheads/openalex-mcp-server/issues/79))
+- **`query_too_long`** error reason on `openalex_search_entities` — an over-length `query` (HTTP 400) now maps to its own contract entry instead of the generic invalid-params one. ([#71](https://github.com/cyanheads/openalex-mcp-server/issues/71))
+
+## Changed
+
+- **Filter aliases** resolving to the same upstream key are now AND'd instead of silently overwriting — `{year: "2020", publication_year: "2024"}` now matches works in both years, matching OpenAlex's own repeated-key behavior. ([#70](https://github.com/cyanheads/openalex-mcp-server/issues/70))
+- **`openalex_get_citation_graph`'s reserved-key guard** now checks the *translated* filter key, so an alias of `cites`/`cited_by`/`related_to` (e.g. `cited_works`) is caught instead of colliding silently with `direction`. ([#70](https://github.com/cyanheads/openalex-mcp-server/issues/70))
+- **Pagination-exhausted notices** — `openalex_search_entities`, `openalex_analyze_trends`, and `openalex_get_citation_graph` now report the traversal as finished on an empty page reached via `cursor`, instead of advising a broader query. ([#74](https://github.com/cyanheads/openalex-mcp-server/issues/74))
+- **`meta.per_page`** on `openalex_search_entities` and `openalex_get_citation_graph` now documents itself as the requested page size, not the record count returned. ([#74](https://github.com/cyanheads/openalex-mcp-server/issues/74))
+- **`meta.count`** under `search_mode: "semantic"` is disclosed as the capped candidate ceiling (≤50), not an exhaustive match total. ([#71](https://github.com/cyanheads/openalex-mcp-server/issues/71))
+
+## Fixed
+
+- **Blank `id`/`query`/`cursor`/`group_by` inputs** on the paginating tools are now rejected at the schema, instead of running as an unfiltered listing or an accepted "exhausted" page. ([#69](https://github.com/cyanheads/openalex-mcp-server/issues/69), [#80](https://github.com/cyanheads/openalex-mcp-server/issues/80))
+- **`openalex_analyze_trends`** no longer reports a successful empty aggregation when OpenAlex answers with its plain list shape (no `group_by` key) — it now throws `upstream_missing_group_by`. ([#69](https://github.com/cyanheads/openalex-mcp-server/issues/69))
+- **`openalex_literature_review`** prompt's step 3 now re-runs the step-2 filtered search sorted by `-cited_by_count` instead of an unfiltered search, and names the fields to `select` on the detail lookup. ([#77](https://github.com/cyanheads/openalex-mcp-server/issues/77))
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` ^0.13.5 → ^0.13.6
+- `@types/node` ^26.6.1 → ^26.6.2

package/changelog/0.7.x/0.7.16.md

@@ -0,0 +1,32 @@
+---
+summary: "Provider text arrives clean on both surfaces (entities decoded, markup removed, Markdown escaped in content[]), plus a flagged unknown group_by bucket, local rejection of sample with semantic search or sort, and corrected group_by field lists and error reasons."
+breaking: false
+security: false
+---
+
+# 0.7.16 — 2026-09-24
+
+## Added
+
+- **`is_unknown`** on `openalex_analyze_trends` groups — set on the missing-value bucket `include_unknown` adds (keyed `-111`, `-111.0`, `unknown`, or an ID ending in `/unknown`). The text output labels it `unknown (no value; key …)` and renders it after the last year of a time series. ([#75](https://github.com/cyanheads/openalex-mcp-server/issues/75))
+- **`sample_with_semantic`** and **`sample_with_sort`** error reasons on `openalex_search_entities` — `sample` with `search_mode: "semantic"` (which OpenAlex does not sample) or with any `sort` (which OpenAlex refuses) is rejected before the upstream call. `id` lookups still drop both with a notice. ([#83](https://github.com/cyanheads/openalex-mcp-server/issues/83), [#85](https://github.com/cyanheads/openalex-mcp-server/issues/85))
+
+## Changed
+
+- **Provider text in `structuredContent`** — string values now carry decoded HTML entities (full WHATWG table) with HTML comments removed and HTML/JATS/MathML formatting tags unwrapped; literal text such as `A < B` or `Fish <Actinopterygii>` is kept. Affected records return different values than before. ([#76](https://github.com/cyanheads/openalex-mcp-server/issues/76))
+- **`content[]` escaping** — every `format()` backslash-escapes provider text for Markdown, so a stray `*`, `<tag>`, or `[x](y)` renders as written; IDs and URLs that render as links stay byte-identical. ([#76](https://github.com/cyanheads/openalex-mcp-server/issues/76))
+- **`openalex_analyze_trends` group `key`** is passed through raw, exactly as OpenAlex returns it (it was entity-decoded before); `key_display_name` gets the provider-text normalization. ([#76](https://github.com/cyanheads/openalex-mcp-server/issues/76))
+
+## Fixed
+
+- **Named-entity decoding** no longer resolves `Object.prototype` names — `&constructor;` stays literal instead of becoming `function Object() { [native code] }`. ([#76](https://github.com/cyanheads/openalex-mcp-server/issues/76))
+- **`openalex_describe_fields` `group_by` view** drops the fields OpenAlex refuses to aggregate — decimal scores such as `fwci`, several source year fields, `display_name`, external-ID fields, and the concept keys on authors — and five works fields whose grouping fails with an HTTP 500 on every attempt (`cites`, `has_embeddings`, and the three `raw_type` location fields), per a live sweep of every listed field on all eight entity types; they stay valid filters. ([#86](https://github.com/cyanheads/openalex-mcp-server/issues/86))
+- **`group_by` rejections** on authors' concept keys (reported upstream as an invalid ID) and on `referenced_works` now surface as `upstream_ungroupable_group_by`, whose recovery points at `openalex_describe_fields`; an invalid-ID 400 quoting a value from the request's `filter` keeps `upstream_invalid_id_value`. ([#87](https://github.com/cyanheads/openalex-mcp-server/issues/87))
+- **`openalex_resolve_name`** reports the HTTP 500 that typed autocomplete returns for a `query` over 1,000 code points as `query_too_long` after one attempt, instead of a retried `upstream_unavailable` outage. ([#81](https://github.com/cyanheads/openalex-mcp-server/issues/81))
+- **Semantic `meta.count`** — descriptions and the runtime notice no longer claim a 50-candidate ceiling; the candidate count is query-dependent and can exceed 50 (the 50-per-page cap stands). ([#84](https://github.com/cyanheads/openalex-mcp-server/issues/84))
+
+## Dependencies
+
+- `mdast-util-from-markdown` ^2.0.3 (new devDependency)
+- `mdast-util-gfm` ^3.1.0 (new devDependency)
+- `micromark-extension-gfm` ^3.0.0 (new devDependency)

package/dist/mcp-server/prompts/definitions/literature-review.prompt.js

@@ -41,7 +41,7 @@ Follow this workflow using the OpenAlex tools:
    - Search with multiple related topic IDs to capture adjacent areas`}
    Use select to keep payloads manageable.
 
-3. **Identify key papers** — Sort by cited_by_count to find landmark works. Use openalex_search_entities with id to get full details on the most important ones.
+3. **Identify key papers** — Re-run the step 2 search with sort: "-cited_by_count" to surface landmark works, keeping the topical filters in place: an explicit sort replaces relevance ranking, so without them you get the most-cited works in the catalog rather than in "${args.topic}". Then call openalex_search_entities with id and a select naming the fields you need (e.g. ["abstract", "authorships", "primary_location"]) for the most important ones — an id lookup on its own returns the curated default projection.
 
 4. **Trace citations** — For each key paper, use openalex_get_citation_graph with direction "cites" to find subsequent work that cites it, and direction "cited_by" to find foundational work it references.
 

package/dist/mcp-server/prompts/definitions/literature-review.prompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"literature-review.prompt.js","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/literature-review.prompt.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAEnD,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC,4BAA4B,EAAE;IACzE,WAAW,EACT,wHAAwH;IAC1H,SAAS,EACP,2HAA2H;IAC7H,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;QACb,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,QAAQ,CACP,+FAA+F,CAChG;QACH,KAAK,EAAE,CAAC;aACL,IAAI,CAAC,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;aACzB,QAAQ,EAAE;aACV,QAAQ,CACP,wGAAwG,CACzG;KACJ,CAAC;IACF,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE;QACjB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,QAAQ,CAAC;QACrC,OAAO;YACL;gBACE,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE;oBACP,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,+CAA+C,IAAI,CAAC,KAAK;;SAEhE,KAAK;;;;mHAIqG,IAAI,CAAC,KAAK;;iFAGjH,KAAK,KAAK,QAAQ;wBAChB,CAAC,CAAC;;;qCAGqB;wBACvB,CAAC,CAAC;;;sEAIN;;;;;;;;;;;;+IAYqI;iBACtI;aACF;SACF,CAAC;IACJ,CAAC;CACF,CAAC,CAAC"}
+{"version":3,"file":"literature-review.prompt.js","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/literature-review.prompt.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAEnD,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC,4BAA4B,EAAE;IACzE,WAAW,EACT,wHAAwH;IAC1H,SAAS,EACP,2HAA2H;IAC7H,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;QACb,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,QAAQ,CACP,+FAA+F,CAChG;QACH,KAAK,EAAE,CAAC;aACL,IAAI,CAAC,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;aACzB,QAAQ,EAAE;aACV,QAAQ,CACP,wGAAwG,CACzG;KACJ,CAAC;IACF,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE;QACjB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,QAAQ,CAAC;QACrC,OAAO;YACL;gBACE,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE;oBACP,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,+CAA+C,IAAI,CAAC,KAAK;;SAEhE,KAAK;;;;mHAIqG,IAAI,CAAC,KAAK;;iFAGjH,KAAK,KAAK,QAAQ;wBAChB,CAAC,CAAC;;;qCAGqB;wBACvB,CAAC,CAAC;;;sEAIN;;;+QAGqQ,IAAI,CAAC,KAAK;;;;;;;;;+IAS1I;iBACtI;aACF;SACF,CAAC;IACJ,CAAC;CACF,CAAC,CAAC"}

package/dist/mcp-server/tools/definitions/analyze-trends.tool.d.ts

@@ -34,6 +34,7 @@ export declare const analyzeTrendsTool: import("@cyanheads/mcp-ts-core").ToolDef
         key: z.ZodString;
         key_display_name: z.ZodString;
         count: z.ZodNumber;
+        is_unknown: z.ZodOptional<z.ZodLiteral<true>>;
     }, z.core.$strip>>;
 }, z.core.$strip>, readonly [{
     readonly reason: "rate_limited";
@@ -41,64 +42,83 @@ export declare const analyzeTrendsTool: import("@cyanheads/mcp-ts-core").ToolDef
     readonly when: "OpenAlex throttled the request for exceeding its per-second ceiling (HTTP 429).";
     readonly retryable: true;
     readonly recovery: "Wait several seconds and retry; consider lowering request frequency for this caller.";
+    readonly thrownBy: "service";
 }, {
     readonly reason: "upstream_budget_exhausted";
     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 thrownBy: "service";
 }, {
     readonly reason: "upstream_timeout";
     readonly code: JsonRpcErrorCode.Timeout;
     readonly when: "OpenAlex did not respond within the request deadline.";
     readonly retryable: true;
     readonly recovery: "Retry after a short delay; if timeouts persist, narrow the request with tighter filters to reduce upstream load.";
+    readonly thrownBy: "service";
 }, {
     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 retryable: true;
     readonly recovery: "Wait and retry; check https://openalex.org for service status if the outage persists.";
+    readonly thrownBy: "service";
 }, {
     readonly reason: "upstream_unauthorized";
     readonly code: JsonRpcErrorCode.Unauthorized;
     readonly when: "OpenAlex rejected the API key (HTTP 401).";
     readonly recovery: "Check that OPENALEX_API_KEY is set to a valid OpenAlex account API key (free from https://openalex.org/settings/api).";
+    readonly thrownBy: "service";
 }, {
     readonly reason: "upstream_forbidden";
     readonly code: JsonRpcErrorCode.Forbidden;
     readonly when: "OpenAlex denied access to the requested resource (HTTP 403).";
     readonly recovery: "Confirm the API key has access to this entity type or endpoint, then retry the request.";
+    readonly thrownBy: "service";
 }, {
     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 thrownBy: "service";
 }, {
     readonly reason: "upstream_invalid_params";
     readonly code: JsonRpcErrorCode.InvalidParams;
     readonly when: "OpenAlex rejected an invalid group_by or filter field name (HTTP 400).";
     readonly recovery: "The upstream message names the rejected key and suggests close matches. Use openalex_describe_fields(entity_type, \"group_by\") to browse valid group_by fields, or openalex_describe_fields(entity_type, \"filter\") for filter fields.";
+    readonly thrownBy: "service";
 }, {
     readonly reason: "upstream_invalid_id_value";
     readonly code: JsonRpcErrorCode.InvalidParams;
     readonly when: "An entity-ID filter received a value that is not an OpenAlex ID — usually a name (HTTP 400).";
     readonly 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 and primary_topic.id accept IDs only.";
+    readonly thrownBy: "service";
 }, {
     readonly reason: "upstream_ungroupable_group_by";
     readonly code: JsonRpcErrorCode.InvalidParams;
-    readonly when: "group_by targets a raw date, float, or *.search field OpenAlex cannot aggregate (HTTP 400).";
-    readonly recovery: "Group by a categorical or year field (e.g. publication_year, type, oa_status, or an integer count field) — raw date fields and *.search operators cannot be grouped. Call openalex_describe_fields(entity_type, \"group_by\") for the groupable set.";
+    readonly when: "group_by targets a field OpenAlex cannot aggregate — a raw date, a decimal score, a *.search operator, a field such as display_name, doi, or referenced_works, or a concept key on authors, which OpenAlex reports as an invalid OpenAlex ID (HTTP 400).";
+    readonly recovery: "Group by a field OpenAlex can aggregate, such as publication_year, type, or oa_status — call openalex_describe_fields(entity_type, \"group_by\") for the full groupable set of this entity type.";
+    readonly thrownBy: "service";
 }, {
     readonly reason: "upstream_invalid_params_other";
     readonly code: JsonRpcErrorCode.InvalidParams;
     readonly when: "OpenAlex rejected the request (HTTP 400) for a reason other than an invalid field name.";
     readonly recovery: "Read the upstream message in the error above and adjust the request — check filter operators, value formats, and the group_by field.";
+    readonly thrownBy: "service";
 }, {
     readonly reason: "upstream_validation_failed";
     readonly code: JsonRpcErrorCode.ValidationError;
     readonly when: "OpenAlex rejected the request as semantically invalid (HTTP 422).";
     readonly recovery: "Read the upstream message for the specific field, then adjust the request to satisfy validation.";
+    readonly thrownBy: "service";
+}, {
+    readonly reason: "upstream_missing_group_by";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "OpenAlex answered with its plain list shape, carrying no aggregation for the requested group_by.";
+    readonly retryable: true;
+    readonly recovery: "Retry the request; if it repeats, confirm group_by names a field OpenAlex can aggregate with openalex_describe_fields(entity_type, \"group_by\").";
+    readonly thrownBy: "service";
 }], {
     readonly echo: z.ZodString;
     readonly totalCount: z.ZodNumber;

package/dist/mcp-server/tools/definitions/analyze-trends.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyze-trends.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/analyze-trends.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAKjE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+S5B,CAAC"}
+{"version":3,"file":"analyze-trends.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/analyze-trends.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAMjE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAwV5B,CAAC"}

package/dist/mcp-server/tools/definitions/analyze-trends.tool.js

@@ -4,6 +4,7 @@
  */
 import { tool, z } from '@cyanheads/mcp-ts-core';
 import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { escapeMarkdown } from '../escape-markdown.js';
 import { renderBudgetTrailer } from '../render-budget.js';
 import { getOpenAlexService } from '../../../services/openalex/openalex-service.js';
 import { ENTITY_TYPES } from '../../../services/openalex/types.js';
@@ -18,6 +19,7 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
             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',
@@ -25,6 +27,7 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
             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',
@@ -32,6 +35,7 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
             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',
@@ -39,54 +43,71 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
             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 group_by or filter field name (HTTP 400).',
             recovery: 'The upstream message names the rejected key and suggests close matches. Use openalex_describe_fields(entity_type, "group_by") to browse valid group_by fields, or openalex_describe_fields(entity_type, "filter") for filter fields.',
+            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 and primary_topic.id accept IDs only.',
+            thrownBy: 'service',
         },
         {
             reason: 'upstream_ungroupable_group_by',
             code: JsonRpcErrorCode.InvalidParams,
-            when: 'group_by targets a raw date, float, or *.search field OpenAlex cannot aggregate (HTTP 400).',
-            recovery: 'Group by a categorical or year field (e.g. publication_year, type, oa_status, or an integer count field) — raw date fields and *.search operators cannot be grouped. Call openalex_describe_fields(entity_type, "group_by") for the groupable set.',
+            when: 'group_by targets a field OpenAlex cannot aggregate — a raw date, a decimal score, a *.search operator, a field such as display_name, doi, or referenced_works, or a concept key on authors, which OpenAlex reports as an invalid OpenAlex ID (HTTP 400).',
+            recovery: 'Group by a field OpenAlex can aggregate, such as publication_year, type, or oa_status — call openalex_describe_fields(entity_type, "group_by") for the full groupable set of this entity type.',
+            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 the group_by field.',
+            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',
+        },
+        {
+            reason: 'upstream_missing_group_by',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            when: 'OpenAlex answered with its plain list shape, carrying no aggregation for the requested group_by.',
+            retryable: true,
+            recovery: 'Retry the request; if it repeats, confirm group_by names a field OpenAlex can aggregate with openalex_describe_fields(entity_type, "group_by").',
+            thrownBy: 'service',
         },
     ],
     inputAliases: { filter: 'filters' },
@@ -94,7 +115,8 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
         entity_type: z.enum(ENTITY_TYPES).describe('Entity type to aggregate.'),
         group_by: z
             .string()
-            .describe('Field to group by. Works examples: "publication_year", "type", "oa_status", "primary_topic.field.id", "authorships.institutions.country_code", "is_retracted". Authors: "last_known_institutions.country_code", "has_orcid". Sources: "type", "is_oa", "country_code". Not all fields support group_by — check entity docs if unsure.'),
+            .min(1)
+            .describe('Field to group by. Works examples: "publication_year", "type", "oa_status", "primary_topic.field.id", "authorships.institutions.country_code", "is_retracted". Authors: "last_known_institutions.country_code", "has_orcid". Sources: "type", "is_oa", "country_code". Not all fields support group_by — call openalex_describe_fields(entity_type, "group_by") for the groupable set.'),
         filters: z
             .record(z.string(), z.string())
             .optional()
@@ -102,7 +124,7 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
         include_unknown: z
             .boolean()
             .default(false)
-            .describe('Include a group for entities with no value for the grouped field. Hidden by default.'),
+            .describe('Add a group for entities with no value for the grouped field. Hidden by default. That group carries `is_unknown: true`; OpenAlex keys it -111 or -111.0 on numeric fields, "unknown" on text fields and under order "key", and an ID ending in /unknown on ID fields — a sentinel, not a measured value. The key is not a filter value: passing -111 as a filter matches a numeric range, not the entities with no value. Boolean fields have no separate group — a missing value counts as false.'),
         per_page: z
             .number()
             .int()
@@ -116,8 +138,9 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
             .describe('Sort order for groups. Omit or pass "count" (default) to return the top-N groups by count descending — no further pages. Pass "key" to enumerate all distinct values in key-ascending order with cursor pagination. Use "key" only when you need a full traversal; most analysis calls want "count".'),
         cursor: z
             .string()
+            .min(1)
             .optional()
-            .describe('Pagination cursor from a previous response. Only relevant when order is "key" — count-descending results have no next page. Pass the next_cursor from the previous response to advance.'),
+            .describe('Pagination cursor from a previous response. Only relevant when order is "key" — count-descending results have no next page. Pass the next_cursor from the previous response to advance. 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 the first page.'),
     }),
     output: z.object({
         meta: z
@@ -133,9 +156,17 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
         groups: z
             .array(z
             .object({
-            key: z.string().describe('Group key (OpenAlex ID or raw value).'),
-            key_display_name: z.string().describe('Human-readable group label.'),
+            key: z
+                .string()
+                .describe('Group key (OpenAlex ID or raw value), exactly as OpenAlex returns it.'),
+            key_display_name: z
+                .string()
+                .describe('Human-readable group label as plain text, with HTML entities decoded and markup removed.'),
             count: z.number().describe('Number of entities in this group.'),
+            is_unknown: z
+                .literal(true)
+                .optional()
+                .describe('Present only on the group include_unknown adds for entities with no value; its key is an OpenAlex sentinel (-111, -111.0, unknown, or an ID ending in /unknown), not a measured value.'),
         })
             .describe('A single aggregation group with its key, display label, and entity count.'))
             .describe('Aggregation groups with counts.'),
@@ -153,7 +184,7 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
         notice: z
             .string()
             .optional()
-            .describe('Guidance notice. Set when no groups are returned (recovery suggestions) or when the page is full and more groups likely exist (truncation signal with narrowing advice). Absent otherwise.'),
+            .describe('Guidance notice. Set when a first call returns no groups (recovery suggestions), when a `cursor` continuation returns none because the traversal is already finished, or when the page is full and more groups likely exist (truncation signal with narrowing advice). Absent otherwise.'),
         budget: z
             .object({
             costUsd: z
@@ -195,8 +226,14 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
         });
         const echo = buildAnalyzeEcho(input);
         ctx.enrich({ echo, totalCount: result.meta.count });
+        // An empty page on a `cursor` continuation means the key-ascending traversal already
+        // enumerated every group, so there is nothing left to remove or regroup. On a first call
+        // the same shape can still be an honest zero — including the all-values-unknown case,
+        // where `count` is nonzero but every matched entity is null for the grouped field.
         if (result.groups.length === 0) {
-            ctx.enrich.notice(`No groups returned for ${echo}. Try removing filters or grouping by a different field.`);
+            ctx.enrich.notice(input.cursor === undefined
+                ? `No groups returned for ${echo}. Try removing filters or grouping by a different field.`
+                : `Pagination exhausted for ${echo} — the previous page held the last group, so this one came back empty. Stop paging rather than removing filters or regrouping.`);
         }
         else if (input.order === 'key') {
             // Key-ascending traversal: omitted groups sit beyond the cursor, not in a count tail, so
@@ -234,15 +271,16 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
             ];
         }
         // Time-series groupings are returned upstream in count-desc — useful for "top N years"
-        // but jarring when reading a trend. Only the rendered text is reordered;
-        // structuredContent stays in upstream order for callers that want it.
-        const renderOrder = isTimeSeriesGrouping(result.groups)
-            ? [...result.groups].sort((a, b) => a.key.localeCompare(b.key))
+        // but jarring when reading a trend. Only the rendered text is reordered, with the
+        // unknown bucket after the last period; structuredContent stays in upstream order.
+        const known = result.groups.filter((g) => !g.is_unknown);
+        const renderOrder = isTimeSeriesGrouping(known)
+            ? [
+                ...known.sort((a, b) => a.key.localeCompare(b.key)),
+                ...result.groups.filter((g) => g.is_unknown),
+            ]
             : result.groups;
-        const lines = renderOrder.map((g) => {
-            const label = g.key === g.key_display_name ? g.key_display_name : `${g.key_display_name} (${g.key})`;
-            return `${label}: ${g.count}`;
-        });
+        const lines = renderOrder.map((g) => `${renderGroupLabel(g)}: ${g.count}`);
         const footer = result.meta.next_cursor
             ? `\n\n*More groups available — next_cursor: \`${result.meta.next_cursor}\`*`
             : '';
@@ -258,6 +296,22 @@ const YEAR_OR_DATE_PATTERN = /^\d{4}(-\d{2}-\d{2})?$/;
 function isTimeSeriesGrouping(groups) {
     return groups.length > 1 && groups.every((g) => YEAR_OR_DATE_PATTERN.test(g.key));
 }
+/**
+ * The label a group line opens with. The unknown bucket is named as such — its key is a
+ * sentinel, and `-111.0: 48777` reads as a measured value. A label that begins the line is
+ * escaped for that position; the key is upstream's own and stays byte-identical unless it
+ * carries Markdown syntax.
+ */
+function renderGroupLabel(g) {
+    const key = escapeMarkdown(g.key);
+    if (g.is_unknown) {
+        const redundant = g.key_display_name === g.key || g.key_display_name.toLowerCase() === 'unknown';
+        const label = redundant ? '' : `, label ${escapeMarkdown(g.key_display_name)}`;
+        return `unknown (no value; key ${key}${label})`;
+    }
+    const display = escapeMarkdown(g.key_display_name, 'line-start');
+    return g.key === g.key_display_name ? display : `${display} (${key})`;
+}
 function buildAnalyzeEcho(input) {
     const parts = [`entity_type=${input.entity_type}`, `group_by=${input.group_by}`];
     if (input.filters && Object.keys(input.filters).length > 0) {