SpendPreflight

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

Annotations already cover read-only/idempotent/closed-world, but the description adds context beyond them: results are cached, the caller's URL is never fetched, the endpoint is never paid, unlisted/unavailable/stale data is not charged, unknown means missing evidence, and repeated paid calls may incur another charge. Pricing ($0.005 with a shared free trial) is disclosed, which no structured field provides.

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 what is returned, then behavior, parameters, routing, and price. Almost every sentence carries distinct information, though the cost statements ('Price $0.005 per cached lookup' and 'repeated paid calls may incur another charge') are close enough to feel slightly redundant.

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

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

An output schema exists, so return shape needn't be explained, and the description still covers the semantics an agent needs: caching, scoring/unknown meaning, billing behavior, listing prerequisite, and the sibling routing decision. Nothing material is left to inference for this two-parameter, read-only tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes slightly beyond the schema by emphasizing the URL must be the exact resource URL and by giving a practical rule for method ('add method when the URL has multiple advertised methods'), which adds conditional intent even though it overlaps the schema's 'required if the URL is ambiguous' wording.

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 (returns cached observations) and resource (an x402 endpoint URL) plus the artifact returned (transparent score, components, seven-day probe history). It also explicitly carves out what it is not ('not a paid-delivery or compliance guarantee') and names sibling tools, so an agent can distinguish it from check_payee and preflight_payment without opening any schema.

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

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

Gives explicit when-to-use ('for endpoint history and price context before paying') and routes two named alternatives with their own conditions: check_payee for wallet/name screening, preflight_payment for an allow/hold/block decision. It also states the precondition that the URL must already be publicly listed by Bazaar or x402scan.

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=true and openWorldHint=true, so the safety profile is partly covered. The description adds genuinely useful context beyond them: cost ($0.05 USDC on Base), a possible shared trial, the privacy guarantee that no target payment or request bodies are stored, and explicit non-guarantees. However, the schema permits POST while readOnlyHint=true, and the description never reconciles that — an agent could reasonably wonder whether the scanner sends a mutating request.

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 decision-critical fact (alias, use listing_guard instead), which is the right ordering. It runs long, and the 'same operation, not two independent checks' point is restated across two clauses, but every remaining sentence (checks, return values, limits, price) 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?

For a 2-parameter tool with no output schema and only two hints, the description covers return values (riskScore, flagged spans, rewrite suggestions), cost, privacy, and scope limits. The only real gap is method-selection semantics, which the schema does not supply either.

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

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

Schema description coverage is 0%, so the description must carry the params, and it only partially does: 'Public HTTPS only' meaningfully constrains the url parameter's accepted form. The method enum (GET/HEAD/POST) is never explained — no guidance on which method to choose or why POST is supported for a read-only scan.

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 (a compatibility alias of listing_guard) and immediately clarifies the relationship: 'these are the same operation, not two independent checks.' The second sentence enumerates the actual checks performed (CDP technical validation, heuristic metadata screen for instructions, embedded URLs, tool calls, invisible Unicode, long fields, outlier prices), so an agent knows exactly what it gets and how it differs from 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 routes the agent: 'Prefer listing_guard for a new detailed metadata check' while explaining that check_listing exists only for existing clients. It also names the exclusion boundary ('Not Coinbase policy certification or guaranteed detection') and the operational precondition ('Public HTTPS only'), leaving nothing to inference about when to pick this over listing_guard.

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, openWorld and idempotent, so the safety profile is covered. The description adds genuinely non-schema context: per-call cost ($0.01, free trial first), the required-input invariant, and the risk vocabulary and flag names. It stops short of stating latency or what happens on partial input matches, but that is a minor omission against the annotation coverage.

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

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

The core purpose is front-loaded in the first sentence, followed by return values, input rules, the sibling redirect, and pricing in descending priority. No sentence is redundant.

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

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

For a 3-param, zero-required read-only screening tool with an output schema present, the description supplies everything needed: purpose, trigger, alternative routing, input combination rules, expected output vocabulary, and cost. Return-format detail is correctly delegated to the output schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond it by stating the cross-parameter constraint ('Provide at least one of domain, address, or name; inputs may be combined') and the accepted domain format ('hostname or URL'), neither of which is derivable from the schema alone.

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 ('screens a payee wallet address and name against the OFAC SDN sanctions list') plus the concrete secondary check (domain registration age and DNS). It is immediately distinguishable from preflight_payment and the other siblings, which are named explicitly.

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

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

