Agent402.Tools: pay-per-call web tools

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

Goes well beyond the annotations: discloses per-call pricing ($0.030), that no API key is needed, that billing happens via x402, that diarize swaps to the scribe-v2 model at the same price and cap, and that output gains extra fields. This is exactly the cost/auth/model-substitution 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?

Four tight sentences with the cost and capability front-loaded; every clause carries decision-relevant information. The closing sentence partially restates the opening 'Paid ($0.030/call)' point, a minor 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?

Return values are covered by the output schema, and parameter details by a fully-described schema, so the description only needs to supply cost, auth path, and model behavior — all of which it does. 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%, so the schema already documents all three parameters including the diarize output fields. The description adds a little (same price/cap for diarize) but omits the optional `language` parameter entirely, so it doesn't meaningfully exceed the schema.

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

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

States a specific verb and resource ('Transcribe audio to text'), names the underlying model (gpt-transcribe), and specifies the input form (a URL to an audio file). No sibling tool in the list offers transcription, so there is no ambiguity to resolve.

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

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

Gives clear conditional guidance for the main optional path ('Add diarize:true for speaker labels, word timestamps and a language confidence score') and states the input requirement. It does not spell out when-not-to-use or compare against any alternative, but no plausible alternative exists among the siblings.

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

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

Annotations only say readOnly=false, openWorld=true, non-idempotent, non-destructive. The description adds pricing ($0.01/call), that JS actually executes in headless Chromium, that output is markdown, and – importantly – an untrustedContent warning about prompt injection from page content. That is substantive behavioral context the agent could not 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?

Cost and core action are front-loaded, followed by the decision rule and the security caveat. Every clause carries decision-relevant information; nothing is redundant with the schema or annotations.

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

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

An output schema exists, so return-value explanation is unnecessary. For a paid, open-world render tool the description covers cost, execution model, output shape, alternative routing and prompt-injection risk – everything needed to call it safely and 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?

Single required parameter with 100% schema description coverage ('Public http(s) URL to render'). The description adds no syntax, format or constraint 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: render a page in real headless Chromium with JavaScript executed, then extract main content as clean markdown. It also distinguishes itself from the cheaper 'extract' path and from 'screenshot', so an agent can place it among alternatives 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 routing: use for SPAs/JS-heavy sites where plain fetching returns an empty shell, try cheaper extract first for static pages, use screenshot for pixel evidence. Names both the selection condition and the alternatives.

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

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

Adds substantial context beyond annotations: rate limiting via proof-of-work, paid tools settled over MPP with challenges carried in _meta, and an error on unknown slug. This is real operational detail the annotations don't convey. It does not acknowledge the destructive/open-world side effects declared in annotations (it proxies arbitrary tool execution), which is the remaining 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?

Four compact sentences, front-loaded with the action and the discovery alternatives, then billing/rate-limit behavior, then the error case. No filler and no repetition of the 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?

With an output schema present, return values need not be explained, and the description covers the two hardest unknowns for a proxy tool: cost/rate-limit model and failure on bad slug. The one thing an agent might still want – a warning that executed tools can have side effects – is absent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the key semantic that params must conform to the *target tool's* inputSchema – a dynamic contract the schema alone cannot express. That is meaningful extra guidance for constructing the nested object.

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 ('Run an Agent402 tool by slug') and immediately differentiates itself from catalog.find/catalog.search, which are named as the way to discover slugs. An agent can tell this is the execution endpoint versus the discovery endpoints 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?

Routing is explicit: use catalog.find or catalog.search to obtain a slug, then come here. It also splits the free (proof-of-work, rate-limited) path from the paid (MPP) path, giving a concrete condition for each. It lacks an explicit 'do not call this for X' exclusion, which keeps it from a 5.

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

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

Annotations already declare destructiveHint=false and openWorldHint=true, so the description doesn't need to carry the safety profile. It adds genuine behavioral context beyond that: the response shape { task, results } with the top pick first, and the fact that results are call-ready. Minor tension worth noting: readOnlyHint=false on what reads like a pure lookup, but the description never claims read-only, so this is ambiguity rather than contradiction.

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

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

Three sentences, front-loaded with the core verb and resource, then alternatives, then follow-up. Every clause carries routing or return-shape information; nothing is repeated from the annotations 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 don't need exhaustive explanation, and the description still names the top-level shape and the top-pick ordering. It stops short of covering the no-match or low-confidence case, which matters for a resolver that must always return 'the single best' match.

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 both parameters are already documented, including the limit default of 5. The description clarifies the nature of the task string (plain-language) and the shape of the result set, but adds nothing about the limit parameter or ranking behavior. 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?

