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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: it explains that for 'company' it pulls latest 10-K data and handles off-calendar fiscal years, for 'drug' it pulls FAERS data, results are sorted by primary metric, and returns paired data with citation URIs. This adds significant value beyond annotations, but could still detail the response format more.

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 highly efficient: it starts with example trigger phrases, states the core function, provides usage guidelines, and explains data sources—all in a few well-structured sentences. Every sentence adds value 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?

Given no output schema, the description adequately covers return values ('paired data + pipeworx:// citation URIs') and sorting behavior. It also addresses the tool's efficiency benefit. The tool's complexity is low, and the description covers all essential aspects for an agent to use it 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?

Schema description coverage is 100%, and the description enriches it significantly by detailing the enum values (company vs drug) with specific data sources, explaining the values array with examples and constraints (2–5 items), and adding context about the underlying data (SEC EDGAR/XBRL for companies, FAERS for drugs).

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 specific verbs like 'compare', 'rank', and 'side-by-side comparison' and clearly identifies the resource (2–5 companies or drugs). It distinguishes itself from sibling tools like sequential single-pack lookups.

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 states 'ALWAYS PREFER over sequential single-pack lookups' and provides example queries. However, it does not explicitly mention when not to use the tool or list alternatives beyond the sequential lookups.

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