ENTIA — 5.5M Verified Entities for AI Agents

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that free callers get a trace-level identity preview and authenticated callers receive the full paid dossier, which is a useful access-tier behavior. However, it does not disclose rate limits, error behavior, or explicitly state that the operation is read-only, leaving gaps in 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 consists of two concise sentences with no redundancy. The first sentence front-loads the verb and resource, and the second adds valuable access-tier context. Every word earns its place, making it appropriately sized.

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?

While the description covers the basic purpose and access levels, it lacks essential context for an agent: without an output schema, it does not describe the response structure or what a 'trace-level identity preview' or 'full paid dossier' contains. It also fails to clarify how this tool differs from similar siblings like 'search_entities' or 'verify_vat', leaving significant gaps for tool selection and invocation.

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 already provides complete descriptions for all parameters (q, name, query), including the alias relationships and accepted formats. The description's mention of identifier types mirrors the schema's content and adds no additional semantic detail, so a baseline score of 3 is appropriate given the 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 clearly states the tool's function: looking up business entities by name, CIF/NIF, EU VAT, or LEI. It uses a specific verb ('look up') and resource ('business entity'), making the core purpose obvious. However, it does not explicitly differentiate from sibling tools like 'search_entities' or 'verify_vat', which could cause confusion.

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 context on when to use the tool (looking up entities by identifiers) and mentions the free vs. authenticated access levels, which indicates a distinction in client states. However, it does not explicitly state when to prefer this tool over alternatives like 'search_entities', nor does it mention exclusions, leaving usage guidance implied rather than explicit.

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?

No annotations are provided, so the description must convey behavior. It discloses that results are ranked and filtered by 'real' competitor status and matching criteria. However, it omits details like read-only nature, possible rate limits, or empty-result 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?

Two sentences, with the primary purpose front-loaded. Every word contributes; no redundancy or 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?

No output schema and no annotations mean the description must define returns. It mentions 'ranked entities' but not the response structure, pagination, or no-result case. For a simple 3-parameter lookup, it is adequate but leaves 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 descriptions already cover sector and city with examples. The description adds the concept of identity + location + sector matching but does not explain the 'limit' parameter, which lacks a schema description. With 67% schema coverage, the description adds moderate value but not complete compensation.

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 finds 'real competitors' in a sector and geography, and specifies 'Ranked entities with identity + location + sector matching.' This concretely distinguishes it from sibling tools like search_entities or 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?

The description gives a clear context for when to use (same sector and geography), implying competitor identification. It does not explicitly mention alternatives or when not to use, but the purpose is specific enough to guide selection.

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

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

With no annotations provided, the description carries the burden and does well by revealing the fail-closed behavior and the fact that it never returns ENTIA corporate marketing as if it were the entity. It also discloses the endpoint format and the need for a pre-resolved canonical path. It does not explicitly address error conditions or response envelope, but the core behavioral guarantee is present.

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 deliver a high density of useful information with no filler. The first sentence states the core purpose and endpoint, the second clarifies input acquisition, and the third provides a safety guarantee. Every sentence earns its place.

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

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

For a read-oriented retrieval tool with 4 required params and no output schema or annotations, the description covers the essential context: exact endpoint, path construction, source for parameter values, and a fail-closed guarantee. The agent has enough information to invoke it correctly and interpret its machine-readable nature.

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 already covers all four parameters with descriptions, examples, and patterns (100% coverage), so the baseline is 3. The description adds value by clarifying these parameters are path segments, that cif/q are not acceptable, and that the canonical_url from entity_lookup/showcase is the intended source, which goes 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 retrieves the Schema.org JSON-LD @graph for a specific entity's Entia Home, with an explicit endpoint pattern. It distinguishes itself from related tools by emphasizing the machine layer and path-based addressing, and distinguishes from entity_lookup/showcase by noting it is the actual retrieval tool after obtaining the path.

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 the required path segments (country, sector, city, slug) and what not to use ('not cif/q'). It also directs the agent to obtain the path via entity_lookup or showcase (canonical_url), providing clear guidance on how to prepare inputs and when this tool should be used.

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?

Without annotations, the description carries the disclosure burden. It does mention 'Read' (implying safe operation), 'no ad-hoc MCP enrichment' (no processing side effects), and the R2 storage source. However, it does not disclose potential errors, rate limits, or the effect of the include_render_context parameter.

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, each providing distinct value: purpose, source parity, and implementation note. It's tight and front-loaded, though the final sentence could be seen as implementation detail.

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 tool with no output schema, the description states the data content (claims, projection, policy) and the lack of enrichment, but it omits the return format and does not mention the include_render_context toggle that affects payload size. This is a moderate 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 covers 100% of parameters, and the description adds no additional parameter semantics. It doesn't reference any parameter or explain how they're used beyond what the schema already states. 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 states a specific verb ('Read') and a specific resource ('materializer snapshot entia.entity_home_projection.v1'), and clarifies content ('claims + projection + policy'). It doesn't explicitly differentiate from siblings like get_entia_home, but the 'no ad-hoc MCP enrichment' hint provides a distinction.

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 context ('Same truth as the public ficha') but no explicit guidance on when to use this tool versus alternatives like get_entia_home or get_full_dossier. The 'no ad-hoc MCP enrichment' implies a use case but is not framed as an exclusion.

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?

