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

Annotations already establish this as a read-only, idempotent, non-destructive tool, but the description adds substantial behavioral context beyond those hints: internal cascading through multiple lookup endpoints, graceful degradation when GLEIF/OpenFIGI is unavailable (EDGAR identifiers still return), ambiguous-match handling via `figi_candidates`, source-labelling of each identifier, and explicit `unresolved` reporting rather than silent omission. No contradiction exists between the description and 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 and dense, packed into a single paragraph, which makes it harder to scan. However, it is efficiently front-loaded with the core purpose and usage directive ('Use FIRST'), and each sentence contributes substantive information — examples, input rules, failure modes, and output behavior. For a tool with this many identifier types and edge cases, the length is largely justified, though breaking it into structured sections would improve readability.

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 systems, cross-source identity resolution, parent/ownership data, and graceful degradation — the description is remarkably complete. It covers input formats, output behavior (including `figi_candidates` and `unresolved`), source attributions, and failure handling. There is no output schema, but the description compensates by clearly stating what the agent should expect under normal, ambiguous, and degraded conditions. Nothing essential for correct invocation is missing.

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?

The input schema already documents both parameters at 100% coverage, so the baseline is 3. The description adds meaning beyond the schema by explaining how ISINs resolve to legal entities via GLEIF, why non-equity instruments resolve here, and that the `value` field for bonds must be the issuer name exactly as printed, not the full noun phrase. This enriches the parameter semantics beyond what the schema provides, though the schema already does much of the heavy lifting.

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 begins with concrete example queries and a clear verb-resource pair: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It explicitly distinguishes itself from other tools by framing itself as the first step when you have a name but need an ID, and it details the supported entity types (company, drug) with their specific identifier outputs. This goes far beyond a vague statement and leaves no doubt about what the tool accomplishes.

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 provides explicit usage direction: 'Use FIRST whenever you have a name but need an ID.' It also gives concrete input rules such as passing the issuer exactly as printed for bonds ('never the question's full noun phrase') and notes when the tool deliberately returns candidates instead of asserting an answer. It effectively communicates when to use this tool and how to avoid common mistakes, even if it doesn't enumerate alternative sibling tools by name.

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