Tolca: business verification (KYB)

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

Annotations cover read-only/idempotent/open-world safety, and the description goes well beyond them: live read from the company's own site with no third-party database, per-field source attribution, 404 means no charge, and a full payment model ($0.02 USDC via x402 on Base) with the required PAYMENT-SIGNATURE header. That is exactly the kind of operational context annotations cannot express.

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 payload description before commercial details, and every sentence carries information. It is dense and slightly long, with the x402/HTTP-endpoint instructions taking significant space, but none of it is 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 no output schema, the description does the heavy lifting by enumerating return fields and source attribution, plus cost and endpoint details. The only gap for a 6-param tool is the unexplained official_checks toggle and the fact that no parameters are strictly required.

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 50% schema coverage, the description compensates by restating the input shape (domain or name, optional city, country, lang en|fr), which clarifies the domain-vs-name intent. It omits the official_checks boolean entirely, leaving one meaningful flag undocumented in both places.

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 opening sentence states a specific verb and resource ('Company profile from a domain or name in ONE call') and enumerates exactly what comes back: industry, services, service area, address, phones/emails with source pages, social links, sanction screening. This is clearly distinguishable from siblings like verify_business or web_search.

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 names the intended audience (sales and research agents), scopes the domain ('Businesses only'), and gives concrete failure semantics ('No website found = HTTP 404 = no charge'). It does not, however, explicitly say when to prefer this over verify_business or web_search.

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, open-world, but the description adds information annotations cannot carry: cost ($0.03 USDC via x402 v2 on Base), the required PAYMENT-SIGNATURE header and endpoint, and the billing guarantee 'No website found = no charge'. Pricing and failure-billing behavior are exactly the traits an agent needs before invoking a paid tool.

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 the value proposition, then output shape, then inputs, then payment mechanics — a sensible order with no filler sentences. It is dense but slightly overloaded, bundling endpoint URL and payment protocol detail into the same block as the semantic description.

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

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

With no output schema, the description does the work of describing return values (verdict, score, reasons, opening line), and it covers the nested 'for' object and pricing/auth model. The gap is the four unexplained auxiliary parameters (city, country, lang, official_checks) on a fairly complex nested-schema tool, which an agent may need to set 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 only 14%, so the description has to compensate. It does document the core inputs (domain or name, and the 'for' object with seller, goal enum values, optional ideal_customer), but leaves city, country, lang, and official_checks entirely unexplained in both schema and description. That is meaningful but partial compensation for a 7-parameter 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?

The opening sentence names the exact decision the tool answers ('Is this company worth contacting FOR YOU?') and quantifies the deliverable: verdict (good/maybe/poor), 0-100 score, fact-grounded reasons, and an opening line. It explicitly positions itself against the sibling company_enrich ('Everything in company-enrich, plus a fit verdict'), so an agent can choose between the two without inspecting 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?

The framing 'Is this company worth contacting FOR YOU?' plus the required 'for' payload makes the use case clear: personalized outreach qualification rather than generic enrichment. It also implies the alternative (company_enrich) for plain data. It lacks an explicit 'do not use when you only need raw company data / no seller context' exclusion, so it stops just short of 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?

Annotations already cover read-only/idempotent/non-destructive/open-world, and the description adds substantial behavioral context beyond them: pay-per-call pricing ($0.02 USDC), payment protocol (x402 v2 on Base), expected challenge latency (~5 ms) and processing time (~1.5 s), and the exact auth mechanism (PAYMENT-SIGNATURE header). This is exactly the operational context an agent needs before invoking a paid tool.

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 is front-loaded in the first sentence, with payment/logistics details following. Efficient overall, though the latency statistic ('7-day average processing ~1.5 s') is marginally promotional and 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?

With no output schema, the description correctly explains the return value shape (clean JSON matching the provided schema) and fully covers payment/auth. It omits error behavior and the input size limit that lives only in the schema.

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

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

Schema description coverage is 50%; the schema documents the `schema` parameter as 'Field name -> type or description' while the `text` parameter has no description in either place. The description restates the schema parameter's meaning ('field names and types'), so it adds only marginal value and does not compensate for the undocumented text parameter or its 40,000-character cap.

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 transformation: turn messy text into clean JSON matching a caller-supplied schema. The mechanism (field names and types you provide) is clear. It does not explicitly contrast itself with the sibling extract_url, so a 4 rather than a 5.

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 case is implied by the description (caller supplies both text and schema), and it names the concrete invocation path (POST endpoint, PAYMENT-SIGNATURE header). However, it never states when to prefer this over the sibling extract_url or why, leaving routing 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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description goes well beyond them by disclosing the payment/auth requirements: x402 pay-per-call in USDC on Base, $0.03 per call, an ~8 ms payment challenge, and the exact PAYMENT-SIGNATURE header needed. This is exactly the kind of auth/cost context an agent cannot get from structured fields.

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 core purpose, then flows into payment mechanics. The payment sentence is dense but earns its place because it is a genuine invocation prerequisite; only minor trimming is possible.

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

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