States a specific verb and resource: resolve a plain-language task to the single best-matching Agent402 tool, and enumerates what comes back (slug, price, input schema, worked example). It explicitly distinguishes itself from catalog.search, which compares candidates, so an agent can pick 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?

Names the alternative (catalog.search) and the condition that selects it (comparing several candidates), and gives the downstream step: run the result with catalog.call using the slug and params it lists. Both the when-to-use-this and the when-to-use-something-else are explicit.

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

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

Beyond the annotations it discloses the return shape ({ results, workflows }), the cost model (170 pure-CPU tools free via proof-of-work, others paid per call), and the exact payment mechanics (MPP credential in _meta with mppx auto-pay, or npx agent402-mcp with a wallet). That is exactly the kind of economic and side-effect context the annotations cannot express.

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

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

Front-loaded with the core action and scope in the first clause, then the return shape, then cost. The payment sentence is dense with brand-specific detail (MPP, mppx, npx) but each clause carries operational information an agent needs before calling.

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

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

An output schema exists, yet the description still names the two top-level keys, and it covers cost, payment prerequisites, and the follow-up call — the things an agent most needs for this connector. The only real gap is the missing contrast with catalog.find.

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 query parameter already carries rich natural-language examples, so the description adds nothing about parameter meaning. Baseline 3 applies; it does not explain how limit interacts with the catalog size or how to phrase queries for best recall.

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?

"Keyword search over the Agent402 catalog of 500+ tools" gives a specific verb (search) and resource (catalog), and the word "keyword" implicitly separates it from an intent-based lookup. It does not explicitly contrast with the sibling catalog.find, so an agent must infer which of the two search entry points to pick.

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

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

The description tells the agent what to do after a hit ("run one with catalog.call") and explains the free-vs-paid routing, which is genuine usage context. It never states when to prefer this over catalog.find or the specialized siblings (web.search, memory.read, etc.), so selection guidance is only implied.

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

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

