---
summary: "openalex_describe_fields tool, ranked invalid-field suggestions, comma-safe filters"
breaking: false
security: false
---

# 0.6.21 — 2026-06-08

## Added

- **`openalex_describe_fields`** — new tool: lists valid `filter`, `group_by`, and `select` field names for any entity type. Accepts an optional `query` for similarity-ranked narrowing (token-set + Jaro-Winkler). Backed by a build-time-generated catalog (`src/services/openalex/field-catalog.json`) derived from OpenAlex's own field validation. ([#40](https://github.com/cyanheads/openalex-mcp-server/issues/40))
- **`field-ranker.ts`** — zero-dependency field ranking module: token-set overlap blended with Jaro-Winkler; used by `openalex_describe_fields` and the invalid-field suggestion path. ([#40](https://github.com/cyanheads/openalex-mcp-server/issues/40))
- **`scripts/generate-field-catalog.ts`** — build-time catalog generator; re-run via `bun run generate:field-catalog` when OpenAlex's field validation changes. ([#40](https://github.com/cyanheads/openalex-mcp-server/issues/40))

## Changed

- **`throwNormalizedRequestError`** — invalid-field 400s now append ranked "did you mean" suggestions (top 5 matches from the catalog) and an `openalex_describe_fields` usage hint, replacing the previous `(list of valid fields omitted — was truncated upstream)` dead-end. ([#40](https://github.com/cyanheads/openalex-mcp-server/issues/40))
- **`search-entities`**, **`analyze-trends`**, **`citation-graph`** tools — invalid-field recovery hints updated to reference `openalex_describe_fields`. ([#40](https://github.com/cyanheads/openalex-mcp-server/issues/40))
- **`buildFilterString`** — `.search` filter values containing commas are now double-quote-wrapped for faithful phrase passthrough (e.g., `title.search:"climate, biodiversity"`). Non-search filters with commas raise a clear `comma_in_filter_value` pre-flight error suggesting `|` for OR logic. ([#38](https://github.com/cyanheads/openalex-mcp-server/issues/38))

## Changed (deps)

- **`@types/node`** `^25.9.1 → ^25.9.2`