With no output schema, the description correctly summarizes the return shape (schema-matched JSON plus page title and source) and fully documents the payment flow. It omits error behavior and rate limits, a minor gap for an OpenWorld fetch tool.

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

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

Schema coverage is only 33%, and the description adds real meaning only for the 'schema' parameter ('return JSON matching your schema'), which is the most non-obvious input. The 'url' and 'max_chars' parameters gain nothing from the description beyond their schema definitions, so it only partially compensates for the coverage gap.

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

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

States a specific verb (fetch) and resource (public URL) plus supported content types (HTML article, PDF, JSON) and the return shape (JSON matching your schema, with page title and source). This clearly distinguishes it from siblings like extract, summarize, and translate, which serve different transformations.

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

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

The description implies usage (public URLs only) and conveys cost/payment context, but never states when to choose this over the sibling 'extract' tool or when not to use it (e.g., non-public or authenticated URLs). Usage is inferable rather than explicit.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds critical operational context annotations cannot: the $0.25 USDC per-call cost, x402 v2 on Base, and the required PAYMENT-SIGNATURE header or endpoint. For a paid tool this payment/auth disclosure is exactly the missing piece.

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 and output shape, which is good. However, the full French restatement and the HTTP/payment mechanics add bulk, and the value proposition is repeated (per-question risk plus fixes appears twice), so not every sentence earns its place.

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

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

With no output schema, the description carries the return-value burden well by naming the overall 0-100 risk, per-question breakdown (risk, why, fix), and general tips. Combined with payment details, an agent has enough to call it correctly, though the text/url exclusivity remains implicit.

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 60%, and the description compensates by naming the accepted inputs (text or url), the optional grade, subject, and the lang enum values fr|en. It adds useful framing beyond the schema, though it does not clarify mutual exclusivity between text and url.

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: assesses whether a homework assignment can be AI-completed, returning an overall risk score and per-question breakdown. Clearly distinguishable from siblings like extract, summarize, and translate, which perform unrelated operations.

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?

Specifies the audience ('For teachers and schools') and both accepted input modes (paste text or public PDF URL), plus the 'No student data' constraint. It stops short of explicitly naming an alternative tool or stating when not to use it, but the context is clear.

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

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

Annotations already declare the safe read-only/idempotent profile, and the description goes beyond them with genuinely useful operational context: a 100/day shared free quota and an x402 paid fallback with URL and price. It also discloses the return shape (verdict, score, reasons, one-line recommendation). It stops short of explaining latency or what happens when a package is unknown.

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 question and verdict taxonomy, then inputs, then access/pricing. Every sentence carries information, though the quota/pricing sentence is more commercial than functional and could be trimmed without loss to an agent.

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

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

For a three-parameter read-only check with no output schema, the description supplies the verdict vocabulary, the evidence categories, and the recommendation format, plus quota/pricing context. An agent has everything needed to call it and interpret the result without opening anything else.

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%, so the schema already documents most parameters including the version default and the ecosystem enum. The description's 'Input: name, ecosystem (npm | PyPI), optional version' largely restates the schema without adding syntax, constraints, or edge-case meaning. 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 opening question plus 'One call, one verdict: safe / caution / avoid' states a specific action (safety assessment) and a concrete output shape, and the parenthetical lists exactly what signals are evaluated. It does not, however, distinguish itself from the sibling pkg_meta, leaving the boundary between 'safety check' and 'package metadata' to inference.

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 framing 'Is this package safe to install?' implies the pre-install decision context, but there is no explicit when-to-use, when-not-to-use, or routing to the sibling pkg_meta (which an agent could easily confuse for this). Usage is inferable rather than stated.

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 the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: a per-call price ($0.005 USDC), the payment protocol (x402 v2 on Base), the required PAYMENT-SIGNATURE header, and the direct endpoint URL. Auth/payment requirements of this kind are exactly what annotations cannot express.

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 highest-value information — what it returns and the cheapest-tier positioning — before the payment mechanics. Dense and somewhat run-on in the final sentence, but essentially every clause carries distinct 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?

