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. It discloses the output structure (4-node @graph) and purpose, but does not mention any side effects, authorization needs, or whether it makes external calls. The behavior is mostly implicit.

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 long, front-loaded with the core purpose, and contains no fluff. Every word 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 single parameter and lack of output schema, the description is fairly complete: it specifies the output structure and intended use. However, more context about the tool's niche among many siblings (e.g., how it differs from zone_profile) would be beneficial.

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 description does not add new information about the 'query' parameter beyond what the schema already states ('Company name or domain'). No additional semantics are provided.

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 a JSON-LD profile with a specific 4-node @graph structure. It highlights 'AI-ready' and 'direct AI citation', which differentiates it from siblings like entity_lookup 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 phrase 'Designed for direct AI citation' gives a hint about usage context, but there is no explicit guidance on when to choose this tool over similar siblings (e.g., get_full_dossier, zone_profile). No exclusion criteria or alternatives 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?

Discloses key behavioral difference between free (trace-level preview) and authenticated (full dossier) callers. No annotations exist, so description carries full burden; it adequately covers the main behavioral trait for a read-only lookup.

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. Front-loaded with purpose, then authentication effect. Perfectly concise.

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, description mentions output difference (preview vs dossier) based on auth status. Adequate for a simple 1-param lookup tool, though could detail output structure more.

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 'q' with 100% schema coverage; schema already includes examples and constraints. Description adds marginal value beyond schema, 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?

Clearly states 'look up' verb and 'business entity' resource, specifies identifier types (name, CIF/NIF, EU VAT, LEI), and distinguishes from siblings like lookup_by_domain and 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?

Provides context on free vs authenticated callers but lacks explicit exclusions or alternatives. Mentions authentication requirement for full dossier, implying when to expect different 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, the description must fully disclose behavioral traits. It mentions ranking and matching criteria but omits details such as result limits, authentication needs, error behavior, or read-only nature. This minimal disclosure is insufficient for a tool with no other documentation.

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, both front-loaded and without unnecessary words. Every sentence adds value: first states purpose, second elaborates on matching logic. No wasted content.

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 (3 parameters, no annotations, no output schema), the description is incomplete. It lacks usage guidance, parameter details, and behavioral traits. While it covers the core purpose, it leaves significant gaps for an agent to select and invoke the tool 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 67%, and the description adds no new parameter meaning beyond the schema. The limit parameter lacks a description in both schema and description. The description mentions sector and geography but does not provide format details or constraints, failing to compensate for the coverage gap.

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 verb 'Find', the resource 'competitors', and the criteria 'same sector and geography'. It also mentions ranking, which adds specificity and distinguishes it from sibling 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?

No guidance is provided on when to use this tool versus alternatives. The description implies its use for finding competitors but does not mention when not to use it or provide context about prerequisites 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?

No annotations are provided, so the description carries the full burden. It discloses the output structure (4 specific nodes) which adds transparency. However, it fails to state that the operation is read-only, idempotent, or what happens when the entity does not exist. The verb 'Retrieve' implies safety, but explicit statement would improve transparency.

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

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

The description is a single, efficient sentence of 18 words. It immediately conveys the core purpose and the exact content of the return value. No superfluous information, making it highly concise for quick agent comprehension.

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 adequately explains the return value's structure (4 nodes). Parameters are fully documented in the schema. However, it does not mention error conditions or the meaning of 'Entia Home page'. Overall, it is mostly complete for the tool's simplicity, missing only minor behavioral context.

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 four parameters (city, slug, sector, country) have descriptions in the input schema with 100% coverage. The tool description adds no additional semantics beyond what the schema provides; it does not explain how parameters uniquely identify the entity or form the request URL. Baseline 3 is appropriate as schema already covers details.

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

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

The description clearly states the tool retrieves a full Schema.org JSON-LD @graph for an entity's Entia Home page, specifying the four nodes included. This is a specific verb+resource combination. While it distinguishes from siblings like 'search_entities' or 'get_full_dossier' by focusing on structured data for a home page, it does not explicitly differentiate from similar retrieval tools like 'get_showcase'.

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. The description does not mention preferred contexts, exclusions, or prerequisites. Given the sibling tools list, there is no indication of when this tool is more appropriate than e.g., 'ai_ready_profile' or 'entity_lookup'.

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?