Gives an explicit trigger ('Call this before a USDC payment when you only have a payee name, wallet or domain') and names the alternative with the condition that selects it ('For an x402 challenge or cart and an allow/hold/block spending-rule decision, use preflight_payment instead'). Nothing about tool selection is left to inference.

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

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

Annotations already establish read-only, non-destructive, open-world behavior, and the description adds substantial context: bounded public-chain reads, OFAC matching, exact tier capabilities, missing-data semantics, non-verdict language, pricing, and trial availability. There is no contradiction with the annotations.

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

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

The description is dense but front-loads the core purpose and tier differences before exclusions and disclaimers. Pricing and legal language add length, but most of the detail is useful for correct tool selection and interpretation.

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?

Given there is no output schema, the description effectively lists the observations returned by basic and deep tiers. Combined with the annotations and explicit limitations, it gives an agent enough information to invoke the tool and interpret results without overclaiming safety.

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

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

Schema description coverage is 0%, so the description must add meaning. It does so well for the tier parameter by defining basic versus deep observations, and it reinforces that the tool applies to Base contracts, though it does not separately explain the address or chain parameters beyond the schema constraints.

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 function: retrieving Base contract safety signals from bounded public-chain reads and OFAC. It clearly distinguishes basic versus deep scope and explicitly lists what is not assessed. It does not name sibling tools as alternatives, so it stops short of full sibling differentiation.

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 useful usage context by explaining what the basic tier covers, what deep adds, and which safety dimensions are explicitly out of scope. However, it does not state when an agent should choose this tool over sibling checks or when not to use it at all.

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 cover readOnly and closed-world, but the description adds cost ($0.01), the stale snapshot date, straight-line-only accuracy, absence of potable-water assurance and road routing, and licensing terms. These are exactly the caveats an agent needs before charging a 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?

Four tight sentences, front-loaded with purpose then cost, then caveats, then licensing. Each sentence carries distinct information with no restatement of the name 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?

For a 5-parameter, zero-coverage tool with no output schema, important gaps remain: what a returned station record contains, result ordering, and how service 'either' behaves are all unstated. Cost and staleness are well covered, but the call-shaping and result-shaping details are not.

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

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

Schema description coverage is 0% across 5 parameters, and the description never mentions latitude, longitude, limit, radius_km or the service enum values. The phrase 'bounded straight-line proximity' does meaningfully imply that radius_km is a crow-flies radius rather than driving distance, which is the only semantic gain.

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 ('Nearest RV dump/water stations') plus the exact data source and snapshot date. Nothing in the sibling list (check_*, preflight_*, lint_*, size_solar) overlaps, so an agent can select this unambiguously.

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

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

Explicitly carves out what this is not ('not live access, potable-water assurance or road routing') and points to the free underlying projection under ODbL as an alternative. It stops short of naming a sibling tool or stating a positive 'use this when' condition, which keeps it below 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 readOnlyHint, idempotentHint, and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral scope in the negative: it 'performs no payee screening or payment decision' and takes no arguments, which prevents an agent from wrongly expecting a decision from it. Return format is left to the output schema.

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

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

Three sentences, front-loaded with the identity of the tool and its contents, then routing guidance. Dense but every clause carries routing or scope information; the middle 'optional' clause is slightly redundant with the preceding conditional but not wasteful.

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. For a zero-argument reference tool with full annotation coverage, the description supplies everything needed to choose it correctly versus its three siblings.

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?

Zero parameters, so the baseline is 4; the description correctly reinforces this with 'Takes no arguments,' matching the empty schema and the 'Example arguments: {}' note. No parameter semantics are needed or missing.

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

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

States a specific verb+resource ('free, read-only service reference') and enumerates the exact content it returns: prices, default spending rules, payment setup, trial allowance, and an example call. An agent can distinguish this from check_payee and preflight_payment immediately.

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 when-to-use conditions and names both alternatives with their selecting conditions: 'If you already have a payment challenge or cart, call preflight_payment directly; this reference call is optional' and 'Use check_payee for standalone payee risk.' 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?

Goes well beyond the annotations by describing exactly what comes back (heuristic riskScore 0–100 or 'unknown', fixes, public seven-day report link), the disclaimers that scores are not safety or acceptance guarantees, and the fact that no payment or credentials are involved. It also clarifies the badge path 'reads only the existing seven-day snapshot, never runs a check,' preventing a false assumption about side effects. Nothing here contradicts readOnlyHint=false / openWorldHint=true.

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

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

