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

Beyond the read-only, idempotent, non-destructive annotations, the description discloses substantial non-obvious behavior: internal cascade across multiple lookup endpoints, graceful degradation when GLEIF or OpenFIGI are unavailable, ambiguity handling by returning figi_candidates, explicit `unresolved` listing, source-labelled identifiers, and ISIN-to-LEI mapping. This gives the agent a reliable model of what the tool will and will not do.

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 and dense, but almost every clause earns its place by covering a real edge case or disambiguation rule. It is front-loaded with purpose and usage guidance, and the supporting examples clarify the schema rather than repeating it. The heavy parenthetical nesting makes it slightly harder to scan, but the complexity of the tool justifies the length.

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 compensates by describing the important return artifacts: canonical identifiers, source labels, `figi_candidates` for ambiguous matches, the `unresolved` field, and the RxNorm citation for drugs. It also covers failure modes such as unavailable enrichment sources and multi-instrument matches. An agent has enough context to know when the call succeeded and how to interpret ambiguous results.

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 the schema already documents both parameters at 100% coverage, the description adds significant meaning beyond the bare enum and string fields. It explains accepted input formats (ticker, CIK, ISIN, name), examples for both company and drug types, and the crucial rule to pass only the entity name rather than the full noun phrase. This materially helps the agent construct correct calls.

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 phrasings and states a precise purpose: resolve a user-spoken name to the canonical or official identifiers that other tools require as input. It clearly differentiates this resolver from broader tools like entity_profile or compare_entities by emphasizing that it is the entry-point lookup for IDs. This is a specific verb-plus-resource definition, not a tautology.

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 instructs 'Use FIRST whenever you have a name but need an ID,' providing a clear selection rule. It also gives detailed input-format guidance, such as passing the entity name only and avoiding trailing security-class words, which is critical for the FIGI lookup. It does not enumerate sibling alternatives or state when not to use this tool, though the guidance is otherwise strong.

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