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

Annotations already indicate read-only and idempotent behavior, so the bar for extra disclosure is met with the description's extensive behavioral detail. It explains graceful degradation when GLEIF/OpenFIGI are unavailable, that ambiguous entity matches return an unresolved `figi_candidates` list rather than asserting a wrong answer, and that unresolved identifiers are explicitly listed under `unresolved` instead of omitted. It also discloses that each call cascades through several internal lookup endpoints, which is valuable context beyond the 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 long, but it is dense with necessary operational detail for a multi-source entity resolution tool, and each clause contributes to correct invocation or behavior. The opening example list and 'Use FIRST' instruction are front-loaded, and the supported-type sections are organized and scannable. It loses a point only because some parenthetical expansions, such as the full explanation of why a bond issuer name should not include security-class words, could be trimmed without losing core guidance.

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 required parameters, full schema coverage, and no output schema, the description is remarkably complete. It covers input formats, entity types, source systems, multi-match behavior, failure modes, degradation, and output field naming (`unresolved`, `figi_candidates`). An agent has everything needed to decide when to call it and what to pass, even without a formal 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?

Although schema description coverage is 100%, the description adds substantial meaning to both parameters. For `value`, it provides concrete examples (AAPL, 0000320193, ozempic), distinguishes company vs drug inputs, and adds a crucial precision rule for bond issuers, warning that trailing security-class words like 'revenue bonds' will fail matching. The description fully compensates for the schema's minimal enum descriptions and gives the agent actionable grounding.

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 uses a specific verb, 'resolve', with a clear resource: a user-spoken name to canonical official identifiers. It lists concrete example queries, supported entity types (company, drug), and the identifier systems involved (SEC EDGAR, GLEIF, OpenFIGI, RxNorm), making the tool's purpose unmistakable. It also carefully distinguishes itself from generic search by noting it produces IDs other tools require as input.

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 says 'Use FIRST whenever you have a name but need an ID,' giving direct when-to-use guidance. It also provides precise exclusions and formatting rules, such as passing only the issuer name for bonds and never the full noun phrase, and clarifies that ISINs resolve through GLEIF when EDGAR cannot reach non-US issuers. This goes well beyond a vague hint and fully instructs the agent on when and how to apply the tool.

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