geld machen x402 agent utilities

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 genuinely non-structured behavior: a free sample is returned, the full result costs $0.025 Base USDC via x402, and payment steps are surfaced rather than charged here. The one soft spot is 'optionally 402-probed', which never says who controls that option or what probing changes; openWorldHint=false against 'scraped from public catalogs' is arguably in tension but defensible for a fixed catalog set.

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 verb+resource, then routing, then the pricing caveat. Every sentence carries routing or cost information, though the 'Pick this when...' sentence partially restates the usage guidance already given two sentences earlier.

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

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

An output schema exists, so return-shape explanation is not required, and annotations already carry safety. The description supplies the payment model and alternatives, which is what an agent needs to decide to call it; only the 402-probe behavior and the count-vs-sample interaction remain underspecified.

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

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

Schema description coverage is 100% and the single parameter's schema text ('optional count n (10-80)') already documents the range. The description adds nothing about the query format, and the relationship between the 'query' count and the free-sample/paid-full split is left ambiguous. Baseline 3 for a fully-covered single 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 ('Return a fresh timestamped list of live x402 endpoints scraped from public catalogs (PayAI, CDP)'), including the data source and an optional 402-probe step. It explicitly separates itself from phantom-allowlist (vetted/signed sellers) and phantom-seller-scan (single URL), so an agent can route 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?

Gives an explicit when-to-use ('fresh, broad discovery leads of payable agent APIs'), explicit when-not ('not for a vetted/signed seller list', 'not for checking one URL'), and names the two alternative siblings for those cases. It even supplies a framing question ('what x402 APIs exist right now?') that maps directly to the tool.

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, closed-world), and the description adds the non-obvious behavior that matters here: a free sample is returned plus a paid URL, nothing is charged at this step, and the full result costs $0.02 Base USDC via x402. That payment-path disclosure materially changes how an agent invokes and reports the 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?

Three tight sentences: what it returns, when to use it, and what it costs. The scope and routing constraint are front-loaded, and no sentence is redundant.

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-value explanation is unnecessary, and the description instead covers the things schema cannot: the sample-plus-paid-URL model and the x402 charge. Nothing needed 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% and the single 'query' parameter is documented as a 0x Base address. The description adds token/spender context for the response but no additional syntax or format guidance for the parameter, so the schema carries this dimension.

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 ('List') plus resource ('notable ERC-20 allowances') plus precise scope (Base address, named tokens, DEX/bridge spenders). It explicitly distinguishes itself from the sibling base-balance, 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?

States the trigger ('Use when checking approval risk of a wallet') and an explicit exclusion with the correct alternative ('Not for balances (use base-balance)'). This is exactly the 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 already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description still adds genuinely non-obvious behavior: the call returns a free sample plus paid URL and pay steps without charging, while the full result costs $0.01 Base USDC via x402. It stops short of stating rate limits or what the sample omits.

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

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

Three tight sentences in a deliberate order: what it does, when to use it versus alternatives, then cost/return behavior. Every sentence carries information and none is redundant.

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

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

An output schema exists, so return values need not be described, and the description still covers purpose, alternatives, and the paid-invocation model. It could be slightly more explicit about what the free sample contains versus the paid result, but an agent has what it needs to call correctly.

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

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

Schema description coverage is 100% and there is only one parameter, so the schema already documents that 'query' is a 0x Base address. The description adds no format, example, or validation detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Read live Base ETH and USDC balance of one address') with clear scope. It also distinguishes itself from two named siblings, so an agent can route 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?

Gives explicit when-to-use ('Use when you only need balances') plus two exclusions that each name the correct alternative tool. Nothing about selection 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), but the description adds material behavior beyond them: the call returns only a free sample plus a paid URL and pay steps, no charge is incurred here, and the full result costs $0.02 Base USDC via x402. That payment/partial-result behavior is exactly what an agent needs and cannot infer from 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?

Three compact sentences that front-load the decode scope, then the routing condition, then the payment behavior. No filler, and each sentence 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?

An output schema exists so return values need no explanation, annotations carry the safety profile, and the description fills the remaining gap (payment flow, partial result). Nothing an agent needs to invoke 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?

One parameter with 100% schema description coverage, so the schema already documents 'query' as the 0x tx hash. The description's 'tx hash' phrasing aligns with but does not extend the schema, so the baseline of 3 applies.

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

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

