ENTIA Entity Verification

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the call is free with no API key, and the response depth is tiered (trace-level identity preview when unauthenticated versus the full paid dossier when authenticated). It stops short of stating rate limits or what the trace-level preview actually contains.

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 short sentences, front-loaded with the strongest differentiator ("FREE (no API key needed)") and then the usage trigger. The identifier list in sentence three partially repeats sentence two, a small redundancy, but nothing else is wasted.

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

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

An output schema exists, so return-shape explanation is not required, and the free-versus-authenticated response tiers are the key thing an agent needs to set user expectations. The remaining gap is disambiguation from the many lookup-adjacent siblings and what happens with no arguments at all.

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 q and its aliases (name, query) are fully documented in the schema, including formats and length bounds. The description restates the same identifier types but adds no syntax, precedence rules for when both q and name are supplied, or guidance on the empty-argument case (zero required params). 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?

States a concrete verb+resource ("Look up any business entity") plus the accepted identifier types, and enumerates the questions it answers (existence, ownership, legal name, city, sector, BORME status). It does not name or distinguish itself from siblings like search_entities, professional_lookup, or get_full_dossier, which overlap heavily with this space.

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?

"Use when the user asks whether a company exists, who is behind a CIF/NIF, EU VAT or LEI..." gives explicit trigger conditions tied to user intent, which is strong. There are no when-not conditions and no named alternatives, so an agent still has to guess whether search_entities or professional_lookup is the better fit.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds genuinely useful context beyond that: it is free with no API key required, and it wraps entity_lookup with a preview mask, telling the agent results are a restricted subset rather than the full record. It does not explain how the preview differs in scope (which fields are masked), leaving a small 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 high-value fact (FREE, no API key) is front-loaded and the description is short. However, sentence two largely repeats sentence one's purpose statement ('read one company's free registry preview by its id' vs 'Fetch one company's free registry preview by the id returned by search'), so it is not entirely waste-free.

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

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

For a single-parameter, read-only lookup there is little missing: an output schema exists so return values need not be spelled out, and annotations carry the safety profile. The only substantive omission is what the 'free preview mask' actually withholds compared with entity_lookup or get_full_dossier, which would help an agent decide whether to escalate.

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 documents the single id parameter at 100% coverage, including the same 'CIF/NIF, EU VAT or LEI' guidance. The description restates that rather than adding format details, so the schema is doing the work and this sits at the 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?

