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

The annotations already mark the tool readOnly, non-destructive, and idempotent, and the description adds substantial behavioral context beyond that: it explains ambiguous matches return 'figi_candidates' and assert nothing, unresolved identifiers are explicitly reported under 'unresolved', LEI/FIGI enrichment degrades gracefully, and each call cascades through multiple lookup endpoints. These details meaningfully inform the agent about edge cases and expected resilience without contradicting the annotations.

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 nearly every sentence adds operational value: call patterns, supported types, ambiguity behavior, degradation, and input caveats. It is front-loaded with the most important usage rule at the beginning. It loses one point because the lengthy parentheticals and run-on structure make the central behavior harder to scan quickly, and 'Use FIRST' is a slightly awkward phrasing.

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?

Despite having no output schema, the description explains what the tool returns conceptually: labeled source identifiers, 'figi_candidates' for ambiguous cases, 'unresolved' for failures, and RxCUI plus ingredient/brand citations. It covers error and degradation behavior, supported entity types, and input constraints, so the agent has enough information to invoke the tool correctly in most scenarios.

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% for the two parameters, so the baseline is already solid, but the description goes much further. It clarifies accepted input formats for company value (ticker, CIK, ISIN, or company name), warns against passing full noun phrases for bonds, and explains how ISIN values are resolved through GLEIF. It also gives concrete examples like 'ozempic' and 'metformin', which the schema alone does not provide.

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 intents ('What's the ticker for…' / 'find the CIK for…') and states the core function: resolving a spoken name to the canonical official identifiers other tools require. It distinguishes supported types ('company' and 'drug') and clearly separates this from sibling tools like entity_profile by focusing on identifier resolution. The verb 'resolve' plus the resource's identifier-returning behavior is specific and unambiguous.

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 says 'Use FIRST whenever you have a name but need an ID,' which is a clear when-to-use directive with a motivating condition. It also gives detailed substitution examples and notes it replaces 2-3 manual lookups. However, it does not state when to prefer alternatives such as entity_profile or compare_entities, or provide any exclusion cases.

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