ENTIA Entity Verification MCP

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 the tool is read-only, open-world, idempotent, and nondestructive. The description adds behavioral insight by explaining how sector aliases are resolved (e.g., `abogados` resolves to canonical slug) and that the response includes `_meta.sector_resolved_from`. This goes beyond annotations, though it does not detail rate limits or potential response variability.

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 concise (3 sentences) and front-loaded with the core purpose. The additional detail about sector vocabulary is placed naturally, but the last sentence could be slightly more streamlined to avoid over-explaining the alias resolution, though it remains valuable.

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 an output schema and clear annotations, the description covers the key aspects: purpose, sector vocabulary behavior, and geographic scope. It does not address pagination or ordering of results, which could be inferred from the `limit` parameter. For a ranking tool with clear constraints, this is nearly complete but missing an explicit statement about result ordering (e.g., by relevance).

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 significant value beyond the schema by explaining that `sector` is a closed vocabulary with aliases that resolve to canonical slugs, and that the response will indicate the resolution. It also clarifies that `city` is limited to Spanish cities, reinforcing the geographic constraint. This rich semantic guidance helps the agent avoid errors with non-canonical values.

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: 'Find real competitors in the same sector and city.' It specifies the criteria (identity, location, sector matching) and geographic scope (Spain only), which distinguishes it from siblings like `search_entities` or `entity_lookup` that likely have broader or different search capabilities.

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 guidance by specifying the geographic constraint ('Spain only on the public surface') and noting that the `sector` parameter uses a closed vocabulary with aliases. However, it does not explicitly mention when not to use this tool (e.g., for non-Spain competitors or non-public data) or compare it directly to sibling tools, though the sibling context suggests differentiation from `search_entities`.

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 cover read-only, idempotent and non-destructive semantics, so the bar is lower, yet the description still adds provenance the agent needs: the data is a materializer snapshot served verbatim from a stored object with no server-side enrichment. That tells the agent the result is canonical but not freshly computed. It stops short of stating staleness windows or refresh behavior.

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 tight sentences, no padding, with the core action front-loaded. The middle sentence about R2 sibling objects is implementation detail that helps less than the space it occupies, but nothing is redundant or bloated.

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, full parameter coverage and annotations, the safety and return-shape burdens are already carried elsewhere, and provenance is covered. The remaining gap is tool selection: a sibling named get_entia_home exists and the description never says how these differ, which is the one thing an agent cannot infer from structured fields.

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%: country, sector, city and slug all carry format/slug examples, and include_render_context documents its own default and the stripping behavior. The description adds nothing beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The verb ('Read') and resource ('materializer snapshot entia.entity_home_projection.v1 for an Entia Home') are specific, and 'claims + projection + policy' clarifies the payload. However, it never distinguishes itself from the near-named sibling get_entia_home, leaving real ambiguity about which home-fetching tool to pick.

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?

There is no explicit when-to-use or when-not guidance, and no alternative (e.g. get_entia_home, entity_lookup) is named. The only implied routing cue is 'Same truth as the public ficha HTML/JSON-LD twin — no ad-hoc MCP enrichment,' which hints at canon rather than telling the agent when this is the right call.

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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, yet the description adds real behavioral context: counts are computed live rather than cached, and Country/Entia Home values may be null and flagged _unverified until measured. That caveat prevents an agent from misreading placeholder nulls as real zero values.

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 scope (total entities and BORME acts) is front-loaded, and the data-quality caveat follows only because it changes how the result should be read.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation, and with no parameters there is little else to document. The description supplies the one thing the structured data cannot convey — that nulls are unmeasured rather than genuinely empty — though it stops short of routing the agent relative to sibling tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The description's mention of _unverified relates to output fields, which is covered by the output schema rather than parameter semantics.

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?

States a specific resource and its contents: platform-wide totals for entities and BORME acts. It is clearly an aggregate-stats tool, distinct in kind from the entity-specific lookups among its siblings, though it never names or contrasts with them explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than stated — an agent infers this is a global overview call as opposed to per-entity tools like entity_lookup or get_entity_home. No when-to-use or when-not-to-use guidance and no named alternatives are given.

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 readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds scope context ('24 Spanish health/legal/psychology verticals') and lists returned fields, but does not disclose additional behavioral traits such as external source behavior, rate limits, or missing-result handling.

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 short sentences: the first states the tool's core purpose, and the second lists the key return fields. It is front-loaded, free of filler, and every sentence adds useful 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?

For a simple two-parameter, read-only lookup with complete schema descriptions and an output schema, the description is largely sufficient. It could add a brief explicit pointer to sibling tools or an example, but nothing essential is missing for selecting and invoking 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 description coverage is 100%, with query described as 'Professional name, colegiado number, or REPS identifier' and vertical as 'Healthcare/legal vertical (dental, medicos, psicologia, ...)'. The tool description itself adds little parameter-level meaning beyond naming the vertical domains, so 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 opens with a specific action and resource: 'Verify professional registrations' across 24 named Spanish health/legal/psychology verticals. It clearly separates this tool from generic siblings like entity_lookup or search_entities, and the listed return fields make the purpose concrete.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context: use it to verify professional registration data across Spanish verticals, and it names the vertical categories. It does not explicitly mention when not to use it or point to a sibling alternative, 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 declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely non-obvious operational context: a 5 req/min rate limit and a 30s timeout, which matter for a potentially slow audit call.

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 compact sentences, each carrying distinct information: purpose, analysis scope, return value, and operational limits. The core purpose is front-loaded with zero 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?