With no annotations, the description must carry the full transparency burden. It discloses that the tool aggregates in parallel across four sources, which is useful behavioral context. However, it does not explicitly state that it is read-only, mention auth requirements, error behavior, or potential data incompleteness if one source fails.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded, using two sentences to convey the aggregator nature, the sources combined, and the target use case. There is no wasted wording.

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

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

The description covers the tool's purpose, data sources, and intended use, which is sufficient for a simple single-parameter aggregator. However, it does not describe the output structure (since no output schema exists) or edge-case behavior, leaving a minor 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?

The single parameter 'query' is fully described in the schema with examples of accepted values (company name, CIF/NIF, EU VAT, LEI). The description adds no extra semantic detail about the parameter, so the baseline 3 applies 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 clearly states it is an aggregator that returns 90+ fields about an entity in one call, combining four specific ENTIA sources (identity, zone, BORME, VIES). This distinguishes it from siblings like verify_vat or zone_profile, making its purpose unambiguous.

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 mentions use for 'due diligence/KYB', giving clear context. It implies this is the comprehensive alternative to more specific lookups, though it does not directly name alternatives or state when not to use it.

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?

With no annotations, the description carries the full burden. It mentions 'live' to imply real-time data and lists the stats, but it does not disclose whether the operation is read-only, any caching behavior, or the response format. For a simple stats tool, this is adequate but not rich.

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, efficient sentence, front-loaded with the core concept ('Live platform stats') and using a colon to list details. No unnecessary words or repetition.

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 zero-parameter tool with no output schema, the description is relatively complete. It clarifies the scope of stats and indicates the 'live' nature. However, it lacks notes on access requirements, freshness guarantees, or any global vs. scoped behavior, leaving minor 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?

There are zero parameters, so the baseline is 4. The description adds value by enumerating the exact metrics returned (entities count, countries, sources, homes published), giving the agent useful context about the tool's output beyond the empty 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 identifies the tool as providing live platform stats with specific metrics (entities count, countries, sources, homes published). This is distinct from sibling tools like entity_lookup or get_competitors, which focus on individual entities or competitor data.

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 guidance is provided on when to use this tool versus alternatives. It does not state preferred contexts, exclusions, or scenarios where another tool might be more appropriate. The description simply states what it does without usage direction.

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?

With no annotations provided, the description carries the burden of disclosure. It adds valuable behavioral context by stating the tool is FREE and consumes no quota, and describes examples as 'curated' (suggesting a static set). It does not specify the exact return shape, but for a showcase tool this is sufficient.

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 concise, using three short clauses: a statement of content, a cost/behavior note, and usage guidance. Every word contributes value, 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 zero-parameter tool with no output schema and no nested objects, the description is adequately complete. It covers purpose, cost, and usage intent. It could optionally mention that the output is a list of examples, but 'examples' already implies this, so the gap is minimal.

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 zero parameters, so the baseline is 4. The description adds no parameter details because none exist, but that does not detract; the schema already has 100% coverage (empty properties).

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 curated IBEX35 and EU entity examples, with an explicit use case to explore data depth. This distinguishes it from sibling tools like entity_lookup and search_entities, which serve 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?

The phrase 'Use to explore data depth' gives clear context for when to invoke this tool, implying it is not for targeted entity searches. However, it does not explicitly name alternative tools or provide when-not-to-use 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?

No annotations are provided, so the description carries the burden. It discloses the return fields, which is useful, but fails to mention any typical behavioral caveats such as whether the operation is read-only, data freshness, or limitations on query formats. For a lookup tool this is adequate but not rich; it adds some value but leaves gaps.

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 concise sentences. The first sentence states the primary purpose, and the second lists return values. No redundant words; every sentence earns its place.

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

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

For a simple, single-parameter lookup tool with no output schema, the description provides the core purpose and return fields. It does not explain pagination or multiple-result behavior, but such details may be unnecessary given the tool's simplicity. It is adequately complete for its complexity.

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 already covers 100% of the parameter with a clear description ('Professional name, colegiado number, or REPS identifier'). The description adds no additional parameter-level details beyond confirming the tool's purpose, 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 uses a specific verb 'Verify' and clearly identifies the resource: professional registrations across 24 Spanish health/legal/psychology verticals. It also lists the return fields (colegiado number, college, specialty, status), making it distinct from sibling tools like verify_vat or 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?

The description gives clear context: it is for verifying professional registrations in specific Spanish verticals. While it does not explicitly mention alternatives or when not to use it, the specificity of the purpose implies appropriate usage. This matches a 'clear context, no exclusions' scenario.

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?

