VIA - Web/PDF extraction and API comparison

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

Annotations declare openWorldHint=true, readOnlyHint=false, and idempotentHint=false, and the description adds substantial context beyond them: the exact cost (0.01 USDC or 0.01 USD credit), the required wallet/header auth, and the requestId retry semantics that prevent a duplicate debit. It stops short of describing failure/refund behavior or what happens if the credit balance is insufficient, so it is strong but not exhaustive.

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?

Payment and auth conditions are front-loaded and the output ("recommendation and alternatives") and boundary ("supplier purchase is separate") are stated compactly. The clause stacking is dense but each sentence contributes information; there is little 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 supply the return shape (recommendation plus alternatives), payment model, auth requirements, and the retry/idempotency contract. The main gap is that the country and language parameters affecting comparison are left unexplained, which matters for a geographically scoped comparison 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 only 25%, so the description carries added burden; it does explain requestId well (fresh UUID per task, reused only for identical retries) and ties it to the credit payment path. But country and language are never mentioned, and intent is only indirectly conveyed through "buyer task."

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?

"Compare APIs for a buyer task" gives a specific verb (compare) and resource (APIs) scoped to a buyer use case, which separates it from sibling listing/lookup tools like via_list_services. It does not explicitly contrast with via_one_call or via_one_call_quote, the closest competing buyer tools, so the distinction is inferable rather than stated.

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 does explain the two payment paths (x402 USDC on Base vs prepaid VIA credit with an x-credit-token header) and that supplier purchase is a separate step, which implies this is a pre-purchase comparison step. However, it never states when to choose this over via_one_call, via_one_call_quote, or via_list_services, so selection guidance is implied 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?

The annotations mark this as readOnly=false and non-idempotent, which is confusing for a pure extraction; the description resolves that by disclosing that it is a paid call (0.02 USDC on Base via x402) whose payment executes only after buyer approval. It still doesn't say what 'structured text' looks like, whether auth-restricted pages fail, or how truncation behaves.

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

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

Two tight sentences, front-loaded with the action and the cost term. Nothing is wasted.

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

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

With no output schema, a 0%-documented three-parameter schema, and an identical-sounding sibling, the description leaves too much unstated: what the result contains, how maxChars and includeLinks affect it, and why an agent would pick this over via_extract_web_lite.

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% across three parameters, so the description carries the full burden, yet it never mentions url, maxChars, or includeLinks. Only 'public web page or PDF' implicitly hints that the URL must be publicly reachable.

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: extract structured text from a public web page or PDF. However, it gives no cues to distinguish it from the sibling via_extract_web_lite, which sounds like the same job, so an agent cannot tell them apart from the description alone.

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

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

There is no when-to-use guidance and no named alternative; the obvious competitor via_extract_web_lite is never mentioned. The only contextual information is the price, which tells the agent what a call costs but not when to choose this tool over its siblings.

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: discloses the exact price (0.001 USDC on Base via x402), that payment occurs only after buyer approval, and that nothing is charged on failure. The readOnlyHint=false is consistent with a tool that triggers a payment side effect, so there is no contradiction.

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 exclusions are front-loaded and every sentence carries information (limits, exclusions, price, refund policy). The dense nested parentheticals make it slightly harder to scan than it needs to be, but nothing 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 still names what comes back (clean text, title, headings), plus size caps, cost, failure/refund behavior, and the sibling for the PDF case. Nothing an agent needs in order 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 only 50% — url is documented in the schema and maxChars is not, though it carries default/min/max constraints. The description adds useful caps (1 MiB page, max 10000 characters) but does not explain maxChars truncation behavior or the minimum, 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 and resource ('extract clean text, title and headings from a public HTML or plain-text page') plus the output shape and hard limits. It explicitly distinguishes itself from the sibling via_extract_page (which handles PDFs), so an agent can choose 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 explicit when-not-to-use conditions (no PDF, OCR, JavaScript rendering or links) and names the alternative tool with its price for the excluded case. It also notes PDF URLs are refused before payment, so the agent knows failure happens before cost.

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 closed-world, so the description needn't repeat them; instead it adds genuinely new behavior: what is returned (endpoint, schema, example, x402 payment steps) and what is explicitly NOT done (no execution, no payment authorization). It does not mention caching or what happens with an invalid name, but the side-effect profile is clear.

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

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

Two sentences, zero filler, with the value proposition front-loaded and the negative constraint in the trailing clause where it belongs.

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 read-only lookup with no output schema and a fully documented single parameter, the description covers the content of the response and the no-side-effect guarantee. Minor gap: nothing about failure modes if the service name is unknown or unlisted.

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?

One parameter at 100% schema coverage, and the schema already explains it must be the exact name from via_list_services. The description adds only that the name identifies a single service. Baseline 3 given the schema does the heavy lifting.

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 (get) and resource (integration instructions for one VIA HTTP service) and enumerates the payload contents: exact endpoint, JSON input schema, example, x402 payment steps. The closing clause 'Does not execute the service or authorize payment' cleanly separates it from execution-oriented siblings like via_one_call.

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 negation clause implies the correct context (use this to learn how to integrate, not to run a call), and the schema points the agent at via_list_services for valid names. It stops short of explicitly naming via_one_call as the alternative for actual execution, so the routing is inferable rather than spelled out.

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 closed-world, so the safety profile is covered. The description adds real value beyond that: it is explicitly free and will not charge, sign or purchase, which is material for an agent deciding whether calling it has side effects.

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

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