With no output schema, the description correctly enumerates the returned fields, and it supplies pricing, transport, and the sibling alternative. Remaining gaps are minor: error behavior, rate limits, and any latency/pagination expectations for a paid call are unstated.

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%, so the description must carry the burden. It enumerates the three inputs and notes that version is optional and that ecosystem takes npm or PyPI, but the enum and optionality are already in the schema, and it adds no format guidance for name (e.g. scoped packages) or version strings.

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 (package metadata retrieval) and enumerates exactly what is returned: latest/resolved version, license, publish dates, downloads, deprecation, install scripts, maintainer count. It explicitly distinguishes itself from the sibling pkg-check, 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?

Names the alternative ('No vulnerability scan (see pkg-check for the full safe/caution/avoid verdict)') and positions itself as the 'cheapest tier', which is a clear usage signal. However, it is silent on the other overlapping sibling, qc_licence, despite this tool returning license data — leaving a routing ambiguity 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 cover read-only/idempotent/non-destructive, and the description adds substantial behavior beyond them: three verdict tiers with reasons and source dates, an Ed25519-signed verifiable receipt with key URL and verify endpoint, official open-data sourcing, and a 10/day free quota versus unlimited paid x402 access. That quota and cost model is exactly the kind of operational constraint annotations cannot express.

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 trigger and the checked-source list are well front-loaded, but the Ed25519 receipt sentence appears twice verbatim — a whole redundant sentence in a short description. Pricing/quota detail is also packed into the same block, so the structure is serviceable rather than tight.

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

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

With no output schema, the description carries the burden of describing returns, and it does: verdict level, reasons, source dates, plus contract count/total/buyers. Combined with the receipt verification story and quota, an agent has enough to call it. The missing pieces are the `lang` parameter and not-found/multi-match behavior.

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 75%, so the schema already documents neq and name; the description's 'Input: name, NEQ or RBQ licence number' reinforces that these are alternative identifier routes. However it omits the `lang` parameter entirely and never states that identifiers are mutually alternative or what happens with zero identifiers (required list is empty), leaving a real gap.

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

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

The description names the exact resources checked (RBQ licence status/categories/restrictions, RENA listing, environmental penalties, SEAO contract counts/totals/buyers) and the output shape (ok/review/blocking verdict). An agent can tell this is a multi-source Québec contractor due-diligence check. It does not, however, distinguish itself from plausible siblings like qc_licence or verify_business, so it stops short of a 5.

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 opening sentence gives a concrete decision trigger: 'Call before hiring, paying or subcontracting a Québec contractor.' That is a clear when-to-use context. There is no when-not guidance and no explicit routing to qc_licence or verify_business, so it is context without exclusions.

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

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

Annotations already establish this as a safe, idempotent read, but the description goes well beyond them by disclosing per-call cost ($0.01 USDC), the payment protocol (x402 v2 on Base), the required PAYMENT-SIGNATURE header, and the concrete endpoint. That is exactly the operational context an agent needs to actually invoke a paid tool.

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 core purpose and the sibling routing come first, followed by returns, inputs and payment mechanics — a good front-loaded order with no filler. The payment/endpoint sentence is a little implementation-heavy, but it is necessary for invocation, so only a minor deduction.

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

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

With no output schema, the description compensates by enumerating the returned fields (active flag, licence number, name, NEQ, city, restriction flag, categories). Inputs, cost and transport are all covered, so nothing required to call this 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 description coverage is 100%, so the schema already documents neq, name and licence with formats and patterns. The description only restates the accepted inputs ('name, NEQ or RBQ licence number') without adding matching or format semantics, 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 precise verb and resource ('does this Québec contractor hold an ACTIVE RBQ licence right now?') plus the exact return payload. It explicitly distinguishes itself from the sibling qc-contractor-check, 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?

Names the condition that selects this tool ('vet many contractors fast') and the alternative for the other case ('use qc-contractor-check for RENA and penalties'). Accepted input identifiers are also stated, 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?

Annotations cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description goes well beyond them: per-call cost in USDC, payment rail, ~10 ms challenge latency, ~1.5 s average processing, and the exact auth header and endpoint. That is exactly the payment/auth/latency context an agent needs before calling.

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 functional purpose is front-loaded in the first clause, but the payment boilerplate is verbose and repetitive (x402 named three times, cost restated, the URL broken out as if separate from the header instruction). It could lose a third of its length without losing 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?

With no output schema and a non-trivial payment handshake, the description supplies the endpoint, price, required header, and latency expectations, so an agent can invoke it. It stops short of describing the response shape or failure modes, which would matter for a paid call.

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%, so the description carries the burden. It names two of three parameters (max_words, target language) and restates the 40k text limit, but omits the max_words 20–1000 range, the default, and the language enum values (auto/en/fr), leaving meaningful gaps.

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 ('Summarize text') with an explicit input bound (up to 40k chars) and output character ('faithful, tight summary'). No agent could confuse this with siblings like translate, extract, or pkg_meta.

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

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

