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

Even though annotations already declare readOnly/openWorld/idempotent/destructive hints, the description goes far beyond them: it discloses internal cascading through multiple endpoints, graceful degradation when GLEIF/OpenFIGI are unavailable, resolution of non-US issuers via ISIN-to-LEI mapping, the behavior of returning `figi_candidates` when ambiguous, and explicit `unresolved` output. This level of detail is highly valuable for an agent predicting side effects and edge cases.

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 every segment earns its place: usage trigger, supported types, resolution details, edge cases, degradation behavior, and parameter guidance. While it could be tightened, the density of actionable information justifies the length. It is well-organized with clear sections ('SUPPORTED TYPES', 'LEI/FIGI enrichment'), making it scannable despite its size.

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?

For a tool with only 2 parameters and no output schema, the description provides a remarkably complete picture. It explains what outputs can be expected (identifiers with source labels, unresolved lists, candidate lists), how to handle ambiguous inputs, and what fallback behavior occurs. An agent is unlikely to need additional context to invoke this tool correctly, even among 30+ siblings in a large toolset.

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 covers both parameters at 100%, but the description adds critical semantic context beyond enum descriptions. It elaborates on the 'value' parameter with concrete examples per type (ticker, CIK, ISIN, name for company; brand/generic for drug), warns against including security-class words, clarifies that non-ticker instruments still resolve, and explains how ISIN maps to legal entities. This is exactly the kind of nuance an agent needs to call it correctly.

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 specific verb+resource: 'resolve a user-spoken NAME to the canonical/official identifiers'. It lists concrete query examples and explicitly distinguishes itself from tools that consume those identifiers (e.g., 'other tools require as input'). The 'SUPPORTED TYPES' section further clarifies scope for company and drug entities, making it unmistakably distinct from siblings like 'entity_profile' or '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 opens with explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also tells the agent what not to do via the `value` parameter instruction: 'never the question's full noun phrase'. It explains edge cases like non-equity instruments and what happens when a name matches multiple instruments, guiding the agent on expected behavior without needing to inspect schemas.

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