geld machen x402 agent utilities

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

Annotations cover the safety profile (readOnly, non-destructive, idempotent), and the description adds high-value behavioral facts beyond them: optional 402-probing, a free sample vs paid full result, the exact price ($0.025 Base USDC via x402), and that discovery is unvetted/raw. This is exactly the kind of economic and freshness context annotations cannot convey.

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

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

Front-loaded purpose sentence, then usage, then constraint, then economic model. Dense but every clause carries routing or pricing information. Slightly cluttered by the mixed parentheticals but 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?

For a paid discovery tool with an output schema present, the description covers what an agent needs: what it returns, when to use it, cost, and the free-sample/paid split. Minor gap: it doesn't state whether the 402-probe is default-on or requires a flag.

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

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

Schema coverage is 100%, so baseline is 3. The description adds the intent of the query param ('optional count n 10-80') and the payment/probing behavior surrounding it, though it leaves some ambiguity about how 'query' maps to free sample vs paid call. Slightly above baseline.

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

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

States a specific verb+resource ('Return a fresh timestamped list of live x402 endpoints') with explicit data sources (PayAI, CDP) and names the sibling it excludes (phantom-allowlist). An agent can distinguish this from all other discovery tools 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 ('when you need discovery leads of payable agent APIs') and an exclusion with a named alternative ('Not for vetted payable sellers only — use phantom-allowlist'). This is textbook routing.

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 description earns credit for adding the commercial behavior instead: it returns a free sample plus a paid URL and pay steps, with no charge at this call and a stated $0.02 Base USDC x402 price for the full result. That is exactly the kind of context annotations cannot express; it only misses latency/rate-limit or partial-result 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?

Three tight sentences: capability first, then usage/exclusion, then return-and-pricing behavior. No filler, and the routing hint and cost disclosure are both placed where an agent will read them before invoking.

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 elaboration, and the description still previews the shape (free sample + paid URL/pay steps). Combined with the token scope, wallet-risk use case, sibling exclusion, and pricing, an agent has everything needed to call this correctly and interpret 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?

Schema coverage is 100% and the schema already labels the single parameter as a '0x Base address', so the baseline is 3. The description adds scope meaning beyond the schema by fixing which tokens and spender categories the address is scanned for, which tells the agent what the query will actually return.

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 notable ERC-20 allowances of a Base address') and narrows scope with an explicit token/spender list (USDC/WETH/USDT/DAI/cbETH to DEX/bridge spenders). It also names the sibling it is not (base-balance), so an agent can separate it from adjacent tools without reading either schema.

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

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

'Use when checking approval risk of a wallet' gives a concrete triggering scenario, and 'Not for balances (use base-balance)' supplies an explicit exclusion plus the alternative to route to. Nothing about when to pick this tool 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, so the safety profile is covered. The description adds genuinely new behavior: a free sample is returned with the paid URL and pay steps at no charge, and the full result costs $0.01 Base USDC via x402 — the pricing/payment model an agent must know before calling.

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

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

Three sentences, each earning its place: purpose, routing, then payment behavior. Purpose and exclusions are front-loaded before the cost detail.

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. Given a single-parameter read tool with full annotation coverage, the description supplies everything needed: scope, alternatives, and the x402 payment model.

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 the 0x address input. The description restates "one address" but adds no syntax or format detail beyond the schema; baseline 3 is appropriate.

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

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

States a specific verb (read) and resources (live Base ETH and USDC balance) scoped to one address. The sibling list is named and differentiated, so an agent can distinguish this from base-allowance-scan and defi-base-snapshot 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?

Explicit when-to-use ("Use when you only need balances") plus explicit when-not with two named alternatives for allowances and DeFi context. Routing is unambiguous.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description adds genuinely non-obvious behavior: the call itself is free, it returns a sample plus a paid URL and pay steps, and the full result costs $0.02 Base USDC via x402. That payment/authorization model is the key trait an agent must know and is not in any structured field. It stops short of saying what the free sample contains or how the x402 handoff completes.

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 filler, front-loaded on the decode scope and immediately followed by the routing rule and the payment model. Every clause 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?