With no annotations, the description carries the full burden. It discloses useful operational constraints: 5 req/min rate limit, 30s timeout, and what the audit analyzes. It also implies a read-only safety profile by describing an 'audit' that 'analyzes' rather than mutates.

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 four short sentences, each adding essential information: action, analysis scope, return value, and rate/time constraints. It is front-loaded and contains 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?

The description gives a solid high-level overview, but without an output schema it only says 'Returns risk score 0-100' and omits what the full audit response contains (e.g., SSL/DNS details, structured data results). For a comprehensive audit tool, the return contract is under-specified.

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

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

Schema description coverage is 100%, so the schema fully documents all three parameters. The description adds no further parameter-specific meaning beyond mentioning 'domain' context, so the baseline score 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 opens with a specific verb and resource: 'Run comprehensive AI-readiness + digital risk audit on any domain.' It lists concrete analysis areas (SSL, DNS, structured data, LLM visibility) and a distinct output (risk score 0-100), which clearly differentiates it from sibling entity-lookup tools.

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 'on any domain' provides a clear context for when the tool is applicable, but there is no explicit guidance on when to prefer this tool over alternatives or when not to use it. No alternative sibling tools are mentioned.

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?

With no annotations provided, the description carries the full responsibility for behavioral disclosure. It reveals that output depends on authentication status: anonymous callers get a trace-level preview (name + city), while authenticated TRACE+ keys unlock full records. This is significant behavioral context that goes beyond the basic input schema, though it doesn't mention pagination, rate limits, or ordering.

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 concise: two sentences. The first sentence front-loads the main purpose and scope, and the second adds the crucial auth-dependent behavior. Every word earns its place with no redundancy or padding.

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 the absence of an output schema and annotations, the description provides a complete mental model for an agent: it specifies the geographic scope, the filter criteria, and the differential access based on authentication. This is sufficient for an agent to decide whether to invoke the tool and what to expect from the response.

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

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

The input schema has 100% description coverage, with each parameter (q, limit, sector, country) already explained. The description restates these filters (name, keyword, country, sector) but adds no new semantics beyond what the schema provides, so the baseline score 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 the action ('Search'), the resource ('verified entities'), and the scope ('across 10 countries') while enumerating the search criteria (name, keyword, country, sector). This distinguishes it from sibling tools like entity_lookup (which implies direct lookup) and get_full_dossier (which implies retrieval of a detailed report).

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 for when to use the tool: when you need to find entities by search criteria. It doesn't explicitly name alternatives or exclusions, but the search-oriented phrasing contrasts with the lookup-focused sibling names, implying this is the exploratory tool. The auth-tier distinction (anonymous vs. TRACE+) adds practical guidance on expected 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?

With no annotations provided, the description carries the behavioral burden. It discloses that validation is real-time, scoped to 27 countries, and returns specific fields, which is useful context. However, it omits details about error handling, rate limits, or authorization requirements, leaving some behavioral uncertainty.

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, information-dense sentence that front-loads the main purpose and includes the return format. It is impeccably concise with no wasted 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?

The tool is simple, and the description covers the return format and core behavior, partially compensating for the lack of an output schema. However, it doesn't address failure modes or prerequisites, which would be valuable for an agent deciding to invoke it. Overall, it's nearly complete but with a minor 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?

The input schema provides complete descriptions for all three parameters, including aliases for `q`, achieving 100% coverage. The description adds no parameter-specific meaning beyond the schema, so the 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 clearly identifies the tool as performing real-time EU VAT validation via VIES, specifies the geographic scope (27 countries), and outlines the return structure. This is a specific verb+resource combination that distinguishes it from sibling entity-related tools.

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 the tool should be used for EU VAT validation, and sibling tools show no overlapping functionality, making the use case clear. However, it doesn't explicitly state when to use this tool over alternatives or provide exclusion criteria, so it falls short of full 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?

There are no annotations, so the description carries full burden for behavioral disclosure. It does not explicitly state that the tool is read-only, has no side effects, or any limitations. It only summarizes the content returned (e.g., '17 blocks') but does not add transparency about behavior, response size, or data freshness.

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-structured sentence that immediately conveys the core purpose and then lists the content areas. Every word earns its place, and it avoids redundancy or unnecessary detail.

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 tool is a simple single-parameter lookup with no output schema, the description adequately covers the return value by listing the 17 content blocks (income, employment, demographics, etc.). It is complete enough for a basic understanding, though it could be enhanced with an example output or a note about data sources.

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 postal_code parameter already includes a clear description with an example ('28013 = Madrid Gran Vía'). The tool description itself does not add any extra meaning about the parameter, 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?

The description clearly states that the tool provides a socioeconomic profile for a Spanish postal code, and enumerates the content blocks covered (income, employment, etc.). It is specific about the resource (postal code) and the scope (17 blocks), which distinguishes it from siblings like get_full_dossier or ai_ready_profile, though it lacks an explicit verb like 'retrieves' or 'returns'.

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 no guidance on when to use this tool versus alternatives. Sibling tools include entity_lookup, get_full_dossier, and ai_ready_profile, but the description does not explain how zone_profile differs in use case or what scenarios it is intended for beyond the general description of its output.

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