Specific verb ('Decode') plus specific resource ('one Base transaction') and it enumerates the decoded fields: from/to/value/status/logs/method selector. It also names the sibling it is not (base-balance), 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 the trigger condition ('when you have a tx hash and need what it did') and an explicit exclusion with the alternative named ('Not for wallet-wide views (use base-balance)'). Both when-to-use and when-not-to-use are 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 declare the safety profile (readOnly, idempotent, non-destructive), so the description's job is to add context beyond that. It discloses the payment model ($0.05 Base USDC via x402), that the call itself is free and returns a sample plus pay steps, and what the full result covers. Minor gap: it never reconciles the external-URL fetch with the openWorldHint=false annotation, which an agent might want clarified.

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 audit purpose, then usage, exclusions, and the pricing/return note in a tight paragraph with no filler. Slightly dense with secondary commercial details, but each sentence carries information an agent needs.

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 fully explained, and the description still summarizes the free-sample/pay-steps shape. With annotations covering safety and the description covering when-to-use and cost, almost nothing an agent needs is missing; only the payment/completion flow across two calls could be spelled out more.

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

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

Only one parameter and schema coverage is 100%, so the schema already documents that 'query' is the x402 endpoint URL. The description adds no naming, format, or validation detail beyond what the schema states, so the 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 (audit), resource (an x402 endpoint), and the exact dimensions checked (402 header compliance, bazaar schema, quality issues), plus names the CDP Bazaar context. It explicitly distinguishes itself from the sibling url-fingerprint, so an agent can route between them 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 trigger condition ("Use when your x402 endpoint is not showing up in the CDP Bazaar") and an explicit exclusion with the alternative named ("Not for general URL metadata (use url-fingerprint)"). This is the when/when-not/alternative pattern at full strength.

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, closed-world), but the description adds genuinely non-structured behavioral context: a free sample is returned plus the paid URL and pay steps, there is no charge for this call, and the full result costs $0.75 Base USDC via x402. That payment/entitlement disclosure is the kind of thing annotations cannot express; it stops short of a 5 only because it says nothing about latency or rate behavior.

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

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

Five tightly packed sentences: purpose first, then use-when, then use-instead, then a plain-language selector ('what should I check?'), then pricing. Every sentence carries routing or cost information 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?

With an output schema present, return-shape detail is rightly omitted, and the routing plus payment model is covered. The only thin spot is the optional 'query' input, whose role in the paid flow is left entirely to the schema; everything an agent needs to decide and invoke is otherwise present.

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

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

Only one parameter ('query', optional) exists and schema description coverage is 100%, so the schema already documents it as 'offer text (optional)'. The description never mentions the parameter or clarifies that it can be omitted entirely for a generic rubric, so it adds no semantics beyond the schema — the baseline 3 for high coverage 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 concrete verb and deliverable ('Return a 60-second go/no-go checklist and rubric') scoped to 'micro side-income offer'. It explicitly names the siblings it is not (red-flag-scan, offer-score) and frames the selecting question, so an agent can distinguish it from adjacent tools 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 both the positive condition ('when a human-readable checklist is enough and no specific offer needs analysing', 'what should I check?') and the exclusions with named alternatives for each ('Not for scanning a specific offer for scam evidence (use red-flag-scan) or scoring/ranking offers (use offer-score)'). 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds materially new behavior: it returns a free sample plus paid URL and pay steps, with no charge on this call, while the full result costs $0.03 Base USDC via x402. Payment gating is exactly the non-obvious operational context an agent needs before invoking.

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

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

Three tight sentences, front-loaded with the snapshot contents, then routing, then the payment model. No filler and no repetition of the 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, so return-value detail is not needed. The description covers scope, alternatives, and the free-vs-paid x402 flow, which is everything required 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 description coverage is 100% and the single optional parameter is already documented ('optional 0x address'), leaving the description nothing to add beyond what the schema states. Baseline 3 applies when 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 and resource ('Snapshot Base DeFi state: ETH+USDC balances, base fee/block and protocol TVL/APY proxies') and explicitly differentiates from siblings base-balance and base-tx-explain. An agent can select it 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?

Gives an explicit trigger ('when you need a one-call Base market/wallet context') plus exclusions naming the correct alternatives for single-balance and single-tx cases. This is the full when/when-not/alternatives 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 already declare readOnlyHint/idempotent/non-destructive, so the safety profile is covered. The description adds real value beyond that: it discloses the pricing model (free sample, full result $0.05 Base USDC via x402) and that this call itself is uncharted by saying 'no charge here'. It stops short of detailing verification failure modes or rate limits, which keeps it from 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?