Output schema exists, so return values need no prose, and annotations cover the safety profile; the description fills the remaining gap with the payment flow. The only unaddressed item is what happens when the optional 'query' parameter is omitted, a minor gap for an otherwise complete definition.

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 schema already documents 'query' as a 0x tx hash, so the baseline of 3 applies. The description's 'you have a tx hash' restates that without adding format, validation, or alternative-input guidance; it also never mentions that the parameter is optional (0 required).

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 (Decode) and resource (one Base transaction) and enumerates the decoded fields (from/to/value/status/logs/method selector), so the agent knows exactly what comes back. It also names the sibling it is not (base-balance) for wallet-wide views, making it distinguishable 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?

Explicit trigger: 'Use when you have a tx hash and need what it did.' Explicit exclusion plus alternative: 'Not for wallet-wide views (use base-balance).' Both when-to-use and when-not-to-use are stated, with the routing sibling named.

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

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

Annotations already declare a safe, idempotent, non-destructive read (readOnlyHint, idempotentHint, destructiveHint=false). The description adds genuinely non-obvious behavior: a free sample is returned with the paid URL and pay steps at no charge, while the full result costs $0.05 Base USDC via x402. That pricing/return-flow disclosure is above what the structured fields 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 dense sentences, front-loaded with the purpose, then the trigger, then the exclusion, then the payment/return model. No filler and nothing repeated from the name 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?

An output schema exists, so return-value documentation is not required, yet the description still clarifies the free-vs-paid result split and the payment mechanism. Combined with exhaustive purpose and exclusion guidance, an agent has everything needed to select and invoke it.

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

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

Schema description coverage is 100% and the single 'query' parameter is already documented as the https x402 endpoint URL. The description implies the same input but adds no format, syntax, or validation 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 — auditing an x402 endpoint for CDP Bazaar indexing — and enumerates the checks performed (402 header compliance, bazaar schema, quality issues). It also explicitly distinguishes itself from the sibling url-fingerprint, so an agent can route correctly without opening either schema.

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

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

