nordic-data

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds valuable context beyond annotations: the specific official sources (DAWA, Kartverket, BAN, Nominatim) and the output structure (ranked suggestions with lat/lng and confidence). This enriches the agent's understanding without contradiction.

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 two sentences with no wasted words. It front-loads the core purpose ('Address autocomplete with coordinates'), then lists sources and return details efficiently. Every sentence 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?

Given the presence of an output schema (which covers return values), the description sufficiently covers purpose, sources, supported countries, and output highlights. Nothing critical is missing for an agent to call this tool correctly. The tool is simple and the description is complete.

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%, and both parameters (query and country) have clear descriptions in the schema. The tool description reiterates the supported countries but adds no new parameter-specific semantics beyond what the schema already provides. Baseline 3 is appropriate given full coverage.

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 a specific verb (autocomplete) and resource (addresses), and explicitly lists the data sources and supported countries. It is unambiguous and distinct from any sibling tool, none of which handle address autocomplete.

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 makes it clear this is the tool for address autocomplete in DK, NO, SE, FI, and FR, and that it returns ranked suggestions with coordinates. It does not explicitly mention alternatives, but no sibling tool competes for this use case, so the context is sufficient without exclusions.

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 provide readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is well covered. The description adds valuable context beyond these: the specific allowlist of three POST screening endpoints, the refusal of all state-changing operations and /admin endpoints, and the scoped authentication detail. It explains the unusual behavior that POST is permitted only for three specific pure-query endpoints. Minor gap: doesn't describe error/refusal response format or rate-limit behavior, but the added context genuinely enhances the 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 a dense, well-structured paragraph covering purpose, constraints, authentication, and usage flow in a single block. Every sentence contributes meaningful information: the read-only scope, the POST allowlist rationale ('pure queries using POST only to carry a large request body'), the refusal list, and the discovery workflow. It's more verbose than the minimal ideal but earns its length given the complexity of the constraints. Could be slightly tightened but is appropriately front-loaded with purpose.

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 this is an open-ended, discovery-oriented tool with no output schema, the description provides substantial completeness: it covers authentication, allowed methods, the specific POST allowlist, refused operations, and the associated discovery tools. The nuanced constraint handling (path placeholders, query-string vs request-body semantics) is captured in both schema and description. It doesn't detail pagination or error handling for the response, but for a generic endpoint-call tool with strong annotations and full schema coverage, this is adequately complete.

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 explains all three parameters thoroughly (path with placeholder substitution, method with read-only constraints and defaults, params with URL substitution vs query-string/body semantics). The description adds the relationship to list_endpoints/get_endpoint_schema discovery flow and the allowlist constraint, which supplements rather than repeats the schema. Baseline 3 is appropriate since schema carries the heavy lifting and the description adds minor selection-context value.

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 identifies this as a read-only HTTP client for the Nordic Data API, specifying the verb (execute a request) and resource (data endpoints discovered via list_endpoints). It distinguishes from curated siblings by emphasizing its generic/discovery nature: 'any data endpoint discovered via list_endpoints'. However, it doesn't explicitly name sibling alternatives like get_endpoint_schema or list_endpoints in the purpose statement itself, and the contrast with curated tools is implicit rather than naming them.

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?

