Fuentio: UK, France & Spain company data from official registries

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

Annotations already cover readOnly/destructive/idempotent/openWorld, but the description adds genuine context beyond them: a cost hint ('Limits: 1 unit'), an availability constraint ('Spain not available yet'), and the meaning of the 'validated' tri-state return. It stops short of full behavioral detail but clearly enriches the annotation profile.

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 purpose, then organises the rest into labeled Inputs/Returns/Limits sections. Each sentence carries information (source, routing, cost, availability) with no filler.

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

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

Covers purpose, usage routing, input source, and operational limits. An output schema exists so return values needn't be re-explained, yet the description still summarizes the validated tri-state and payload fields, leaving nothing an agent needs in order to call it correctly.

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

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

Schema coverage is 100% with examples, enums, and per-field descriptions, so baseline is 3. The description's only added value over the schema is the cross-reference 'as lookup_company', which is a minor semantic link rather than new format or syntax detail.

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 (validate a company's registered address) and names the backing data source (API Adresse / Base Adresse Nationale). It also distinguishes itself from 'search_companies', so an agent can tell it apart from siblings 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?

Explicitly states two positive use cases (confirm an address exists/is the company's, or geolocate it) and a negative one with a named alternative: 'Don't use it to find companies: call search_companies.' Nothing is left to inference.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, but the description adds value they don't carry: a cost/rate constraint ('Limits: 1 unit') and a critical coverage caveat ('No notice outside the loaded years is not proof of no procedure') plus the covered_since field. Return states and citations are also disclosed, though some of that overlaps 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?

Labeled sections (use/don't use/Inputs/Returns/Limits) make it scannable and the routing guidance is front-loaded. Slightly long because the Returns enumeration partly restates the output schema, but nearly every sentence carries 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?

Given an output schema exists, the description need not explain return values, yet it still covers usage, exclusions, cost limits, and the honest coverage-window caveat. Nothing an agent needs to call this 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 description coverage is 100%, with enum and per-country identifier formats already documented, so baseline is 3. The description adds only a light cross-reference ('as lookup_company') and one example pair, which is marginal beyond what the schema provides.

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 ('Check a company's insolvency notices and state') and enumerates the exact coverage sources (BODACC for France, BORME insolvency acts for Spain) and procedure types, so an agent can distinguish it from siblings like lookup_company or verify_company 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?

Explicitly gives the intended use case ('credit or supplier checks') and a hard exclusion with the correct alternative ('Don't use it for sanctions: call screen_company'), plus a pointer to lookup_company for identifier conventions. This is the full when/when-not/alternative pattern.

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 only declare the operation profile (readOnlyHint false, non-idempotent, openWorld), which fits a tool that creates a batch. The description adds material context the annotations cannot carry: cost in units per row (+2 for name-only), free reuse of checks for 24 h, the asynchronous 'next' signal while still checking, and explicit scope boundaries ('a registry check, not KYB or sanctions clearance; no person's name').

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 purpose and the exclusion, then organized under explicit Inputs / Returns / Limits labels. Dense but every sentence (cost, reuse window, scope disclaimer, async indicator) carries information an agent needs to call it correctly.

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, yet the description summarizes the return shape (counts by review_state, review rows with reasons, share_url, 'next'), and it covers cost, limits, exclusions and the batch_id read path. Nothing essential for correct invocation 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 the baseline is 3, and much of the row guidance is duplicated in the SupplierRow $def. It still adds selection semantics: the mutual alternative between rows and batch_id ('Leave out to read a batch_id'), and the conditional rule that a name alone only resolves with postal_code and street matching one company.

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 ('Check a supplier list against the official registers') plus the output scope (ok / need a look and why, proof code, share link). It explicitly distinguishes itself from the sibling verify_company, so an agent can route correctly without opening either schema.

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

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

Gives a concrete use range ('2 to 100 suppliers at once, or to read a batch you started') and an explicit exclusion with the alternative named ('Don't use it for one company: call verify_company'). When-to-use, when-not-to-use and the substitute tool are all present.

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 read-only and idempotent, but the description adds substantial behavioral context beyond them: it discloses that registration is never checked, that the answer links the official VIES page, that origin can be 'published or computed', and a note field. The 'Spain: no VAT numbers published' data-quality caveat and the '1 unit' cost are useful non-obvious context. It does not contradict the readOnly annotation.

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 purpose and non-use case, then Inputs, Returns, Limits sections. Every line earns its place with zero filler; structured labels make it 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?

Complete for a 2-param, low-complexity lookup. It covers inputs, return fields, the openWorld behavior (VIES link), data-quality limits (Spain), cost, and safety, and an output schema exists so return details needn't be exhaustive.

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 documents both parameters in detail, so baseline is 3. The description reinforces this by naming country and identifier, giving the example pair ('FR', '441639465'), and cross-referencing sibling tool lookup_company as the source of identifier semantics, which adds navigational value.

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

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

The description states a specific verb+resource (give a company's EU VAT number) and clarifies the scope (registration NOT checked, registration_checked false). It distinguishes the tool from what a naive agent would expect, explicitly routing to 'check on VIES' for proof of registration.

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 when to use (filling an invoice or supplier file) and when not to use (as proof of VAT registration — check VIES). Names the alternative action directly. Nothing left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety is covered and the description should not be penalized for restating 'Read-only'. It adds genuinely new behavioral context: the 1-unit cost limit and the fact that stored decisions and links are retrieved, not just today's verdict. It stops short of describing auth requirements or whether stored decisions persist beyond the 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?

Front-loaded with the core purpose, then cleanly labeled Use/Inputs/Returns/Limits blocks with no wasted prose. The Returns enumeration is slightly redundant given a full output schema, which keeps it just short of a 5.

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 purpose, sequencing, parameter identification, return shape and cost in a compact space. With an output schema present the Returns line is bonus rather than a gap, so nothing an agent needs to invoke the tool 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% and both parameters already carry descriptions and examples ('A Fuentio record ID', 'Another record ID'). The description's 'Inputs: left and right, Fuentio record IDs' with the same example strings largely duplicates the schema, so this sits at the baseline rather than adding new meaning such as ordering effects or type/format constraints.

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?

Specific verb (explain) plus a precisely scoped resource (whether two register records are the same company), naming exactly what is returned: today's decision, reason codes, evidence, stored decisions, links, and shared-entity status. An agent can distinguish it from resolve_company and the other check_/verify_ siblings without opening any 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?

Explicit sequencing ('Use it after resolve_company or lookup_company') and an explicit exclusion with the alternative named ('Don't use it to find companies: call resolve_company'). Both the when and the when-not are stated with the redirect target.

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 read-only/idempotent/non-destructive, but the description goes well beyond them: a cost model (1 unit, keyless 20 units/day) and country-specific history depth (France from Fuentio's first fetch, Spain from 2 Jan 2009, UK latest filings plus everything since first held). These are non-obvious operational constraints an agent cannot 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?

Front-loaded with purpose, then alternative, inputs, returns, limits, and search words in labeled blocks, which makes it skimmable. It is on the long side and 'Read-only' restates the annotation, but nearly every line carries 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?

For a history/versioning tool with five parameters and an output schema, nothing material is missing. It covers the sibling alternative, the quota cost, per-country history horizons, and the meaning of meta.history_since, so an agent can call it and interpret the result 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 the schema already documents country, identifier, id_scheme, page, and detail. The description adds only one genuinely useful link ('identifier as for lookup_company') and otherwise restates enum values; notably it never mentions the `detail` parameter at all, so it adds little beyond the structured 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?

States a specific verb and resource ('see what changed at a company, and when') and immediately names the discriminating content: versions with the changed fields plus their official source. It explicitly separates itself from lookup_company, so an agent can route between the two without opening either schema.

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

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

Gives both the positive case ('Use it for changes over time') and the exclusion ('Don't use it for the current state: call lookup_company'), naming the alternative tool directly. It also lists the supported countries and identifier style, which tells the agent when this tool is even applicable.

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, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: a cost limit ('1 unit') and an operational constraint. It does not disclose auth needs or pagination, keeping it short of 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?

Front-loaded with purpose, then cleanly delimited Inputs/Returns/Limits sections. Every sentence carries distinct information with no repetition or filler.

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

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

With an output schema present, the return values need not be explained in prose, and the description still summarizes them. Inputs, usage context, and the unit limit are all covered, so nothing an agent needs to invoke 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 the baseline is 3, but the description goes further by enumerating the accepted field values (name, status, address, legal_form, creation_date, activity) where the schema only offers 'One field, e.g. status'. It also restates the as_of format and gives an entity_id example, adding 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 gives a specific verb (show) and resource (evidence behind a company's stated facts) and details exactly what that evidence comprises — served value, competing values, sources, hashes, and match decisions. This is far more precise than the sibling names alone, letting an agent distinguish it from lookup_company or explain_match.

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

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

It states both when to use it ('justify an answer in a review or an audit') and when not to ('Don't use it to look a company up'), and routes the agent to the prerequisite tool resolve_company for the entity_id. Explicit when/when-not plus a named alternative.

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, non-destructive), and the description adds real behavioral context on top: cost limits (2 units), API key requirement, that ownership covers only signals and not beneficial owners, that companies without an LEI show no links, and that no people/director links are returned.

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 purpose, then clearly labeled Inputs / Returns / Limits blocks. Each sentence carries distinct information; none is filler or restatement.

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 pre-empts the key questions for this kind of traversal tool: what nodes and edges mean, evaluation cost, auth requirements, and the LEI/people coverage gaps that would otherwise surprise an agent.

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 already 100% for both parameters, and the description reinforces the entity_id format example and the depth 1-or-2 constraint. The parent_of kind and edge fields it mentions describe returns rather than inputs, so it adds only modest input-side value, landing at the baseline-plus level rather than degrading.

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 ('Show a company's group: its parent and child companies from GLEIF') with the edge semantics pinned down. It explicitly distinguishes itself from resolve_company by naming the sibling it is not.

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 both when-to-use ('Use it to map a company's group') and when-not ('Don't use it to look a company up') plus the prerequisite step ('call resolve_company first for its entity_id'). Nothing is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real context on top: a 30-per-minute rate limit, that the operation is free, and a meaningful authorization nuance ('The key that ran the check also sees its reference; anyone else, the public view'). That access-scoping detail is behavioral information an agent cannot derive 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?

Dense but organized with Inputs/Returns/Limits labels, so an agent can scan to the part it needs. It leads with the return payload rather than the purpose action, and a few clauses restate schema content, which slightly dilutes front-loading.

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 two-parameter read tool with annotations and an output schema, the description is fully sufficient: it explains what is returned, how to render it ('show it as is'), the rate limit, and the access model. 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% and the enum already documents the two formats, so the baseline is 3. The description adds a concrete proof-code example, confirms case-insensitivity, and clarifies that a lookup's meta.receipt.request_id is 'the same key' — the equivalence claim is genuinely useful even though the schema hints at it.

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 ('give back the Fuentio receipt of a verification by its proof code') and immediately enumerates the payload, so the agent knows exactly what comes back. It explicitly distinguishes itself from the sibling 'verify_company', which is the closest confusable 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?

Gives when to use ('when the user asks for a receipt or proof of a check'), when NOT to use ('Don't use it to run a new check: call verify_company'), and even the required interaction step ('Always ask the user first: Normal or detailed receipt?'). The alternative is named explicitly, leaving nothing to inference.

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

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

Beyond the annotations' readOnly/idempotent hints, it discloses cost and auth ('Free, no key'), the quota ('Limits: 0 units'), the return shape per country (status, coverage level, ID formats with real examples, regional registers, sources with licence and update frequency), and the current live coverage set (France, Spain, United Kingdom). These are exactly the traits annotations cannot convey.

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 purpose and routing, then labelled sections (Inputs, Returns, Limits, Search words) that make it scannable. The trailing multilingual keyword block is long and largely redundant for an agent reader, which costs it the top score.

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 pre-frames its contents, adds quota and coverage-state context the schema cannot express, and leaves no ambiguity about how or when to call a zero-parameter tool. Nothing needed for correct invocation 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?

The tool takes no parameters, so the baseline is 4. The description confirms this explicitly ('Inputs: none') and supplies a call example, which is the most an agent needs for a zero-argument tool.

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 — listing the countries, ID formats and official sources covered — with a clear scope boundary ('Fuentio covers'). It explicitly disambiguates from siblings by name, so an agent can distinguish it from lookup_company or search_companies without opening either schema.

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

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

Gives explicit when-to-use ('Use it first when unsure whether a country or ID format is supported, or to explain coverage') and when-not with named alternatives ('Don't use it to check a company: call lookup_company or search_companies'). This is a complete routing rule.

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/non-destructive), yet the description adds genuinely new behavior: billing ('1 unit, also a valid ID not found'), a rate limit ('keyless 20/day'), and per-country coverage ceilings (BODACC since 2008, BORME since 2 Jan 2009, no UK officers or PSCs). The privacy rule ('No person's name in any answer') is a non-obvious output constraint that is not in any structured field.

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?

Purpose and the sibling alternative are front-loaded in the first two sentences, and the Inputs/Limits blocks are scannable. It runs long, though, and the closing keyword list ('SIREN, RCS, Annuaire des Entreprises, société; BORME...') is closer to search-term padding than operating instruction.

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 five-parameter lookup with an output schema, everything an agent needs to call it correctly is present: which countries, accepted ID schemes, format trade-offs including the 24-hour link for xlsx/parquet, cost and quota, and per-registry coverage gaps. The return-shape note is redundant with the output schema but not harmful.

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

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

Schema description coverage is 100%, so the baseline is 3 and the description largely restates identifier formats already documented per parameter. It does add a useful ambiguity signal ('id_scheme if ambiguous'), but it also says ES has 'no NIF/CIF' while the id_scheme enum still offers ES_NIF, which muddies rather than clarifies that parameter.

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 ('Look up one company in its official register by ID') and enumerates what comes back (status, address, legal form, activity, source, check date). It also draws the boundary against the sibling search_companies by requiring an official ID rather than a name, so the agent can pick 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?

Explicit when-to-use ('when you have an official ID'), explicit when-not ('Don't use it with a name: call search_companies first'), and it names the correct alternative. It further maps real-world colloquialisms (SIREN, RCS, BORME, Companies House, Ltd, plc) to the tool, reducing misrouting.

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?

Goes well beyond the annotations: it discloses that reporting is free, requires an API key, and is rate-limited to 20 reports per key per day, plus the exact return payload (issue_id, status 'open'). The annotations only flag non-read-only, open-world, non-idempotent; the description adds the operational constraints an agent actually 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?

Front-loaded purpose followed by tightly labeled Inputs/Returns/Limits blocks. No filler sentences; each line delivers a distinct fact an agent needs before calling.

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 3-param mutation with an output schema present, the definition covers trigger, exclusions, all inputs, return shape, and operational limits. Nothing required to invoke 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 67%, and the description compensates by restating all three inputs with meaning: subject accepts an entity ID, record ID (with a concrete 'FR-SIREN-441639465' example) or a tool name, and it enumerates the five category values. It adds useful disambiguation over the schema, though the category values merely repeat the enum.

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 ('Report an answer you believe is wrong or missing') and names the downstream action ('Fuentio checks it against the official source'). It is immediately distinguishable from all sibling lookup/verification tools because it is a write-back channel rather than a query.

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 it when a result contradicts an official document you hold') and an explicit exclusion ('Don't use it to ask questions: call the lookup tools'). Both the when and the when-not are stated, with the alternative named.

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

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

Annotations already establish read-only, idempotent, open-world, and non-destructive behavior. The description adds crucial operational context beyond annotations: a 2-unit limit, the rule that only an official ID links exactly while a name plus address is never proof, and confirmation that nothing is stored.

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 purpose is front-loaded, then Inputs, Returns, and Limits are cleanly sectioned. Every part is brief and useful, with only minor overlap with the output schema.

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

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

For a 7-parameter, open-world matching tool with a full output schema, the description covers country scope, input expectations, return shape, and limits. Nothing an agent needs to invoke 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?

With schema coverage at 71%, the description usefully groups and exemplifies the key inputs (country, name, postal_code, identifier, optional id_scheme, locality, limit) and clarifies the and/or relationship between name and identifier. It duplicates a few schema descriptions and leaves locality/id_scheme only lightly explained, so it adds value but not full compensation.

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

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

States a specific decision verb and resource: deciding whether a known company is in official registers, with evidence and candidate outcomes. It explicitly distinguishes itself from lookup_company, so an agent can select it without opening either schema.

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

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

Explicitly says to use it for matching a supplier or customer record to a register record, and says not to use it to read a company already identified, directing to lookup_company. That gives clear when, when-not, and alternative.

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, openWorldHint and destructiveHint=false, so the safety profile is largely covered. The description still adds real operational context beyond them: a cost ceiling ('8 units') and an auth requirement ('API key required'). It stops short of richer behavior like latency, caching, or whether the report is persisted, so it is not 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?

Front-loaded with the core verb and payload, then cleanly segmented into usage, exclusion, Inputs, Returns, and Limits lines. Dense but every clause carries information, with no filler or restated title.

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, yet the description still names the top-level return fields (company, facts, links, decisions, changes_last_year, modules, gaps, uncertainty, sha256, markdown), plus the two parameters, the usage boundary, the cost limit and the auth requirement. Nothing an agent needs to decide or invoke 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 both parameters are documented inline (enum values, SIREN/SIRET/VAT formats, examples). The description only adds a cross-reference that the inputs work 'as lookup_company' with the same format — marginal added meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('Produce one review-ready report on a company') and enumerates the report's contents (identity, facts with sources, changes, all checks at once). It explicitly distinguishes itself from siblings by naming lookup_company as the alternative for a single fact, so an agent can route 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?

Gives explicit when-to-use ('registry part of a KYB or supplier review you must file'), explicit exclusions ('not full KYB: no UBO, PEP or adverse-media checks'), and an explicit alternative with its triggering condition ('Don't use it for one quick fact: call lookup_company'). Both the positive and negative cases are covered.

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

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

Annotations already cover readOnly/idempotent/non-destructive, but the description goes well beyond them: it discloses a metered cost ('2 units'), an auth requirement ('API key required'), and crucial interpretation semantics ('A possible match is not proof; no match is never clear'). That last point materially changes how an agent reports results and is not derivable from any structured field.

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?

Labeled sections (Inputs / Returns / Limits) front-load the purpose and routing rule, and every sentence carries distinct information: routing, cost, auth, output states, and interpretation caveat. No filler or restated name/title.

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

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

Despite the tool's three possible result states and external list dependencies, the description covers inputs, outputs (including the 'not_checked' state and list versions), cost, auth, and the critical caveat about match interpretation. An output schema exists, and the description still summarizes results usefully rather than being redundant.

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 enum is documented in the schema, so the schema does the heavy lifting. The description adds only a cross-reference ('as lookup_company') and a format example, which is a marginal gain over the schema text. 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?

Starts with a precise verb+resource ('Screen a company's own names against sanctions lists') and enumerates the four specific lists consulted. It also explicitly distinguishes itself from the identification siblings (resolve_company, lookup_company), so an agent can route correctly without opening any 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?

Names the exact pipeline step ('sanctions-list step of onboarding a supplier or customer'), explicitly scopes it as 'not full KYB', and gives a when-not with the alternative: 'Don't use it to identify a company: call resolve_company or lookup_company first.' This is full when/when-not/alternative coverage.

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 read-only, open-world, idempotent, and non-destructive behavior. The description adds substantial context beyond annotations: unit costs per page and per file rows, country-specific data coverage and vintage, UK limitations on officers/PSCs, GLEIF ISIN/BIC sourcing, and the no-person-name constraint.

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 front-loaded with purpose and routing, then structured as inputs, returns, limits, country caveats, and search terms. It is appropriately detailed for a complex multi-country search tool, but the trailing keyword list and some schema-repetitive details could be trimmed.

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 nine parameters, output schema, and cross-country complexity, the description is complete enough to invoke correctly. It covers when to use it, alternatives, required and optional inputs, return-shape highlights, cost limits, data coverage caveats, and privacy constraints.

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

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

Schema description coverage is 100%, so the schema already documents all parameters, including query length, country enum, page size, format behavior, and limit/unit rules. The description groups inputs and repeats key constraints, but adds little semantic detail beyond what the schema already provides.

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: find companies by name in official registers for France, Spain, and the UK. It also distinguishes this from ID-based lookup, so an agent can tell it apart from sibling tools such as lookup_company or verify_company.

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 to use it when you know a name but no ID, then call lookup_company or verify_company with an ID from the results. It also explicitly says not to use it when an official ID is already known, which is exactly the routing guidance an agent needs.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, and idempotentHint=false. The description adds substantial context beyond those annotations: outcomes such as open insolvency never verifying, rate/cost limits (5 units, keyless 20/day), 24-month storage, country-specific coverage gaps, and the no-person-name constraint.

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 dense but front-loaded: purpose first, then usage, inputs, returns, limits, and coverage. Every section adds actionable information for a complex verification tool, with no filler beyond useful search terms.

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, the description covers purpose, alternatives, required inputs, outcome semantics, limits, and country-specific coverage. Output schema exists, so the brief return summary is sufficient and appropriately augments rather than duplicates it.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description still adds useful semantics, especially that identifier is an official ID and "Never a name," and that reference is the caller's own case id stored with the result.

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 a company against its official register," and explicitly scopes it as "A registry check, not full KYB." It also distinguishes the tool from siblings by naming lookup_company and search_companies as alternatives for different cases.

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 explicit use cases (onboarding, before paying or signing, deciding about a company) and explicit exclusions: don't use for a cheap single read, use lookup_company; don't use with a name, call search_companies first. This is clear when-to-use and when-not-to-use 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 only declare the generic profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false). The description adds genuinely new behavioral context: signing_secret is shown once, private/local callback addresses are refused, API key required, 1 unit cost, and a 3-watch free-plan cap.

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 what the tool does, then routes to the alternative, then the Inputs/Returns/Limits blocks. Every sentence carries information, though the compressed Inputs/Returns/Limits enumeration is slightly dense rather than maximally economical.

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 spelled out, yet the description still flags the critical one-time secret. Covers mechanism, cost, auth, callback constraints, and the sibling alternative – nothing an agent needs to invoke 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 baseline is 3, but the description adds real meaning beyond the schema: entity_id must come from resolve_company, and callback_url carries a hard constraint (private or local addresses are refused) that the schema's 'Your https endpoint' does not state.

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 ('Watch a company') plus the operational mechanism (signed POSTs to your https endpoint when official records change). It explicitly names the sibling it is not (what_changed) for one-off checks, so an agent can distinguish it without reading either schema.

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

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

Gives a positive trigger ('monitor a supplier or customer') and an explicit exclusion with the alternative to use instead ('Don't use it for a one-off check: call what_changed'). Nothing is left to inference.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), and the description adds substantive context beyond them: a cost limit ('1 unit'), the critical invariant that 'a gap is never reported as no change', and the fact that gaps and uncertainty are part of the response. These are exactly the operational caveats an agent needs before trusting the result.

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?

Uses a labeled structure (purpose, use cases, Inputs/Returns/Limits) that front-loads the action and keeps each block tight. The opening sentence is slightly overloaded with the record-type enumeration, and the Returns block partly duplicates the output schema, but there is no filler.

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

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

Despite an output schema existing, the description supplies the semantics that matter most – gap handling, uncertainty signaling, and a cost unit – leaving no ambiguity about how to interpret or trust results. Complete for a read-only change-audit 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% – entity_id, since, and until all carry their own descriptions and examples. The description restates the same facts (entity_id 'from resolve_company' with the fu_ prefix example, date format, until defaulting to today) without adding syntax or constraint detail beyond the schema, so 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 with scope ('List what changed at a company since a date') and enumerates the record types covered (status, name, address, legal form, BORME acts). It explicitly names the sibling it is not (lookup_company), so an agent can route without opening either schema.

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

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

Gives an explicit when ('review a supplier or customer since your last check') and an explicit when-not ('Don't use it for the current state'), plus the alternative to call instead (lookup_company). Nothing is left to inference.

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