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

Annotations already mark the tool read-only, idempotent, and open-world, and the description adds substantial behavioral context: per-type identifier sources, graceful degradation when GLEIF or OpenFIGI is unavailable, ambiguity handling that returns figi_candidates without asserting, and explicit unresolved identifiers. No contradiction.

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, but nearly every sentence carries operational details an agent needs to call the tool correctly, and key guidance is front-loaded. It could be tightened in places, but the density is justified by the tool's dual entity types and multi-source behavior.

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?

Even without an output schema, the description covers the important return concepts: canonical identifiers, source labels, unresolved fields, figi_candidates for ambiguity, and fallback behavior when upstream sources are unavailable. For a tool that internally cascades through several lookup endpoints, this is complete enough for correct selection and invocation.

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 schema already documents both parameters at 100% coverage, but the description enriches value semantics well beyond the schema: accepted input formats (ticker, CIK, ISIN, name), the instruction to pass only the entity name, and the bond-specific warning that trailing security-class words break the FIGI match. It also clarifies what the type enum values imply about the returned identifier family.

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 user-phrase examples and names the exact action ('resolve a user-spoken NAME to the canonical/official identifiers'), the supported entity types, and the primary use case ('Use FIRST whenever you have a name but need an ID'). This clearly distinguishes it from siblings 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?

It explicitly says 'Use FIRST whenever you have a name but need an ID,' shows example queries, and describes the supported types and inputs. It does not spell out when not to use it or name alternative tools, but the identifier-resolution role is distinctive enough that exclusion guidance is less critical.

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