Excellent usage guidance: explicitly instructs 'Use list_endpoints and get_endpoint_schema first to find the correct path, method, and parameters.' Clearly differentiates from curated tools by noting it 'Authenticates with the same scoped API key as the curated tools,' implied that one would use this only when curated tools don't cover the endpoint. Also gives explicit exclusions: all state-changing operations (watch lists, webhooks, DELETE/PUT/PATCH) and /admin endpoints are refused.

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, and non-destructive, and the description adds further behavior: it returns a company object plus an industryStats time series, with industryStats.available false when no statistics exist, and names the data source (Danmarks Statistik for DK). 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 dense but every clause earns its place: core promise, return shape, edge-case flag, data source, country scope, and fallback routing. It remains readable and front-loaded.

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 the output schema and complete parameter schema, the description provides enough extra context for correct invocation: country constraints, id format reference, the availability flag, and alternatives for unsupported countries. Nothing critical is omitted.

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%, but the description still adds value: it clarifies id uses the same format as lookup_company and explains the country enum values are lowercase codes for DK/NO/SE/FI only. This supplements the schema rather than repeating it.

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/resource: 'Company registry data plus national industry statistics in one call.' It clearly distinguishes itself from siblings by naming lookup_company and kyb_full as fallbacks for other countries, so an agent can tell what this tool adds.

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 explicitly states the supported countries (DK, NO, SE, FI) and instructs: 'For other countries use lookup_company (basic registry data) or kyb_full (full due-diligence report).' This gives both when-to-use and when-not-to-use guidance with named alternatives.

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 readOnly, openWorld, idempotent, and non-destructive. The description adds concrete behavioral details: quota cost (1 unit), 24h server-side cache, and a breakdown of four error conditions with their triggers (invalid ID, privacy-protected, not found, upstream unavailable). It also reveals the internal bitemporal derivation and initial events, going far beyond 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?

The description is dense but well-structured: purpose and event types are front-loaded, then input, cost, cache, and error conditions follow in a logical order. Every sentence conveys a distinct operational detail (quota, free tier, errors) and none are wasted.

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 that output schema exists, the description covers the necessary input requirements, data scope, error semantics, caching, cost, and notifies the agent about free tier availability. This is complete enough for an agent to decide to use the tool and handle failure modes—nothing necessary is missing.

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 input schema has 100% description coverage, including pattern, format, and examples for the 'siren' parameter. The description's one-line 'Input: 9-digit SIREN number' adds no extra semantic information or operational nuance beyond what the schema already provides.

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: 'French company history timeline' and enumerates exactly which events are returned (name, activity, status, legal form, social-economy flag) and the data source (INSEE Sirene bitemporal periodesUniteLegale). This distinguishes it from sibling tools like lookup_company that provide current snapshots.

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 makes clear that the tool is for France and SIREN input, mentions the free tier and the 'unlike NL and DE' comparison, which implies geographic restriction. However, it does not explicitly name alternative tools or state 'when not to use this'. The usage guidance is clear but lacks an explicit exclusionary statement.

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?

Beyond the readOnlyHint, it reveals that data is read from the 'backend's live OpenAPI spec with $refs resolved inline' and that admin endpoints are rejected. This adds meaningful behavioral context about data source, processing, and restrictions that annotations do not capture.

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 core purpose and followed by concise usage guidance. Every word earns its place with no redundancy.

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 meta-tool, the description is complete: it states what it returns, where data comes from, when to use it, and an exclusion. Combined with the rich annotations and schema, it leaves no major gaps.

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%, with path and method already documented with examples and defaults. The description does not add parameter-level detail beyond what the schema provides, so the baseline 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 opens with 'Discovery meta-tool' and clearly states it 'Returns the full parameter and response schema for a single Nordic Data API endpoint (path + method)'. The verb is specific and the resource is well-defined, distinguishing it from siblings like list_endpoints and call_endpoint.

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?

Explicitly instructs to 'Use after list_endpoints to learn exactly which parameters an endpoint takes before calling it with call_endpoint', providing clear sequencing and placing it between list and call operations. Also notes that admin endpoints are rejected, which is a usage constraint.

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 establish readOnly/idempotent/non-destructive, and the description dramatically extends this with rich behavioral disclosures: cold vs warm cache timing, 6h/60s cache policies, partial response structure ('truncated: true', 'sectionsUnavailable'), the 402 upgrade_required retry warning, and quota costs for NL/DE. It also adds a legal disclaimer clarifying the report is informational, not a definitive determination.

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 content is information-dense and valuable, but it's a single large paragraph covering many distinct concerns (purpose, performance, caching, partial responses, tier caveats, legal disclaimer) with no structural separation. Front-loading is good (opens with use cases), but a long block of text is harder for an agent to parse than a structured or bulleted layout.

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?

