Paddock

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

Goes well beyond the readOnly/openWorld annotations by disclosing the cost model ($0.02/call via x402, key paths, free trial limited to 1/day over MCP only), the ranking methodology and window, and an integrity guarantee (formula published, positions not sold). Auth and rate-limit behavior are explicit.

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 decision question, then layers pricing, method, and integrity in a compact block with no filler sentences. It is slightly dense and could separate the payment mechanics from the ranking explanation, but nothing is wasted.

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

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

With no output schema, the description compensates reasonably by stating what is returned ('every input so the score can be checked') and by covering pricing, auth, trial limits, and valid categories. A little more on the return shape (ordering, per-provider fields) would fully close the gap.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it enumerates the valid category values with alias acceptance and explains the api_key trade-off (omit for free trial or to surface x402 payment details). This goes beyond the schema's example-only category description.

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

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

States a specific verb+resource with the exact ranking inputs: reliability (7-day probe success share), reputation (unique buyers), and price. An agent can distinguish this from siblings like get_category_detail or get_provider_revenue because the description names the composite decision it produces ('which provider should my agent 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?

Frames the use case directly as a selection question and clarifies the payment routing (x402 vs Builder/Pro key vs 1 free MCP trial/day), which is real context for deciding whether to call it. It stops short of naming alternatives or exclusions (e.g., when to prefer verify_before_pay or get_category_detail), so it does not reach 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 cover the read-only, non-destructive, non-open-world profile, so the description's added value is real: it discloses that data comes from a nightly snapshot (freshness), that a free pk_free_ key works against a shared 10 calls/day quota (rate limit/auth), and that aliases are resolved. It stops short of describing latency or pagination.

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 compact and the operational facts (what is returned, key/quota, valid values, aliases) all earn their place. The opening rhetorical question 'Who's selling in this category, and who's actually getting paid?' is tone rather than information and slightly delays the front-loaded payload.

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 correctly carries the burden of describing the return payload (transactions, volume, buyers, reliability score) and the accepted input domain. A 2-parameter tool with no nested objects needs little more; only the absence of explicit sibling routing keeps it from a 5.

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, but the description genuinely extends the schema by enumerating all eight valid category values and giving alias mappings ('LLM inference' -> llm, 'defi' -> markets) that the schema's bare 'e.g.' examples do not 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?

The description states a specific resource (per-category service roster) and enumerates the fields returned (daily transactions, USDC volume, unique buyers, reliability score), which an agent can distinguish from sibling getters like get_market_summary or get_provider_revenue. The verb is implied by the tool name rather than stated, and sibling differentiation is only implicit, so it falls short of a 5.

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 concrete input guidance (valid categories and accepted aliases) and notes the free-key rate limit, which helps the agent call it correctly. However, it never says when to choose this over siblings such as get_best_value_provider or get_provider_revenue, leaving the selection decision to inference.

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

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

Annotations already declare this a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the burden is lighter — and the description adds genuinely useful behavior beyond them: $0.10 per call via x402, Builder/Pro Agent key requirement, a 1-call/day free trial restricted to MCP, and a 90-day lookback window. Cost and auth disclosure of this kind is exactly what an agent needs before invoking. It stops short of describing failure modes when the lookback is exceeded or the key is invalid.

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

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

Three tight sentences, front-loaded with the purpose question before pricing and scope. The pricing sentence is the longest but earns its place by covering three distinct payment paths. No filler or repetition of annotation data.

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 usefully pre-announces what the payload contains — new/retired services, category share shifts, top movers, with figures on both sides — plus the cost, auth, and lookback limits for a paid tool. An agent has what it needs to decide and invoke, though ordering or response shape details are left unspecified.

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 (since, api_key) are already fully documented in the schema, including the YYYY-MM-DD format and 90-day cap. The description restates the date-scoping constraint but adds no format, syntax, or edge-case meaning beyond it, so the baseline of 3 applies.

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

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

The tool is framed as a diff operation ('what changed since a date I name') over a specific resource, and it enumerates the concrete dimensions of the comparison (new services, retired services, category share shifts, top movers). That is enough to distinguish it from siblings like get_market_summary or get_liveness, though the differentiation is left implicit rather than stated.

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

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

It gives real context for when the tool applies — 'diffs today against any snapshot up to 90 days back' — and explains the payment paths (paid per call, Builder/Pro key, one free trial/day over MCP). However, it names no alternative sibling tool and gives no explicit when-not-to-use guidance, so selection among the eleven siblings is still left to inference.

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

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

Annotations already declare a safe read, but the description adds material context beyond them: pay-per-call pricing ($0.99 via x402 or Builder/Pro key), a 1 free trial call/day limit over MCP, and an explicit return-scope guarantee that no seller wallet addresses, operator identity, or per-wallet rows are ever returned. Auth requirements and privacy boundaries are exactly the kind of disclosure 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?

The opening question is a strong hook and the return-field list is compact and front-loaded. However, pricing and access details are interleaved before the core capability, which slightly muddies the front-loading, and the single block of sentences could be segmented more cleanly.

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 must convey return values, and it does by naming the four signal components. It also covers payment and privacy constraints. It stops short of explaining output shape (units, whether 'flagged' is boolean vs score), which would fully close the gap.

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

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

Schema description coverage is 100% for both parameters, including the 'default 30d' window note and the api_key usage, so the schema does the heavy lifting. The description adds no parameter syntax or format detail beyond what the schema already provides, making the baseline 3 correct.

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

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

States a specific resource and scope: 'wash/circular-settlement signal per facilitator', then enumerates the exact outputs (flagged clusters, flagged volume and share, self-funding percentage, detection date). The subject matter is distinct enough from siblings like get_liveness or verify_before_pay that an agent can route to it without opening a schema.

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

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

Usage is only implied by the opening question ('Is this facilitator's volume real, or is it paying itself?'). It never states when to prefer this over sibling signal tools (e.g. get_liveness, verify_before_pay) or any exclusion conditions. The bulk of the text covers billing rather than when-to-use guidance.

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

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

Annotations cover the safety profile (readOnly, non-destructive, closed-world), and the description adds substantial behavioral context: nightly capture cadence, independent third-party source, coverage of domains with no payment history, and the up threshold definition (>=0.95). It doesn't mention caching, staleness windows beyond 'nightly', or error behavior, which keeps this below 5.

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

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

Front-loaded with the core question (was the domain up) and the nightly-vs-live distinction is placed well, but the pricing/key paragraph is dense and interrupts the flow between purpose and the sibling pointer. Multiple tiers of payment detail in a single run-on sentence dilute the signal.

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

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

Complete for a 2-param read tool with no output schema: purpose, data source, cadence, coverage edge case (domains with no payment history), the up definition, and the sibling alternative are all present. Return field names (share, latency p50/p95, sample counts, last-probe time) are enumerated, which compensates for the lack of an 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?

With 100% schema description coverage, the schema already documents both domain and api_key. The description adds payment semantics not in the schema (free pk_free_ key at 10 calls/day shared, $0.001/call via x402, 1 free MCP trial/day), which is useful pricing context but not parameter-format guidance. Baseline 3 is appropriate.

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

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

States a specific verb+resource and frames it as a third-party nightly probe of domain uptime. It explicitly contrasts itself with the sibling verify_before_pay ('for a check taken at query time use verify_before_pay'), so an agent can distinguish the two without opening either schema.

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

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

Clear context: historical nightly liveness series, not a live check, and the alternatives are named (verify_before_pay for query-time checks). It does not spell out exclusions like when historical liveness is unhelpful (e.g., brand-new domains with no probe history), but the when-to-use routing is strong.

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 destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: keyless/no-rate-limit access and, critically, a warning that category share_of_transactions is a share of categorized transactions only and that only the top 6 are returned so shares sum to <100%. That misinterpretation trap is exactly the kind of disclosure annotations cannot convey.

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

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

The output list and the share-of-transactions caveat are front-loaded and dense with earned information. The 'citation number' aside and rhetorical question are mild filler, but most sentences carry weight.

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 correctly carries the burden of describing return values and it does so, including the non-obvious share-percentage caveat. An agent can interpret the payload correctly without further docs.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline is 4. The description instead spends its words on return-value semantics, which is the right allocation.

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

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

The description names the concrete outputs (daily transactions, USDC spend, unique buyer agents, live providers, top categories by share), so an agent knows exactly what resource this returns. It only implicitly distinguishes itself from siblings like get_category_detail; there is no explicit contrast. The rhetorical opening ('How big is agent commerce today?') adds flavor rather than precision.

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

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

It states an invocation condition ('Keyless - no key, no payment, no rate limit'), which is genuinely useful access guidance. However, it never says when to choose this over get_category_detail, get_report_data, or other ecosystem-level siblings, leaving the routing decision to inference.

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

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

Annotations already declare a safe read (readOnlyHint=true, destructiveHint=false), but the description adds genuinely useful behavioral context beyond them: rate limits (shared 10 calls/day on a free pk_free_ key, 1 free trial call/day over MCP) and per-call x402 pricing. This is exactly the auth/rate-limit disclosure that is hard to obtain from structured fields. It stops short of 5 because it says nothing about latency, pagination, or result size for a ranked-all-categories query.

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 billing block (free key, x402 pricing, MCP trial) occupies the middle of the description and interrupts the flow between the opening question and the actual output description. The output details, arguably the most important for selection, arrive last. It is not bloated for its content, but the ordering is not 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 no output schema, the description carries the return-value burden and does describe the payload: all categories ranked by opportunity score, concentration, and a labeled market signal with published thresholds. Combined with annotations covering safety and the description covering auth/pricing, an agent has most of what it needs. Field-level return format remains unstated.

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 `top` and `api_key` are already fully documented in the schema with bounds and purpose. The description's mention of free/pk_free_ keys loosely reinforces the api_key parameter but adds no new syntax or format detail. Baseline 3 is appropriate when the schema carries the parameter burden.

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

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

The description delivers a specific output concept: 'Every category ranked by opportunity score (high volume, few providers), with concentration and an Open/Tightening/Consolidating/Mature signal.' That is concrete enough to distinguish it from get_market_summary or get_category_detail. It opens with a rhetorical question rather than a direct verb+resource statement, and it never names a sibling, so it falls short of a 5.

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

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

There is no when-to-use guidance and no comparison to the many sibling tools (get_market_summary, get_category_detail, get_circular_signal). The billing detail does not help an agent decide between this and adjacent categories of query. An agent must infer the place of this tool in the family on its own.

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

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

Goes well beyond the readOnly/destructive annotations: it discloses the payment model ($0.99 x402, Builder/Pro key, 1 free MCP trial/day), the attribution method, the exclusion rules (facilitator pass-through, circular-flagged wallets), and that unresolved wallets surface as one explicit unattributed row. It also reveals two non-obvious return behaviors — the per-day recipient-completeness flag and the retroactive_exclusion_caveat with its 2026-07-28 cutoff.

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?

Dense but well-organized: scope and methodology come before the caveats, and each clause carries real information. The opening rhetorical question is slightly wasteful and the payment sentence is long, but there is little true padding for a tool with this much non-obvious behavior.

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

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

With no output schema, the description still tells the agent what comes back — a ranked provider list, an explicit unattributed row without dollar values, a completeness flag, and a retroactive caveat marker — plus cost and access. Nothing material needed to interpret or price the call 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 top, window, and api_key are already fully documented in the schema (ranges, defaults, and the trial/x402 behavior of omitting the key). The prose adds no syntax or format detail beyond that, so the baseline 3 applies.

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

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

The opening 'Who earns the most' plus the explicit methodology ('Resolved by payTo wallet attribution, not by counting events') makes clear this is a provider-revenue leaderboard. It implicitly separates itself from a full-ecosystem census tool, but never names a concrete sibling like get_market_summary or get_best_value_provider, so the differentiation is inferred rather than stated.

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

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

The description defines the applicable universe ('ATTRIBUTED universe only, never the full-ecosystem census'), which implicitly tells the agent when this answer is valid, but it never says when to pick this over the sibling revenue/market tools or what prerequisites exist beyond payment. Usage 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 only cover the safety profile (read-only, closed-world, non-destructive), and the description adds substantial behavior beyond that: cost ($0.99 via x402 or Builder/Pro key), no free trial, a free metadata endpoint, and the fact that ACI output is a suspended historical print per ADR 0006. The only blemish is that the 'no free trial' claim conflicts with the input schema, which tells the agent to omit api_key 'to use the free trial (1 call/day)' — an inconsistency against the schema, not 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?

Most sentences carry real information (pricing, deprecation status, endpoint), but it opens with a rhetorical question that adds nothing for an agent and restates the free-metadata fact twice. The pricing/auth content would be better front-loaded as a single compact block rather than interleaved with marketing 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?

With no output schema, the description correctly compensates by enumerating the return contents (per-figure universe labels, methodology versions, trends, breakdowns, protocol comparison, reliability). It also discloses the deprecation caveat. The one gap is that the conflicting auth story between description and schema leaves the agent unsure whether a free call is possible.

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 month (YYYY-MM, default latest) and api_key, making 3 the appropriate baseline. The description adds cost/auth context but arguably degrades parameter semantics by contradicting the schema's free-trial behavior for api_key.

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 resource and the exact payload contents ('the monthly State of Agent Commerce as structured JSON: every figure with its universe label and methodology version, plus trends, category breakdowns, protocol comparison and reliability'), so an agent knows what it retrieves. It never names or contrasts itself with any sibling (e.g. get_market_summary, get_category_detail), so differentiation is left to inference.

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 practical context — pricing path, that metadata is free at a separate endpoint, and that retained ACI blocks are historical — which implies when the tool is and isn't worth paying for. However, it offers no explicit guidance on when to pick this over the many sibling data tools, and no exclusions beyond the ACI note.

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

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

Annotations already declare a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description adds real context beyond them: rate limits (shared 10 calls/day, 1 MCP trial call/day), per-call cost, and the important disclosure that the aci series is SUSPENDED per ADR 0006 with existing prints retained but no new prints. That suspension note is exactly the kind of behavioral 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?

The opening rhetorical question ('Is today's number a real move or ordinary noise?') is marketing framing rather than information, and pricing details precede the actual content. The metric list and the aci caveat are valuable, but the piece is not tightly front-loaded.

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

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

For a no-output-schema read tool with fully documented parameters, the description covers cost, rate limits, metric semantics, and a suspended-series caveat well. The main gap is that one enum value (settled_share_by_service) is absent from the metric list, leaving a slight mismatch with the 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 adds meaning for the aci metric's suspension and clarifies the series is not market data, but it omits settled_share_by_service even though the schema enum contains it, and says nothing about days/from/to semantics that the schema doesn't already cover.

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

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

The description states a specific verb and resource — returning Paddock's own first-party chart series by metric and date range — and enumerates the available metrics. It also draws a boundary against non-siblings ('this is Paddock's series, not token prices'), though it doesn't distinguish itself from close siblings like get_liveness or get_market_summary.

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 context is implied through pricing tiers (free pk_free_ key, x402 at $0.01/call, MCP-only free trial) rather than stated as when-to-use guidance. There is no explicit statement of when to pick this tool over the sibling series tools, so the agent must infer the choice.

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

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

Annotations cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower, and the description adds genuinely useful non-schema context: pricing model, auth paths, the free-trial limit, and a privacy guarantee ('no individual seller identity is returned'). It does not disclose result size, pagination, or latency behavior.

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

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

The payment/pricing sentences earn their place because cost is not captured in annotations or schema, but the opening rhetorical question is pure filler and the core 'what it returns' sentence is buried last. Four sentences with poor front-loading of the primary purpose.

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 three optional parameters, full schema coverage, and no output schema, the definition tells the agent the aggregation dimensions and the identity-privacy constraint, which is enough to call and interpret it. It stops short of describing how movers are counted or what a 'size band' looks like.

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 window, api_key, and min_usd with ranges and defaults. The description only echoes 'over a window' and 'large settlements' without adding syntax or format detail, 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?

The description names a specific resource and scope: large settlements over a window, aggregated by facilitator, category and size band, plus per-category mover counts. The rhetorical opener ('Where did the large settlements go?') is soft, but the substantive sentence pins down exactly what is returned. It distinguishes itself from siblings by topic (whale/large-settlement flow) without explicitly naming an alternative.

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 access conditions (paid via x402 at $0.99/call, Builder/Pro Agent key, or 1 free MCP trial call/day) but never states when to pick this tool over alternatives like get_provider_revenue or get_market_summary. Usage is only implied by the framing question.

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 (readOnlyHint, openWorldHint, destructiveHint=false) are consistent and minimal, and the description far exceeds them: it discloses that probes are unpaid GET/POST, that HTTP 200 is never treated as live, that the bias favors 'inconclusive', that route:true is not an all-clear, that no success-rate field exists by design, and that attest:true issues a signed record. This is unusually rich behavioral context beyond 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?

This is an oversized wall of run-on text with no headers or bullets. The single most important instruction ('CALL THIS BEFORE YOUR AGENT AUTHORIZES ANY x402 PAYMENT') is buried mid-paragraph after pricing minutiae, so it is neither front-loaded nor easy to scan. The content is mostly relevant but the density and lack of structure hurt selection usability.

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, yet the description fully covers the return surface: route, route_state, contract_and_request_ok, contract_and_request_ok_excludes, the checks block, and the attestation id/URL. Given a 10-parameter tool with no output schema and no required params, the agent has everything needed to call it and interpret the verdict.

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, but the description adds cross-parameter meaning beyond the schema: how each expect_* mismatch yields route:false, that omitting intended_params means 'I have not told you' rather than 'none', and that passing both intended_params and intended_params_empty is an error. It slightly over-restates what the per-field schema already covers, so it stops short of a 5.

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

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

The description states a specific verb+resource: it verifies whether an x402 payment endpoint should be paid before authorization. The opening framing ('Should my agent pay this endpoint right now?') and the explicit job of probing a 402 make the purpose unmistakable and clearly distinguish it from the data-fetching siblings (get_liveness, get_market_summary, etc.).

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

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

It gives an explicit directive: 'CALL THIS BEFORE YOUR AGENT AUTHORIZES ANY x402 PAYMENT.' It also spells out the pricing/access conditions (free pk_free_ key at 10 calls/day, $0.25/call via x402 beyond, 1 free trial/day without a key) and the alternative path, so an agent knows exactly when this applies and what it costs.

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