Front-loaded with the action and the checks performed, and most clauses carry weight (limitations, privacy warning, score caveats). The trailing CI Action URL and badge-path explanation are marginal for tool selection and add density without helping an agent decide or invoke, keeping it below 5.

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?

There is no output schema, and the description compensates by describing the return payload (riskScore range, fixes, report link) and its reliability caveats. For a one-parameter, unauthenticated lint tool it covers what an agent needs to call it correctly and interpret the result, including the key failure mode (POST-only endpoints cannot be validated).

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 0% and the only parameter is a bare `url` string with no description, so the description carries the burden — and it does: the URL must be public, HTTPS, and GET-addressable, with an explicit 'Do not submit private URLs.' It still does not clarify whether query strings/paths are accepted (the schema's example implies they are), leaving a small gap.

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

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

States a specific verb and resource: checks a public HTTPS x402 endpoint with an unpaid GET, and enumerates what it validates (v1/v2 challenge shape, payTo/asset/network syntax, price, Bazaar metadata, CORS headers). The purpose is unambiguous, but it never names the sibling it overlaps with (check_endpoint) or explicitly contrasts them, so an agent must infer the boundary.

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 real usability boundaries: 'No payment or credentials; GET cannot validate a POST-only endpoint or paid delivery. Do not submit private URLs.' It also clarifies that paid Listing Guard/monitoring links are optional and 'no paid call is made,' which implicitly separates it from listing_guard and preflight_payment. What is missing is an explicit 'use check_endpoint instead when…' routing statement.

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=true and openWorldHint=true, and the description adds substantial context beyond them: bounded heuristic detection, explicit non-guarantees, public-HTTPS-only scope, no stored target payment or request bodies, and pricing details. This gives the agent a useful operational, privacy, and cost profile.

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 definition is front-loaded with the tool name and core function, then layers caveats, privacy, and pricing. It is dense but every sentence carries relevant operational information; minor compression could improve readability without losing meaning.

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

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

With no output schema, the description helpfully names riskScore, flagged spans, and rewrite suggestions. However, for a two-required-parameter tool with 0% schema coverage, it omits parameter semantics and lacks sibling-routing guidance, leaving key invocation details incomplete.

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

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

Schema description coverage is 0%, and the description does not explain what url or method mean in this context or how method affects validation. 'Public HTTPS only' adds a relevant constraint for url, but the required method parameter remains semantically unexplained beyond its enum values in 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: CDP technical validation plus a bounded heuristic metadata screen for listings, with named signals like embedded URLs and invisible Unicode. It is clear what the tool does, but it does not distinguish itself from the very similar sibling check_listing or explain how it differs from check_endpoint.

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

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

The description explains the capability but gives no explicit guidance on when to use this tool versus check_listing, check_endpoint, or preflight_payment. Usage is only implied by the 'Bazaar Listing Guard' framing and the listing-metadata screening focus; there are no exclusions or alternative-routing instructions.

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/openWorld/non-idempotent/non-destructive, and the description adds genuinely new behavior: paid operation at $0.01 USDC with no free trial, ambiguous matches failing without charge, and returned artifacts (signed observation, OFAC flags, confirmations, printable HTML). It doesn't explain settlement mechanics or what a failure/payment-refund path looks like.

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 primary lookup mode and tight overall, but the telegraphic fragment style ('Signed observation, OFAC flags, confirmations and printable HTML') reads as a compressed feature list rather than structured prose. Nearly every clause carries information, so little is wasted.

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

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

With no output schema and no annotation-level detail on returns, the description steps in by naming the response payload (signed observation, OFAC flags, confirmations, HTML) and the failure mode for ambiguity. It leaves the cost/charge interaction and error taxonomy slightly under-specified for a paid 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 0%, so the description must carry the load, and it does: it ties tx_hash to an optional log_index, groups pay_to + decimal amount + start/end into an alternative lookup path, and imposes a 90-day window on the dates. It adds little on field formats (hex patterns, amount precision), which remain schema-only.

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

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

States a specific verb and resource ('Verify a native Base USDC transfer') and enumerates the two exact identification modes. An agent can tell this apart from siblings like check_token or preflight_payment purely from the description.

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?

Clearly specifies the two invocation modes (tx_hash [+log_index] vs pay_to + amount + date range) and scopes the date range to max 90 days in the past. It also carves out what the tool is not ('not invoice ownership or finality proof') and states pricing/no-free-trial. It stops short of explicitly routing to a sibling alternative when this tool doesn't fit.

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 readOnlyHint by disclosing cost ($0.02/call, free trial), non-idempotency consequence (each repeat call creates a new receipt and may consume trial or paid calls), the fact it never signs/settles/holds funds, and that it embeds payee screening. These are non-obvious traits annotations cannot express.

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

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

Front-loads purpose and usage, then adds pricing and the sibling alternative. Fairly dense but every clause carries information; slightly list-heavy on rule names, though not wasteful.

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

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

Despite an output schema existing, the description still conveys the return decision set (allow|hold|block, reasons, cheapest option, receipt id), cost model, and read-only guarantee. It provides everything an agent needs to decide to call it and what to expect.

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 nested rules object is fully typed, so the schema already documents parameters. The description enumerates rule categories (per-payment max, hold threshold, daily cap, allowlists, new-domain days, price multiple, liveness, payTo changes) and the challenge/cart distinction, adding modest mapping value but no syntax 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?

States a specific verb (preflight/evaluate) and resource (x402/USDC payment challenge or cart) and frames its decision output as allow|hold|block. It explicitly distinguishes itself from the sibling check_payee by scoping to payments with embedded payee screening.

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 ('Call this before any x402/USDC payment', 'Use before every payment') and when-not ('For standalone wallet, name, or domain screening without a payment, use check_payee instead'). Both the trigger and the alternative are 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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real context beyond them: the $0.02 per-calculation cost and 'no stored inputs' data-handling note are exactly the kind of operational facts annotations can't convey.

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

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

Three tight sentences: what it computes, what you supply, what it explicitly is not. Costs and data policy are last, so the essential content is front-loaded.

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

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

With 6 params, nested objects, 0% schema coverage, and no output schema, the description leaves notable gaps: it never says what the estimate returns (array size, battery Ah, panel count) and drops two parameters. Adequate to call, but not complete for interpreting results.

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

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

Schema description coverage is 0% (only an example object), so the description must carry semantics; it names 4 of 6 inputs conceptually but omits panel_watts and inverter_efficiency entirely. No units or meaning for 'pv_loss_fraction' vs 'peak_sun_hours' beyond the naming convention.

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 computation ('Off-grid PV energy-balance estimate') with attribution, so the agent knows exactly what it produces. It is trivially distinguishable from all siblings (endpoint/payment/listing checks), none of which do solar sizing.

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?

'Supply daily loads, peak sun hours, PV losses, and optional battery assumptions' tells the agent the required input shape, and the explicit exclusions ('No location/weather lookup, electrical design, surge or installation certification') set a clear when-not boundary. It stops short of naming an alternative tool, but no sibling overlaps this domain.

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

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

Goes well beyond the annotations by disclosing hard limits (1000 transfers / 128 RPC calls / 25 seconds), the failure mode and its cost consequence ('fails without charge'), and the price point. These are exactly the facts an agent needs before committing a paid, rate-limited call. Nothing conflicts with readOnlyHint=true or destructiveHint=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?

Front-loaded with the capability and range, then constraints, then price; no sentence wastes space except the 'Informational, not tax advice' disclaimer, which is boilerplate but still protects against misuse. Slightly telegraphic in places, but dense rather than padded.

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

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

With no output schema, the description compensates by naming the returned content (exact decimal running balances, counterparties, OFAC flags) and the two output formats. Limits, cost and failure behavior are covered; field-level output structure and pagination/size semantics remain unstated, which is a minor gap for a 4-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?

With 0% schema description coverage the description carries the burden, and it does add real meaning: 'start inclusive/end exclusive' and the 90-day maximum define the range semantics that the schema only types as date-time. The address parameter is only implied ('native Base USDC wallet') and the csv/json trade-off is not elaborated, so a gap remains.

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 ('Export native Base USDC wallet transfers as JSON or CSV') with scope qualifiers (past range up to 90 days). An agent immediately knows this is a paid historical transfer export, not a live balance or payment check, which cleanly separates it from payment_receipt / preflight_payment-style 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?

Gives clear operating conditions: past ranges only, capped at 90 days, priced at $0.05 USDC with no free trial, and oversized/unavailable data fails without charge. It never names an alternative tool or an explicit 'do not use for X' case, so it stops short of full routing guidance.

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