ENTIA Entity Verification

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

Annotations already establish that this is read-only, idempotent, and non-destructive, so the description only needs to add context beyond that. It does so by disclosing an auth-dependent output split: free callers get a trace-level preview, while authenticated callers get the full paid dossier. This is useful behavioral context 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 with no filler: the first states the core purpose and accepted identifiers, and the second adds the key access-level behavior. Every sentence earns its place, and the most important information is 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?

For a read-only lookup with three optional parameters and an existing output schema, the description covers the essential context: what can be looked up and what different callers receive. It does not specify behavior when no query parameter is supplied, but the output schema and annotations reduce the impact of that gap.

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%; q, name, and query are each documented in the schema, including alias relationships. The description adds no parameter-level detail beyond what the schema already provides, so it stays at the baseline for high 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 names a specific verb ('look up'), a resource ('business entity'), and the accepted identifier types (name, CIF/NIF, EU VAT, LEI). It is immediately clear what the tool does, though it does not explicitly differentiate itself from siblings like search_entities or get_full_dossier.

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 identifier list and 'look up any business entity' imply when the tool should be used, but the description gives no explicit guidance about alternatives or exclusions. With sibling tools such as verify_vat, search_entities, and get_full_dossier, the routing decision is left to inference.

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 indicate read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral context: geographic restriction to Spain, public surface only, ranked results, and alias resolution behavior documented in _meta.sector_resolved_from. No contradictions.

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 plus a concise note on sector behavior. It is front-loaded with the core purpose, and every sentence adds necessary 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?

Given that the schema covers all parameters and an output schema exists, the description is reasonably complete. It explains geographic scope and ranking, though it does not mention pagination or result limits beyond the schema's max. Minor gap, but overall sufficient for a tool with good structured metadata.

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 adds value beyond schema by explaining that sector is a closed vocabulary with aliases that resolve to canonical slugs, and provides example city names. The param info is useful for correct usage.

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 purpose: find competitors based on sector and city in Spain. It uses specific verbs ('Find') and resources ('competitors') with key filters. The scope is well-defined and distinguishes from sibling tools like search_entities.

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: Spain-only, public surface, and notes that sector is a closed vocabulary with alias resolution. However, it does not explicitly state when not to use this tool nor contrast with alternatives like search_entities or entity_lookup, leaving some implicit guidance.

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, openWorldHint=true, and destructiveHint=false. The description adds critical context beyond annotations: it reveals the machine-layer URL structure, the exact data format (JSON-LD @graph), and the 'fail-closed' behavior that prevents confusion with corporate marketing. This is precisely the kind of behavioral detail annotations alone cannot 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 extremely dense and front-loaded: two sentences with zero waste. The first sentence identifies the exact action, resource, and URL pattern. The second sentence provides critical usage guidance (path sourcing) and behavioral guarantee (fail-closed). Every clause serves a distinct 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 the existence of an output schema (covering return values), a clear input schema (100% coverage), and strong annotations, the description is complete for an agent: it explains what the tool retrieves, how to get the right path, and what failure behavior to expect. A 5 would require mentioning a prerequisite (e.g., 'entity_lookup must be called first to obtain the canonical_url') or potential error 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% with each parameter having a description and regex pattern. The description reinforces the path-segment nature of the parameters ('country, sector, city, slug path segments') but adds no new constraints or semantics beyond what the schema already provides. A 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 uses specific verbs ('Retrieve the Schema.org JSON-LD @graph') and names the exact resource ('Entia Home (machine layer at /v1/identity/{country}/{sector}/{city}/{slug}.jsonld)'). It clearly distinguishes itself from siblings like 'get_showcase' and 'entity_lookup' by detailing the path structure and data format.

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 that the path must come from 'entity_lookup / showcase (canonical_url)' and clearly excludes using 'cif/q'. It does not, however, explicitly state when NOT to use this tool compared to siblings like 'get_entity_home_projection' or 'get_full_dossier', which would elevate it to 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: the snapshot is served from a specific R2 file, has the same truth as a public HTML/JSON-LD twin, and no ad-hoc enrichment is performed. This goes beyond the annotations by clarifying source and consistency.

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 tightly packed sentences, each earning its place: first sentence states the action and content, second establishes truth equivalence, third explains the backend and constraint. No filler, jargon overload, or repetition of schema fields. Front-loaded with the core verb and resource.

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 existence of a full output schema and comprehensive annotations, the description covers key contextual aspects: what the snapshot contains, its relationship to the public twin, and the serving mechanism. The only minor gap is the lack of guidance on when to use this vs sibling tools, but with an output schema present and all parameters documented, the description is largely 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% – every parameter has a clear description in the input schema. The tool-level description does not add further meaning to any parameter (e.g., it does not elaborate on the slug or country formats beyond what the schema provides). Baseline 3 is appropriate because the schema already 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 specific verb 'Read' and a precise resource 'materializer snapshot entia.entity_home_projection.v1'. It clearly states the snapshot contains 'claims + projection + policy' and links to the public twin. This level of specificity leaves no ambiguity about what the tool does, and the implementation detail 'no ad-hoc MCP enrichment' further sharpens the scope.

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?