Gives an explicit trigger ('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 declare the read-only, idempotent, non-destructive profile, so the bar is lower. The description adds non-obvious monetization behavior: a free sample plus a paid URL, with the full result gated at $0.75 Base USDC via x402 and no charge on this call. That payment-gating disclosure is genuinely useful, though failure modes are not covered.

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 earning its place: purpose, usage routing, then payment model. The core purpose is front-loaded and 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?

With an output schema present, return values need not be explained, and the description covers purpose, the alternative sibling, and the payment gating. Complete for a single optional-param read tool, with only minor depth missing on the free-vs-paid boundary.

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

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

Schema description coverage is 100%, so the single optional 'query' parameter is already documented as offer text. The description adds no additional parameter syntax or meaning 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 ('Return a 60-second go/no-go checklist and rubric for any micro side-income offer') and names the sibling it is not (red-flag-scan). An agent can distinguish it from offer-score and red-flag-scan 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 ('when a human-readable checklist is enough') and when-not ('Not for evidence-grounded scam detection'), routing the agent to the named alternative red-flag-scan. 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 safety (readOnly, idempotent, non-destructive) but the description adds the critical commercial behavior that structured fields cannot: it returns a free sample plus a paid URL and pay steps with no charge at snapshot time, and the full result costs $0.03 Base USDC via x402. For a monetized tool, this pricing/payment context is essential and non-obvious.

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, then usage/exclusions, then the payment model. Every sentence earns its place with zero padding, and the most decision-critical routing info (when to use / not use) precedes the pricing detail.

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 not needed, annotations handle the safety profile, and the description covers the remaining gaps: what data is bundled, sibling disambiguation, and the x402 payment flow including cost and that this call is free. 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?

Only one optional parameter (query) with 100% schema description coverage already explaining it takes an optional 0x address. The description does not add format constraints or examples beyond 'optional 0x address', so the schema does the heavy lifting. 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?

States the specific verb+resource ('Snapshot Base DeFi state') and enumerates the exact bundled outputs: ETH+USDC balances, base fee/block and protocol TVL/APY proxies. It also names the two sibling alternatives it is not, so an agent can differentiate it from base-balance and base-tx-explain without reading their schemas.

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

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

Explicitly states the use case ('when you need a one-call Base market/wallet context') and the exclusions with named alternatives ('Not for a single balance (use base-balance) or one tx (use base-tx-explain)'). This is textbook when-to-use/when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint/idempotent/non-destructive, so the safety profile is covered. The description adds material context beyond them: it returns a free sample plus the paid URL and pay steps, and the full result costs $0.05 Base USDC via x402. It does not cover rate limits or auth details, but the two-tier pricing behavior is the key disclosure.

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 no waste: purpose and mechanism first, then usage routing, then the pricing/return behavior. Every sentence earns its place and nothing is buried.

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, yet the description still summarizes the response shape and cost. Combined with explicit usage routing and a precise purpose statement, an agent has everything needed to select and invoke it.

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

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

Schema description coverage is 100% and there is a single 'query' parameter, so the schema already carries the burden. The description echoes the payload/requirements content of that parameter but adds no format or syntax detail beyond it, making the baseline 3 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?

States a specific verb (dry-run) and resource (x402 payment payload + requirements against the facilitator /verify path), and explicitly distinguishes itself from the sibling payment-receipt-auditor. An agent can identify this tool without opening the schema.

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

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

Gives explicit when-to-use ('when you build an x402 seller and want to know if payments will verify') and an explicit when-not with the named alternative ('Not for auditing a receipt after payment (use payment-receipt-auditor)'). Routing is unambiguous.

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

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

Annotations already declare 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 cover the safety profile (readOnly, idempotent, non-destructive), but the description adds genuinely novel behavior: local Tesseract execution, a free-sample-plus-paid-URL response shape, 'no charge here', and the $0.01 Base USDC x402 cost to unlock the full result. This two-tier payment mechanic is exactly what annotations cannot convey. It stops short of noting rate limits or failure modes, hence not a 5.

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

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

Three dense sentences, front-loaded with the core action and output before routing and pricing details. Every clause earns its place, though the payment mechanics make the tail slightly crowded.

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

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

With an output schema present the description needn't enumerate return fields, and it still flags the sample/paid response shape and pricing. Combined with full annotation and schema coverage, an agent has everything needed 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 already carries the semantics. The description restates 'image URL' but adds no format, size, or encoding guidance 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+resource ('OCR an image URL') and enumerates outputs ('text, word count, confidence'). It also names the sibling it is not for ('Not for web pages (use url-extract)'), 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?

Explicit when-to-use ('text from a screenshot or scanned image') and when-not ('Not for web pages') paired with the concrete alternative (url-extract). Nothing is left to inference about routing.

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), yet the description goes further and discloses the actual behavior: a free sample is returned here with a paid URL and pay steps, no charge at this call, and the full result costs $17 Base USDC via x402. That pricing/payment flow is exactly the 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?

Three short sentences, front-loaded with purpose, then trigger, then return/pricing behavior. Every sentence carries distinct information 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?

For a download tool with an output schema present, the description still covers the essentials an agent needs: audience, exclusion, what is returned free, and the paid path. 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 optional param is documented there as 'Input for the paid endpoint: not needed.' The description adds no parameter detail, but with full schema coverage and one optional param, the baseline of 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?

States a specific verb and resource (download a German PDF guide) plus the exact content scope (7 legal side-income routes in Switzerland). The 'German' qualifier implicitly separates it from the English-named sibling side-income-pdf, and the JSON-tools exclusion further scopes it.

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

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

Gives an explicit trigger ('Use when a Swiss/German-speaking human wants a guide') and an explicit anti-trigger ('Not for agent automation (use the JSON tools)'), naming the alternative category. Nothing about when to pick this vs. siblings 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 (readOnly, idempotent, non-destructive), but the description adds the crucial commercial behavior: local heuristics, a free sample returned here with no charge, and the full result costing $0.35 Base USDC via x402. That payment/auth context is exactly what annotations cannot convey. It stops short of clarifying how much of the score is usable from the free sample versus the paid call.

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

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

