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

While annotations already declare readOnly, openWorld, idempotent, and non-destructive hints, the description adds critical behavioral details beyond them: it cascades through multiple endpoints, degrades gracefully when GLEIF or OpenFIGI is unavailable, returns `figi_candidates` for ambiguous matches rather than asserting a single result, and explicitly lists unresolved identifiers under `unresolved`. This goes well beyond the annotations and provides essential insight into how the tool behaves.

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?

Although lengthy, the description is front-loaded with examples and the core purpose, then systematically covers each supported type, input nuances, and degradation behavior. Every sentence adds necessary information and the logic flows from general usage to specific details, making it well-structured and appropriate for the tool's complexity.

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?

With no output schema, the description adequately explains what the tool returns: canonical identifiers with source labels, unresolved identifiers listed separately, and `figi_candidates` when ambiguous. It also mentions that it replaces several manual lookups, so an agent has a complete picture of the tool's functionality, including edge cases and failure modes.

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 has basic descriptions for both parameters, but the description substantially enriches them. For `type` it explains the two enum values, and for `value` it details accepted formats per type (ticker, CIK, ISIN, company name for company; brand or generic for drug) and even warns against including trailing security-class words for bonds. This semantic depth far exceeds the schema and is crucial for correct invocation.

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 opens with concrete example queries and then precisely states the core purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly distinguishes between the two supported types (company and drug) and positions the tool as the first step when a name but not an ID is available, which differentiates it from sibling tools like entity_profile and compare_entities.

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,' providing a clear directive for when to invoke this tool. It further elaborates on the accepted input formats for each type, notes that it replaces 2-3 manual lookups, and explains the degradation behavior, giving comprehensive guidance on usage conditions and alternatives.

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