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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context beyond these: it discloses that LEI/FIGI enrichment degrades gracefully when external sources are unavailable, that unresolved identifiers are explicitly listed under `unresolved` rather than omitted, that ambiguous name matches assert nothing and return candidates, and that it cascades through multiple internal endpoints. No contradiction with 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 dense and well-structured, with examples up front and then organized by supported type. It is longer than average but every sentence carries information (edge cases, degradation, input rules). The structure is logical (examples → 'use first' → types → enrichment behavior → efficiency note). Minor deduction for length—it could be slightly tightened without loss, but it is certainly not padded.

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 the tool's complexity (two entity types, multiple identifier sources, ambiguity handling, graceful degradation) and the absence of an output schema, the description is remarkably complete. It covers input formats, output expectations (including `figi_candidates` and `unresolved` fields), source attribution, and failure modes. An agent has all necessary information to decide when to call it and what to pass, even without seeing any example output.

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%, so the baseline is 3. However, the description goes well beyond the schema: it explains the `value` parameter's semantics with concrete examples (ticker, CIK, ISIN, or name for company; brand/generic for drug), warns against including trailing security-class words, and specifies how ISINs resolve to legal entities via GLEIF. It also clarifies the `type` enum's implications, such as non-equity instruments resolving under 'company'. This adds meaning the schema alone does not provide.

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 states a specific purpose: resolving user-spoken names to canonical/official identifiers. It provides numerous concrete query examples ('What's the ticker for…', 'find the CIK for…') and explicitly enumerates supported types ('company', 'drug') and the identifier sources (SEC EDGAR, GLEIF, OpenFIGI, RxNorm). This clearly distinguishes it from sibling tools like entity_profile or validate_claim, which likely serve different lookup/verification functions.

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 gives explicit usage direction: 'Use FIRST whenever you have a name but need an ID.' It also explains when the tool deliberately refuses to assert an identifier (ambiguous matches return `figi_candidates`), how to handle input formatting (pass entity name only, not full noun phrase), and that it replaces 2-3 manual lookups. No alternative tools are named, but the 'use first' directive is strong and the edge-case guidance is detailed.

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