Resolve Legal Entity

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

The description significantly expands on the annotations. Annotations only state readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds key behavioral details: 'Register search endpoints are fuzzy and always return something,' 'a record is accepted only when the normalized legal names are identical,' and the resulting resolution rate ('roughly 6 domains in 10 resolve'). It also discloses credit consumption, which is not in the annotations. This provides a thorough behavioral profile beyond the structured fields.

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 longer than average but every sentence earns its place. It is front-loaded with the core purpose, then layers behavioral context, caveats, exclusions, and requirements. There is no fluff; even the redundancy about fuzzy mode emphasizes a critical warning. The structure is logical and easy to scan.

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 full burden of explaining return values, and it does: it lists the returned fields (legal name, company number, jurisdiction, status, entity type, LEI, VAT number), the audit trail, and the match attributes. It also covers failure modes (null results), the reason behind them, and the registers queried. This is a complete picture for a tool of this complexity.

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 description coverage is 100%, so all six parameters are already well-documented in the schema. The description's mention of match_strictness and fuzzy mode largely repeats the schema's own warning ('fuzzy mode will hand you a confidently wrong company on most domains'). Since the schema already carries the heavy lifting and the description adds minimal additional parameter-level meaning, the baseline of 3 is appropriate.

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 clearly states the tool's purpose with a specific verb and resource: 'Give it a company domain and it returns the registered legal entity behind it: legal name, company number, jurisdiction, status, entity type, LEI and VAT number.' It also distinguishes itself from non-purposes by saying 'This is not a company database and not a credit or risk product.' Although there are no sibling tools to differentiate from, this goes beyond a basic definition by listing exact output fields.

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 provides explicit usage guidance: it explains when to trust null results ('a null here is a trustworthy answer rather than a gap'), warns against using fuzzy mode in production ('should be treated as a research mode, not a default'), and tells users to 'Read match_method, match_confidence and rejected_candidates before acting on a match.' It also specifies prerequisites ('Requires an APIFY_TOKEN and consumes Apify credits') and excludes specific use cases, offering clear context and exclusions.

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