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 goes beyond these by detailing graceful degradation (LEI/FIGI enrichment degrades gracefully; EDGAR identifiers still return if GLEIF/OpenFIGI unavailable), explaining that unresolved identifiers are stated explicitly under `unresolved`, and noting that matching multiple instruments returns `figi_candidates` rather than asserting a value. It also explains internal cascading through several endpoints and replaces 2-3 manual lookups, adding behavioral context well beyond annotations. 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 very long, covering many edge cases (bond matching, ISIN-to-LEI, resolution fallbacks). While every sentence adds value, the sheer length may slightly obscure the core purpose for a quick agent read, though the key guidance ('Use FIRST whenever you have a name but need an ID') is front-loaded at the start. It is not excessively verbose given the mental model complexity, but could be tightened in middle sections.

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 2 parameters, rich annotations (read-only, idempotent, open-world), absence of output schema, and the supported entity types add significant mental model. The description covers edge cases and error behavior (unresolved fields, figi_candidates for ambiguous names, degradation when upstream services are down) that an agent needs to understand what happens after a call. No return structure is specified, but since description fully explains resolution behavior and output fields (CIK, ticker, LEI, FIGI, RxCUI, unresolved, figi_candidates), it is complete enough without an output schema.

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?

Despite 100% schema description coverage, the description adds substantial semantic value: it describes what each `type` value resolves to ('company' → CIK+ticker+company_name+LEI+FIGI, 'drug' → RxCUI+ingredient+brand) and gives detailed examples for `value` input (ticker, CIK, ISIN, or name for company; brand/generic for drug), including a bond-specific instruction on passing exactly the issue name. It also specifies the ISIN-to-LEI mapping behavior and SEC EDGAR fallback. The description deeply enriches parameter meaning 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 names a specific verb ('resolve') and resource ('entity' names to canonical identifiers) and clearly distinguishes from siblings by explicitly stating it is the tool to use FIRST when you have a name but need an ID, naming the supported types ('company' and 'drug') and what each resolves to. It differentiates itself from `entity_profile` and `compare_entities` by focusing solely on resolution to identifiers, not enrichment or comparison.

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?

It provides explicit usage guidance: 'Use FIRST whenever you have a name but need an ID' and covers when-not conditions: for non-equity instruments without a ticker that DO resolve here, and states it should not be used when a name matches multiple instruments (returns candidates). While it doesn't exhaustively enumerate alternatives in the sibling list, it gives clear conditions and exclusion criteria for calling this tool vs alternatives.

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