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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context: the cascading internal lookups, graceful degradation (EDGAR identifiers still return if GLEIF/OpenFIGI fail), the fact that non-equity instruments resolve here, and the precise matching behavior for bond issuer names. It also discloses that the tool may return unresolved identifiers in an 'unresolved' field rather than omitting them. This goes beyond the annotations and helps the agent predict edge-case 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 and dense, but every sentence earns its place by adding a distinct piece of operational information. It front-loads the core purpose with example queries, then systematically covers supported types, enrichment behavior, and failure modes. It is structured with clear labels ('SUPPORTED TYPES', 'LEI/FIGI enrichment') that aid scanning. However, it is somewhat overlong and could be tightened by moving some examples into the schema or examples field, and the nested parenthetical about bond issuer matching is a bit convoluted.

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 the tool's complexity (multiple entity types, multiple identifier sources, fallback behavior), the description is remarkably complete. The output schema is absent, but the description explicitly lists all returned identifiers (CIK, ticker, company_name, LEI, parent/ultimate-parent/children, FIGI, RxCUI, ingredient, brand, citation) and the 'unresolved' field behavior. It also covers edge cases like non-US issuers and non-equity instruments. The only minor omission is pagination or rate-limit information, but that is not critical for a read-only resolution tool. For the tool's scope, this is as complete as an agent needs.

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 description coverage is 100%, so the baseline is already strong. The description adds meaningful semantics beyond the schema: it explains that 'value' for company type can be a ticker, CIK, or name, and for drug type a brand or generic name. It also provides the critical warning about passing only the entity name and never the full noun phrase, which is exactly the kind of parameter nuance an agent needs. The only minor gap is that it doesn't explicitly explain what happens if both ticker and name are provided, but that's not applicable here since only one value is accepted.

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 clear verb ('resolve') and resource (user-spoken names to canonical identifiers), and enumerates the exact supported types and identifier outputs (CIK, ticker, LEI, FIGI, RxCUI). It distinguishes itself from sibling tools by explaining that it is the first step when a name is known but an ID is needed, and even names the alternative path (using the EDGAR identifiers if enrichment fails). The title 'Resolve Entity' is consistent and the description provides far more specificity than the title alone.

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 when-to-use guidance ('Use FIRST whenever you have a name but need an ID'), provides concrete example queries, and explains the fallback behavior when GLEIF or OpenFIGI is unavailable. It also clearly states what input format is required (entity name only, not the full noun phrase), which is critical operational guidance. While it doesn't explicitly name sibling tools as alternatives, the 'Use FIRST' instruction and the example queries effectively communicate the intended context relative to other tools.

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