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

Annotations already cover read-only, idempotent, non-destructive behavior, lowering the bar. The description adds that year filtering and sorting by citation count or publication date are supported. However, it says 'all works' but does not disclose that results are paginated via page/per_page, which is a notable behavioral gap.

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?

One sentence, under 20 words, with the core action front-loaded. Every clause adds useful information, and there is no wasted text or redundant restatement of the tool name.

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 annotations and an output schema, the description is not fully burdened. It covers the main intent and filtering/sorting capabilities, but misses pagination behavior and required parameter emphasis. An agent could call it correctly after inspecting the schema, but the description alone is only partially complete.

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 0%, so the description must compensate. It partially explains year filtering and sorting, but omits the required author_id format and the pagination parameters (page, per_page). For a tool with six underlying parameters, this is insufficient compensation.

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 specific action with a clear resource: 'Get all works by a specific author.' This distinguishes it from siblings like oa_get_work (single work) and oa_get_author (author profile), though it does not explicitly name alternatives or contrast with oa_search_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 context is implied: use when you need works by a specific author. However, there is no explicit guidance about when to prefer this tool over oa_search_works or oa_get_work, and no exclusions or alternative routing are mentioned.

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 non-destructive behavior. The description adds useful context about traversing forward citations and impact exploration, but does not disclose additional behavioral details such as pagination behavior or result limits.

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?

The description is two tight sentences with zero filler. The core action is front-loaded, and the use-case sentence adds meaningful context without redundancy.

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 simple citation-lookup tool, the description, schema constraints, and output schema provide sufficient context. Annotations cover safety and idempotence, so the tool is readily invocable by an agent.

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 does not explain accepted identifier formats or pagination inputs; it only refers to 'a specific work.' Schema coverage is reported at 0%, so the description needed to compensate but did not, despite the schema having a brief work_id note.

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 verb-resource relationship: 'Get works that cite a specific work.' 'Forward citation traversal' further distinguishes it from related work-focused tools like oa_get_work and oa_search_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?

The description explicitly frames when to use the tool: 'for exploring a paper's impact and downstream research.' It does not enumerate alternatives or when-not-to-use conditions, but the intended use case is clear and distinguishable from siblings.

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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds useful context about what the response contains (affiliations, work count, citation count, h-index), but it does not disclose potential edge cases like ORCID format ambiguity or network/rate-limit behavior. This is acceptable given 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?

The description is a single, front-loaded sentence that states the operation, the identifier forms, and the key return fields without any redundant filler. Every phrase contributes to correct selection and invocation.

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 simple by-ID lookup with a nested output schema and safety annotations, the description is largely complete. It tells the agent what to pass and what to expect. A minor gap is that the ORCID format is not specified (e.g., bare ID vs. URL), but this is unlikely to prevent correct usage.

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 parameter author_id is documented in the input schema as an OpenAlex author ID or ORCID, and the description restates this identifier requirement. The description adds no significant new semantic detail beyond the schema, but the schema itself is sufficient for this simple parameter.

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 specific verb ('Look up'), a specific resource ('a specific author'), and the two accepted identifier forms (OpenAlex ID or ORCID). It also names the returned profile contents, which clearly distinguishes this from the sibling search tools like oa_search_authors.

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 that this tool should be used when the agent already has a concrete OpenAlex ID or ORCID, as opposed to using oa_search_authors for query-based discovery. However, it does not explicitly state when not to use it or name alternative tools, so the routing guidance is only implied.

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=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds return-content information but not additional behavioral traits such as auth needs or rate limits; with annotations present, this is acceptable but not especially 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?

The description is a single dense sentence that front-loads the lookup action and immediately lists accepted identifiers and key metadata returns. Every clause earns its place, and there is no redundant 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?

Given the single required parameter, rich annotations, the presence of an output schema, and a clear statement of what the tool returns, nothing needed for correct invocation is missing. The description is complete for this simple lookup tool.

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 0%, so the tool description must carry the parameter meaning. It does by specifying that work_id can be an OpenAlex ID, DOI URL, or PMID. Although the schema repeats this, the description ensures the agent knows the accepted identifier formats without opening the schema.

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 work') and names the exact resource and accepted identifiers (OpenAlex ID, DOI, or PMID). It clearly implies a targeted retrieval operation rather than a search, distinguishing it from sibling tools like oa_search_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?

The description clearly conveys that this tool is for looking up one known work by identifier, which is the right context for using it over siblings that search works or look up authors. It does not explicitly state 'use this when you have an ID, not a text query,' but the identifier-focused wording provides clear 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 cover the read-only, idempotent, and non-destructive nature of the tool. The description adds useful behavioral context beyond annotations by explaining that results are disambiguated author profiles and enumerating the key data fields returned, such as work counts and h-index.

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?