Names a specific verb and resource ('read one company's free registry preview by its id') and distinguishes itself from siblings: it is used after search, accepts search ids or CIF/NIF/EU VAT/LEI, and is explicitly framed as entity_lookup with the free preview mask. An agent can select it without opening the schema.

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

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

The description gives a clear usage chain ('Use after search to read one company's...') and lists acceptable id types, which is effective context. It stops short of explicitly saying when not to use it — e.g., when the paid full record from entity_lookup or get_full_dossier is warranted — so the alternative routing is only implied.

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 cover the safety profile (readOnly, idempotent, openWorld), and the description adds genuinely non-derivable context: paid-plan gating (BUILD or higher, €99/month), Spain-only coverage, and that the response declares alias translation in _meta.sector_resolved_from. Missing only things like rate limits or auth token 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?

Front-loads the pricing gate and the use case, then layers constraints. Dense but every sentence (paid tier, Spain-only, closed vocabulary, alias resolution) carries operational weight. Slightly packed but not wasteful.

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

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

With an output schema present and full parameter documentation in the schema, the description only needs to cover gating, geo scope, and vocabulary behavior — all of which it does. An agent has everything required to decide and call 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 coverage is 100%, so the schema already describes all three parameters including enum values and alias behavior. The description's note that sector is a closed vocabulary and aliases resolve largely restates the schema, adding little beyond it — baseline 3.

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

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

States a specific verb+resource+scope: 'Find real competitors in the same sector and city', with ranked entities and Spain-only restriction. This clearly distinguishes it from siblings like entity_lookup, professional_lookup, and get_identity_verification, which are lookups rather than comparative discovery.

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 a clear trigger ('Use when the user asks who competes with a business in a sector and Spanish city') plus geo scoping ('Spain only on the public surface'). It does not explicitly name an alternative sibling or state when NOT to use it, keeping it below a 5.

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

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

Beyond the readOnly/idempotent/openWorld annotations, it discloses cost ('FREE, no API key needed') and a meaningful fail-closed semantic ('never returns ENTIA corporate marketing as if it were the entity'), which is the kind of non-obvious behavior risk an agent must know about. Return shape is covered by the output schema.

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?

Front-loaded with the most decision-relevant fact (free, no API key) and then the usage condition. Dense but every sentence carries information; it is slightly packed with endpoint/path detail that borders on redundant with the schema property descriptions.

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 4-required-param read tool with full annotation coverage, complete schema descriptions, and an output schema, the description supplies the remaining pieces: cost/auth, path acquisition, fail-closed behavior, and the disallowed alternative input. Nothing needed to call it correctly is missing.

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 individual parameter documentation is already handled. The description still adds value by giving the segment order and endpoint template and by stating what is NOT accepted (cif/q) and where valid values come from (canonical_url). Marginal gain above baseline, hence 4 rather than 5.

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

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

States a specific verb and resource: retrieve the Schema.org JSON-LD @graph for a specific entity's Entia Home page. It even names the machine endpoint (/v1/identity/{country}/{sector}/{city}/{slug}.jsonld), which disambiguates it from entity_lookup, showcase, and the projection/dossier siblings.

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 trigger condition ('when you already have an Entia Home URL path and need that public business page as data'), explicit prerequisite ('obtain the path via entity_lookup / showcase (canonical_url)'), and an explicit exclusion ('not cif/q'). An agent knows exactly when to pick this tool over 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?

Annotations already declare readOnly, idempotent and non-destructive, but the description adds information they cannot carry: the SIGNAL-plan paywall, the backing source (the entia.entity_home_projection.v1 materializer snapshot served from R2), and the warning against ad-hoc MCP enrichment. These are exactly the operational facts an agent needs before spending a paid call.

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

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

It is front-loaded with the most costly fact, the paid plan requirement, and stays under five sentences. The middle is dense internal jargon (materializer snapshot, R2 sibling .projection.v1.json) that partly obscures rather than clarifies, but nothing is padded.

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

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

An output schema exists, so return values need no explanation, and the description still covers the pricing gate, data provenance and the authoritative-source relationship to the public ficha. The one gap is the unresolved relationship with the sibling get_entia_home, which matters for a paid 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 patterns and examples documenting each of the four required slugs, so the schema does the heavy lifting and the baseline of 3 applies. The description adds no parameter-level detail beyond implying the payload is structured, and it never explains the include_render_context trade-off itself.

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

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

The description names a specific verb and resource: read the full structured projection of one Entia Home page, covering identity, location and verification. An agent can grasp the payload content, but it never contrasts this with the close sibling get_entia_home, so the distinction has to be inferred from the name alone.

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?

'Use when you need the full structured projection ... for one business' gives a usable trigger condition, and the paid-plan preamble is a real gating note. However, no alternative is named and no exclusion is stated, even though get_entia_home and get_full_dossier sit in the same sibling set, leaving overlap unresolved.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description earns credit for the extra operational context it adds: a paid plan gate (INTEGRATE, €399/month) and the fact that four upstream sources are queried in parallel. It doesn't discuss latency cost or partial-failure behavior of that fan-out, which would have pushed it higher.

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?

Front-loaded with the pricing gate and the primary use case, which is the right order. However, "Aggregator — 90+ fields" restates the earlier "everything about one company," and the closing "Killer tool for due diligence/KYB" repeats the use case already stated, adding mild 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?

With an output schema present, return values need not be described, and the plan requirement plus source composition cover the key decision inputs. Missing are practical notes on call cost/latency given the four parallel lookups, which matters for an agent choosing between this and cheaper siblings.

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 is a single parameter with 100% schema coverage and an enumeration of accepted identifier types (name, CIF/NIF, EU VAT, LEI) already in the schema. The description adds no format hints, normalization rules, or disambiguation guidance, so the baseline 3 applies.

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

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

States a specific verb and resource: aggregates 90+ fields about one company from four named ENTIA sources (identity, zone, BORME, VIES) in a single call. This clearly distinguishes it from narrower siblings such as entity_lookup, verify_vat, or zone_profile, which an agent can rule out without opening a schema.

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

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

"Use for due diligence / KYB when the user wants everything about one company in a single call" gives a clear selection condition that implicitly steers away from single-source siblings. It does not name those alternatives explicitly or state when not to use the expensive aggregate, so it falls short of a full 5.

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

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

Discloses behavior the annotations cannot: a hard plan gate (SIGNAL or higher, from €29/month) and fail-closed semantics, so an agent knows a negative result is meaningful rather than an error. It doesn't say what happens when the plan requirement isn't met (error vs. gated response) or how missing entities surface, which leaves a residual 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?

Four compact sentences with the paid gate and the usage trigger front-loaded, then the fail-closed caveat. Dense and readable, though 'exact canonical HOME projection' is jargon that costs a sentence's worth of clarity without adding usable 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?

An output schema exists, so return values needn't be explained, and annotations cover the read-only/idempotent profile. What's missing is any explanation of the composite key that identifies an entity, which is the one thing an agent can get wrong when calling this over a raw schema with no property descriptions.

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 0% and the description says nothing about the four required parameters. The country/sector/city/slug combination is a composite addressing scheme — an agent must infer from constraints alone that country is a 2-letter code and the rest are slugs, and that all four are mandatory.

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

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

States a specific verb and resource — reading a business's official identity-verification status — and explicitly disambiguates it from CIF existence, which is the most likely confusion. The phrase 'canonical HOME projection' is internal jargon that doesn't map to any sibling tool name, so the differentiation from get_entity_home_projection or verify_vat is only implicit.

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?

'Use when the user asks whether a business's identity has been officially verified, not just whether its CIF exists' gives a clear triggering condition and a negative case. It stops short of naming the sibling tools an agent should pick instead — e.g. verify_vat for VAT validity or entity_lookup when no verification claim is being made.

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

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

Annotations already establish readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint. The description adds useful behavioral context beyond annotations: it is free/no API key, stats are counted live, and country/Entia Home counts are null and marked _unverified until measured. These are meaningful caveats about data quality and 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 short and front-loads the most important fact ('FREE (no API key needed)'). There is minor redundancy in 'Live platform stats' and 'counted live,' but otherwise every sentence adds useful information.

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

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

An output schema exists, so the description need not explain return values. It covers the key caveat about null _unverified fields and the live-counting behavior, making it complete enough for an agent to call correctly. It could be slightly richer about what counts are included, but nothing essential is missing.

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 does not need to explain parameter semantics, and the input schema is empty and fully described.

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 resource (live platform stats: total entities and BORME acts) and frames it around coverage questions. It is clear what the tool returns, though it does not explicitly differentiate itself from sibling tools beyond the coverage angle.

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

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

It gives a clear usage trigger: 'Use when the user asks how much data ENTIA covers (entities, BORME acts).' It does not name when not to use it or point to alternatives, but the context is unambiguous.

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

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

Annotations already declare readOnly, idempotent, non-destructive, openWorld. The description adds genuinely new operational context — no API key needed and no quota consumption — which is exactly the kind of cost/access detail annotations cannot express. It does not cover rate limits or sample freshness, keeping it below a 5.

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?

Short and front-loaded, but 'FREE' is asserted three times across four sentences ('FREE (no API key needed)', 'FREE — does not consume quota'), which is redundant filler. Removing the duplicate would lose nothing.

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

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

An output schema exists so return values need not be explained, there are no required parameters, and the access/cost model is disclosed. A preview tool needs little more, though noting which call to follow up with would make it fully self-sufficient.

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 both parameters documented including bounds and enum values, so the schema carries the burden. The description mentions the IBEX35/EU curation but does not map it to the category enum or add syntax beyond the schema.

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

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

States a specific action — showing example records to illustrate what ENTIA data looks like — and scopes it to curated IBEX35 + EU entities. It positions itself as a preview step rather than a data operation, but does not name a specific sibling tool it complements.

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?

'Use to show example records ... before choosing another tool' and 'Use to explore data depth' give a clear trigger context. No explicit when-not conditions or named alternatives are given, so it stops short of full routing guidance.

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

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

Annotations already declare readOnly, idempotent, open-world, non-destructive, so the safety profile is covered. The description adds the commercially critical fact that this is a paid call requiring an ENTERPRISE contract, which is real value beyond structured fields. It says nothing about not-found behavior or failure modes.

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

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

Three tight sentences with the cost constraint front-loaded before the usage trigger. The final sentence restating return fields is mildly redundant given the output schema exists, but it is short enough not to waste space.

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?

Cost gate, trigger condition, vertical coverage, and returned fields are all covered, and the output schema handles the return shape. Missing only edge-case behavior such as no-match results or invalid professional-type handling.

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 both query and vertical are already documented, and the description adds no syntax, format, or enumeration detail (e.g., accepted vertical values) beyond the schema. 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?

States a specific verb and resource (verify professional registrations) plus scope (24 Spanish health/legal/psychology verticals) and the exact question it answers. This clearly separates it from neighbors like entity_lookup, verify_vat, and get_identity_verification.

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

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

Gives an explicit trigger: 'Use when the user asks whether a Spanish health or legal professional is registered.' The paid-plan gate further narrows when it is viable. It does not name alternatives or say when not to use it, so it falls short of a 5.

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

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

The description adds meaningful operational context beyond annotations: it is a paid tool requiring a SIGNAL plan or higher, has a rate limit of 5 requests per minute, and enforces a 30-second timeout. It also discloses the audit scope and that it returns a 0-100 risk score, which helps the agent understand cost and runtime constraints before invoking it.

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

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

The description is short and front-loaded: the paid-plan constraint and primary usage trigger appear first, followed by scope, output, and rate-limit details. Every sentence carries useful information without 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?

Given the tool's complexity and paid status, the description covers the essential points an agent needs: when to use it, plan requirement, scope of analysis, return value, rate limit, and timeout. Since an output schema exists, the description need not explain the full response structure.

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 input schema already documents all three parameters thoroughly, including domain format and optional context fields. The description only refers to auditing 'any domain' and does not add parameter-specific meaning beyond the schema. 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 names a specific verb and resource: run a comprehensive AI-readiness and digital risk audit on a domain. It also lists the concrete analysis areas (SSL, DNS, structured data, LLM visibility) and the output (risk score 0-100), making the tool clearly distinguishable from lookup and search siblings.

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

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

It gives clear trigger conditions: use when the user asks about AI-readiness, SEO/LLM visibility, or digital risk for a company's website domain. It also states the paid plan requirement. It does not explicitly name alternatives or when not to use it, but no sibling tool appears to provide an equivalent audit.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: no API key required, and results are a masked free preview of search_entities, which implies a limited result set. It could go further on preview limits (result caps) but the key traits are disclosed.

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?

Front-loaded with the highest-signal fact (free, no API key) and compact at four short sentences. There is minor redundancy in restating the id-to-fetch handoff twice.

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 trigger, cost/auth prerequisite, geographic scope, relation to siblings search_entities and fetch, and the return shape, even though an output schema already exists. Nothing an agent needs to call it and chain onward is missing.

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

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

Schema description coverage is 100% and the single query parameter already carries a constraint and example ('inmobiliaria Valencia'). The description only implies the parameter's content ('find companies or businesses'), adding no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource: 'Search the ENTIA business registry (Spain first; also EU)'. It also positions itself against siblings by noting it 'wraps search_entities with the free preview mask' and that returned ids are passed to fetch, so the agent can distinguish it from search_entities and fetch without opening schemas.

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

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

Gives an explicit trigger ('Use when the user asks to find companies or businesses') and names the downstream tool ('pass an id to fetch'), which makes the search-then-fetch workflow clear. It stops short of stating when to prefer the full search_entities instead, leaving the promotion path to inference, though the 'FREE (no API key needed)' framing hints at the selection criterion.

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?

Beyond the annotations, it discloses that results mix registry-backed companies with public listings, that not all results are registry-verified, and that anonymous callers only receive a trace-level preview while authenticated TRACE+ keys unlock full records. These are material behavioral details an agent could not infer from the schema or annotations.

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

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

The text is front-loaded and generally efficient. The repeated natural-language example ('find me a dentist in Madrid') is slightly redundant with the earlier examples, but the description remains readable and purposeful.

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 rich annotations, full schema coverage, and an output schema, the description is complete for correct invocation. It covers result quality, verification routing, sector behavior, and authentication-tier effects.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful sector semantics beyond the schema: the closed vocabulary, alias resolution to canonical slugs, and the response field _meta.sector_resolved_from.

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 and resource ('Search businesses') and enumerates the searchable dimensions: name, keyword, country, city, and sector. It clearly distinguishes this discovery tool from verification siblings by naming entity_lookup and verify_vat.

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

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

It explicitly states when to use the tool, with concrete examples like 'dentists in Madrid' and 'real estate agencies in Valencia'. It also names the alternatives for verification when registry-backed confirmation is needed.

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 cover safety (readOnly, idempotent, openWorld), and the description adds meaningful context beyond them: free/no API key, live VIES reach, the exact return shape, and the important caveat that some Member States withhold name/address, yielding name_disclosure=withheld_by_member_state. That disclosure issue is exactly the kind of operational behavior an agent needs.

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?

Information is dense and front-loaded: pricing/auth, usage trigger, mechanism, return shape, and edge-case caveat in a few sentences. No sentence is filler, and the most decision-relevant facts come first.

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

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

Even though an output schema exists, the description still prepares the agent for the response fields and the name-disclosure edge case. Combined with the annotations and schema, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so all three alias parameters (q, vat, query) are documented in the schema. The description says 'EU VAT number' but adds no format or alias guidance beyond the 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?

Names a specific verb and resource — real-time EU VAT validation via VIES across 27 countries — and explicitly distinguishes itself from entity_lookup for name resolution. An agent can identify the operation without opening the schema.

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

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

States the triggering condition directly: 'Use when the user asks whether an EU VAT number is valid or active.' It also names the alternative, entity_lookup, for the registered-name case, so routing is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds valuable context beyond annotations: it is a paid tool requiring the SIGNAL plan or higher, from €29/month, which is important operational information an agent needs before invoking it.

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

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

The description is two tightly constructed sentences. It front-loads the paid-plan requirement and usage trigger, then lists the data blocks efficiently 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?

With an output schema present, the description does not need to explain return values in detail. It covers the key prerequisites (paid plan), the use case, and the broad data coverage, though it could clarify sibling alternatives for an agent choosing among the many lookup tools.

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

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

Schema description coverage is 100% and the single postal_code parameter already has a clear description with an example (28013 = Madrid Gran Vía). The tool description adds no additional parameter syntax or constraints beyond what the schema provides, so the baseline of 3 applies.

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

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

The description clearly states the resource: a socioeconomic profile of a Spanish postal code, with 17 blocks including income, employment, demographics, business census, real estate, FTTH, poverty, and tourism. It is specific enough for an agent to know what the tool returns, though it does not explicitly differentiate itself from sibling tools such as 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?

It gives a clear usage trigger: 'Use when the user asks about the income, employment, demographics, business census or real-estate profile of a Spanish postal code.' It does not mention when not to use the tool or name alternative siblings, so it stops short of a 5.

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