Goes far beyond the annotations: discloses the $0.001/call price, the resale economics of third-party steps, that payment must come from a Base wallet and cannot use prepaid credits or cards, and that replan adds a plan price. None of this is in the annotations, and nothing contradicts them (readOnly=false, openWorld=true, non-idempotent all fit an execution 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?

Front-loads the paid price and the verb, and the single long sentence carries no filler. It is dense and heavily nested with parentheticals, which slightly hinders scanning, but every clause adds operational information.

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

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

With a rich schema, an output schema, and annotations already covering safety, the description still supplies the payment mechanics and route selection an agent needs. It omits failure and retry semantics for a non-idempotent, money-spending run, which is the main 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%, so the schema already documents all six parameters including steps, params, replan, decisionId, creditToken, and maxBudgetUsd. The description adds only the '2 to 5' step-count hint and no format or semantics beyond what the schema provides, making the baseline 3 the right call.

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 (run/execute) and resource (a decision's plan or a free plan sketch) and explains the two input paths, so an agent can distinguish it from decide.plan, which only plans. It never names the sibling tool decide.plan directly, citing 'POST /api/decide' instead, which is a small differentiation gap.

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 concrete guidance on which input path to use ('decisionId from POST /api/decide, or a free plan sketch (steps)') and where the steps come from (/api/find or /api/route). It does not state when to avoid this tool or when replan=true is preferable beyond a one-line default, so it falls short of full when/when-not coverage.

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

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

Annotations mark this as a non-read-only, idempotent, non-destructive write, and the description adds context the annotations cannot: a later report for the same step replaces the earlier verdict (consistent with idempotentHint), credentials must come from the plan response, and the data feeds future rankings. It stops short of stating failure modes, such as what happens with an expired or invalid feedbackToken.

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 a useful '[free]' cost marker and the core verb, with the credential requirement ahead of the replace-semantics note. Every sentence carries information; only the parenthetical field list is mildly compressed.

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 state-mutating reporting tool with an output schema, this is nearly complete: it explains provenance of the identifying parameters, the replace semantics, and the downstream use. The only gap is guidance on invalid or expired tokens and confirmation of what the write affects.

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

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

Schema description coverage is only 14%, so the description has to compensate, and it does for most fields: it names decisionId and feedbackToken and explains where they come from, and covers outcome, quality (1-5) and latency. Only the step index is left implicit, inferred from its name and the minimum-1 schema constraint.

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

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

States a specific verb and resource — report the outcome of one step of a decide.plan decision — and enumerates the accepted fields (success/failure, optional 1-5 quality and latency). An agent can distinguish this feedback call from the sibling decide.plan and decide.execute 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?

Establishes the calling context clearly: it is used after decide.plan, requires the decisionId and feedbackToken that call returned, and that one verdict applies per step. It does not explicitly name alternatives or say when not to report, but the sequencing 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 disclose openWorldHint=true, readOnlyHint=false and idempotentHint=false, so the bar is lower; the description still adds the per-call price ($0.010), the fact that external sellers are included only when they have a recently verified 402, and that returned params are schema-validated. A gap remains: it doesn't say whether the charge applies on failure or that non-idempotence means repeated calls yield different plans.

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 sentence that front-loads the price and the core verb, with no filler. It is heavily nested with clauses, which occasionally makes it hard to parse, but every clause carries information.

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

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

An output schema exists and all parameters are schema-documented, so return values and inputs needn't be restated. What is missing is the pipeline context: whether this tool performs any action, and how its output feeds decide.execute — for a planning tool in a family with decide.execute and decide.feedback, that omission matters.

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 all three parameters (task, depth, constraints) are documented in the schema, so baseline 3 applies. The description's mention of 'input params that validate against each tool's schema' describes the output, not the inputs, so it adds nothing about depth levels or how constraints like maxBudgetUsd or requireDeterministic shape the plan.

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 ('Describe a job and get a call-ready plan') and specifies the scope: tools from this catalog plus external x402 sellers with a verified 402, ordered with fallbacks. It is clear what the tool produces, though it never names decide.execute or decide.feedback, so an agent must infer that this plans rather than runs.

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?

Usage is implied by 'Describe a job' — you call it when you need a plan — but there is no explicit when-not guidance, no statement that it does not execute, and no routing to decide.execute once a plan exists. The agent must infer the planning/execution split from sibling names alone.

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 declare readOnlyHint=false, openWorldHint=true and idempotentHint=false; the description is consistent with that (it writes a demand record) and adds real context the annotations cannot carry: requests are clustered by need, frequent ones get built, aggregate demand is public at a given endpoint. It stops short of saying whether repeated identical submissions create duplicate demand entries, which matters given idempotentHint=false.

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

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

Four tight clauses, front-loaded with cost and the core action, then the routing condition, then the behavioral caveat, then the API equivalents. Every sentence earns its place and nothing is repeated from the 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?

Output schema exists, so return values need no explanation, and the description covers cost, preconditions, side effects and the downstream fate of the request. For a two-parameter intake tool this is everything 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 coverage is 100% and both properties already carry good descriptions with examples, so the schema does the heavy lifting. The description only implies the semantics of `need` via "clustered by need" and adds no detail on `context` or length limits — baseline 3 is right here.

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

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

Names a specific verb+resource ("report a capability the 500+ tools do not cover") and immediately scopes it to the missing-tool case, which separates it cleanly from catalog.search/find/call in the sibling list. "Records demand only: it runs nothing" removes the main ambiguity an agent would have about whether this triggers anything.

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 precondition — use it "after catalog.search or catalog.find found nothing that fits" — naming the exact sibling tools to exhaust first. It also flags cost ("[free]") and the negative case (it runs nothing), so the agent knows both when to call it and what it will not do.

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 carries the information annotations cannot: it discloses the per-call price ($0.001/call), that the data is end-of-day rather than streaming, and the provenance (official consolidated summary across all US exchanges and ATSs). It does not cover auth requirements or rate limits, and the reason readOnlyHint is false for a pure lookup is left implicit.

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

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

Two sentences, front-loaded with cost and the payload contents, then scope exclusions, then data provenance. Every clause carries information an agent needs; nothing is repeated for padding.

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

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

An output schema exists, so return-value shape needn't be explained, and the description instead spends its space on the things structured fields can't express: cost, end-of-day latency, market coverage and data provenance. 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?

Only one parameter and schema description coverage is 100% — the schema already documents the ticker format and the indices/FX/crypto exclusion. The description restates that exclusion but adds no new syntax, formatting or validation meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource (end-of-day US equity quote) and enumerates exactly what is returned: last close, day range, consolidated volume, previous close and change. It also draws a hard scope boundary against indices, FX and crypto, so the tool is distinguishable without opening the schema.

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

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

Explicitly says US equities only and names the excluded asset classes plus an alternative (crypto-price) for one of them. It falls short of a full when-to-use statement — there is no guidance on when to prefer this over other market data sources, and the named alternative is not in the visible sibling set.

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 repeatedly frames this as a read operation, but annotations declare readOnlyHint=false and idempotentHint=false, which contradicts the described read-only exact-key store behavior. Although the description adds useful cost and grant details, the annotation inconsistency makes the behavioral profile unreliable.

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

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

The description is dense but front-loaded and every sentence contributes: cost, core read behavior, sibling distinction, alternative tool routing, and namespace authorization rules. There is no wasted framing.

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

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

For a two-parameter read tool with an output schema, it covers cost, key behavior, default namespace, grant-based owner access, and the alternative retrieval path. It does not reconcile why a read operation is annotated as non-read-only and non-idempotent, leaving a behavioral ambiguity.

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 both parameters. The description still adds useful semantics beyond the schema: it reinforces that key omission lists keys, and that reads default to your own namespace while owner is only for a namespace you have been granted access to.

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 from a wallet-scoped namespace, with exact-key retrieval or key listing when key is omitted. It clearly distinguishes itself from memory.write and from similarity retrieval via memory-recall.

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

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

Explicitly says when to use this tool versus the alternative: exact-key reads and key listing here, while similarity retrieval over remembered text should use the catalog slug memory-recall. It also states default namespace behavior and the owner grant condition.

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

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

Adds real context beyond the annotations: per-call pricing, that the x402 payment itself is the authentication, and that the paying wallet owns the namespace with no signup or API keys. It does not mention in prose that the same tool can delete a key, nor any rate or size caveat beyond what the schema carries.

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

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

Front-loaded with purpose and cost, and every sentence carries information. The final routing sentence is slightly convoluted with its nested 'on MCP, through catalog.call with that slug' phrasing.

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 explanation, and the description covers cost, auth model, scoping, and alternatives. It leaves the delete path and requestId retry semantics entirely to the schema, which is acceptable but slightly thin for a write 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 every parameter (key, owner, value, delete, requestId, ttlSeconds) is documented in the schema, so the baseline is 3. The description adds namespace-ownership framing but no syntax or format detail the schema does not already provide.

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 resource and behavior: persistent key-value memory scoped to the paying wallet, with exact-key storage for structured state. It explicitly separates itself from meaning-based retrieval tools (memory-remember/memory-recall), so an agent can pick it correctly 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 when-not: use memory-remember/memory-recall when retrieving by meaning rather than key. It implies exact-key lookup is this family's job but never names the sibling memory.read for exact-key reads, so the routing guidance is clear but not exhaustive.

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

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

Annotations already establish a read-only, idempotent, closed-world info call, and the description adds useful context: no wallet is held, free CPU tools use proof-of-work, paid calls settle via USDC/x402/MPP, and spend controls are covered. It does not describe permission requirements or what 'payable here' precisely entails, so it is strong but not exhaustive.

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

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

Four short, front-loaded sentences with no filler establish purpose, mechanics, covered topics, and return areas. The final return-key summary is somewhat redundant because an output schema exists, and 'covers' plus 'returns' overlap slightly, keeping it just below ideal conciseness.

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 informational tool with annotations and an output schema, the description supplies the missing conceptual scope: free vs paid tiers, payment rails, spend controls, and balance/history. Nothing needed to call it correctly is absent; usage routing is the only area left thin.

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?

This is a zero-parameter tool, so there are no arguments to explain; the rubric baseline is 4. The description appropriately focuses on scope and returned areas rather than inventing 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?

The description identifies this as an informational payment/setup resource, enumerating wallet setup, spend caps, payment rails, and balance checks, so the agent knows it is not a payment action or generic catalog call. It is clear but does not explicitly differentiate itself from payment-adjacent siblings such as market.quote.

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 lists covered topics, which implies when the information is relevant, such as wallet setup, caps, rails, and balance checks. However, it gives no explicit when-to-use guidance, no alternatives, and no exclusions, leaving the agent to infer when to call it versus catalog or market tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered. The description adds value beyond them by disclosing that the call is free (no quota/cost impact) and by naming the categories of information returned — cost is a trait annotations cannot express.

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

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

A single sentence with the cost marker and verb front-loaded, followed by a colon list of exactly what comes back. Every clause carries information; nothing is redundant with 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?

With an output schema present, the description only needs to motivate the call and it does so — setup, tiering, discovery URLs. A minor gap is that it doesn't say whether the returned tool list reflects the live catalog or a static snapshot, which matters for an agent deciding how much to trust 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?

The tool has zero parameters, so the baseline is 4; there is nothing for the description to disambiguate, and it correctly says nothing about inputs.

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?

Uses a specific verb ("Describe this connector") on a specific resource and immediately enumerates the content returned: listed tools, install paths, tiers, discovery URLs. No sibling tool (audio.transcribe, catalog.*, web.*) covers connector metadata, so it is unambiguous against the sibling set.

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

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

The "[free]" marker and the enumerated payload (install instructions for Claude Code / Cursor / npm, free vs paid tiers) make it clear this is the onboarding/discovery call an agent makes when it needs setup or tier information. It does not state explicit when-not conditions, but no plausible alternative tool exists for this purpose.

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

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

Adds real context beyond annotations: the per-call cost, that grounding comes from a live external index rather than model weights, and that citations are returned alongside prose. Missing latency/rate-limit behavior and any note on what happens on a failed or uncited answer. There is a mild tension with readOnlyHint=false, but a paid, non-persistent query call is not a genuine contradiction of that flag.

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 cost and output shape, no filler. The closing 'Useful when...' line is slightly generic but earns its place as the only usage guidance present.

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 the return-value explanation is a bonus rather than a requirement, and parameters are fully schema-documented. Combined with openWorldHint and the disclosed cost, an agent has enough to decide and call correctly; only failure/rate-limit behavior is unaddressed.

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 all four parameters (q, country, language, max_tokens) are already documented in the schema, including the 400-char cap and token bounds. The description adds no parameter-level meaning, so the baseline 3 applies.

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

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

States a specific verb and resource — an AI-generated answer to a natural-language question grounded in live web search — plus the mechanism (independent search index, not training data). The 'synthesized answer plus the receipts' framing cleanly separates it from the raw-results sibling web.search without needing to open 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?

The final sentence gives a clear use condition: when the agent needs a synthesized answer plus citations to verify or follow up. The explicit $0.08/call price is a strong routing signal against free siblings. However, it never names an alternative (web.search for raw links, web.news for recent items) nor states when *not* to use it.

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 openWorldHint and destructiveHint, but the description adds material context beyond them: it is a paid call ($0.01/call), returns clean JSON from an independent index, and specifies result fields. The readOnlyHint=false is not explained, but nothing in the text contradicts it.

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

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

Front-loads cost and purpose, then the return shape and freshness note, in two dense but waste-free sentences. Every clause carries information.

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

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

Complete enough for the agent's needs: it names the call cost, output shape, and freshness compatibility. Since a full output schema exists, restating result fields is mildly redundant, but 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%, so q, count, country, and freshness are already documented in the schema. The description reiterates the freshness values (pd/pw/pm/py) but adds nothing new beyond the schema 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 and resource ('Live news search') and describes the returned structure (results[] of title, url, description, age, publishedAt, source, breaking). An agent can distinguish it from the sibling web.search as the news-specific variant.

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 the price ($0.01/call) and notes it shares the freshness filter with web search, which aids the use/skip decision. However, it never explicitly states when to prefer this over web.search or web.answer, nor any exclusions.

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

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

Discloses the per-call price ($0.01), that the index is independent and returns fresh pages, and that the call is non-idempotent in effect (each call is billed). That goes well beyond the annotations. It does not explain why readOnlyHint is false for what reads like a pure query, or mention rate limits or caching.

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?

Cost and purpose are front-loaded, and nearly every clause carries information. The nested parentheticals in the results[] enumeration and the reference to an unlisted 'extract' tool make it slightly denser than necessary.

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

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

For a three-parameter paid search tool with an output schema and full annotation coverage, the description supplies cost, scope, freshness behavior, and next-step routing. Return values are already covered by the output schema, so nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents q's 400-char limit, count's 1-20 range and default, and the freshness enum values. The description restates the freshness values and adds motivation ('fresh pages your model's training cutoff has never seen') but no syntax or semantics beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource (live web search) plus concrete output shape (ranked results[] of title, url, description, age, publishedAt) from an independent index. It is clearly distinguishable from siblings like web.news, web.answer, and catalog.search.

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

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

Gives an explicit workflow directive: 'Start here to DISCOVER pages, then read the winner with extract.' That is a clear when-to-use signal. It falls short of 5 because it never contrasts itself with web.answer or web.news, and the named follow-up tool 'extract' does not appear in the sibling list.

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