Three tight sentences, front-loaded with the output shape before the routing rule and the payment note. Every sentence carries load, though the trailing payment clause is packed into a single dense parenthetical.

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 needn't be restated, and the description covers purpose, routing, heuristics, and cost model. Minor gap: it does not say whether the free sample alone yields a usable band or how to obtain the paid URL's result, which an agent orchestrating a payment flow would want.

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 description coverage, so the schema already defines 'query' as the full offer text. The description repeats the same idea ('full offer text') without adding format, length, or preprocessing guidance, 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 (score) and resource (side-income offer) plus the concrete output shape: 0-100 with GO/MAYBE/NO-GO band, 8 rubric dimensions and rewrite tips. It also names the sibling it is not (red-flag-scan), so an agent can distinguish it 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 an explicit trigger ('when you need a fast comparable score to rank several offers') and an explicit exclusion with the alternative tool ('Not for scam evidence (use red-flag-scan)'). 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 declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the pricing model ($0.02 Base USDC), that the call itself is free with a free sample plus paid URL and pay steps, and the x402 payment path. It stops short of describing error/timeout behavior for an invalid hash, so not a full 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 front-loaded sentences: purpose first, then when/when-not, then cost and return shape. Every sentence carries signal, though the pricing and pay-steps detail is dense and slightly extends length beyond the core selection need.

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, and the description still adds the payment/cost context an agent needs before invoking. Purpose, trigger, alternative, and cost model are all covered for a single-param verification tool.

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

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

Schema description coverage is 100% with a single optional 'query' param, so the schema already documents the accepted input ('settle tx hash 0x… or PAYMENT-RESPONSE JSON'). The description restates this format rather than adding new syntax or constraints, matching the baseline 3 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?

The description states a specific verb (Verify) and resource (x402 PAYMENT-RESPONSE or settle tx hash on Base) and explicitly scopes the trigger to retrying a paid call. It also names the sibling it is not for (facilitator-dry-run), so an agent can distinguish it from alternatives 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 an explicit when ('a paid call failed or looks unsettled and you need proof') and an explicit when-not with the alternative named ('Not for pre-launch payload checks (use facilitator-dry-run)'). 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 (readOnly, non-destructive, idempotent, closed-world), and the description adds substantial context beyond them: HMAC signing, the probe-evidence semantics (402 seen, probe ok, last paid ok), a free sample plus pay steps, and a $0.03 Base USDC x402 cost with no charge on this call. That is rich, non-obvious behavioral disclosure.

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 with zero filler; the identity/evidence statement comes first, then usage routing, then the payment mechanics. Every clause 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?

A read-only listing tool with an output schema, so return values need not be re-explained; the description still covers signing, evidence fields, sampling, and pricing. Nothing an agent needs before invoking is missing.

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

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

With schema description coverage at 100% and a single optional parameter, the schema already documents the max-sellers range. The description adds no syntax or format detail about the query parameter, 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') plus the exact evidence fields included. It explicitly distinguishes itself from the sibling phantom-seller-scan, so an agent can route correctly without opening either schema.

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

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

Gives a positive trigger ('when you want vetted x402 sellers before spending') and an explicit exclusion with the alternative tool ('Not for checking a single URL (use phantom-seller-scan)'). Both the when and the when-not are stated, leaving nothing to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new context: a free sample is returned with the paid URL and pay steps at no charge, while the full result costs $0.03 Base USDC via x402. That pricing/payment boundary is exactly what annotations cannot express. It stops short of describing rate limits or auth requirements.

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 does, when to use it vs the alternative, and what it returns/costs. No filler, and the core purpose is front-loaded ahead of usage and pricing detail.

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

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

An output schema exists, so return values needn't be spelled out, yet the description still flags that a free sample precedes the paid result. Combined with the explicit alternative routing and cost disclosure, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100% and the single 'query' parameter is fully documented in the schema as the https x402 endpoint URL. The description restates that it takes an x402 URL but adds no format, validation, or example 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 (check) and a precisely-scoped resource: whether an x402 URL's payTo actually receives Base USDC (economically live vs phantom). It also names the sibling it is not (phantom-allowlist), so an agent can route without opening either schema.

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

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

