get_paper

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

With no annotations, the description carries the full transparency burden. It discloses that the response includes a safety_notes field and notes a markdown variant, which is helpful. However, it does not mention permissions, side effects, or the nature of the '_markdown' variant, leaving some ambiguity.

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, front-loaded with the core purpose, then a key output note and a pointer to an alternative format. Every sentence earns its place with no wasted words.

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 simple with 2 params and no output schema. The description covers the essential output element (safety_notes) and notes a markdown variant, but it leaves the full return structure vague and the '_markdown' reference cryptic. Slightly incomplete for an agent selecting output handling.

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 explains pmid's role via 'by PMID' but omits any explanation of the lang parameter. With 0% schema coverage, this is a gap; while the enum gives some context, the description does not fully compensate for the missing parameter semantics.

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?

Clearly states the action (fetch) and the resource (a single paper by PMID). The mention that the response includes safety_notes distinguishes it from generic paper fetches and sibling tools, making the purpose both specific and differentiated.

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 'Fetch a single paper by PMID' clearly implies use when a specific paper identifier is available. It does not explicitly exclude alternatives like search_h2_papers, but the distinction is reasonably clear from the direct-fetch behavior.

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