agentum-entity-resolver

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the description does not need to explain the safety profile. Pricing ('$0.025/call after 5 free/day') is genuinely useful context beyond the structured fields. However, it does not say whether failures are per-item or how partial failures are handled in a batch, so it omits the most important operational behavior to disclose here. A 3 is appropriate given the annotation coverage.

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?

Three short sentences, front-loaded with what the tool does, followed by use cases and pricing. No filler, though the pricing parenthetical is somewhat tacked on at the end rather than integrated.

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?

The description includes an output schema, so return values do not need explanation, and the item cap of 25 is already in both the schema and the annotation title. Its remaining gap is not explaining per-item error handling for partial batch failures, which matters for a 25-item concurrent 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 100% and the nested item fields already document query, country, and jurisdiction. The description restates the accepted identifier types (names, registration numbers, domains), which is consistent with the schema but adds nothing beyond it. Baseline 3 applies because the schema does the heavy lifting.

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 uses a specific verb and resource ('Concurrently resolves multiple corporate entity names, registration numbers, or domains across national registries') and makes the batch scope explicit. It does not explicitly name the sibling resolve_entity as the single-entity alternative, leaving the batch-vs-single distinction implicit.

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 lists favorable scenarios ('agent data pipelines, CSV processing, and batch supplier onboarding'), which implies when to use it. However, there is no guidance on when not to use it or which sibling to pick instead, for example a single-entity resolve_entity call or a domain-specific alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, and the description still adds substantial behavior: concurrent execution across registers, the specific data sources queried, the enumerated verdict values (APPROVED/FLAGGED_FOR_REVIEW/REJECTED), the audit trail, single round-trip semantics, and cost/rate-limit terms ($0.010/call after 5 free/day). Pricing and quota are exactly the kind of operational context annotations cannot express.

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?

Three front-loaded sentences: capability, sources, then output and cost. Nearly every clause carries information an agent needs. The trailing parenthetical pricing note is useful but slightly sales-toned, keeping it just below top marks.

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?

An output schema exists, so return structure need not be explained, and the description nonetheless surfaces the verdict enum and audit-trail guarantee. Annotations cover the safety profile and the description covers cost and concurrency. The only real gap is guidance on what an agent should do with a FLAGGED_FOR_REVIEW outcome or how latency scales with more identifiers.

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 every one of the five parameters (name, domain, country, vatNumber, registrationNumber) is already documented with examples in the schema. The description adds no guidance on how the optional identifiers affect match confidence or verdicts, so it earns the baseline 3 and nothing more.

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 names a specific verb+resource ('Composite autonomous KYB vendor due diligence tool') and enumerates the exact sub-tasks performed: corporate identity resolution across global registers, VIES VAT validation, and OFAC/EU/UN sanctions screening. The word 'Composite' plus 'in a single round trip' distinguishes it from the granular siblings resolve_entity, verify_eu_vat, and screen_sanctions without the agent needing to open any schema.

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 clear selection context: this is the all-in-one path that folds three sibling capabilities into one call, which implicitly tells the agent when to prefer it over calling the individual tools. It stops short of explicit exclusions — it never says to use batch_resolve for multiple vendors or resolve_entity alone when only identity is needed — so it lands at 4 rather than 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description still adds genuinely new context: a per-call price with a free tier ('$0.005/call after 5 free/day'), the jurisdictional coverage scope, and the notion of deterministic resolution plus paid-source fallback. It stops short of describing latency or failure behavior when a registry is unavailable.

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?

Three compact sentences, front-loaded with the core capability before coverage, inputs, and price. The long parenthetical jurisdiction list is somewhat marketing-flavored but does convey real scope, so nothing is egregiously wasteful.

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 an output schema present, return values need not be explained, and the description covers scope, input modes, coverage regions, and cost. The main remaining gap is operational guidance for a free-tier-limited, paid-fallback tool in a family of overlapping resolver and verification tools.

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 every one of the eight parameters is already documented in the schema, including the identifier formats, the country/jurisdiction alias, and the sanctions default. The description only restates the accepted query types and the optional ISO country code, adding no new syntax or precedence rules; the baseline 3 applies.

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 and resource ('Resolves official national corporate registry records, company status, and business identifiers') and names the accepted input forms, so the agent knows exactly what class of operation this is. It does not, however, distinguish itself from overlapping siblings such as screen_sanctions or verify_eu_vat, which it partially duplicates via the checkSanctions and verifyVat flags.

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?

