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

The description goes well beyond the annotations, disclosing that enrichment degrades gracefully when GLEIF or OpenFIGI is unavailable, that ambiguous matches assert nothing and return figi_candidates, that unresolved identifiers are explicitly listed, and that each call cascades through multiple lookup endpoints. These behaviors are not visible in the annotations or schema and materially affect how an agent should interpret results.

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 front-loaded with purpose and usage, and nearly every sentence adds operational detail. Some parenthetical expansions could theoretically live in supporting docs, but given the tool's complexity and the lack of an output schema, the length is justified rather than wasteful.

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 two parameters, high internal complexity, and no output schema, the description is remarkably complete: it covers accepted inputs, sources, fallback behavior, ambiguity handling, unresolved-identifier reporting, ISIN-to-LEI mapping, and drug return contents. An agent has enough context to invoke it correctly and interpret its results.

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?

Although schema coverage is 100%, the description adds substantial semantics: value formats, accepted identifiers for company input, brand/generic names for drug input, corrected examples like 'ozempic' vs 'metformin', and a critical anti-pattern warning about trailing security-class words in bond issuer names. This meaningfully exceeds the schema's minimal parameter descriptions.

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 ('resolve'), a clear object ('a user-spoken NAME to the canonical/official identifiers'), and enumerated supported types with concrete examples like tickers, CIKs, LEIs, and RxCUIs. It clearly differentiates itself from lookup tools by emphasizing that it produces identifiers other tools require as input, and scopes its domain to company and drug 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?

It explicitly instructs the agent to 'Use FIRST whenever you have a name but need an ID,' which is direct usage guidance. It also provides alternative-shaped examples, explains when ambiguity should return candidates rather than a single assertion, and gives precise input-format rules such as passing the issuer name exactly as printed and never the full noun phrase.

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