Three tight sentences front-loaded with the action, then usage, then cost/return behavior. Every clause earns its place with no redundancy.

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

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

With rich annotations and a declared output schema, the description only needs to add purpose, routing, and cost context, all of which it provides. Nothing an agent needs to decide and invoke 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 a single documented 'query' parameter, so the schema carries the semantic load. The description adds no format or syntax detail beyond it, which is the expected baseline of 3 when the schema is complete.

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 (dry-run), resource (x402 payment payload + requirements), and target (facilitator /verify path) before going live. It explicitly names the sibling payment-receipt-auditor as the thing it is not, so an agent can distinguish it without opening schemas.

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

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

Gives explicit when-to-use (building an x402 seller, checking whether payments will verify) and when-not (auditing a receipt after payment, routed to payment-receipt-auditor). Both the trigger condition and the alternative are 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, so the safety profile is covered. The description adds genuinely new behavioral context the annotations lack: the call is free, requires no payment, and should be made first as a discovery step before paid tools.

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

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

A single front-loaded sentence ('Free, call first') followed by the payload contents and the routing condition. Every clause carries information — no restatement of the name or title and 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?

For a zero-parameter, read-only discovery tool with no output schema, the description still enumerates what comes back (price, paid URL, teaser, payTo) and when to reach for it. An agent has everything it needs to call it correctly on the first turn.

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 zero parameters, so there is nothing for the description to disambiguate; baseline for a no-param schema is 4. The description does clarify that the returned SKU entries carry price, paid URL, teaser and payTo, which is return-shape information rather than parameter guidance.

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 ('list every SKU with price (Base USDC), paid URL, free teaser and payTo') and explicitly frames the outcome ('so you can pick the right paid tool'). That framing distinguishes it from the 20+ sibling tools, which are all single-purpose actions rather than a catalog.

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 entry condition ('Use when unsure which tool fits') and a priority ordering ('Free, call first'), which is exactly the routing guidance an agent needs. It stops short of naming when not to call it, but the condition is unambiguous.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds valuable context beyond that: it returns a free sample plus a paid URL and pay steps with no charge on this call, and the full result costs $0.01 Base USDC via x402. It does not mention rate limits or the OCR engine's accuracy limits, but the payment and cost behavior is well disclosed.

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

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

Three tight sentences with zero waste, front-loaded with the core action and scoping, followed by the usage routing and cost/payment detail. 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?

An output schema exists, so return values need not be explained. For a single-parameter, read-only tool whose annotations cover the safety profile, the description supplies the two things annotations cannot: the usage routing and the two-stage payment flow. 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 description coverage is 100% and the single 'query' parameter is documented as an https image URL in the schema itself. The description repeats that the input is an image URL but adds no syntax, format, or constraint detail beyond the schema. Baseline 3 is appropriate when the schema carries the parameter documentation.

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 (OCR an image URL with local Tesseract) and enumerates the outputs (text, word count, confidence). It distinguishes itself from the sibling url-extract by explicitly excluding web pages, so an agent can route correctly 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?

Provides both a when-to-use condition ('text from a screenshot or scanned image') and a when-not-to-use exclusion with the named alternative ('Not for web pages (use url-extract)'). 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, but the description adds material behavior beyond them: a free sample is returned, the paid URL plus pay steps are included, no charge happens at this call, and the full result costs $17 Base USDC via x402. That payment-flow and cost disclosure is exactly the kind of context an agent needs before invoking.

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

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

Three tight sentences, front-loaded with purpose, then audience, then a negative routing rule, then the return/pricing facts. No filler sentences.

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-value structure needn't be explained; the description still covers what the caller receives, what it costs, and who should call it. Nothing material is missing for correct invocation.

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

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

There is a single optional parameter with 100% schema description coverage ('Input for the paid endpoint: not needed'), so the schema already carries the semantics. The description adds no further parameter detail, which is the correct baseline-3 outcome when the schema is complete.

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 concrete verb and resource ('Download a German PDF guide: 7 legal side-income routes in Switzerland') and immediately distinguishes itself from agents by stating 'Not for agent automation (use the JSON tools)'. An agent can tell this apart from sibling JSON tools like side-income-pdf 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?

It gives an explicit when ('when a Swiss/German-speaking human wants a guide') and an explicit when-not ('Not for agent automation'), which is exactly the routing guidance needed. The alternative is named generically ('the JSON tools') rather than by exact tool name, but the selection condition is unambiguous.

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

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

