nordic-data

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

Despite annotations already indicating read-only and idempotent, the description adds valuable behavior: country-specific backend selection, return of ranked suggestions with coordinates, and the 402 'upgrade_required' error handling. It also warns that NL and DE require a Starter+ subscription, which is crucial runtime context.

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, each dense with useful information: first sentence explains the mechanism, second lists return value and supported countries, third gives critical error handling. It is front-loaded with the core purpose and has no filler or redundant statements.

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, the description does not need to detail return fields, yet it still mentions ranked suggestions and coordinates. It covers the core functionality, all supported countries, and a key error scenario (402). The tool's complexity (multi-backend, country variations) is fully addressed in the description.

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 provides 100% coverage for parameters query and country, including descriptions and enum values. The description adds meaning beyond the schema by linking country codes to their authoritative registers and by highlighting the subscription limitation for NL and DE, which affects how the country parameter behaves.

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 it performs address autocomplete using authoritative registers and lists specific register names for countries (DAWA, Kartverket, BAN, MML, Nominatim). This distinguishes it from siblings like lookup_company or validate_vat, which serve different domains.

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 implies when to use (address suggestions) and gives concrete usage caveats: supported countries list, NL/DE subscription requirement, and explicit instruction 'do NOT retry on 402'. It lacks an explicit when-not-to-use statement, but the sibling tools are clearly in different domains, so the usage context is sufficient.

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?

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses significant behavioral traits: it aggregates multiple external sources, includes specific data enrichment types, and, most valuably, explains the 402 failure mode for NL/DE on free tiers with explicit 'do NOT retry' guidance and quota cost multipliers. This goes far beyond what annotations 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 moderately long but every part serves a purpose: it enumerates data components, lists supported countries, and ends with a critical tier note. It's structured logically (data → coverage → caveat) and avoids filler, though it could be slightly more compact without losing information.

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 tool's complexity (multiple sources, 15 countries, tier-dependent behavior), the description covers all essential aspects: what data is returned, the one-call model, country coverage, and the critical failure/quota semantics. An output schema exists, so return structure is already documented; the description fills the behavioral gaps completely.

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` have descriptions, and `country` has a full enum. The description adds the list of countries in text but this duplicates the schema's enum. The `id` reference to 'same format as lookup_company' is in the schema, not the description. So the description adds minimal semantic value beyond the schema, keeping the score at the baseline for high 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 the tool provides enriched company data with a specific list of components (registry data, validated address, industry stats, Wikidata enrichment). It distinguishes itself from sibling tools like lookup_company by emphasizing 'One call, multiple sources' and the enriched nature, making its purpose specific and differentiated.

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 implies when to use this tool (when enriched multi-source data is needed) versus basic lookup, though it doesn't explicitly name alternatives. It provides strong usage guidance by detailing the 15 supported countries and the crucial tier note about NL/DE paid registries, including the 402 error and retry prohibition—very actionable 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 annotations (readOnly, idempotent, non-destructive), the description richly discloses behavior: source data (INSEE Sirene 3.11), bitemporal nature, event structure including 'initial:<field>' events, cost, cache duration, and detailed error codes. This is far more than baseline and helps the agent anticipate outcomes.

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 but information-dense, using four sentences to cover purpose, output structure, input, cost, cache, and errors. It is front-loaded with the main purpose and every sentence contributes practical information without 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?

With an output schema present, return values are already specified, and the description fills in additional operational context: source data, event semantics, cost, cache, and error handling. Given the tool's single parameter and safe read-only nature, the description is complete for an agent to invoke it 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?

Schema coverage is 100% and the schema description already explains the SIREN parameter with examples. The tool description merely restates 'Input: 9-digit SIREN number,' adding no semantic value beyond the schema, so 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 'French company history timeline' and explains it returns one event per change to name, activity, status, legal form, or social-economy flag. This is specific and distinct from sibling tools like lookup_company or company_enriched, which typically return current or enriched snapshot data rather than a chronological event list.

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 clear context: it is for French companies, uses a SIREN number, has specific quota/caching behavior, and lists error scenarios. However, it does not explicitly name alternative tools or state when not to use this tool, though the France-specific nature and timeline focus imply appropriate use.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety profile is covered. The description adds valuable behavioral context beyond annotations: the 402 error behavior, the 'upgrade_required' message with upgrade URL, and the 5x/3x/1x quota unit costs for paid tiers. These are operational behaviors the annotations cannot convey. Slight gap: no mention of return format or pagination, but 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?

The description is information-dense but somewhat long. The first sentence front-loads the core purpose. However, the country list, format specs, and tier notes are packed densely into a long block. While everything earns its place, the structure could benefit from separating the legal-entity-check purpose from the operational/tier details. It's still far above the minimum viable threshold.

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-param lookup tool with 100% schema coverage, an output schema, and strong annotations (readOnly, idempotent), this description is comprehensive. It covers purpose, supported scope (15 countries), error handling (402 behavior), cost implications, and when/why to invoke. There is no output schema requirement to explain return values further, and no ambiguity remains about what the tool does or how to handle edge cases.

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 baseline is 3. However the description adds meaningful value beyond the schema: it explains supported countries at the country-registry level (mapping country codes to actual registries like CVR, Brønnøysund, Bolagsverket), and provides tier-specific caveats for NL/DE. The 'id' parameter's format per country is well documented in the schema, but the description's registry mapping adds real semantic value beyond what the schema enum 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 states a specific verb+resource ('look up basic company data from official European business registries') and clearly distinguishes from siblings. It names the fields returned (name, address, status, industry, VAT registration, founding date). The context of 'before onboarding a supplier or customer' gives clear purpose. Differentiates from sibling tools like company_enriched (this is basic data) 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?

Explicitly states when to use ('before onboarding a supplier or customer to confirm the legal entity exists and is active') and implicitly differentiates from siblings like company_enriched (basic vs enriched data). Provides concrete operational guidance: 'do NOT retry on 402' and explains tier differences (paid upstream registries for NL/DE, quota costs). These are actionable usage constraints.

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 mark readOnlyHint=true and idempotentHint=true, but the description adds rich behavioral context: return fields, reverse lookup coverage across 15 countries, and the critical 402 'upgrade_required' behavior with explicit no-retry instruction. No contradiction with annotations 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?

The description is dense but every sentence adds value: main function, return data, reverse lookup capability, and a targeted error-handling note. It is front-loaded and avoids 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?

Given the tool has 5 parameters, two modes, and an output schema, the description covers the core functionality, data returned, country coverage, and a special error scenario. The output schema handles return-value documentation, so the description is complete enough for an agent to invoke 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the two modes ('lei' vs 'reverse'), the country list for reverse mode, and the implication of include_relationships through the listed parent/child entities. It also clarifies the tier limitation for NL/DE.

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 'Look up' and a clear resource 'Legal Entity Identifier (LEI) via GLEIF', enumerating the returned data (legal name, registered address, status, parent/child relationships) and reverse lookup mode. This clearly distinguishes it from sibling tools like lookup_company by focusing on the LEI standard.

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 states when to use the tool (direct LEI lookup or reverse lookup from a national company number) and provides a specific behavioral note (NL/DE paid registries trigger HTTP 402, do not retry). It does not explicitly name alternative tools or exclusions, so it stops short of a 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 cover readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety profile is fully declared. The description adds meaningful behavioral context beyond annotations: it describes the return structure (per-name match lists with fuzzy scores, source attribution, risk topics, disclaimer field), the informational nature of results (not legal/compliance advice), and that matches are 'potential hits' requiring verification rather than confirmed listings. This is genuinely useful behavioral disclosure.

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 single well-organized paragraph that front-loads the core purpose, adds return-structure detail, and closes with an important disclaimer about interpretation. It's somewhat dense but every sentence earns its place. Could arguably be split into clearer sections, but it's efficient and appropriately sized for a tool with meaningful caveats.

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 exists (return format is likely documented there), full schema parameter coverage, and comprehensive annotations (readOnly, idempotent, non-destructive), the description compensates for what structured fields don't cover: interpretation guidance, source scope, use cases, and the informational-vs-confirmatory distinction. For a sanctions screening tool with compliance implications, this level of contextual completeness is appropriate.

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 three parameters are fully documented in the schema (names array with max 1000, fuzzy boolean default true, min_score default 0.7). The description adds value by explaining the interpretation of match scores (potential hits needing verification) but doesn't add syntax or format details beyond what the schema already provides. Baseline 3 with moderate added context 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 uses a specific verb ('screen') with a clear resource ('person or company names against UN, EU, OFAC and PEP sanctions lists'), specifies the data source scale (768K+ entries via OpenSanctions), and names its typical use case. It clearly distinguishes from siblings like lookup_company and company_enriched by focusing on sanctions screening rather than general entity lookup.

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 concrete typical use case ('counterparty checks before onboarding or processing a payment'), which is clear context. However, it does not explicitly state when NOT to use this vs alternatives or name sibling alternatives. It does clarify that matches are informational and require verification, which guides appropriate interpretation of results.

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 annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses external service calls (VIES/HMRC) and the returned fields. This adds valuable behavioral context 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?

Three sentences efficiently deliver usage trigger, core function, and return values 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?

Given the simple tool shape, rich input schema, and existing output schema, the description covers when to use it, what it does, and what it returns. The openWorldHint annotation complements the external service mention, leaving no critical 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?

Both parameters are fully described in the schema (100% coverage), including the country enum and the no-prefix VAT example. The tool description does not add further parameter semantics, so a baseline score 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 states 'Validate a VAT registration number against the official EU VIES service (or HMRC for GB)', using a specific verb and resource. It also notes the return values, distinguishing it from sibling tools like lookup_company or screen_sanctions.

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 opening line instructs to 'Call before issuing an invoice, processing a cross-border payment, or storing a counterparty's VAT number', giving explicit use scenarios. It does not name alternatives, so it lacks a when-not/alternative clause.

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