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

Beyond the readOnly/idempotent annotations, the description discloses key behaviors: ambiguous matches return `figi_candidates` rather than asserting a result, unresolved identifiers are stated under `unresolved` instead of omitted, identifiers are source-labelled, and LEI/FIGI enrichment degrades gracefully if upstream sources are unavailable. It also reveals the tool internally cascades through several lookup endpoints, which is behavior an agent needs to know.

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 detailed and well-structured, front-loading purpose and usage before diving into specifics. The long series of query paraphrases at the start is somewhat redundant, and the company explanation is dense with nested parentheticals. Still, nearly every clause adds unique information, so the length is largely justified.

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 carries the full burden of explaining return behavior, and it does so thoroughly: it describes `figi_candidates` for ambiguity, `unresolved` for failures, source labels, graceful degradation, and the exact output for drug lookups. Input variants, edge cases, and failure modes are all covered, making the tool fully usable without further research.

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?

Although the schema already documents both parameters, the description significantly enriches parameter meaning: it explains that company `value` can be a ticker, CIK, ISIN, or name (ISIN accepted via GLEIF mapping is not in the schema), defines drug inputs as brand or generic, and provides explicit anti-guidance about passing entity names only. This goes well beyond the schema's base descriptions.

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 user query patterns ('What's the ticker for…', 'find the CIK for…') and states the core function: resolving user-spoken names to canonical identifiers. It distinguishes itself with 'Use FIRST whenever you have a name but need an ID' and names the supported entity types (company, drug) with specific identifier sets (CIK, LEI, FIGI, RxCUI).

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 tells agents when to use this tool ('Use FIRST whenever you have a name but need an ID') and gives type-specific guidance for both 'company' and 'drug'. It also warns against passing full noun phrases for bonds. However, it doesn't explicitly name sibling tools as alternatives or state when NOT to use it, so the exclusion guidance is implicit rather than fully explicit.

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