Citation Graph

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

Annotations already indicate readOnlyHint=true and openWorldHint=true, lowering the bar for behavioral disclosure. The description adds valuable context beyond these: results are 'ranked by citation count' and the seed can be resolved via 'DOI, OpenAlex ID, URL, or title'. This meaningfully enriches the behavioral profile without contradicting 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 three sentences, each with a distinct purpose: definition, use cases, and identifier resolution. It is front-loaded with the primary verb 'Map', contains no redundant phrasing, and every sentence earns its place. Excellent conciseness.

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 detailed parameter descriptions, the description does not need to explain return values. It covers the tool's purpose, use cases, and identifier resolution, which is sufficient for a 3-parameter tool with good annotations. A minor gap is lack of explicit mention of limitations or alternative tools, but overall it is 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 coverage is 100%, so the baseline is 3. However, the description adds important parameter-related semantics: 'each ranked by citation count' clarifies that the 'limit' parameter refers to top-N results by that ranking, which is not stated in the schema. This extra information enhances the interpretation of the limit 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 clearly states a specific action: 'Map the citation neighbourhood of a seed paper using OpenAlex', and defines exactly what that entails (backward and forward citations). It distinguishes itself from siblings like search-literature or fetch-paper by focusing on the citation graph structure rather than general search or retrieval.

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 provides explicit use cases: 'Use to snowball a literature search, trace a finding to its origins, or surface the most influential follow-on work.' However, it does not explicitly mention when not to use this tool or name alternative sibling tools, so it falls short of the 5-level criteria.

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