With an output schema present and annotations covering the safety profile, the description needs mainly to convey scope and operational constraints, which it does. Only minor gaps remain, such as failure behavior or whether a partial audit is possible.

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 name, domain, and sector_id are already documented in the schema with examples and a regex pattern. The description adds no parameter-level detail (e.g., how sector_id affects the audit), so 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?

States a specific verb (run) and resource (AI-readiness + digital risk audit) with explicit scope ('on any domain') and enumerates the analyzed dimensions (SSL, DNS, structured data, LLM visibility). No sibling tool performs an audit, so the agent can distinguish it immediately.

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?

There is no when-to-use or when-not-to-use guidance and no mention of any alternative tool. 'On any domain' implies broad applicability but gives the agent no routing criteria against siblings like entity_lookup or get_full_dossier.

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

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

Annotations already declare readOnly, idempotent, open-world and non-destructive behavior, so the safety profile is covered structurally. Beyond that the description does add genuinely useful context – results are a mix of registry-backed companies and unverified public listing data, and output is tier-gated by API key level. Naming the mixed provenance is a real behavioral caveat, though it does not discuss rate limits or pagination.

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, each carrying a distinct load: capability, result provenance, routing to verification siblings, example queries, then the sector-vocabulary rule and the auth-tier rule. The most decision-relevant information (what it searches, what it returns, which sibling verifies) comes first.

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?

Five parameters, one enum and an output schema present, and the description still supplies the two things the schema cannot: the reliability of the result set and the auth-dependent result gating. Return-value detail is correctly left to the output schema, and the _meta field is mentioned only where it affects interpretation.

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 baseline is 3; the description earns above that by explaining that `sector` is a closed vocabulary, that aliases resolve to canonical slugs, and that the resolution is reported back in `_meta.sector_resolved_from`. That resolves the main ambiguity an agent would hit when it sees 80+ enum values containing both English and Spanish synonyms.

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?

States a specific verb (search) plus the resource (businesses) and the facets available (name, keyword, country, city, sector), then explicitly names the alternatives it is NOT (entity_lookup, verify_vat). An agent can separate discovery search from lookup/verification without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete usage contexts ('find me a dentist in Madrid', 'list law firms in Barcelona') and routes the agent to entity_lookup or verify_vat when a single result must be verified. It also states the access precondition: anonymous callers get a trace-level preview while authenticated TRACE+ keys unlock full records.

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 read-only/idempotent/open-world safety, so the description's job is added context — and it delivers: 'real-time' signals a live call with no caching, and the Spain/withheld_by_member_state null-name behavior is a non-obvious failure mode an agent would otherwise misread as a bad VAT number. That is exactly the kind of quirk 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?

Two sentences, no filler. The core capability leads, the return shape follows inline, and the caveat plus its remediation land last — the front-loading order matches how an agent reads a definition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so the description is not obliged to enumerate return values, yet it names the key ones cheaply. Combined with the withheld-disclosure edge case and the sibling handoff, everything needed to call this correctly and interpret a null result is present.

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 already documents q and its vat/query aliases with format examples (ESA28015865, IE6388047V), so the description correctly does not repeat them. It adds marginal value by naming vat_number among the returned fields, which loosely connects the input to output, but it adds no input syntax or constraint detail 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?

States a specific action and resource ('Real-time EU VAT validation via VIES') with the scope (27 EU countries) pinned down. It also separates itself from the sibling entity_lookup by assigning that tool the registered-name use case, so an agent can discriminate without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear routing rule: if name/address come back null with name_disclosure=withheld_by_member_state, use entity_lookup instead. That is concrete when-else guidance rather than vague context, but it only covers the fallback path — there is no explicit statement of when verify_vat should not be used (e.g. non-EU VAT or already-cached lookups).

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, openWorldHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds useful context about the breadth of returned data (17 blocks), but discloses nothing about data freshness, coverage limits, or how unknown postal codes are handled.

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?

A single, front-loaded sentence that wastes no words: it leads with the resource and scope, then lists contents. Nothing is redundant with the title or 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?

With an output schema present, the description need not explain return values, and it helpfully previews the 17 blocks. For a one-parameter read-only tool this is nearly complete; only the absence of any routing guidance to sibling tools keeps it short of a 5.

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 the single parameter is well documented in the schema, including the pattern and a Madrid example. The description adds no further parameter meaning, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific resource (socioeconomic profile) and its scope (a Spanish postal code), then enumerates the 17 content blocks it returns. This clearly distinguishes it from sibling tools like entity_lookup, professional_lookup, and run_risk_audit, which operate on entities rather than geographic zones.

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 says what the tool returns but never states when to reach for it instead of alternatives such as get_full_dossier or run_risk_audit, nor any prerequisites or exclusions. Usage is only inferable from the fact that it takes a postal code.

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