ENTIA Entity Verification

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

With no annotations provided, the description carries the full burden of disclosure. It mentions the API key requirement (auth) and describes the output structure, but does not explicitly state whether the operation is read-only, idempotent, or has any side effects. The description implies a query operation without destructive behavior, but this is not confirmed.

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 (three sentences) and front-loaded with the core purpose. Every sentence adds value: the first states the return type and nodes, the second adds verification and territorial data, the third notes the API key requirement. No unnecessary 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 a single parameter and no output schema, the description adequately covers what the tool returns (4-node @graph with verification flags and territorial data) and an important prerequisite (API key). It could be considered complete for a profile retrieval tool, though it omits details on how verification flags are structured or how to interpret territorial data.

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 for the single 'query' parameter, which already explains it expects a company name or domain and the result structure. The tool description adds little beyond restating this, so the schema carries the load. The description provides no additional syntax or format details 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 returns a full AI-ready JSON-LD profile for any entity, specifying the four nodes included (Organization, Place, LocalBusiness, PostalAddress) and mention of verification flags and territorial data. This distinguishes it from siblings like entity_lookup or zone_profile by emphasizing the AI-ready formatted output tailored for direct citation.

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 notes that an API key is required, which is an important usage guideline. However, it does not explicitly state when to use this tool versus alternatives (e.g., when a simpler entity lookup is sufficient) or provide exclusion criteria. The guideline is minimal and lacks comparative context.

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

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

No annotations provided, so description carries full burden. It discloses return data types, coverage numbers (40M+ acts since 2009), geographical scope, and API key requirement. However, it does not mention rate limits, error handling, or side effects.

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 concise paragraph listing key data points and constraints. It front-loads the main purpose. Could be slightly more structured but 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?

No output schema exists, so description should compensate. It lists return data types but not format. Missing behavior on missing companies, pagination, or error cases. Adequate but not fully complete for a complex lookup tool.

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?

Only one parameter 'company' with 100% schema coverage. Description adds value by specifying it accepts company name or CIF, which is not in schema description. Baseline 3 is elevated due to this added clarity.

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 full BORME corporate history with specific data types (acts, officers, capital, etc.) and coverage. It distinguishes from siblings by specifying Spain-only scope and API key requirement.

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 (Spain only, API key required) but does not explicitly state when to use this tool versus alternatives like entity_lookup or search_entities. It implies use for Spanish companies but lacks clear when-not 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?

With no annotations, the description fully discloses behavior: returns identity data, trust score (VERIFIED/PARTIAL/UNVERIFIED), cross-verification against BORME, VIES, GLEIF, OFAC. It transparently notes enrichment depth varies by country and advises checking the data_coverage field. 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 three sentences covering purpose, return data, coverage, limitations, and guidance. No wasted words; front-loaded with the core action. Every sentence earns its place.

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

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

Given the tool's complexity (multiple identifier types, cross-references, country-specific depth) and no output schema, the description explains return fields, coverage scope, and how to interpret results. It is complete enough for an agent to use 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?

The single parameter 'q' has full schema coverage, but the description adds significant value: explains accepted input types (name, CIF/NIF, EU VAT ID, LEI), provides examples, and states auto-detection. This goes beyond the schema's description.

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: 'Look up any business entity by name, CIF/NIF, EU VAT ID, or LEI code.' It specifies the resource and multiple lookup methods, distinguishing it from siblings like search_entities (broader search) and lookup_by_domain (domain-based). The verb 'look up' is specific and actionable.

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 implicitly tells the agent when to use this tool (when you have a specific entity name or identifier). It provides coverage scope ('34 countries') and examples. However, it does not explicitly contrast with siblings like search_entities or lookup_by_domain, nor does it state when not to use it. The context makes it clear enough.

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?

Describes output as ranked entities with identity, location, and sector matching; implies safe read operation despite no annotations, though lacks details on authentication failure 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?

Three sentences cover purpose, output, and usage guidance with no filler; front-loaded with core action.

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 no output schema, description adequately explains returns but lacks detail on output structure; adequate for the 3-parameter tool.

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?

All parameters are fully described in the schema (100% coverage), and the description adds no extra semantic value beyond mentioning sector and geography.

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?

Clearly states the tool finds real competitors by sector and geography from a specific corpus, distinguishing it from sibling entity lookup or search 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?

Mentions using a dedicated skill for workflow guidance and notes API key requirement, providing context but not explicit alternatives or 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?

