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

Beyond annotations (readOnly, openWorld, idempotent), the description discloses substantial behavior: cross-source identity spine, graceful degradation of LEI/FIGI enrichment when upstream services are unavailable, explicit `unresolved` fields, and returning `figi_candidates` on ambiguous matches. It also states it replaces 2-3 manual lookups, which sets accurate expectations for cost and behavior.

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 the complexity of the tool (two entity types, multiple identifier sources, edge cases) justifies most of the length, and the core purpose is front-loaded. Some redundancy exists in the many example query phrases at the start, but each subsequent sentence adds unique behavioral or parameter guidance.

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 no output schema, the description does an excellent job covering what the agent needs: return shape highlights (figi_candidates, unresolved), source labeling, degradation behavior, and an explicit parameter anti-pattern. The edge cases around ISIN-to-LEI and non-equity instruments make the tool's unusual behavior fully predictable.

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 coverage is 100% (both type and value are described), which normally sets a baseline of 3, but the description goes well beyond the schema: it explains accepted formats (ticker, CIK, ISIN, name), gives examples, and warns to pass only the entity name without trailing security-class words. This materially improves correct invocation for edge cases like bond issuer lookups.

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 uses a specific verb-resource pairing: resolve a user-spoken NAME to canonical/official identifiers other tools require as input. It enumerates concrete trigger phrases and supported types (company, drug), and differentiates itself from siblings like compare_entities and entity_profile by focusing on name-to-ID resolution. The scope is unambiguous.

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 states 'Use FIRST whenever you have a name but need an ID,' giving clear when-to-use guidance with many example queries and limitation notes (e.g., multiple matches return figi_candidates). It does not explicitly name alternative tools or exclusion criteria, but the 'use first' directive plus coverage of non-equity instruments makes usage conditions clear.

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