Annotations already cover the safety profile (readOnly, idempotent, not destructive, closed-world), and the description adds substantial context beyond them: local heuristics (no external calls), a free sample plus paid URL/pay steps, and the exact cost ($0.35 Base USDC via x402). That payment and sample/full distinction is behavior an agent cannot derive from 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 the capability, then routing, then pricing. Dense but every sentence carries information; slight cost is that exclusions, selection cue, and pricing are packed into a single block that 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?

With an output schema present, return values need no explanation, yet the description still summarizes the result bands and free-sample behavior. Cost, input nature, and sibling boundaries are all covered, leaving nothing an agent needs 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 description coverage is 100% for the single 'query' parameter, so the schema fully documents input. The description only implies the input is pasted offer text via the title; it adds no syntax or format guidance beyond structured data, 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+resource with the exact output shape (0-100 score, GO/MAYBE/NO-GO band, 8 rubric dimensions, rewrite tips) and explicitly names what it is not (scam evidence, URL checks). An agent can distinguish it from red-flag-scan and deal-brief 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 when-to-use ('rank several offers', 'which offer is best?') plus when-not, naming the two alternative siblings by name for the cases this tool doesn't cover. 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 the safe-read profile (readOnlyHint, idempotentHint, non-destructive), and the description layers on the non-obvious commercial behavior: a free sample plus paid URL, no charge on this call, and the $0.02 Base USDC x402 cost of the full result. That payment/retry semantics is exactly the context the 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?

Three tightly packed sentences that front-load the core action and the routing exclusion. The final pricing sentence is information-dense but earns its place by stating the cost model up front.

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, annotated, read-only tool with an output schema, the description supplies everything an agent needs: trigger, exclusion, payment cost, and free-sample behavior. Nothing material 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 there is only one parameter, so the schema already documents the input. The description reiterates the same accepted forms (0x… hash or PAYMENT-RESPONSE JSON), adding little beyond the schema; baseline 3 is warranted.

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 (Verify) and resource (x402 PAYMENT-RESPONSE or settle tx hash on Base), with the exact artifact being audited named. It explicitly distinguishes itself from the sibling facilitator-dry-run, 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 a clear trigger ('when a paid call failed or looks unsettled and you need proof') and an explicit exclusion with the alternative named ('Not for pre-launch payload checks (use facilitator-dry-run)'). Both when-to-use and when-not-to-use 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 declare readOnly, idempotent, non-destructive, closed-world. The description adds real behavioral context beyond that: a free sample plus the paid URL and pay steps with no charge here, and the full result costs $0.03 Base USDC via x402. It slightly undersells what the paid purchase actually yields, so not quite 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 purpose, then routing, then the payment model. Every sentence carries information, though the rhetorical 'Pick this when the question is...' line is slightly promotional rather than purely functional.

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 restated, and the description supplies purpose, alternatives, and the free-vs-paid cost model. A brief note on what the signed allowlist actually enables after purchase would make it fully 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 100% and there is only one optional parameter (max sellers, 1-40), already documented in the schema. The description adds no parameter syntax or format beyond 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 — 'Return an HMAC-signed allowlist of x402 sellers with probe evidence' — including the concrete evidence fields (402 seen, probe ok, last paid ok). It also names the sibling tools it is not, so an agent can distinguish it from phantom-seller-scan and agent-lead-pack 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 when-to-use ('before spending', 'whom can I safely pay?'), explicit when-not (one specific URL -> phantom-seller-scan; raw unvetted leads -> agent-lead-pack), and names each alternative with its selecting condition. 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 the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), and the description adds non-obvious behavioral context: a free sample is returned, the paid URL and pay steps are exposed, and the full result costs $0.03 Base USDC via x402. That pricing/payment behavior is exactly the kind of thing structured fields do not convey, though pagination/response shape detail is absent.

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 scoping statement and exclusions are front-loaded and every sentence carries information. A couple of phrasings are slightly clunky ('Use when before integrating'), 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?

An output schema exists, so return values need not be explained, and the description still summarizes what comes back (free sample plus paid URL and pay steps). With one simple parameter and full annotation coverage, the definition is essentially complete; only deeper result-format nuance is missing.

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

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

There is a single parameter with 100% schema description coverage, so the schema already documents that 'query' is the x402 endpoint URL. The description adds only the framing that this is an unknown endpoint the caller already possesses, not new syntax or format detail — baseline 3 is appropriate.

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

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

The description names a specific verb and resource — checking whether an x402 URL's payTo actually receives Base USDC (live vs phantom) — and explicitly distinguishes itself from phantom-allowlist and agent-lead-pack. An agent can identify the tool's exact job 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?

