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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, which cover safety and idempotency. The description goes well beyond: it discloses graceful degradation ('if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'), ambiguous-match handling ('asserts nothing and returns figi_candidates'), unresolved-identifier handling ('stated explicitly under `unresolved` rather than omitted'), source labeling, and the internal cascading of lookup endpoints. These are behavioral traits an agent needs to predict output quality and failure modes, and none are in the schema or 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 (~350 words) but dense with actionable information. It is front-loaded with examples and the core use case, then organizes details by type, enrichment fallback, and input caveats. There is minimal fluff; nearly every sentence adds value. It slightly over-achieves in detail (e.g., the GLEIF ISIN-to-LEI mapping sentence), but this is warranted given the tool's complexity. A 4 is appropriate—comprehensive but not perfectly concise.

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 there is no output schema and the tool is complex (multi-source cascade), the description is remarkably complete. It covers supported types, input formats, edge cases (ambiguous matches, unresolved IDs, non-equity instruments), degradation behavior, and the internal cascade. It even explains why certain inputs fail (trailing security-class words). An agent has everything it needs to invoke the tool correctly and interpret results, making this a model definition.

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%, so parameter names/types are documented. But the description adds critical semantics: it warns to pass the entity name ONLY, not the full noun phrase (e.g., 'NEW YORK ST DORM AUTH' not 'NEW YORK ST DORM AUTH revenue bonds'), and explains why (FIGI lookup matches instrument names). It also clarifies accepted inputs for `value` (ticker, CIK, ISIN, name for company; brand/generic for drug) and the `type` enum values. This goes far beyond the schema's basic descriptions ('ticker (AAPL), CIK... or name').

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 example queries ('What's the ticker for…' / 'find the CIK for…'), then states the verb and resource precisely: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It explicitly lists supported types (company, drug) and the sources (SEC EDGAR, GLEIF, OpenFIGI, RxNorm). This clearly differentiates it from sibling tools like entity_profile or compare_entities, which operate on already-resolved 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 gives an explicit usage directive: 'Use FIRST whenever you have a name but need an ID.' This instructs when to invoke the tool and implies it is the entry point before other tools. It also explains that the tool replaces 2–3 manual lookups, reinforcing when it is the right choice. However, it does not explicitly mention alternatives or cases where one should NOT use it (e.g., when the entity ID is already known and one needs a profile), so it lacks explicit exclusion guidance but still provides clear context for when to use it.

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