While the description implies the tool is suitable for obtaining the canonical projection snapshot, it does not explicitly state when to prefer this tool over sibling tools like get_entia_home or get_full_dossier. There is no mention of exclusions or alternative tools, leaving the agent to infer usage context from the tool name alone.

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, openWorldHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context beyond annotations: it is an 'Aggregator' that combines four sources 'in parallel' and returns a large field set, which informs expectations about scope and data provenance.

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 exceptionally compact: scope ('90+ fields in one call'), mechanics ('4 ENTIA sources in parallel'), and use case ('due diligence/KYB') each get a short, meaningful clause. There is no wasted text, and the key aggregation fact is 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?

With a read-only, idempotent annotation profile, a single well-documented parameter, and an output schema present, the description does not need to explain return values. It provides the essential behavioral identity, source composition, and intended use, leaving no significant gap for an agent deciding to invoke it.

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%: the single 'query' parameter already documents accepted formats ('Company name, CIF/NIF, EU VAT, or LEI'). The description adds no additional parameter-level meaning beyond referring to the target as an entity, 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 clearly identifies the tool as an aggregator returning '90+ fields about an entity in one call' and names the four combined sources. It conveys a broad entity dossier concept but does not explicitly contrast it with sibling lookup tools like entity_lookup or search_entities.

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 states a target use case ('Killer tool for due diligence/KYB'), indicating when an agent would want comprehensive entity intelligence. However, it does not provide explicit when-to-use vs alternatives guidance or exclusions, leaving selection partially to inference.

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 indicate read-only, idempotent, and open-world characteristics. The description adds 'Live' which suggests real-time data, but does not elaborate on caching, update frequency, or any limitations. The behavioral transparency is adequate given the rich annotations but could be improved.

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 sentence, front-loaded with the key concept 'Live platform stats'. It is efficient and to the point, with no filler.

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 simplicity (zero parameters, output schema exists), the description is largely complete. It lists the major statistics included. However, it does not clarify whether these are aggregated across all users or any other scope. The output schema likely fills in the gaps, so it's acceptable.

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 tool has no parameters, so the schema is fully covered. The description adds value by hinting at the output fields (entities count, countries, sources, homes published), which provides context beyond the empty schema. This is helpful for an agent to understand what the tool returns without inspecting the output 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 clearly states the tool returns 'Live platform stats' and lists the specific data points (entities count, countries, sources, homes published). This distinguishes it clearly from sibling tools that focus on individual entities or specific lookups.

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?

No explicit usage guidance is provided. The description implies it is for obtaining overall platform statistics, but does not specify when to prefer this over tools like search_entities or get_full_dossier. The intended use case is understood from context but not articulated.

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 read-only, idempotent, and non-destructive behavior. The description adds meaningful behavior beyond that: it explicitly says the operation is FREE and does not consume quota, and notes that results are curated rather than exhaustive. This is useful operational context for an agent deciding whether to invoke it.

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 short sentences communicate scope, cost behavior, and intended use with no filler. The most important qualifier, 'does not consume quota', is front-loaded. 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?