With no annotations, the description carries full burden for behavioral disclosure. It explains the tool returns up to 4 nodes with specific content, mentions ES-only data, and states no API key is required. However, it does not specify the response format in case the entity does not exist (e.g., empty result or error), which is a minor gap.

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 dense paragraph that efficiently packs purpose, output details, limitations, and usage guidance. It is not overly long, though it could be slightly more structured with bullet points for the four nodes.

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 input schema fully covers parameters and there is no output schema, the description adequately explains the output structure (four nodes) and their contents, plus constraints. It lacks details on error handling or exact return format, but overall is complete for a retrieval tool.

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 each parameter already having a clear description in the schema. The description adds context by tying the four parameters together as a path and listing them, but does not provide significant additional 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 it retrieves the full Schema.org JSON-LD @graph for a registered entity's Entia Home page. It lists the four specific nodes returned, which aligns with the required path parameters. It also distinguishes from the sibling `search_entities` tool by advising to use that if the exact path is unknown.

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 tells when to use this tool: when you have the exact path (country, sector, city, slug). It provides guidance on when not to use it: if the path is unknown, use `search_entities` first. It also notes that only ~500K published pages exist, setting correct expectations.

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, description carries burden. It discloses parallel aggregation, typical latency, API key requirement, and geographical scopes (ES only, EU only). However, it does not explicitly state read-only nature, error handling, or what happens for non-EU/non-ES companies.

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 sentences, each purposeful: purpose+source enumeration, usage guidance, efficiency claim, practical caveats. No redundant information, well front-loaded with 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?

Tool is complex (aggregating 4 sources, 90+ fields) with no output schema. Description gives high-level idea but omits specific fields or structure of the dossier. Agent may need to infer from component tool schemas, which is not ideal for full understanding.

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 has 100% description coverage for single 'query' param, but description adds value by listing accepted input types (name, CIF/NIF, EU VAT, LEI) beyond the schema's generic description. This provides practical guidance for the agent.

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?

Description clearly states verb 'Return', resource 'complete dossier', and specifies 90+ fields from 4 named sources. It distinguishes from sibling tools by naming them as components and highlighting that this tool replaces 4 separate calls.

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

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

Explicit usage contexts: 'due diligence, KYB, or when the user asks for everything about a company'. Implicitly suggests when not to use (if only one source needed) via 'single call replaces 4 separate tool calls'. Also provides latency and API key requirement.

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 provided, but the description fully covers behavioral traits: 1-hour server-side caching, no API key required, and clarification that total_entities includes unqualified entries. 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?

Two clear, front-loaded sentences with no superfluous information. Every sentence adds value.

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 zero parameters and no output schema, the description adequately covers the tool's purpose, caching, authentication, and data interpretation. Complete for a straightforward stats tool.

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?

No parameters exist (empty input schema, 100% coverage baseline). Description adds meaning by listing the specific statistics returned, which compensates for the absence of params.

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 ENTIA platform statistics and lists specific metrics (total entities, country coverage, etc.). It distinguishes from sibling tools like entity_lookup and search_entities which focus on individual 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 description explains the tool provides real-time stats (with cache) but does not explicitly state when to use it versus siblings or offer exclusions. Usage context is implied but not definitive.

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, but description discloses free, no quota, no API key. For a zero-parameter read-only tool, this is sufficient. Doesn't describe output format, but acceptable.

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 wasted words. Key info front-loaded: what it is, cost, usage, requirements.

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?

Simple tool with no parameters and no output schema. Description covers purpose, usage context, and cost. Could mention example outputs, but not necessary for a showcase.

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?

No parameters, schema coverage 100%. Description adds meaning about data content (curated IBEX35 + EU entities), which is valuable despite zero params.

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?

Clearly states it provides curated IBEX35 and EU entity examples, free and no quota. Distinct from siblings like search_entities or borme_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?

Explicitly says use to explore data depth before purchasing higher tiers. Notes free and no API key required. Lacks explicit when-not, but implied for exploration.

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?

Since no annotations are provided, the description carries full burden of behavioral disclosure. It reveals the tool is not yet functional (returns 501) and automatically normalizes domains. It does not describe the expected return value when functional, but given the current status, this is adequate.

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: first states the core purpose, second conveys status and workarounds. No redundant or extraneous content; every sentence adds value.

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 single parameter, lack of output schema, and non-functional status, the description informs about purpose, state, and alternatives. It could mention the expected return type upon implementation, but is otherwise complete for current usage.

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% coverage with a single parameter 'domain' described in detail (examples, normalization). The description adds context ('business entity') but does not provide additional parameter semantics beyond the schema; thus 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 the tool's purpose: 'Identify the business entity associated with a website domain.' It distinguishes itself from siblings like entity_lookup and search_entities by explicitly mentioning them as alternatives, showing differentiation.

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 notes that the tool is 'Coming in v1.1 — currently returns 501,' advising against current use. It provides concrete workarounds: 'use entity_lookup with company name, or search_entities with the domain.' This covers when-not-to-use and alternatives.

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

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

