---
summary: "search_entities — random sampling via sample/seed (#14); alias common LLM-prior field/filter names to OpenAlex canonical names (#17)."
breaking: false
---

# 0.6.8 — 2026-05-05

Two field-test follow-ups against `openalex_search_entities`. Both close gaps surfaced from production traffic where LLM callers either lacked an OpenAlex feature surface (random sampling) or guessed intuitive names that don't match upstream's vocabulary (`year` for `publication_year`, `cited_works` for `cites`, `id` for `openalex`).

## Added

- `openalex_search_entities` — `sample` (1-100) and `seed` parameters expose OpenAlex's native random sampling. Single page only; mutually exclusive with `cursor`. `seed` requires `sample`. Both rejections wired through typed error contracts (`sample_with_cursor`, `seed_without_sample`) so the recovery hint reaches the LLM. Service layer aligns `per_page` to `sample` to prevent silent truncation when `sample > per_page`. Closes [#14](https://github.com/cyanheads/openalex-mcp-server/issues/14).
- `tool-defs-analysis` skill — read-only audit of LLM-facing definition language across tools/resources/prompts (voice, leaks, recovery, sparsity, structure).

## Changed

- `openalex_search_entities` filter description anchors positive priors with concrete common keys (`openalex`, `cites`, `publication_year`, `authorships.author.id`, `type`, `is_oa`) and resolves the most-mistaken names server-side: see Fixed.
- `semantic_per_page_cap` error code reclassified `InvalidParams` → `ValidationError` for parity with the other pre-upstream input-shape rejections in the contract.

## Fixed

- `openalex_search_entities` filter aliases — works-only `cited_works` → `cites`, `year` → `publication_year`, plus a universal `id` → `openalex` rewrite when the value matches an OpenAlex ID pattern (bare or URL-form, pipe-joined OR supported). Pure key renames; values pass through. Misses fall through so upstream's helpful 400 still fires for typos. Closes [#17](https://github.com/cyanheads/openalex-mcp-server/issues/17).
- `openalex_search_entities` select aliases — works-only `year` → `publication_year`, `authors` → `authorships`, joining the existing `abstract` → `abstract_inverted_index` rewrite. Same shape as filter aliases.