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

Annotations already declare read-only, idempotent, non-destructive behavior, but the description adds rich behavioral detail: it handles off-calendar fiscal years correctly, sorts results by a primary metric, returns paired data with citation URIs, and sources data from SEC EDGAR/XBRL, FAERS, and FDA. This goes far beyond the annotations and informs the agent about side effects (none) and output structure.

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 front-loaded with trigger phrases, then methodically covers purpose, preference rule, data specifics, sorting behavior, output, and efficiency gains. Every sentence adds value; no filler. It is appropriately sized for a tool with two modes and complex data sourcing.

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?

This tool has no output schema, yet the description covers return values (paired data + citation URIs) and sorting behavior. It also explains data provenance, fiscal-year handling, and usage scope (2–5 entities). Nothing critical is missing, making it fully self-contained for correct invocation.

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?

While the schema describes both parameters, the description enriches them with concrete semantics: for type="company" it specifies the exact financial fields (revenue, net income, cash, long-term debt), and for type="drug" it lists FAERS counts, FDA approvals, and trial counts. It also clarifies that values accept tickers/CIKs or drug names, adding practical usage detail beyond the schema.

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 opens with concrete trigger phrases and a clear statement: "side-by-side comparison of 2–5 companies or drugs in ONE parallel call." It specifies distinct data sources for company vs drug types and what metrics are pulled, making the tool's purpose unmistakable and differentiating it from single-entity lookup tools.

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 when comparing entities," providing a clear when-not-to-use directive. It lists common user queries ("X vs Y", "rank these companies") that signal when to invoke the tool, and explains that it replaces 8–15 sequential lookups, giving concrete usage context.

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