This is a complex, high-consequence tool with no output schema, so the description carries the full burden — and it meets it comprehensively: 9 sections enumerated, country list, performance expectations, partial-response handling, retry semantics, tier-specific costs, and legal framing. Every ambiguity an agent might face is addressed.

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% — both id and country already carry descriptive text (with format hints like 'CVR 8 digits' and enum values). The description adds the reference to lookup_company for the id format, which adds a small cross-tool tie-in, but mostly the schema handles parameters. Baseline 3 is appropriate since the description doesn't add significant param semantics beyond schema coverage.

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 concrete use-case framing ('Run before a consequential decision...') and specifies the exact output ('Full Know-Your-Business master report') with country scope and a detailed list of the 9 aggregated sections. It clearly distinguishes from siblings like lookup_company, screen_sanctions, and validate_vat by covering the full composite report across 15 countries.

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 explicitly states when to use ('before onboarding a counterparty, approving a payment, extending credit, signing a contract'), covers caching behavior, partial-response retry semantics, and includes a crucial tier note (NL/DE paid registries, do NOT retry on 402). This gives the agent strong decision guidance on when the tool is appropriate and what pitfalls to avoid.

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?

Beyond the readOnlyHint annotation, the description reveals key behavioral traits: it reads a live OpenAPI spec at runtime, covers only read-only operations (GET/HEAD plus POST screening queries), never returns admin/state-changing endpoints, and notes the catalog has 230+ endpoints. This adds substantial value beyond the annotations about the tool's runtime behavior and coverage boundaries.

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?

Four dense sentences with zero waste — every sentence earns its place. The purpose, usage workflow, behavioral boundary (read-only only), and catalog size are all conveyed efficiently. Front-loaded with the purpose verb in the first word.

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 this is a discovery meta-tool with a single optional parameter and no output schema, the description is fully complete. It discloses the runtime mechanism (live OpenAPI read), the coverage boundary (read-only only, 230+ endpoints), and the full follow-up workflow with named sibling tools. No information gap for the agent to fill.

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 the schema fully documents the search parameter and its matching semantics. While the description doesn't add much beyond the schema (it mentions the filter exists), it does note case-insensitivity is covered by schema, and use of the search parameter is contextualized in the discovery workflow. This is at or slightly above baseline.

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 ('Lists') with a clear resource ('ALL available Nordic Data API data endpoints') and scope ('HTTP method, path, short description'). It explicitly distinguishes from the curated high-level tools and names sibling tools (get_endpoint_schema, call_endpoint) as follow-up actions, making this a distinct discovery meta-tool.

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?

Explicit guidance states when to use it ('discover capabilities the dedicated tools do not cover') and when not to use it (admin/state-changing endpoints never returned). It also provides a clear workflow chain: call get_endpoint_schema for params, call_endpoint to execute. The search filter examples ('sanction', 'address', 'cvr') give concrete usage context.

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?

Beyond the readOnly/idempotent annotations, the description discloses the 402 'upgrade_required' failure mode, instructs not to retry on 402, and quantifies quota consumption (NL 5x, DE 3x, others 1x). This is actionable behavioral detail the schema and annotations don't provide.

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 trigger and then lays out countries, then tier/error behavior in a logical order. The country list partly repeats the schema enum, but it's not padded; every section adds operational context.

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 and read-only/idempotent annotations, the description covers the key operational aspects: use case, country coverage, failure/retry behavior, and quota impact. No essential information for calling the tool correctly is missing.

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 the baseline is 3; the description adds the country-specific quota costs (NL/DE premium tiers), which is meaningful semantics for choosing among country values. It doesn't add id-format detail, but that's already in the schema.

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 ('look up'), a concrete resource ('legal entity ... from official European business registries'), and a clear purpose ('confirm the legal entity exists and is active'). It also scopes to basic company data, which distinguishes it from sibling enrichment/validation tools like company_enriched and validate_vat.

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 a clear trigger: 'Call before onboarding a supplier or customer...' This is explicit context, though it doesn't name alternatives or when-not-to-use relative to siblings.

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?

