Corroborum

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

Annotations already declare readOnly/openWorld/non-destructive, so the description is free to add the parts annotations can't: the shape of returned hits, the presence of open_access full-text links, and a prompt-injection warning that title/authors/venue/abstract are untrusted third-party data. That warning is genuinely useful context beyond structured fields, though it omits rate-limit 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 dense sentences, usage stated first, return shape and the safety caveat trailing. Every sentence carries information; only the return-field recap brushes against redundancy with the output schema.

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?

Coverage is strong for a 3-param graph traversal: id formats, relation semantics, return fields, and a data-trust warning are all present, and annotations carry the safety profile. The one omission is the cap/default behavior of limit, which matters for an agent budgeting calls.

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 only 33% schema coverage, the description does real work: it adds 'a hit's pid' as an accepted id form (not in the schema pattern) and maps the opaque enum values to human meaning ('its references, the works citing it, or OpenAlex's related works'). The limit parameter (default 10, max 25) is left undocumented in both places, which is the only gap.

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 gives a specific verb+resource ('walk the citation graph from a paper') and enumerates the three traversals (references, cited_by, related), which cleanly separates it from a plain paper search. It stops short of naming search_papers to draw the contrast explicitly, so it is clear but not maximally differentiated from its sibling.

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 leads with 'Use to...' and describes the exact scenario (expanding from a known paper's id). However, it never states when NOT to use it or points at search_papers as the alternative for discovering papers in the first place, so the agent must infer the routing.

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, non-destructive, open-world), so the description's job is to add what they cannot. It does: retraction flags are always present even when not excluding retracted papers, open-access links appear only when available, pagination via next_cursor when truncated is true, and a data-trust warning that title/authors/venue/abstract and open_access links are untrusted third-party data. That last point is genuinely important and cannot be inferred from structured fields.

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 most important content (what it searches, what it returns, the filter conservatism rule, the pagination hint, the trust warning) is front-loaded across six tight sentences with no filler or 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 16-parameter open-world search with a 94%-covered schema and an output schema, this description supplies everything an agent still needs: the filter-conservatism policy, pagination behavior, retraction handling, and the untrusted-data caveat. Nothing material 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?

Schema description coverage is 94%, so the schema already documents all 16 parameters thoroughly. The description repeats the schema's cross-cutting rule ('every filter is optional, set one ONLY when the user explicitly asks') but adds no parameter-level semantics of its own. 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?

States a specific verb and resource ('search scholarly literature') plus the input shape ('one plain-language query') and enumerates what comes back (ranked hits with ids, title, authors, year, venue, citations, abstract, retraction flags, open-access link). It does not, however, differentiate itself from the sibling expand_citations, so an agent gets no help choosing between the two.

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 clear operating context: set a filter ONLY when the user explicitly asks, re-call with a new query for another angle rather than combining queries, and page with next_cursor when truncated. This is actionable guidance, but it never names expand_citations or states when that sibling is the better choice.

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