'Accepts company names, domains, or national registration numbers with optional ISO country code' implies when the tool applies, and 'deterministic' hints at the non-fuzzy matching use case. But there is no explicit when-to-use/when-not guidance and no routing to the obvious alternatives (batch_resolve for volume, verify_eu_vat for standalone VAT checks, screen_sanctions for dedicated screening), leaving the agent to infer selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context beyond the annotations: the two data sources screened, that matching can be fuzzy or exact with configurable similarity, and the pricing model ($0.005/call after 5 free/day), which matters for call budgeting. It stops short of describing what a match result looks like or list-refresh currency, though an output schema exists.

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?

Two sentences, front-loaded with the capability and sources, with pricing isolated in a parenthetical so it can be skipped. Every clause carries information; only the pricing aside is slightly tacked on rather than integrated.

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?

An output schema exists, so return values need not be explained, and the annotations cover the safety and idempotency profile. Combined with the named lists, matching modes, and cost model, an agent has enough to decide to call it and how to tune the threshold, though sibling selection remains slightly underspecified.

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 the schema already carries per-parameter meaning and the baseline is 3. The description adds context that the threshold parameter controls fuzzy-vs-exact similarity behavior, but it does not clarify how 'exact' mode interacts with the threshold value or how country and registrationNumber affect matching strictness.

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 states a specific verb and resource ('sanctions screening') and names the exact data sources covered (OFAC SDN, EU Financial Sanctions), plus the matching modes (fuzzy and exact). It does not differentiate against siblings like check_vendor or verify_bank_payee, so an agent cannot tell from the text alone which screening tool applies in a given case.

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?

Usage is only implied: the agent can infer this is the tool for sanctions/compliance checks, and 'exact' vs 'fuzzy' with configurable thresholds hints at when to lower thresholds. There is no explicit when-to-use, no exclusion of the sibling verification tools, and no statement of prerequisites or follow-up steps on a hit.

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

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

The annotations already declare read-only, idempotent, open-world, and non-destructive behavior, so the description does not need to repeat safety basics. It adds useful behavioral detail: ISO 13616 validation, MOD-97 checksum checking, country/jurisdiction matching, fraud-prevention intent, and per-call pricing after a free tier.

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 three tight sentences and front-loads what is validated before explaining the fraud-prevention purpose and price. The pricing parenthetical is useful but slightly ancillary to the core capability statement.

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 four-parameter read-only validation tool with annotations, full schema coverage, and an output schema, the description gives enough context to understand purpose and behavior. The main omission is explicit routing against sibling tools, which is handled separately in usage guidelines.

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 the schema already documents all four parameters and the baseline is 3. The description clarifies that the country match is against expected corporate jurisdiction, but it adds little beyond the schema for payeeName and payeeTaxId.

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 uses specific verbs (validates, verifies) and names the resource (IBAN, issuing country, corporate jurisdiction), plus ISO 13616 and MOD-97. It does not explicitly distinguish this tool from siblings such as verify_eu_vat or check_vendor, so it stops short of a 5.

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 implies the tool should be used before payments to prevent invoice fraud and redirection attacks, which gives contextual when-to-use guidance. However, it does not state when not to use it or name the sibling alternatives for overlapping vendor/tax-country checks.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context beyond them: the lookup is against a live external system (implying network dependency and possible latency/outage), it enriches with known company profiles, and it carries a per-call cost of $0.005 after 5 free calls per day.

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?

Two compact sentences with zero filler: the core operation and its authoritative source come first, and the pricing caveat is correctly subordinated in parentheses. Every clause earns its place.

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?

The tool is simple (one param), an output schema exists so return values need no explanation, and annotations cover side effects. The only remaining gap is failure semantics — whether a non-registered VAT number yields a false result or an error — which the description leaves unstated.

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?

With 100% schema description coverage and a single required parameter, the schema already documents the vatNumber format including the 2-letter country prefix. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.

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 names a specific verb ('Validates') and resource ('European Union VAT identification numbers') and specifies the authoritative source (the live official EU VIES system). It does not explicitly differentiate itself from siblings like check_vendor or batch_resolve, so it stops short of a 5.

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?

Usage is implied by the purpose: an agent can infer this is the tool for single VAT number verification. However, there is no explicit when-to-use guidance, no prerequisites, and no routing to batch_resolve for bulk checks or check_vendor for vendor-level verification, which would be the obvious alternatives to name.

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