Discloses parallel aggregation from 4 sources, but with no annotations, it omits failure handling, rate limits, or output format 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?

Two concise sentences front-loading the core aggregator function and use case 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?

Explains input flexibility and provides output scope (90+ fields), though lacks error behavior given no output schema.

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 already covers the single parameter with its description; the tool description adds no extra semantic meaning.

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 aggregates 90+ fields from 4 sources for due diligence, distinguishing it from simpler lookup tools like entity_lookup or zone_profile.

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?

Implies use for due diligence/KYB but doesn't specify when to avoid it or name alternatives among sibling tools.

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 burden. It does not disclose behavioral traits such as whether the tool is read-only, requires authentication, or has rate limits. The description merely lists output fields, lacking context about data freshness or latency.

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 sentence that lists key data points. It is front-loaded and contains no redundant words. However, it could be slightly more structured to better assist an agent.

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 no parameters, no output schema, and no annotations, the description is minimally adequate. It explains expected output fields but does not clarify data freshness, source, or format. A bit more context would improve completeness.

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

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

The tool has no parameters (schema coverage 100% for empty schema). Per rubric, baseline is 3. The description adds no parameter-level detail but is not required to. It provides context about what statistics are returned.

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 platform statistics listing entities count, countries, sources, and homes published. The tool name 'get_platform_stats' provides the verb, and the description specifies the content. However, it does not explicitly differentiate from siblings like 'get_entia_home' or 'get_showcase' which serve different purposes.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not state use conditions or exclusions. For example, an agent might not know if this is for current counts or historical data.

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. It discloses it is curated and free, but does not detail output format, number of examples, or any limitations. More specifics on behavior would enhance transparency.

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

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

Two sentences with no waste. The first sentence states purpose, the second highlights key features. Information is front-loaded and concise.

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

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

Given the tool's simplicity (no parameters, no output schema), the description is largely complete. It covers purpose, cost, and use case. Minor omission: details on output structure or number of examples could improve completeness.

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 no parameters, and schema coverage is 100% trivially. The description adds no parameter information, which is acceptable as none exist. Baseline 3 applies due to 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 provides curated IBEX35 and EU entity examples, with the verb 'explore' and the resource 'data depth'. It distinguishes itself from sibling tools by being a showcase of pre-built examples rather than a lookup or search tool.

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

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

The description explicitly mentions it is free and does not consume quota, guiding usage when exploring without cost. However, it lacks explicit when-not-to-use or alternative tool references, which would improve guidance.

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

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

