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

The description goes well beyond the readOnly/idempotent annotations, disclosing internal cascading lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, behavior on ambiguous matches (returns figi_candidates rather than asserting), and explicit reporting of unresolved identifiers. It also explains enrichment behavior and the ISIN-to-LEI mapping. This gives an agent a strong model of how the tool behaves.

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 purpose and usage, but it becomes a dense wall of text with many parentheticals and comma-heavy qualifiers. Every sentence adds some technical value, but the length and run-on structure make it harder to parse than necessary. It could be tightened with bullet lists or shorter sentences 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 covers input formats, supported types, edge cases, fallback behavior, and the shape of ambiguous results (figi_candidates, unresolved). It does not spell out the exact return object for a successful unique resolution, but it provides enough behavioral detail for an agent to invoke the tool correctly and interpret common outcomes.

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 the schema already covers both parameters, the description adds critical operational semantics, especially for the 'value' parameter: pass the entity name only, use the issuer exactly as printed for bonds, and avoid trailing security-class words. It also clarifies what each 'type' value resolves to and the accepted input formats. This meaningfully exceeds the schema 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 opens with a specific verb-resource pairing — 'resolve a user-spoken NAME to the canonical/official identifiers' — followed by concrete example queries and the sentence 'Use FIRST whenever you have a name but need an ID.' This clearly distinguishes it from sibling tools like entity_profile or compare_entities, which have different purposes.

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 an explicit usage instruction: 'Use FIRST whenever you have a name but need an ID.' It also describes what kinds of names are accepted (company, drug, bond issuer) and when it should be preferred over manual lookups. It does not name specific alternative tools to use instead, but the context is clear enough to guide selection.

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