This is a simple, optional-parameter, read-only sampling tool with a full output schema and complete parameter documentation. The description supplies the missing operational context—curated, free, quota-free, exploratory—so an agent has everything needed to invoke it correctly without additional inference.

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 limit and ategory well. The description's mention of 'IBEX35 + EU' loosely aligns with the category enum values but adds no new parameter information beyond what the schema 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 clearly identifies the tool as returning curated IBEX35 and EU entity examples, which distinguishes its purpose as a sampler/exploration tool. It lacks an explicit verb like 'returns' or 'retrieves', and it does not directly contrast with sibling tools, but the resource and intent are clear.

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 phrase 'Use to explore data depth' gives a clear intended context, and the quota note helps the agent know when cost is a concern. However, it does not explicitly state when to prefer this over alternatives such as search_entities or entity_lookup, nor does it provide 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 declare this as read-only, open-world, idempotent, and non-destructive. The description adds useful behavior beyond that: it defines the output semantics (colegiado number, college, specialty, status) and scopes the domain to 24 Spanish verticals. There is no contradiction with 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?

Two tight sentences with no filler. The core action is front-loaded, followed by a compact list of return fields. Every word contributes.

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 a 2-parameter schema with 100% coverage, an output schema, and strong safety annotations, this description is complete for an agent to select and invoke the tool correctly. It covers what the tool does, its scope, and what it returns.

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 does not add parameter-specific details beyond what the schema already states, but it does reinforce that the query is for professional identity and that verticals are health/legal/psychology domains. That is adequate but not additive.

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, 'Verify', and a concrete resource: professional registrations across 24 Spanish health/legal/psychology verticals. It also tells the agent what result to expect (colegiado number, college, specialty, status), which sharply distinguishes it from broader siblings like entity_lookup or search_entities.

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 phrase 'Verify professional registrations' makes the intended use case clear: an agent should call this when confirming a professional's credential status. It does not explicitly name alternatives or exclusions, but the verification framing provides a distinct context among 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the description's primary job is to add context. The description does this by stating rate limits (5 req/min, 30s timeout) and the scope of analysis (SSL, DNS, etc.). However, it does not explicitly disclose what happens on failure (e.g., partial results or timeout), which would further enhance transparency.

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 one sentence with bullet-like clarity, covering purpose, components, output, and constraints without fluff. Every sentence earns its place, making it easy for an agent to parse quickly.

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?