Gives an explicit trigger ('Use when before integrating or paying an unknown x402 endpoint') and an explicit exclusion with the alternative named ('Not for listing many sellers (use phantom-allowlist)'). Both when-to-use and when-not 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?

Goes well beyond the readOnly/idempotent/non-destructive annotations by disclosing the commercial model: a free sample plus a paid URL and pay steps, no charge at this call, and the full result costing $0.49 USDC via x402. That payment/auth context is exactly what 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 what it returns, then usage, then the payment mechanics. Every sentence earns its place with 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 values need not be detailed, yet the description still flags the free-sample/paid-URL split. Purpose, usage, and the payment flow are all covered for a simple one-param 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?

Only one optional parameter, and the schema description already says it is 'not needed' at 100% coverage. The description adds no further parameter detail, but with a single non-required param the schema carries the burden adequately.

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 (Return 10 reusable prompts) plus the resource (finding, pricing, pitching, delivering side-income work), and explicitly names the sibling it is not (offer-score). An agent can route between the two 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?

Explicitly gives the when ('agent needs ready prompts for freelance/gig operations') and the when-not with the alternative named ('Not for analysing a specific offer (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 already declare readOnly/idempotent/non-destructive, but the description adds genuinely new behavioral facts: a free sample is returned, the full result costs $0.25 Base USDC via x402, and nothing is charged at this step. That pricing and payment-flow disclosure is exactly the kind of context annotations cannot carry.

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: purpose and coverage first, then the usage trigger and exclusions, then cost/return behavior. No filler, no restatement 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?

With an output schema present, return values need no prose explanation, and the description still flags that a free sample plus paid URL/pay steps come back. Purpose, routing, and cost are all covered for a single-parameter read tool.

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

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

Schema description coverage is 100% and the single 'query' parameter is fully documented in the schema, including the ' | https://…' URL-append convention. The description adds no syntax or format detail beyond what the schema already provides, 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+resource with precise scope: 'Scan one offer/pitch for 12 evidence-quoted scam red flags plus live URL anchors (HTTP/TLS/DNS, RDAP domain age).' The enumeration of what is checked (domain age, TLS, DNS) makes it immediately distinguishable from the sibling scanners.

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

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

Gives an explicit trigger ('Use when you must decide whether a specific offer or seller page is a scam before paying or replying') and names two alternatives with the condition that selects them: offer-score for a numeric quality score, deal-brief for a quick checklist.

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, which only cover the safety profile. It discloses the payment model (free sample returned here, full result costs $17 Base USDC via x402, no charge on this call) and what the response contains, which is the critical behavioral fact for a paywalled resource.

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 artifact and then the routing and payment facts in priority order. 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?

Complete for a zero-required-param download tool. Even though an output schema exists, the description still pre-empts the paywall confusion by explaining the free-sample-plus-paid-URL return shape, so an agent will not misread a successful call as a delivered guide.

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' param is explicitly marked 'not needed', so the schema carries the meaning. The description adds no parameter-level detail beyond that, which is the expected baseline when the schema does the work.

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 (Download), the artifact (an English PDF playbook), and its content (7 side-income plays under $100). The 'English' qualifier implicitly separates it from the German sibling nebenverdienst-pdf, and 'use the JSON tools' separates it from the analysis siblings.

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

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

Explicitly gives the trigger ('Use when a human wants a full guide') and the exclusion ('Not for agent automation'), plus a redirection to the JSON tool family. An agent can route correctly without opening the schema.

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 behavioral facts they cannot carry: it is a local fetch, it returns a free sample with the paid URL and pay steps, no charge is incurred on this call, and the full result costs $0.02 Base USDC via x402. The payment/charging model is the kind of context an agent must know before calling.

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

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

Three tight sentences front-loaded with the payload and scope, then the routing exclusion, then the cost model. Every clause carries information; the parentheticals are short and load-bearing rather than 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-value detail is not needed, and the description still covers what is missing elsewhere: cost, the free-sample-then-pay flow, and the sibling alternative. Nothing an agent needs to call this correctly is absent.

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

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

Schema description coverage is 100% and there is a single parameter, so the schema already documents the https URL input fully. The description's '(local fetch)' hints at how that URL is retrieved but adds no syntax or format meaning beyond the schema. Baseline 3 is correct.

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

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

States a precise verb and resource plus the exact payload returned: title, meta description, ~3k chars of plain text and outbound links. It also names the sibling (web-extract) it is not, so an agent can separate the two without opening either schema.

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

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

Gives an explicit use condition ('when you need readable page text cheaply') and an explicit exclusion with the alternative to use instead ('Not for clean markdown of JS-heavy pages (use web-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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint=false), it discloses the commercially important behavior: a free sample is returned here with no charge, and the full result requires $0.01 Base USDC via x402 pay steps. That is real behavioral context an agent must know before calling. It doesn't cover failure modes (unreachable host, TLS errors) or rate limits, and there is a mild tension between 'live TLS/HTTP' fetching and openWorldHint=false, so it falls short of a 5.

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

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

Three tight sentences front-load the output shape, then routing, then payment mechanics — no filler and no repetition of the title. The most decision-relevant content (what it returns, when to use it) comes first.

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

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

An output schema exists, so return values need no prose expansion, and the annotations already cover the safety profile. The description fills the remaining gaps an agent needs — sibling disambiguation and the x402 payment flow — making the definition complete for a 1-parameter tool.

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

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

Schema description coverage is 100% for the single 'query' parameter (an https URL for the paid endpoint), so the schema already carries the semantics and the baseline is 3. The description confirms the URL/endpoint framing and implies the paid URL comes back from the free sample, but adds no syntax or format detail beyond the schema.

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

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

The description gives a specific verb (fingerprint) plus the exact resource and the concrete return fields (final URL, status, content type, body SHA-256, TLS issuer, DNS sample). It explicitly distinguishes itself from the two nearest siblings, url-extract and web-extract, so an agent can route correctly without opening any schema.

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

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

It states the positive trigger ('detecting page changes or verifying a site cheaply') and the negative trigger ('Not for page text ... or markdown'), each paired with the named alternative tool. This is about as complete a when/when-not routing statement as a description can carry.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds critical economics the annotations cannot: a free sample is returned, the full result costs $0.03 USDC via x402, there is no charge in this call. That disclosure materially changes invocation decisions.

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 waste, front-loaded with purpose then routing then cost. Each 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?

Single-parameter read tool with an output schema, so return-shape explanation is unnecessary. Safety (annotations), routing (siblings), and the non-obvious paywall behavior are all present; nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents the single 'query' parameter as an https URL. The description adds no syntax, format, or constraint detail beyond the schema. Baseline 3 per the rubric 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 (scrape) and resource (URL) and names the conversion target (clean markdown via Firecrawl). It also names the siblings it is not (url-fingerprint, url-extract) for the cheaper hash/excerpt case. Loses a point only because the differentiation is framed as a negative rather than a positive use case.

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 ('when you need LLM-ready markdown of a page') and explicit when-not plus alternative ('Not for a cheap hash/excerpt — use url-fingerprint or url-extract'). Routing is unambiguous.

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

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

The description states the tool performs a live web search via an external upstream ('Serper upstream'), which is the canonical open-world case, yet the annotations declare openWorldHint=false. That is a direct conflict between the stated behavior and the structured metadata.

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, front-loaded with purpose, then the routing rule, then the payment flow. Every clause earns its place given this is a metered paid tool where the x402/price steps must be disclosed.

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 covers purpose, routing, and payment. It is nearly complete; only the open-world behavior question is left mismatched with the annotations rather than unresolved.

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 schema already documents the query string and the optional n=5..10 JSON. The description ('for a query') adds no syntax or format detail beyond that, so the baseline 3 applies when the schema carries the parameter semantics.

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

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

Names a specific verb and resource ('Web search: ranked title/url/snippet results') and even discloses the upstream provider (Serper). It distinguishes itself from url-extract by name, so an agent can separate it from siblings 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?

States the trigger condition ('Use when you need live search results for a query') and an explicit exclusion with the correct alternative ('Not for fetching a known URL (use url-extract)'). 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.