The description explains the invocation precondition (pay-per-call over x402, cost, required PAYMENT-SIGNATURE header, endpoint URL), which is real context. It gives no guidance, however, on when to choose summarize over translate or extract, so usage 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, non-destructive), and the description goes well beyond them: it discloses the paid x402 flow, the required PAYMENT-SIGNATURE header, the $0.04 USDC cost on Base, ~25 ms payment challenge latency and ~1.5 s average processing. These are behavioral traits an agent cannot get from the 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?

Purpose is front-loaded in the first clause, which is good, but the remaining sentences are repetitive marketing/payment detail: 'Pay-per-call over x402 in USDC on Base' and 'Costs $0.04 USDC per call (x402 v2, Base)' state the same fact twice. It is denser than it needs to be for a 3-parameter tool.

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

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

With no output schema, the description should ideally state the return shape (translated string), which it does not. However, for this complexity level it covers the critical operational facts an agent needs — endpoint, auth header, cost, and latency — so it is close to complete.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It identifies the language pair (fr/en, matching the target enum) and calls tone optional, but never enumerates the tone values or notes the 1–40,000 character bounds on text, so it only partially compensates.

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 the specific verb (translate), the resource (text), and the scope (French including Quebec French ↔ English) with the optional tone modifier. Nothing about this overlaps with siblings like extract, summarize, or pkg_check, so the agent can route to it unambiguously.

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

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

The description implies when the tool applies (text translation between FR/EN) but never states when to prefer it or what to do instead when the text is already in the target language or too long. It offers payment mechanics rather than usage guidance or exclusions.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial unstated-elsewhere context: $0.05 USDC per call via x402 on Base, the PAYMENT-SIGNATURE header requirement, the exact verdict vocabulary, and the Ed25519-signed receipt with key URL. It falls short of 5 because the receipt sentence is duplicated verbatim and the raw-HTTP payment instructions are awkward for an MCP caller, but the disclosure itself is genuinely rich.

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

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

Front-loaded well with the use case and decision output, but the entire receipt/public-key sentence appears twice word-for-word, wasting roughly a fifth of the text. The tail also drifts into raw endpoint and HTTP-header instructions that clutter the tool-call framing.

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?

Without an output schema, the description usefully pre-announces the return shape: action (allow/review/block), 0-100 risk score, corroborating registries, verdict enum and signed receipt. Coverage of sources and cost is thorough; only edge behavior (e.g. what not_found implies, latency/caching) is absent.

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 name, region and country are already documented. The description restates them ('Input: name, optional country (ISO-2) and region (WA, OR, QC)') and adds only the rationale that specific region codes unlock contractor-licence checks, which is already present in the schema. Baseline 3 is correct.

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 'business' for KYB) and immediately frames the decision output (allow/review/block plus risk score). It is clearly distinguishable from enrichment siblings like company_enrich or the narrow qc_contractor_check, since it names the registries and sanctions lists it corroborates against.

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?

'Call before paying, onboarding or contracting a company' gives an explicit trigger context, and 'Businesses only' sets a scope exclusion. It does not name alternatives or say when to prefer a sibling (e.g. qc_licence for a single licence lookup instead of a full KYB verdict), so the routing guidance stops short of 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?

Goes well beyond the annotations by disclosing pricing ($0.008 USDC via x402 v2 on Base), the required PAYMENT-SIGNATURE header / POST endpoint, and the no-charge 404-on-empty behavior, plus the exact return shape (title, url, snippet, date, clean text, fetch time, sha256). This is unusually rich behavioral disclosure for a read tool.

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 front-loaded: the core capability leads, then features, then cost/auth last. Sentences are information-packed, though the payment/auth tail is slightly run-on and could be tightened.

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 having no output schema, the description fully covers return contents, cost, authentication mechanics, and failure semantics. Nothing an agent needs to invoke and interpret this 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?

The description enumerates the inputs (query, optional read 0-5, official, lang, country, freshness, site) and adds the default read count and mode meanings. Schema coverage is 71% with per-param descriptions already present, so the description mostly reinforces rather than adds new semantics.

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 compound verb+resource ('Search the web and read the top pages in ONE call') and immediately distinguishes itself from pure-fetch siblings by emphasizing it both searches AND reads content. An agent can tell this apart from extract_url or extract 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?

Gives clear contextual conditions: French queries default to French/Canada results, 'official-sources mode' for governments/registries/courts/laws, plus freshness and site: restriction options. It does not explicitly name when to prefer a sibling (e.g. extract_url for a single known URL), 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.