Beyond the readOnly/idempotent annotations, the description discloses the returned data shape and adds a concrete failure mode: NL and DE require paid upstream registries, and free-tier keys get HTTP 402 'upgrade_required' with a do-not-retry instruction. This is exactly the kind of behavioral context annotations do not carry.

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 sentences, front-loaded with the core purpose and return values, then reverse mode, then the critical error caveat. No filler or redundant restatement of the schema.

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 an output schema and rich annotations, the description covers purpose, modes, country coverage, return fields, and the one environment-specific error behavior. An agent has enough to invoke it correctly and know what to expect.

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 description does not need to explain each parameter. It reinforces the mode/country relationship and relationship-fetching behavior, but adds no parameter-level detail beyond what the schema already provides; baseline 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 opens with a specific verb and resource ('Look up a Legal Entity Identifier (LEI) via GLEIF') and immediately lists what it returns. It also covers the reverse lookup mode, which distinguishes it from sibling company-lookup tools even without naming them.

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 clearly states the two lookup modes and the 15 supported reverse-lookup countries, so an agent knows when the tool applies. It also gives an explicit do-not-retry rule for HTTP 402 in NL/DE, but it does not name sibling alternatives or state when another tool should be chosen.

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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds substantial context beyond those: it discloses the return structure (per-name match lists, fuzzy scores, source attribution, risk topics, disclaimer) and, crucially, sets expectations that matches are 'informational decision-support... not legal or compliance advice' and that a match 'requires verification, not a confirmed listing.' This is exactly the kind of behavioral caveat agents need and that 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?

Four tight sentences with zero filler. The core purpose is front-loaded, followed by use case, return format, and the decision-support caveat. Every sentence earns its place and nothing is redundant with the schema or annotations.

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-value explanation is unnecessary, and the description still sketches the output fields. Combined with 100% schema coverage and full annotations (read-only, idempotent, non-destructive, open-world), the description covers purpose, usage, behavior, and limitations. Nothing an agent needs to invoke this correctly is missing.

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% — names, fuzzy, and min_score each have meaningful descriptions in the schema itself. The tool description references fuzzy match scores but adds no syntax or formatting detail beyond what the schema already documents. The baseline of 3 applies correctly since the schema carries the parameter-semantics burden.

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+resource: 'Screen one or more person or company names against UN, EU, OFAC and PEP sanctions lists'. It names the exact list sources (UN, EU, OFAC, PEP) and the data provider (OpenSanctions, 768K+ entries), making it clearly distinguishable from sibling tools like lookup_company, lookup_lei, or validate_vat, which serve different counterparty-check purposes.

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 an explicit typical use case — 'counterparty checks before onboarding or processing a payment' — which tells an agent when to reach for this tool. It does not, however, explicitly name alternative tools or state when NOT to use it, leaving some routing to inference. Given the siblings include overlapping due-diligence tools (kyb_full, company_enriched, lookup_company), an explicit exclusion would have pushed this to 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 provide readOnlyHint, openWorldHint, and idempotentHint, but the description adds valuable context beyond them: the data source (VIES, with DK via CVR), the return fields (validity status, possibly registered name/address), and the meaning of HTTP 503 upstream_unavailable with retry guidance. This enriches the agent's understanding of behavior without contradicting the 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 compact and front-loaded with the most critical usage guidance, followed by purpose, return info, edge cases, and error handling. It is dense but every sentence carries relevant information; a slightly more structured layout could improve scannability, but there is no waste.

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 2-parameter read-only tool with an output schema, the description covers everything needed to invoke it correctly: when to use it, unsupported cases, alternative tools, special country handling, and error semantics. The output schema covers return values, so the description is contextually complete.

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 fully documents both parameters. The description largely repeats schema facts ('Use EL for Greece', 'VAT number WITHOUT country prefix') rather than adding new semantic meaning. Baseline 3 applies because the schema carries the load adequately.

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: 'Validate a VAT registration number for any of the 27 EU member states against the official EU VIES service.' It clearly distinguishes itself from sibling tools by explicitly naming lookup_company as the alternative for Norway, so an agent can tell them apart.

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 opens with explicit when-to-use guidance: 'Call before issuing an invoice, processing a cross-border payment, or storing a counterparty's VAT number.' It also states what is not supported (GB, NO) and gives a concrete alternative for Norway, making the selection criteria fully explicit.

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