It states when to use it ('before integrating or paying one unknown x402 endpoint you already have'), when not to (listing many vetted sellers, finding new endpoints), and names the alternative tool for each exclusion. The selecting question is spelled out verbatim.

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, but the description adds genuinely new behavior: a free sample plus a paid URL, pay steps returned, and a $0.49 Base USDC x402 charge. It does not detail what the free sample contains versus the paid result, which is the only meaningful gap.

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

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

Three sentences, zero filler, front-loaded with the deliverable before the routing note and the pricing note. Every sentence contributes 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?

An output schema exists so return values need no explanation, and the payment model, free sample, and alternative tool are all disclosed. The only omission is how the x402 payment is actually completed, which the description defers to 'pay steps' in the response.

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 optional 'query' parameter with 100% schema coverage, and the schema description itself says it is 'not needed.' The description adds no parameter semantics beyond that, so the baseline 3 applies when the schema carries the burden.

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 count and scope: 'Return 10 reusable prompts for finding, pricing, pitching and delivering micro side-income work.' It also explicitly names what it is not ('Not for analysing a specific offer') and routes to the sibling offer-score.

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 a positive trigger ('Use when an agent needs ready prompts for freelance/gig operations') and an explicit exclusion with the alternative tool named ('use offer-score'). Selection is unambiguous.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), but the description adds real value beyond them: the free-sample vs paid-result split, the exact price ($0.25 Base USDC via x402), and that no charge occurs on this call. That payment/auth context is the key operational fact an agent needs before invoking, though it does not discuss latency or rate limits.

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

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

Three tight sentences, front-loaded with what it does and followed by routing exclusions and the payment flow. No filler and every clause carries decision-relevant information.

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

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

An output schema exists, so return structure need not be described, yet the description still clarifies the free-sample vs paid-URL/pay-steps split. Together with the explicit sibling routing and cost, an agent has everything needed to select and call this tool correctly.

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

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

Schema coverage is 100% and there is only one parameter, whose description already documents the offer-text format and the ' | https://…' URL-append convention. The description adds no syntax or format detail beyond the schema, 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 ('scan one offer/pitch') and enumerates exactly what it produces (12 evidence-quoted red flags plus live URL anchors covering HTTP/TLS/DNS and RDAP domain age). It also explicitly contrasts itself with the closest siblings (offer-score, deal-brief), so an agent can route 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?

Gives an explicit when-to-use ('decide whether a specific offer or seller page is a scam before paying or replying'), explicit when-not-to-use cases, and names the two alternative tools with the conditions that select them. It even restates the routing question as 'is THIS offer a scam?', 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 only declare safety traits (readOnly, idempotent, non-destructive); the description goes well beyond them by disclosing the delivery model: a free sample plus paid URL and pay steps, with no charge at call time and a $17 Base USDC x402 charge for the full result. That payment/return behavior is exactly what the 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?

Three tight sentences, each earning its place: artifact, usage routing, then pricing/return behavior, front-loaded in that order. No repetition of the title or redundant 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?

For a zero-required-param download tool with an output schema present, the description supplies everything else the agent needs: audience, exclusion, cost, and what the response contains. Nothing material is missing.

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

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

Schema description coverage is 100% and the single 'query' parameter is already documented as 'not needed' in the schema, so the description carries no additional parameter detail. Baseline 3 applies since the schema does the heavy lifting and no enum/format nuance is missing.

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 artifact: 'Download an English PDF playbook with 7 side-income plays starting under $100.' It also differentiates itself from the JSON/automation siblings and implicitly from nebenverdienst-pdf, so an agent can tell what it produces 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?

Explicit when-to-use ('Use when a human wants a full guide') and when-not ('Not for agent automation (use the JSON tools)'), routing the caller to an alternative tool class. Nothing about selection 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?

Beyond the annotations (readOnly/idempotent/non-destructive), it discloses that fetching is local, that this call returns a free sample plus the paid URL and pay steps with no charge, and that the full result costs $0.02 Base USDC via x402. This payment/cost model is substantial behavioral context an agent cannot get from 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, followed by usage, exclusion, then payment model, with no filler sentences. The final payment sentence is dense but each clause carries needed information, so it is close to optimally sized.

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

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

With an output schema present, return values need not be explained, and the description still covers purpose, scope, alternative, fetch method, and pricing. 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 coverage is 100% and the single param is already documented as an https URL input for the paid endpoint. The description only loosely restates 'from a URL' and adds no format or constraint detail. Baseline 3 is appropriate when 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?

