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

Annotations (readOnly, idempotent, openWorld) already declare safety, but the description adds substantial behavioral context: cascading internal lookups, graceful degradation if GLEIF/OpenFIGI are unavailable, handling of ambiguous matches by returning figi_candidates, explicit reporting of unresolved identifiers, and ISIN-to-LEI resolution for non-US entities. It also mentions source labeling on each identifier, giving the agent a clear model of what happens during execution.

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 a dense wall of text with a long parenthetical inside the SUPPORTED TYPES clause. Every sentence contributes valuable information, but the structure hampers scanning; a bulleted list or shorter paragraphs would improve readability. It is not tautological or empty, but it is over-stuffed relative to the ideal.

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 must carry the full burden of explaining return behavior. It covers input formats, types, edge cases (bonds, ambiguous matches, unresolved identifiers), failure behavior (graceful degradation), and even citation URLs for drug lookups. Nothing an agent needs to correctly invoke this tool or interpret its results is missing.

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% with detailed descriptions for both parameters, especially 'value' which includes examples and the bond-name warning. The description goes further by explaining the behavioral implications of the 'type' enum (company vs. drug) and what each type resolves to (e.g., company returns CIK, ticker, LEI, FIGI; drug returns RxCUI, ingredient, brand). This enriches the schema's bare enum, though the schema already carries the core instructions.

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 verb-resource pair: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It immediately distinguishes itself from siblings like entity_profile by framing itself as the ID-resolution step, and the 'Use FIRST' directive removes ambiguity. The supported types are explicitly enumerated (company, drug) with the identifiers each returns.

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 first sentence lists typical use cases (ticker, CIK, LEI, RxCUI lookups), and the description explicitly instructs 'Use FIRST whenever you have a name but need an ID.' It further clarifies when not to over-interpret a name (e.g., for bonds, pass the issuer exactly as printed), and notes that it replaces 2-3 manual lookups, setting expectations for when it is the efficient choice.

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