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

Beyond annotations (readOnly, openWorld, idempotent), the description discloses rich behavioral detail: the tool cascades through multiple lookup endpoints, degrades gracefully when GLEIF/OpenFIGI are unavailable (EDGAR identifiers still return), asserts nothing on ambiguous matches and returns `figi_candidates` to pick from, lists unresolved identifiers explicitly, and labels every identifier with its source. It also explains that ISINs resolve to the legal entity via GLEIF, covering non-US issuers. No contradiction with 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 but every sentence carries useful information. It is front-loaded with the core directive ('Use FIRST...') and example queries, then systematically details supported types, source integrations, edge cases, and graceful degradation. The structure (paragraph breaks for types and behaviors) keeps it scannable. No fluff — each clause clarifies a decision the agent must make.

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 only 2 parameters and no output schema, the description covers every necessary context: what identifiers are returned (CIK, ticker, LEI, FIGI, RxCUI), how sources are labelled, what happens on ambiguity, what happens on upstream failure, and that it replaces 2-3 manual lookups. There is no missing piece an agent would need to call this tool correctly.

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?

The schema already describes both parameters (type enum and value string), but the description goes much further. It provides concrete examples for value (ticker, CIK, name; brand/generic drug), explains the exact input format for bonds (issuer name only, not the full noun phrase), and warns about trailing security-class words causing no match. This adds semantic clarity far beyond the schema's generic 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 concrete example queries that identify the exact resource (canonical/official identifiers) and the action (resolve). It explicitly states 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input' and 'Use FIRST whenever you have a name but need an ID.' This distinguishes it from siblings like entity_profile and compare_entities, which consume IDs, making the purpose unmistakable.

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 a clear directive: 'Use FIRST whenever you have a name but need an ID.' It also specifies when to use which entity type ('company' vs 'drug') and provides input-format guidance (ticker/CIK/name vs brand/generic). It implies that if you already have the ID, you don't need this tool, and it names alternatives indirectly by saying other tools require these IDs. The when-to-use is explicit and actionable.

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