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

Annotations already declare readOnlyHint=true and openWorldHint=true, indicating the tool is a safe, read-only operation. The description adds context beyond the annotations by specifying the output is 'formatted citations' and that it accepts both single and multiple formats. However, it does not disclose details like how invalid PMIDs are handled or how multiple formats are returned (e.g., as an object keyed by format). Given that annotations cover the safety profile, the description does contribute additional behavioral context, warranting a 4.

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 concise and front-loaded: it starts with the core action and resource, then immediately lists the supported formats, and explains the input flexibility in the second sentence. There is no fluff, and every sentence contributes to agent understanding. The tool name and formal title are clear, and the description avoids redundancy with the schema. This is exemplary conciseness and structure.

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 description, combined with the rich input schema and the presence of an output schema, provides sufficient information for an agent to use the tool correctly. The context signals indicate low complexity: only 2 parameters, single required, no nested objects, and full schema coverage. The description clarifies the only ambiguity (string vs. array for format) and lists all allowed values. The output schema likely covers return structure, so nothing critical is missing. However, it does not mention potential errors or behavior for invalid PMIDs, which could be a minor gap for a complete understanding.

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 input schema provides exhaustive descriptions for both parameters (pmids and format), covering 100% of the schema. The description reinforces the parameter semantics by stating that a single format can be a string or an array, which aligns with the schema's anyOf definition. While the schema already explains the parameter types and allowed values, the description adds clarity on how to combine the two parameters (e.g., 'for multiple formats, pass an array'). This adds marginal value over the schema, so a 4 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 clearly states the tool's purpose: 'Get formatted citations for PubMed articles in one or more formats.' It specifies a concrete verb ('get'), a resource ('formatted citations for PubMed articles'), and enumerates the exact supported formats (apa, mla, bibtex, ris, vancouver). This allows an agent to differentiate it from sibling tools that fetch articles, search, or convert IDs, as none of those involve citation formatting.

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 clear usage direction by specifying the input variations: 'Pass a single format as a string or multiple as an array.' It also implicitly indicates when to use this tool (when formatted citations are needed) and when not (e.g., when raw article data is needed, use pubmed_fetch_articles). However, there is no explicit exclusion or comparison to sibling tools, but the context is sufficient for an agent to infer the appropriate use case.

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