Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds useful behavior beyond that—identifier filtering rather than term search and a unified envelope return—but it does not describe pagination behavior, empty-result behavior, or any special handling. This is adequate but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, each carrying distinct information: scope, optional filters/sort, return envelope, and the important contrast with term search. No filler or schema repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a list-by-author tool whose safety profile is covered by annotations and whose return stucture is covered by the output schema, the description is nearly complete. It could be slightly stronger by naming pagination defaults or explicitly directing term queries to oa_search_works, but nothing essential to invoking the tool correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The visible input schema already documents author_id (OpenAlex ID or ORCID), sort_by, year_from, and year_to with descriptions; the tool description only summarizes these as 'identifier', 'optional year filter', and 'sort'. That adds useful high-level grouping but not extra per-parameter meaning, so a baseline score is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear retrieval action—works by one author—and narrows it with optional year filtering and sorting. The closing clause, 'A filter on an identifier, not a term search,' differentiates it from oa_search_works, so an agent can tell this tool from its siblings without inspecting the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It clearly signals the intended context: use when an author identifier is known and works by that author are wanted. 'Not a term search' is an explicit exclusion, but the description could have named the sibling search tools as alternatives, so it stops short of full when-to-use/when-not-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare the operation safe, read-only, idempotent, and non-destructive. The description adds useful behavioral details beyond those: results are ordered most-cited first, the response uses the unified envelope, and no searched_for headline is set. These additions give the agent practical expectations without contradicting the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, each contributing distinct information: the result set and ordering, the return envelope, and the identifier-filter caveat. There is no filler, and the most decision-relevant information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and safety annotations covering read-only and idempotent behavior, the description covers the essential remaining details: ordering, envelope, and headline behavior. The only minor gap is not explicitly pointing to a search tool to use when no identifier is available, but that is a small omission given the sibling set and clear identifier framing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description clarifies that the key input is an identifier rather than a search term, which complements the schema's 'OpenAlex work ID or DOI' note. However, it does little to explain page or per_page behavior beyond what the schema defaults already convey. The added semantic value is modest but real.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the operation: return works that cite a given work, ordered most-cited first. It explicitly distinguishes itself from term search by framing the tool as a filter on an identifier, which separates it from the search siblings. The purpose is specific, actionable, and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for when to use this tool: when you already have a work identifier and need the works citing it. It also warns that this is not a term search and that no searched_for headline is set, which helps prevent misuse. It does not explicitly name alternative tools, but the identifier-vs-term contrast is strong enough to route an agent correctly.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare the operation safe, read-only, and idempotent. The description adds useful behavior beyond that: it returns the unified envelope with a single author item or NOT_FOUND, which helps an agent anticipate the response shape and failure mode.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler. The action, identifier types, and expected outcome (single item or NOT_FOUND) are all front-loaded and immediately actionable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter lookup tool with rich annotations and an output schema present, the description is complete. It covers what the tool takes, what it returns, and the main edge case (NOT_FOUND), with nothing critical missing for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single author_id parameter is already documented in the schema with an explicit format and example. The tool description restates that OpenAlex IDs or ORCIDs are accepted but adds no new constraints or format details, so it is adequate but not enhancing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific action ('look up'), a specific resource ('one author'), and the accepted identifier types (OpenAlex ID or ORCID). The singular 'one author' plus the NOT_FOUND outcome clearly distinguishes this from the search-oriented sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The exact-lookup wording makes it clear this tool is for retrieving a single known author rather than searching, and the return of NOT_FOUND reinforces that it is a direct fetch. It does not explicitly name alternatives like oa_search_authors as the fallback for unknown identifiers, so it stops short of full routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark the tool as read-only, idempotent, open-world, and non-destructive. The description adds useful runtime behavior beyond annotations: it returns the unified envelope with a single item, or NOT_FOUND. This helps the agent anticipate the response shape and missing-record handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no filler: the first states the action and accepted inputs, the second states the response behavior. The most important information is front-loaded and every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter lookup tool with rich annotations and an output schema, the description is complete. It covers what the tool does, what inputs are accepted, what the response envelope looks like, and the not-found behavior. No critical operational information is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With schema description coverage reported at 0%, the tool description compensates by explicitly naming all three accepted forms for work_id: OpenAlex ID, DOI, and PMID. This fully specifies the parameter's core semantics, though it does not elaborate on formatting rules such as required DOI URL structure.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Look up'), a specific resource ('one work'), and enumerates the accepted identifier types (OpenAlex ID, DOI, PMID). It clearly distinguishes this tool from search-oriented siblings like oa_search_works and from oa_get_author by focusing on a single work lookup.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly implies the tool should be used when the agent already has a known work identifier. It does not explicitly name alternatives or state when-not-to-use conditions, so it stops short of full routing guidance, but the context is sufficiently clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that results come in a 'unified envelope' and that h-index lives in 'extra', which is useful context, but with a full output schema available it is largely redundant and says nothing about rate limits or auth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with zero waste, leading with the action and following with the result shape. Nothing is padded or repeated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Because an output schema exists, not explaining return values in depth is acceptable, and the envelope note is a reasonable pointer. However, for a four-parameter search tool it omits any guidance on the institution filter or pagination, leaving the agent to infer capabilities from the schema alone.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description never mentions the parameters; it notes searching 'by name' but says nothing about the institution_id filter or page/per_page pagination. With effectively low schema description coverage, the description fails to compensate for the undocumented filtering and paging controls.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a clear verb+resource ('Search OpenAlex for authors by name') and identifies the returned record type ('record_type author'). It distinguishes the resource from sibling searches like oa_search_works, but does not explicitly distinguish it from oa_get_author or oa_author_works.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied by the name and phrase 'by name'; there is no explicit when-to-use guidance, no mention of when to prefer oa_get_author or oa_author_works, and no prerequisites or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds only the record_type/envelope detail, and since an output schema exists that return-shape note is partly redundant; nothing is said about rate limits or paging behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, zero filler, with the core purpose front-loaded before the return/use-case detail. Slightly dense in the second sentence but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Annotations and an output schema cover safety and return shape, and the description supplies purpose plus one workflow use case. It still omits any parameter guidance (notably the country_code filter and paging), which is a meaningful gap given 0% schema coverage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is reported at 0%, so the description must carry the parameter burden, and it names no parameters at all. It never mentions query, the country_code ISO filter, page or per_page, leaving the filtering and pagination semantics to inference.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Search OpenAlex for institutions') and pins the return type ('unified envelope, record_type institution'). The resource name itself separates it from oa_search_works/authors/sources, though those siblings are never named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives one concrete use case — finding institution IDs to feed into work searches — which implies when to reach for it. It offers no exclusions, no mention of when to prefer oa_search_authors or oa_get_work, and no prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds one useful piece of behavioral context beyond that — the response comes back as the unified envelope with record_type=source — but says nothing about rate limits, result caps, or pagination behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the purpose and followed by the return-shape note. Minor redundancy in restating 'Search OpenAlex for sources' after the tool name, but no wasted clauses.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and rich annotations, the description needn't explain return values, and it doesn't. However, for a paginated search tool it omits the practical calling details an agent needs — result limits, paging semantics, and how the type filter interacts with the free-text query — leaving it only minimally adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is reported as 0% at the top level (the single 'params' object is undocumented), and the description offers no parameter guidance at all — no query syntax, no wildcard/boolean hints, no note about page/per_page limits. The nested schema does describe 'query' and 'type', but the description itself contributes nothing to compensate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Search OpenAlex for sources') and enumerates what a source is (journals, repositories, conferences), which implicitly separates it from sibling searches for works, authors, and institutions. It stops short of explicitly naming a sibling or a routing rule, so it is clear but not maximally differentiating.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied by the resource scope: an agent can infer 'use this when you need journal/repository/conference entities'. There is no statement of when not to use it, no mention of alternates like oa_search_works, and no guidance on building the query or paging through results.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds genuinely non-obvious behavior: stemming over title/abstract/fulltext makes result.total a loose count with expected high breadth, and CJK titles fall back to extra.title instead of being guessed into ja/ko. That is real context an agent could not get from structured fields, though the unified envelope itself is not described.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the verb+resource and nicely paragraphed by concern (what it searches, how matching behaves, what filters do). Slightly verbose in the second paragraph but every claim carries information; no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value explanation is unnecessary, and the description instead covers the two things that matter for correct use: matching semantics (loose total, full-text stemming) and filter precision. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description names the filter families (year, author, institution, source, open-access) which maps to most of WorkSearchInput's fields and adds the useful note that filters narrow "exactly" versus the loose query match. However, it says nothing about page, per_page, or sort_by semantics, and gives no syntax or ID-format cues beyond what the schema already contains.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ("Search OpenAlex for scholarly works") and enumerates the indexed entity types (articles, books, datasets, theses), which cleanly separates it from the author/source/institution sibling search tools. An agent can pick this over oa_search_authors or oa_get_work immediately.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use it (query-based discovery over a filtered corpus) and lists the narrowing dimensions (year, author, institution, source, open-access), but never explicitly states when to prefer this over oa_get_work, oa_author_works, or oa_cited_by. Usage is inferred rather than prescribed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.