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 explains graceful degradation (if GLEIF/OpenFIGI are unavailable, EDGAR identifiers still return), that it cascades through multiple lookup endpoints internally, that it returns figi_candidates when multiple matches exist, and that unresolved identifiers are explicitly listed under `unresolved` rather than omitted. This enriches the agent's understanding of what happens in edge cases and failure modes, going well 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 a single, dense paragraph that runs on for many sentences. While every sentence adds relevant detail, the lack of bullet points or section breaks makes it harder to scan. It is front-loaded with the purpose and usage guidance, which is good, but the middle sections on LEI/FIGI enrichment and degradation are verbose and could be condensed. It earns a 3 because it is informative but not concise or well-structured.

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 only two parameters, the description covers a wide range of contextual needs: supported input types (ticker, CIK, ISIN, name for company; brand/generic for drug), handling of ambiguous matches, behavior when enrichment fails, and what fields appear in the response (identifiers with sources, `unresolved`, `figi_candidates`). It does not explicitly describe the full JSON response structure, but given the absence of an output schema, it provides sufficient detail for an agent to understand expected outputs and edge cases. A complete specification would include exact field names and nested structure, but the description is adequate for the task.

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% for both parameters, but the description adds valuable nuance. For `type`, it explains the two supported values and their meaning. For `value`, it gives critical guidance: 'Pass the ENTITY NAME ONLY — for a bond that is the ISSUER exactly as printed... never the question's full noun phrase,' which is essential for correct invocation. It also explains that an ISIN resolves to the legal entity, not the security. These details are not present in the schema and significantly reduce misuse.

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-resource pair: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It gives multiple example phrasings and explicitly says 'Use FIRST whenever you have a name but need an ID,' which clearly distinguishes it from sibling tools by positioning it as the primary name-to-ID resolver. The supported types (company, drug) and core outputs (CIK, ticker, LEI, FIGI, RxCUI) are enumerated, leaving no ambiguity about what the tool does.

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 when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also specifies when the tool is appropriate for bond/issuer lookups, how to handle ambiguous matches (returns figi_candidates, asserts nothing), and that it replaces 2-3 manual lookups, reinforcing its role as the go‑to resolver. It clearly implies when not to use it (when you already have the ID or need a different type of lookup), though it doesn't name specific sibling tools as alternatives, but the guidance is strong enough.

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