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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses important behaviors: it pulls from SEC EDGAR/XBRL for companies and FAERS/FDA/trials for drugs, handles off-calendar fiscal years correctly, sorts results by a primary metric, and returns paired data with citation URIs. This adds substantial context beyond the structured 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 longer than average but every sentence delivers useful information: trigger phrases, count limits, data sources, fiscal-year handling, sorting, and output format. It is front-loaded with usage cues and structured logically. It earns its length given the tool's dual-type complexity.

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 no output schema, the description adequately summarizes the return value (paired data + citation URIs, sorted by primary metric) and the data points per entity type. It does not provide a precise response shape or unit details, but for a read-only comparison tool with clear parameters, this is sufficient for an agent to understand and invoke 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?

The input schema already documents both parameters fully (type enum with descriptions, values array with min/max and examples). The description goes further by explaining what each type actually retrieves (latest 10-K financials vs. FAERS counts), thereby enriching the semantic meaning of the 'type' parameter beyond the schema's basic enum description.

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 identifies the tool's purpose: side-by-side comparison of 2–5 companies or drugs in a single call. It uses specific verbs like 'compare' and lists concrete example query patterns ('X vs Y', 'which is bigger'), and distinguishes itself from single-entity lookups by emphasizing it replaces 8–15 sequential calls.

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 when to use this tool: whenever comparing entities, and it strongly prefers it over sequential single-pack lookups. It gives concrete trigger phrases and describes what each type pulls. However, it does not explicitly name an alternative tool (e.g., entity_profile) or say when not to use it, though the guidance is still clear.

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