It names a specific verb (Extract) and resource (URL) and enumerates exactly what is returned: title, meta description, ~3k chars plain text, and outbound links. It also differentiates itself from the sibling web-extract by naming what it is not for.

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 the positive condition ('when you need readable page text cheaply') and the negative condition with the named alternative ('Not for clean markdown of JS-heavy pages (use web-extract)'). Both when-to-use and when-not are explicit, so no inference is required.

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), so the bar is lower, yet the description adds substantive context: a free sample is returned here with no charge, and the full result requires $0.01 Base USDC via x402. That payment/authorization behavior is not in any structured field. It stops short of disclosing rate limits, caching, or when the paid URL must be called, so a 4 rather than 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?

Three sentences, each with a distinct job: what it returns (front-loaded), when to use it, and the payment model. No filler and no repetition of the title or 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?

An output schema exists, so return values need not be explained in prose, yet the description still summarizes them. Combined with the payment flow and sibling routing, an agent has everything needed to call this tool correctly.

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

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

There is a single parameter with 100% schema description coverage, so the schema already documents it. The description's mention of 'a URL' adds no syntax or format detail beyond the schema's 'https URL'. Per the high-coverage rule, 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?

The description names a specific verb ('Fingerprint') and resource ('a URL') and enumerates the exact artifacts returned: final URL, status, content type, body SHA-256, TLS issuer, DNS sample. It also explicitly distinguishes itself from the url-extract and web-extract siblings, so an agent can route 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?

It gives a positive trigger ('detecting page changes or verifying a site cheaply') and explicit exclusions with named alternatives ('Not for page text (use url-extract) or markdown (use web-extract)'). This is exactly the when/when-not/alternative structure that removes 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 the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower, and the description still adds real behavioral context: JS-heavy pages are handled, the call is free and returns a sample plus pay steps, and the full result costs $0.03 Base USDC via x402. It stops short of describing what the free sample contains, truncation limits, or what a caller needs (wallet/auth) to complete the paid step.

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 first, then use-when, then exclusion, then cost — every sentence is load-bearing. The final cost sentence is slightly run-on ("Returns a free sample plus the paid URL and pay steps (no charge here); the full result costs $0.03..."), which keeps it just under ideal.

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 structure need not be described; the description covers the unusual parts an agent needs (free sample vs paid full result, x402 payment). It leaves the payment mechanics and any prerequisites for the paid call unexplained, which is the only remaining 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 description coverage is 100% for the single parameter, so the baseline is 3. The description adds no parameter-level detail (it never mentions the `query` field or the https-URL format), but the schema already carries that meaning.

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

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

Specific verb + resource + modality: "Scrape a URL to clean markdown via Firecrawl (handles JS-heavy pages)". It also carves out what it is NOT (cheap hash/excerpt) and names the two siblings that serve that need, so an agent can separate it from url-extract and url-fingerprint 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 when-to-use ("Use when you need LLM-ready markdown of a page") and explicit when-not-to-use with named alternatives ("Not for a cheap hash/excerpt (use url-fingerprint or url-extract)"). 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?

The description does add useful behavioral context beyond annotations: it discloses the free-sample/paid-URL response shape, that this call itself is not charged, and the $0.02 Base USDC x402 cost of the full result. However, it describes a live external web search (Serper upstream), which directly conflicts with the annotation openWorldHint=false; an agent relying on that annotation would misjudge whether the tool reaches outside the sandbox.

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 sentences, front-loaded with purpose and routing before the commercial detail, with no filler. The payment sentence is slightly dense and parenthetical, but every clause conveys something an agent needs (free sample, pay steps, price).

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 one-parameter search tool with an output schema and read-only annotations, the description covers purpose, the sibling alternative, and the x402 payment flow. Return values need not be explained because an output schema exists, so nothing essential is missing.

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

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

Schema description coverage is 100% for the single query parameter, including the optional n=5..10 JSON encoding, so the schema already carries the parameter detail. The description adds no syntax or format information beyond that, which is the baseline-3 case.

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 ('Web search: ranked title/url/snippet results') plus the upstream provider (Serper), and explicitly distinguishes itself from the sibling url-extract. An agent can identify what this returns and what it is not 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 both the positive trigger ('Use when you need live search results for a query') and the exclusion with a named alternative ('Not for fetching a known URL (use url-extract)'). This is explicit when/when-not/alternative guidance.

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