Two short sentences, zero waste, with the positive scope stated before the exclusions. Nothing redundant with the schema or annotations.

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

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

For a single-optional-parameter, read-only discovery tool with no output schema, the description covers what it returns (services and advertised prices) and what it will not do. Minor gaps: no hint about result volume or how to follow up with via_get_service.

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% for the single optional query parameter, so the baseline is 3. The description adds no guidance on filter syntax or matching behavior beyond what the schema already says.

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

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

States a concrete verb and resource: "Lists HTTP services and advertised prices." The negative clause ("does not run research, charge, sign or purchase") implicitly separates it from the transaction-oriented siblings like via_one_call and via_one_call_quote, though it never names them.

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?

"Free VIA service discovery" hints that this is the entry point before via_get_service or via_one_call_quote, and the exclusions tell the agent what this tool will not do. But there is no explicit "use this first, then X" routing or statement of when to prefer via_get_service instead.

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?

Adds substantial behavior beyond the annotations: money moves (buyer pays before the supplier), VIA relays delivery and retains margin, there is no automatic signing or financial retry, and the retry must be identical. This matters because destructiveHint=false and idempotentHint=false alone would not tell an agent that a real charge occurs or that retries are unsafe.

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 action and then the payment protocol; every clause carries operational weight (offer phase, retry identity, funding exclusions). Dense phrasing ('retains its margin', 'eligible external supplier') is compressed but not padding.

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 paid, open-world, non-idempotent tool with no output schema, the description covers the offer-phase return value and the payment protocol. It does not say what a successful execution returns or how delivery/status is retrieved (e.g., via_one_call_status), leaving a small gap.

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 already documents maxUsdc and orderId, but the description adds the retry contract (identical task, maxUsdc, orderId) and the location of the buyer-signed payload in params._meta['x402/payment'] — a field that is not in the schema at all despite additionalProperties=false. That extra detail is valuable but slightly at odds with the schema.

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

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

States a specific verb and resource: execute a VIA toll operation via the One-Call payment/delivery handler, and describes the two-phase x402 offer-then-pay flow. It is distinguishable from most siblings, though the first-call-returns-offer behavior overlaps with the sibling via_one_call_quote, which is never named.

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 clear procedural context: first call without payment, then retry with an identical body after buyer approval. It also states exclusions ('Only supported tasks/suppliers', 'No automatic signing or financial retry', 'Prepaid comparison credits do not fund this tool'). It stops short of explicitly routing to via_one_call_quote or via_one_call_status by name.

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?

Adds real behavior beyond the annotations: what the response contains (supplier cost, VIA margin, total), that no wallet signature or payment is required, and that the result carries ok/executionEnabled gates an agent must check. Annotations already cover the read-only/idempotent profile, so this is a solid supplement rather than a full disclosure (no mention of quote expiry, error behavior, or bind semantics).

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

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

Four short sentences, front-loaded with what the tool produces, then the safety/eligibility constraint. No filler or repetition.

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

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

With no output schema, the description carries the burden of describing returns and does name the key fields plus the ok/executionEnabled gates and the no-payment guarantee. It is nearly complete for a read-only quote; the main omission is anything about quote validity/lifetime or the meaning of a failed quote.

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 never mentions task, maxUsdc, or orderId, so it adds nothing to what the schema documents. With schema coverage at 67% and a non-obvious param (private client UUID for retry/recovery) described only in the schema, the description should have explained that orderId is unnecessary for a quote—it does not.

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

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

Names a specific verb+resource ('quote for the VIA toll') and describes the sourcing rule (VIA-owned delivery first, eligible paid supplier otherwise). It implicitly separates itself from execution siblings like via_one_call by being the free preflight, though it never names an alternative tool outright.

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 gating rule: 'Continue only if ok and executionEnabled are true', which tells the agent exactly when to proceed versus stop. It also signals this is a no-cost, no-signature step, implying it precedes payment/execution. It stops short of naming the follow-up tool or listing when-not-to-use cases.

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 closed-world, so the safety profile is covered; the description adds genuinely new facts — the call is free, never submits payment, and 404 must not be read as proof of non-payment. It stops short of describing what the status/recovery payload looks like, which matters given there is no 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?

Three short sentences: purpose first, then the non-mutating guarantee, then the scope caveat. No filler, and the most decision-relevant facts are front-loaded.

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

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

For a single-parameter read tool this is close to sufficient, and the 404 caveat is valuable. But with no output schema, the description should say what a successful lookup returns (status fields, recovery details) — that gap is left entirely to inference.

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 100% schema description coverage, the schema already documents orderId as a private client-generated UUIDv4 that must be preserved for retry. The description's "private UUIDv4" phrasing reinforces but does not extend that, 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: a status/recovery lookup for an external Transit order keyed by its private UUIDv4. "Never submits payment" implicitly separates it from the order-submitting sibling via_one_call, though no sibling is named explicitly.

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 conditions for use (status/recovery of an existing external order) and scope exclusions ("Does not cover VIA-owned service receipts"). It also supplies interpretive guidance that a 404 is not proof a payment failed, but does not explicitly name which sibling to call instead for submitting or quoting.

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