The description is two sentences with no filler: the action is front-loaded, and the second sentence adds relevant return-value detail. 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 read-only search tool with annotations and an output schema present, this description covers the essential purpose and result semantics. It could be slightly more complete by noting pagination and the optional institution filter, but those details are already represented in the input schema.

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 only reinforces the query parameter by saying 'by name' and does not explain page, per_page, or institution_id. With schema description coverage reported at 0%, the description fails to compensate for the lack of parameter documentation, even though the parameter names themselves are somewhat self-explanatory.

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 and resource: 'Search OpenAlex for authors by name.' It also states what the search returns — disambiguated author profiles with affiliations, work counts, citation counts, and h-index — which clearly distinguishes it from sibling tools like oa_search_works or oa_get_author.

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 establishes when to use the tool: when searching for authors by name. It does not explicitly name alternatives or exclusion conditions (e.g., use oa_get_author when a known author ID exists), so it stops short of full routing guidance, but the intended usage is not merely implied.

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 establish read-only, open-world, idempotent, and non-destructive behavior, so the description does not need to repeat that. It adds context about the OpenAlex data source and intended role, but does not disclose additional behaviors like result shaping 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 focused sentences with no filler. The primary action is front-loaded and the second sentence adds a concrete use case, making every word earn 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?

The tool is straightforward, has an output schema, and the annotations cover the safety profile, so the description does not need to document return values. It covers source, scope, and purpose; the only minor gap is the absence of explicit sibling tool routing for edge cases.

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 at 0%, the description was expected to compensate for parameter-level guidance, but it only broadly frames the query as institution names. It does not explain country_code, page, or per_page semantics, leaving the agent to rely on the schema alone for parameter meaning.

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 specific action ('Search OpenAlex for institutions') with concrete examples ('universities, research organizations') and clarifies the downstream purpose (finding institution IDs for work-search filters). This clearly distinguishes it from sibling search tools for works, authors, and sources.

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 explicitly identifies when to use the tool—when institution IDs are needed as filters in work searches—without naming sibling alternatives or stating when not to use it. This gives clear context but stops short of explicit exclusion 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 establish read-only, open-world, idempotent, non-destructive behavior. The description adds value beyond them by revealing that results include work counts, citation data, and open access status. It does not mention fuzzy matching or pagination quirks, but the output schema and annotations cover much of the operational context.

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 first states the action and scope, the second states the return value. The most useful information is front-loaded, and every clause 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 search tool with rich annotations and an output schema, the description plus structured fields provide enough to invoke it correctly: resource scope, query requirement, optional type filter, pagination bounds, and expected output categories. It could add explicit alternative routing, but is not incomplete enough to mislead.

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 itself provides no direct parameter guidance for query, type, page, or per_page. However, the schema documents the required query and the type filter values, and the description's list of source types maps naturally onto valid type options. Given the reported 0% schema coverage, the description only partially compensates, though the nested schema keeps this usable.

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 names an explicit action ('Search OpenAlex'), a concrete resource type ('sources'), and enumerates the resource's members ('journals, repositories, and conferences'). It also states the key returned metrics, making it clear this is about source-level scholarly metadata rather than works, authors, or institutions.

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 phrase 'Search OpenAlex for sources' and the enumeration of source types imply when the tool is appropriate. However, the description does not explicitly say when not to use it or name alternatives like oa_search_works for individual articles, leaving routing to inference rather than explicit 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 establish safety: readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds context by indicating scale (240M+ records), supported filter dimensions, and the kinds of fields returned. It does not mention pagination or sorting behavior, but those are documented in the schema and this is a read-only search, so no additional risk disclosure is needed. No contradiction with 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 sentences with no fluff: purpose/scope, filter capabilities, and return fields. The most identifying information is front-loaded, and every sentence adds information not already obvious from the tool name alone.

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 search tool with a rich input schema and an output schema, the description covers purpose, scope, filters, and expected result fields. It does not explain pagination, sort defaults, or when to prefer sibling tools, but those are either in the schema or penalized in the usage dimension. Overall it gives an agent enough orientation to invoke the tool correctly.

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 schema's nested WorkSearchInput provides descriptions for every parameter, including query scope, sort_by options, per_page range, and ID examples for author_id. The description adds only a high-level summary of filter dimensions (year, author, institution, source/journal, open access). Since the schema carries the semantic weight, a baseline 3 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 specific action ('Search OpenAlex') and a specific resource ('scholarly works'), then narrows scope with content types (articles, books, datasets, theses) and a record count. The resource name 'works' differentiates it from sibling tools that search authors, sources, or institutions, though it does not name those alternatives 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?

The description implies this is the general tool for finding scholarly works, but it gives no explicit guidance about when to choose it over siblings like oa_get_work, oa_author_works, or oa_cited_by. There are no conditions, exclusions, or alternative routing hints, so an agent must infer usage from the tool name and sibling names.

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