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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the bar for additional disclosure is met by the description. The description reveals important behaviors beyond annotations: graceful degradation ('if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'), ambiguity handling ('returns figi_candidates to pick from' when a name matches multiple instruments), and explicit reporting of unresolved identifiers. It also notes that each call cascades through multiple endpoints.

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 front-loaded with trigger phrases and the 'Use FIRST' directive, but the SUPPORTED TYPES section is a long, dense block with many nested parentheses and dash-separated clauses. While every piece of information is valuable, the structure makes it harder to scan. A bulleted format for company/drug types and behaviors would improve readability without losing content.

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 no output schema, the description is remarkably complete: it specifies accepted input forms (ticker, CIK, ISIN, name; brand/generic drug names), return fields (CIK, ticker, LEI, FIGI, RxCUI, etc.), ambiguity behavior (figi_candidates), unresolved-identifier reporting, and failure degradation. An agent would know exactly what to pass and what to expect.

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%, but the description adds critical semantic context beyond the schema. For the value parameter, it warns against using full noun phrases (e.g., 'NEW YORK ST DORM AUTH revenue bonds') because the FIGI lookup matches instrument names and trailing security-class words match nothing. It also adds ISIN as an accepted input for company lookups (not mentioned in the schema) and clarifies the ISIN-to-LEI resolution behavior.

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 query examples and states the core action: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It also positions the tool distinctly with 'Use FIRST whenever you have a name but need an ID,' which differentiates it from sibling tools like entity_profile or compare_entities. This is a specific verb + resource + clear scope.

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 gives explicit usage context: 'Use FIRST whenever you have a name but need an ID.' It also explains that 'using resolve_entity replaces 2-3 manual lookups' and describes supported entity types. It lacks explicit 'when not to use' statements or named alternatives, but the directive to use it first is strong and the scope is clearly defined.

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