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

Despite strong annotations (readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false), the description adds substantial behavioral detail: it cascades through multiple lookup endpoints internally, degrades gracefully when GLEIF/OpenFIGI are unavailable, returns figi_candidates when ambiguous rather than asserting a single result, lists unresolved identifiers explicitly, and labels each identifier by source. These are beyond what annotations convey and match the read-only, open-world nature declared there.

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 front-loaded with example queries and a clear statement, but it quickly becomes a dense wall of text with deep nesting, long parentheticals, and run-on specification. Several sentences pack multiple distinct facts, making it harder to scan. While every sentence arguably contributes information, the lack of formatting and the sheer length strain conciseness.

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?

For a tool with no output schema and high complexity (two entity types, multiple identifier sources, ambiguity handling, degradation behavior), the description is nearly exhaustive. It covers accepted inputs, per-type outputs, ambiguity policy (figi_candidates), unresolved handling, source labeling, and failure degradation—leaving no obvious gap an agent would need to call it correctly.

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. The description adds value above the schema by elaborating on the 'value' parameter's rules (e.g., 'Pass the ENTITY NAME ONLY — for a bond that is the ISSUER exactly as printed... never the question's full noun phrase') and by expanding what each 'type' enum value implies (company payloads, drug payloads, accepted aliases like ISIN for company). This enrichment justifies a score above baseline.

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 verb ('resolve') and resource: it maps a user-spoken NAME to canonical/official identifiers needed by other tools. It distinguishes itself from siblings by explicitly positioning itself as the first step ('Use FIRST whenever you have a name but need an ID') and by enumerating supported entity types (company, drug) and the identifiers produced (CIK, ticker, 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?

It gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also provides practical usage constraints, such as passing only the entity name, never the full noun phrase, and describes accepted input forms (ticker, CIK, ISIN, brand, generic name). It does not explicitly name alternative sibling tools or give when-not-to-use exclusions, but the 'use FIRST' framing and detailed input examples make the intended context clear.

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