company_identity

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

Annotations declare readOnlyHint=false and idempotentHint=false, which could confuse an agent for a lookup tool; the description resolves this by disclosing the 0.05 USDC x402 payment on Base, the AGENT_PRIVATE_KEY and MAX_USDC_PER_CALL prerequisites. It also discloses the deterministic matching policy and the 'ambiguous' status behavior, adding real value beyond annotations, though it does not describe latency or failure modes when payment is unconfigured.

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 the core resolution statement, then sources, then matching behavior, then exclusions, then cost. It is dense and mostly earns its length, though the registry enumeration and the cost paragraph could be tightened slightly.

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?

With no output schema, the description carries the burden of describing returns, and it does so partially: it names the GLEIF fields returned (legal name, other names, addresses, jurisdiction, registry id, parents) and the 'ambiguous' status with ranked candidates. It does not specify the success status value or the full response envelope, leaving a small gap for a 9-parameter tool.

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 already 89%, so the baseline is 3, but the description adds genuine meaning: domain is 'only used to guess a name and to prefer matching candidates' and is never fetched, and country is a scoring hint rather than a filter. It does not clarify how multiple identity inputs are combined when several are supplied.

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-plus-resource statement ('Resolves a company name, web domain, LEI, EU VAT number, SEC CIK or stock ticker to one legal entity') and enumerates the exact registries consulted. It is clearly distinguishable from siblings like lead_enrichment or token_due_diligence because it names its inputs, sources, and output shape.

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 concrete use cases ('For KYC, vendor onboarding and CRM de-duplication by agents') and a strong negative scope ('does NOT fetch or scrape the domain, does not cover companies without an LEI, does not return beneficial owners or financials'). It stops short of naming a specific alternative sibling tool to use instead, which keeps it from a 5.

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