Annotations are absent, so description carries full burden. It adds one key behavioral fact: the tool is not yet deployed (coming in v1.2). However, it does not explain what happens if invoked now (e.g., error 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 concise sentences with no wasted words. The status note is front-loaded after the purpose, which is acceptable.

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, yet description provides no hint about return format. Deployment status is useful but incomplete without explaining error behavior. Given the tool is not available, more context is needed.

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, so baseline is 3. The description does not add meaning beyond the schema's property 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?

Clearly states it looks up a business entity by domain name. Distinguishes from siblings like 'entity_lookup' which may have broader search criteria.

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 on when to use this vs other lookup tools. Does not mention alternatives or prerequisites.

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 disclose behavioral traits. It states the tool verifies registrations and returns key fields, implying a read-only lookup, but does not mention side effects, authorization needs, or rate limits. Adequate but not thorough.

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 efficiently conveys purpose, scope, and output. 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 no output schema and a single parameter, the description covers the tool's core function, supported verticals, and return fields. Minor gaps exist (e.g., error handling or confidence), but overall sufficient for a straightforward 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?

Schema coverage is 100%, so the input schema already fully describes the 'query' parameter as a professional name, colegiado number, or REPS identifier. The description adds no further parameter meaning beyond restating output fields.

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 specifies a clear action ('Verify'), a specific resource ('professional registrations'), and provides scope ('across 24 Spanish health/legal/psychology verticals'), which distinguishes it from sibling 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?

The description implies the tool is for verifying Spanish professional registrations but offers no explicit guidance on when to use it vs. alternatives or situations to avoid. Context from sibling tools is not addressed.

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. The description discloses rate limit (5 req/min) and timeout (30s), adding credibility. However, it does not mention permissions, error handling, or whether the audit is destructive.

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 efficient sentences: first states purpose and scope, second details technical constraints. No wasted words, front-loaded with key 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?

Describes outputs (risk score) and rate limits but lacks details on error cases, result structure, or how to interpret the score. Without output schema, more description would be helpful.

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 clear parameter descriptions. The description adds context about what is analyzed (SSL, DNS, etc.) but does not significantly enhance understanding of parameters 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 verb 'run', the resource 'AI-readiness + digital risk audit on any domain', and lists specific analyses (SSL, DNS, structured data, LLM visibility) and output (risk score 0-100). It distinguishes itself from siblings by being comprehensive.

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

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

No explicit guidance on when to use this tool vs. alternatives like ai_ready_profile or entity_lookup. The description implies it's comprehensive but does not set boundaries or mention 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 provided, the description partially fulfills transparency by mentioning API key requirement and rate limit (10 req/min). However, it lacks disclosure of other behavioral traits such as pagination behavior, sorting, allowed empty queries, or what constitutes a 'verified entity'. The description adds some value but is incomplete.

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 fluff. The first sentence front-loads the core purpose and filters; the second adds crucial authentication and rate-limit info. 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 tool with 4 parameters (1 required) and no output schema, the description covers the purpose and key constraints but omits return format details (e.g., fields returned, pagination). Given the complexity of a multi-country search with filters, more context on output structure would improve completeness.

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 adds context beyond the schema by specifying the geographic scope (34 countries) and the nature of data ('verified entities'). This helps the agent understand the overall domain without repeating schema details.

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

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

The description clearly states the action (search), the resource (verified entities), and the scope (34 countries, filters by name/keyword/country/sector). It distinguishes from siblings like entity_lookup and lookup_by_domain by emphasizing multi-country verification and broad filter options.

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 usage for broad entity searches across countries with filters, but does not explicitly state when to prefer this tool over siblings (e.g., entity_lookup for single entity lookup, or lookup_by_domain for domain-based search). No exclusion criteria or alternatives 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?

No annotations are provided, so the description carries the burden. It mentions real-time validation via VIES and the return structure, but fails to disclose rate limits, error handling, or any potential side effects. For a read-only validation, the lack of behavioral traits is acceptable but not thorough.

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 efficiently convey the tool's purpose, method, and return format. No wasted words, front-loaded with key 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 tool with one parameter and no output schema, the description is adequate but lacks usage context, error handling, or connection to sibling tools. It covers the basics but could be more complete.

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

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

Schema coverage is 100%, with the parameter 'q' fully described in the schema including examples. The description adds no additional meaning beyond what the schema provides, 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 the tool validates EU VAT numbers in real-time via VIES, covering 27 countries, and specifies the return fields. This is a specific verb+resource, distinguishing it from sibling tools like entity_lookup or get_competitors.

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 on when to use this tool versus alternatives, nor any prerequisites or context. Sibling tools include various lookups, but the description does not exclude or compare.

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 burden. It lists data blocks but does not disclose behavioral traits like data freshness, response size, rate limits, or whether results are cached. For a tool with no annotations, more behavioral disclosure is needed.

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?

Single sentence front-loads the purpose and key data blocks with no wasted words. Efficient and scannable.

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 and no annotations, the description could be more complete. It lists blocks but lacks details on how to interpret results or handle errors. Adequate but has gaps.

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

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

Schema description coverage is 100% (parameter has pattern and example). The description adds value by listing the 17 data blocks beyond what the schema provides, giving context on output content.

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 a socioeconomic profile of a Spanish postal code, listing 17 specific data blocks. It distinguishes itself from sibling tools like entity_lookup or get_full_dossier by focusing on location-based socioeconomic 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?

The description implies usage for getting socioeconomic data by postal code but does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusions.

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