No annotations are provided, so the description carries full behavioral disclosure burden. It mentions the tool covers 24 verticals and returns specific data, and notes the API key requirement. However, it does not disclose rate limits, data freshness, or any side effects. The description is adequate but not comprehensive.

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 that efficiently conveys the core capability and key details. It is front-loaded with the main action. However, the list of verticals could be more readable (e.g., bullet points) without losing conciseness.

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 only one parameter and no output schema, the description provides sufficient context: what it does, which registries it covers, what fields it returns, and that an API key is required. It does not cover error handling or edge cases, but overall it is fairly complete for the tool's simplicity.

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 one parameter well-described in the schema. The description adds value by listing the specific registries and output fields, giving concrete examples of what the query can be and what results to expect. This complements the schema effectively.

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's purpose: verifying professional registrations across 24 specific Spanish verticals. It lists concrete registries (REPS, CGAE, COP, etc.) and the return fields (colegiado number, college, specialty, status), making it highly specific and distinguishable from sibling 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 implicitly suggests when to use the tool (for verifying Spanish professional registrations) by listing covered verticals. However, it provides no explicit guidance on when not to use it or how it differs from siblings like entity_lookup or verify_vat. The mention of 'API key required' is a requirement, not usage context.

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

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

Since no annotations are provided, the description carries full disclosure burden. It discloses the operation is slow, requires authentication, and has rate limits. It also describes the output (risk score, gaps). However, it does not explicitly state that the operation is read-only and non-destructive, though the term 'audit' implies it. Missing idempotency details.

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: four sentences with no fluff. It front-loads the core purpose, then details checks, then output interpretation, then operational warnings. Every sentence adds value.

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 tool with three parameters and no output schema, the description is highly complete. It explains what the tool checks, what the score means (with actionable threshold), and operational constraints. It covers input, output, and behavior without leaving major gaps.

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

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

The input schema has 100% description coverage, so the schema already describes each parameter. The description adds value by providing examples for domain and sector_id, and by explaining that the audit checks SSL, DNS, etc., which gives context to the parameters. This extra context justifies a score above baseline.

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

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

The description clearly states the tool's function: running an AI-readiness and digital risk audit on a domain. It lists specific checks (SSL, DNS, structured data, LLM visibility) and output (risk score 0-100 with gaps). This distinguishes it from sibling tools like entity_lookup or search_entities, which are search/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 description provides important usage context: it is a slow operation (up to 30s), requires an API key, and has a rate limit of 5/min. This helps the agent decide when to call it. However, it does not explicitly mention when not to use it or compare it to siblings, leaving some ambiguity.

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 varying data coverage by country, the need to check data_coverage in results, and an API key requirement. Missing details like rate limits, pagination, or error handling, but the provided behavioral context is substantial.

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 sentences efficiently cover purpose, coverage nuances, usage guidance, and authentication. No redundant or vague statements; every sentence adds value.

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 no output schema, the description mentions data_coverage but not other result fields. It provides good coverage of search scope and pre-usage guidance (use before get_entia_home). Missing output structure hint, but the tool's primary purpose is clear enough for selection.

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 baseline is 3. The description restates parameters briefly but adds little beyond schema descriptions (e.g., 'by name, keyword, country, or sector'). The country coverage nuance is helpful but not parameter-specific.

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 action: 'Search 5.5M+ registered entities across 34 countries by name, keyword, country, or sector.' It distinguishes itself from sibling tools by referencing get_entia_home and providing country-specific coverage details.

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 advises to 'Use this to find entities before calling get_entia_home,' providing a clear when-to-use context. However, it does not explicitly exclude other siblings like entity_lookup or lookup_by_domain, nor does it specify when not to use this tool.

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 carry full behavioral disclosure. It mentions real-time validation, required API key, and return object structure, but does not elaborate on rate limits, idempotency, or whether it modifies state. The return format is described, which is helpful.

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 concise sentences that quickly convey purpose, input format, and output structure. No filler words; every sentence adds essential 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 tool with one parameter, no output schema, and no annotations, the description reasonably covers purpose, input constraints, output fields, and authentication requirement. It lacks usage scenarios or error behavior, but is sufficient for basic understanding.

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 'q' is well-described in the schema (100% coverage). The description adds value beyond schema by providing concrete examples (ESA28015865, A28015865) and explaining that it accepts country prefix or bare number, which clarifies acceptable formats.

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 validates EU VAT numbers via VIES, specifies 27 countries, provides example formats, and distinguishes it from sibling tools like entity_lookup which are for broader entity searches.

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 explains the tool's function and input format, implying use for VAT validation. It mentions API key requirement as a prerequisite, but does not explicitly state when to use this tool vs alternatives, though the specialized nature is clear.

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 fully reveals the tool's behavior: lists data blocks, requires API key, and returns empty for non-Spain codes. Slightly lacks details on error handling or key acquisition.

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. Front-loaded with purpose and content list, ends with constraints. Every word 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?

Covers output categories and geographic scope well despite no output schema. Missing details on API key usage and error responses, but adequate for a simple tool.

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 schema description already explains the parameter. The description reinforces 'Spain only' but adds minimal new semantic value 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?

Clearly states it provides a socioeconomic profile of a Spanish postal code and lists 17 specific blocks. Distinguishes from siblings like entity_lookup by its geographic and thematic specificity.

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

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

Explicitly states 'Spain only' and warns that other countries return empty. Does not name alternative tools but provides sufficient context for when to use.

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