Despite having 3 parameters and an output schema (which may document return values), the description is complete for a tool with strong annotations. It explains the audit's components, output format, and rate limits. The combination of annotations and description covers safety (read-only, idempotent), usage (rate limits, domain specificity), and output (risk score range).

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 three parameters. The description adds meaning by linking the domain parameter to the audit's purpose but does not clarify the optional parameters' impact on the audit (e.g., does sector_id change the risk weighting?). A higher score would require explicit parameter behavior details.

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 runs an AI-readiness and digital risk audit on a specified domain, listing the components analyzed (SSL, DNS, structured data, LLM visibility) and the output (risk score 0-100). This explicit verb+resource combination distinguishes it from sibling tools like entity_lookup or get_competitors, which have different 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 provides clear context that the tool is for auditing a domain, and the sibling tools list helps an agent understand alternatives. However, it does not explicitly state when NOT to use this tool (e.g., for a single metric check or when rate limits are critical) or specify prerequisites like domain ownership verification.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safe, non-mutating, and idempotent nature is covered. The description adds valuable context beyond annotations: the 'sector' parameter has alias resolution (e.g., 'abogados' resolves to canonical slug) with the response declaring the translation in _meta.sector_resolved_from. It also explains the access level difference between anonymous and authenticated callers. These are important behavioral traits not captured by 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 two sentences of core purpose plus one sentence each for sector details and authentication behavior. It is well front-loaded with the main purpose and examples. The only minor issue is that the sector detail could be slightly more compact, but overall every sentence justifies its presence and it remains concise at around 70 words.

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 complexity (5 parameters, 1 with a large enum), 100% schema coverage, and existence of an output schema, the description covers all necessary aspects: what the tool searches, what parameters are available with important behavioral notes (sector alias resolution, auth-based access levels), and examples. The output schema presumably documents the return format, so the description does not need to. All dimensions are sufficiently 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%, so the schema already documents all five parameters with types, constraints, and descriptions. The description adds value by explaining that 'sector' is a closed vocabulary with alias resolution behavior and that aliases like 'abogados' resolve to canonical slugs with response metadata. It also clarifies the 'city' parameter with example city names beyond what the schema provides. This is a clear addition of meaning beyond 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 clearly states the tool searches verified entities across 10 countries by various criteria (name, keyword, country, city, sector). It gives concrete query examples like 'find me a dentist in Madrid' and 'list law firms in Barcelona', which explicitly differentiate it from sibling tools that do entity lookups by ID (entity_lookup, professional_lookup) or retrieve dossier/competitor data (get_full_dossier, get_competitors). The verb is specific and the resource is well-defined.

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 usage context by mentioning search queries and filters, and gives example natural language queries. It also notes that anonymous callers get limited results while authenticated TRACE+ keys unlock full records. However, it does not explicitly state when NOT to use this tool in favor of siblings like entity_lookup or professional_lookup, which would be useful for disambiguation.

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 declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the description does not need to restate safety. The description adds value by specifying the return shape ({valid, name, address, vat_number, country}), which complements the annotations and output schema. It also mentions 'Real-time' and 'VIES (27 countries)', providing context beyond annotations. No contradictions.

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 sentence (plus a return type snippet) that is fully front-loaded. Every word provides value: 'Real-time', 'EU VAT validation via VIES (27 countries)', and the return structure. No wasted or redundant 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?

The tool has a clear purpose, good annotations, and an output schema. The description adds the VIES source and return fields, making it complete for most common use cases. However, it does not address edge cases like VIES unavailability (common in production) or the fact that no parameters are required (a subtle issue). Given the tool's simplicity, this is slightly incomplete but still strong.

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%—all three parameters (q, vat, query) are documented in the schema with examples and descriptions. The tool description does not add any parameter-specific meaning beyond what the schema provides, such as clarifying when to use each alias. Baseline 3 is appropriate since 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 ('validate'), a specific resource ('EU VAT'), and names the authoritative source ('VIES (27 countries)'). It distinguishes itself from sibling tools (e.g., entity_lookup, professional_lookup) by focusing on VAT validation rather than entity searches or risk audits. The one-line purpose is immediately clear.

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 this is for real-time VAT checks against EU countries, but provides no explicit guidance on when to use it versus alternatives (e.g., when to prefer this over entity_lookup for VAT data). There are no exclusions or prerequisites stated, such as requiring a specific VAT format or noting VIES downtime. The context is clear but lacks 'when-not' details.

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, openWorldHint, idempotentHint, and destructiveHint as false, providing a strong behavioral baseline. The description adds the 17 data blocks (income, employment, demographics, etc.), which goes beyond annotations by specifying the content scope and confirming it's a non-destructive read-only operation.

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 sentence with 15 words, front-loading the core purpose and listing the key data blocks concisely. Every word earns its place with no redundancy or fluff.

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 single-parameter tool with 100% schema coverage, read-only annotations, and an output schema present, the description is complete. It explains what the tool does, what it applies to, and what the output contains, without needing to detail return values since the output schema handles that.

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 a clear description for the postal_code parameter, including an example. The description adds conceptual meaning by summarizing what data the tool returns (17 blocks), but doesn't detail each block, which is acceptable given the output schema exists.

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 'socioeconomic profile' and clearly identifies the resource 'Spanish postal code'. It lists 17 data blocks, which distinguishes it from sibling tools like entity_lookup or get_competitors, and the input schema confirms it takes a single postal code parameter.

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 it's for a Spanish postal code and provides an example (28013 = Madrid Gran Vía), making the usage context clear. However, it doesn't explicitly say when not to use it or mention alternatives among the listed siblings, such as get_full_dossier for broader entity data.

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