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

Annotations already mark the tool as read-only, idempotent, non-destructive, and open-world, so the bar is lower, yet the description still adds substantial behavioral context. It discloses graceful degradation when GLEIF/OpenFIGI are unavailable, explicit representation of unresolved identifiers, candidate-returning behavior for ambiguous matches, and internal endpoint cascading, which go well beyond the structured 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 information-dense and mostly front-loaded, but it is structured as one long run-on paragraph with heavy nested parentheses, making it harder to scan. The content mostly earns its place, yet the formatting sacrifices conciseness and clarity, and several caveats could be condensed into bullet points or shorter sentences.

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, the absence of an output schema, and the two distinct entity types, the description is remarkably complete. It covers return fields, ambiguity handling, unresolved identifiers, source attribution, degraded enrichment, and input constraints. An agent has enough context to know when to call it, how to pass value correctly, and what to expect in the response.

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 crucial parameter meaning beyond the schema. For the company type it specifies accepted input forms (ticker, CIK, ISIN, name) and explains how ISIN maps to legal entity; for the value parameter it gives concrete examples and an important negative instruction: pass the entity name only, not the full noun phrase, because trailing security-class words break FIGI matching.

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 very specific verb-resource pair: resolve a user-spoken name to canonical/official identifiers that other tools require. It distinguishes itself from the broader sibling set by positioning itself as the identity-resolution entry point ('Use FIRST whenever you have a name but need an ID') and by enumerating the exact identifier types it produces (CIK, 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?

The description gives an explicit trigger condition: 'Use FIRST whenever you have a name but need an ID.' It also lists representative user queries as positive signals and notes that it replaces 2-3 manual lookups. It does not explicitly name sibling alternatives or exclusion criteria, but the guidance is clear enough for an agent to route identity-resolution requests to this tool.

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