Diamond Bitcoin Intelligence

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

Beyond annotations, the description discloses live node fee estimates, round-up to whole sats, selection of the fastest estimate fitting each cap, the no-confirmation-guarantee caveat, and that nothing is signed or broadcast. It also states cost per call (20 sats / US$0.01 USDC), which annotations do not cover. It does not address the l402/pay_with payment handshake or rate limits.

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

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

Front-loaded with what it does, then the plan format and an inline example, then caveats and price. Sentences are short and mostly earn their place; the fee-cap example slightly duplicates 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?

An output schema exists, so return-value explanation is unnecessary, and the description covers inputs, estimation behavior, caveats, and pricing. The only gap is the payment flow around l402/pay_with, though those parameters are described in 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 coverage is 100%, so the schema already documents plan, l402, and pay_with. The description repeats the plan example that is also in the schema and adds one fact the schema lacks (the 1-to-25 size limit). Baseline 3 is appropriate since the schema carries the parameter detail.

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

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

The description gives a specific operation on a specific resource: analyze 1-25 transaction sizes against a per-transaction fee cap using live node estimates. That is clearly distinguishable from the sibling risk/screening/report tools. The generic tool name 'analyze' is only rescued by the title and the description, so it falls just short of 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?

Usage is implied by the input contract (a fee cap plus transaction sizes) and the 'no transaction is signed or broadcast' line hints at the planning use case. There is no explicit when-to-use or when-not-to-use guidance and no named alternative 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 already cover safety (readOnly, idempotent, non-open-world), and the description adds material context they cannot express: the call is metered and costs 2 sats / US$0.002 USDC. That cost signal is genuinely useful for an agent deciding whether to call it. The description does not explain the payment dance itself (invoice, L402 token), though the l402 and pay_with parameters carry part of that.

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 tight sentences: the first front-loads what the tool does and exactly what comes back, the second states the cost. No filler, nothing 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?

With no output schema, the description correctly enumerates the return fields (validity plus reason, type, witness version, scriptPubKey), which is what an agent needs to use the result. The metered-payment flow is only partly covered, but the supporting parameters and annotations fill most of that 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 addr, l402 and pay_with are all documented in the schema, and the description adds no further meaning about them. The pricing sentence loosely motivates pay_with but does not clarify how the two payment modes behave. 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?

The description gives a specific verb pair and resource ('Validate and classify one Bitcoin address') and enumerates the returned classifications (P2PKH, P2SH, P2WPKH, P2WSH, P2TR), so the scope is unmistakable. It stops short of separating itself from look-alike siblings such as bitcoin_address_risk or watch_bitcoin_address, leaving the agent to infer that this tool is validation rather than risk scoring or monitoring.

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?

'One Bitcoin address' implies the single-address case, which implicitly contrasts with the batch and monitoring siblings, but there is no explicit when-to-use or when-not-to-use statement. An agent must infer that this is the right call for a cheap validity/type check rather than a risk assessment.

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

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

Annotations already declare read-only, idempotent, closed-world behavior, so the safety profile is covered. The description adds a genuinely useful non-annotation trait: it is a paid endpoint (300 sats or US$0.25 USDC per call), which affects how an agent should invoke it. It still omits failure modes and rate/quotas.

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, zero filler. What it screens comes first and the cost constraint second, so the most decision-relevant 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?

For a single-input, paid, read-only lookup with a fully documented schema and no output schema, the description supplies enough: scope of screening and price/payment context. It could say more about what the result contains, but return values are largely inferable from the listed signal categories.

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 address format, the l402 token/preimage flow, and the pay_with enum are all already documented in the schema. The description adds no parameter-level meaning beyond that, which is the expected baseline when the schema does the work.

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

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

Specific verb (Screens) plus resource (one Bitcoin address) and an enumerated set of risk signals (OFAC, ransomware lists, ownership clusters, sweeper bots, laundering patterns). This clearly separates it from market/geopolitics siblings, though it never explicitly contrasts with the closest sibling, watch_bitcoin_address, which also targets addresses.

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: call this to risk-screen a single address. There is no explicit when-to-use vs watch_bitcoin_address (one-shot screening vs ongoing monitoring), no stated prerequisites, and no exclusions. The pricing note hints that this is a paid per-call lookup but does not guide tool selection.

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, idempotentHint, openWorldHint=false), and the description adds genuinely non-redundant behavior: results are capped at 25 and sorted by score, the signal is heuristic rather than proof, and each call is billed. The per-call cost and the heuristic caveat are exactly the kind of context annotations cannot carry.

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

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

The return shape is front-loaded in the first sentence, followed by two short sentences for the caveat and the price. Every sentence carries information, though the parenthetical rule list ('peel chains, post-mix consolidation, structuring...') could be trimmed 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?

There is no output schema, yet the description describes the return payload well: a ranked list of up to 25 cases with the rules that fired. The paid-call flow is only partially covered, since the 402/invoice mechanics live in the parameter descriptions, but nothing critical is missing for an agent to decide and invoke.

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 (l402, pay_with) are already documented in the schema with an enum. The description mentions payment and price but adds no syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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

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

The description names a specific resource (laundering-pattern cases scored by this node), the exact threshold (score 40 or more), the time window (last 60 minutes), the cap (up to 25) and the ordering (highest score first). That is far more precise than the sibling names alone convey, and it distinguishes this live feed from per-transaction tools like bitcoin_transaction_aml_check.

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 'this node scored in the last 60 minutes' and 'Heuristic, not proof', which tells an agent this is a monitoring feed rather than an authoritative screen. However, it never says when to prefer it over bitcoin_transaction_aml_check or bitcoin_sanctions_screen, 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?

Annotations already carry readOnly/idempotent safety, but the description adds genuinely non-obvious behavior: the call is paid (3000 sats or US$2.5 USDC), which is material to how an agent must sequence invocation. It also discloses the per-address plus flagged-summary return shape. It omits what happens if some addresses are invalid or how flagged results are prioritized.

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 what is screened, then who it is for, then what it costs. No filler and the batch constraint appears in the opening clause.

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 does the necessary work of naming the per-address categories and the flagged summary, and it explains the paid-invocation flow that gates the call. It could be slightly stronger on failure handling or partial-batch behavior, but nothing essential for correct invocation 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 25-item cap, the address formats, and the l402/pay_with payment parameters are all already documented in the schema. The description's 'up to 25' and price-per-call restate this rather than adding interpretation, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Screens up to 25 Bitcoin addresses in one call') and enumerates the exact risk categories returned (OFAC, ransomware lists, ownership clusters, sweeper bots, laundering patterns). It differentiates itself from the single-address sibling by referencing 'single checks' and the batch cap, though it never names bitcoin_address_risk or bitcoin_sanctions_screen 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 a concrete use context ('counterparty and withdrawal-address due diligence') and an economic reason to prefer this over single checks ('about 60% cheaper per address'). It stops short of stating when NOT to use it — e.g. for a single address, or when only a sanctions screen is wanted via bitcoin_sanctions_screen.

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 and repeatability are covered. The description adds behavior the annotations do not: this is a paid, per-call metered endpoint with a concrete price in both sats and USDC, which materially affects how an agent should invoke it. It omits what happens on an unknown block_id, so it is not a 5.

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

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

Two sentences with the returned-field inventory front-loaded and the commercial terms second. The long comma-separated field list is dense but each item is informative; nothing is redundant filler.

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

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

With no output schema, the description carries the burden of telling the agent what comes back, and it does so by enumerating the header fields. The payment flow is partly deferred to schema descriptions for l402 and pay_with, which is reasonable, though error/not-found behavior is never addressed.

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 earns a bump by explaining the payment model (2 sats via Lightning or US$0.002 USDC via x402), which gives meaning to the pay_with enum and the l402 token parameter beyond their schema text. It adds nothing new about block_id itself, which the schema already fully documents.

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 resource (Bitcoin block header), the lookup key (by height or hash), and enumerates exactly which fields are returned, so an agent knows precisely what it gets. It does not explicitly distinguish itself from close siblings like bitcoin_block_stats or bitcoin_latest_block, which keeps it out of 5 territory.

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?

"Any Bitcoin block by height or hash" implicitly positions this as the arbitrary-block lookup versus bitcoin_latest_block, but no sibling is named and there is no explicit when-to-use/when-not-to-use guidance. The pricing note tells the agent about cost, which is useful selection context, but routing between block-related siblings is left to inference.

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

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

Annotations already declare readOnly, idempotent, and closed-world, so the safety profile is covered; the description adds materially different context: the node is pruned to ~10,000 recent blocks and each call is paid (3 sats / US$0.003), which an agent must know before invoking. It stops short of describing the payment handshake flow itself, which is left to the schema's l402/pay_with fields.

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 the resource and capped by pricing. The metric enumeration is long but each item is informative; the pricing sentence is required for a paid endpoint and is not 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?

For a one-required-param read tool with no output schema, the definition covers what is returned (by metric name) and the two non-obvious operational facts: pruned history depth and per-call cost. The only gap is that it does not explain the x402-vs-Lightning payment path or what happens on an unpaid call, which the agent must derive from the parameter descriptions.

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 block_id (height or 64-hex hash), l402, and pay_with are already documented at the parameter level. The description only reiterates the height-or-hash choice and adds the pruning window as an implicit bound on valid heights; it offers no extra syntax or format detail beyond the schema.

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

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

States a specific resource and scope ('Statistics for one recent Bitcoin block... by height or hash') and then enumerates the exact metrics returned: tx count, total fees, fee-rate percentiles, size, weight, subsidy, inputs/outputs, SegWit share, and miner/coinbase tag. The metric list cleanly separates it from neighbors such as bitcoin_block_header, bitcoin_latest_block, and bitcoin_mempool_blocks without needing to name them.

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 rather than stated: the caller learns it takes a height or hash and that the node only retains roughly the last 10,000 blocks, which constrains which blocks are valid targets. It never says when to pick this over bitcoin_block_header (header-only) or bitcoin_latest_block, so the agent must infer the choice from the metric list.

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 the safety profile is covered; the description usefully confirms 'Nothing is signed or broadcast' and adds operational context absent from annotations (paid per call, 5 sats or US$0.005 USDC) plus a caveat that fee/fee-rate appear only when input data is present. It does not describe response shape, latency, or failure modes (e.g., malformed base64), so the addition is real but modest against already-rich 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?

Two sentences, front-loaded with the core action and followed by the payment/price note; very little waste. The first sentence crams six outputs into one comma-separated list, slightly reducing scannability, but nothing is extraneous.

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-content burden and does so by enumerating the decoded fields and the 'next step' guidance. Combined with the read-only annotations and explicit payment model, an agent has enough to call it correctly; only error handling and output formatting remain 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 the schema already explains psbt (base64, URL-encode + as %2B), l402 token format, and the pay_with enum. The description only echoes '(base64)' and adds nothing about l402 or pay_with, which is acceptable given the schema covers them, hence the baseline 3.

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

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

The description gives a specific verb pair ('Decode and analyze') and a precisely named resource ('PSBT (base64)'), and enumerates what the analysis yields: inputs, outputs, fee and fee rate, estimated vsize, missing signatures, and next step. The PSBT resource implicitly distinguishes this from siblings such as bitcoin_decode_transaction and bitcoin_decode_script, but it never names those siblings, so the 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?

Usage is implied rather than stated: an agent can infer it should call this when it holds a base64 PSBT and wants inspection without signing. There is no explicit when-not guidance, no mention of when to prefer bitcoin_decode_transaction or plan_cpfp, and no prerequisites beyond the payment 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?

The annotations already establish read-only, idempotent, closed-world behavior. The description adds important non-annotation behavior: per-call pricing of 2 sats or US$0.002 USDC and an enumeration of returned fields, though payment retry mechanics are left to the 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?

Front-loads the action and returned fields in a dense but efficient first sentence, followed by short payment terms. There is no filler and the key usage information appears early.

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 simple decoder with no output schema, the description adequately lists the returned fields and covers the key payment constraint. Annotations and full schema descriptions handle safety and parameter details, so nothing essential for correct invocation 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 the parameters are already documented. The description adds useful meaning for the script parameter by clarifying it can be a scriptPubKey, redeem script, or witness script, but it does not further explain l402 or pay_with beyond what the schema says.

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: decode a Bitcoin script from hex, with enumerated outputs including type, asm, descriptor, address, and P2SH/P2WSH wrapping addresses. The script resource clearly separates it from sibling tools such as bitcoin_decode_transaction and bitcoin_decode_psbt.

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 usage context by specifying that the input is a hex-encoded scriptPubKey, redeem script, or witness script, and notes that calls are paid. It does not explicitly say when to choose this over bitcoin_decode_transaction or bitcoin_decode_psbt, nor 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 readOnly/idempotent/closed-world, so the bar is lower, and the description adds real value beyond them: the explicit 'Nothing is broadcast' confirmation, the decoded-field inventory, and the crucially non-obvious payment model ('Paid per call. Price: 3 sats or US$0.003 (USDC)'). It still does not mention failure behavior on malformed hex or response shape beyond the field list.

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

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

Three compact, front-loaded sentences: what it does and returns first, the safety/orientation note second, pricing last. No filler or repetition of the title.

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

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

With no output schema, listing the decoded fields is exactly the right compensation, and the payment requirement (rare and critical for callers) is disclosed. Minor gaps remain on error handling for invalid hex and on how the payment retry flow works in practice, but the definition is sufficient to call correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description only gestures at the main parameter with '(hex)' and adds nothing about l402 or pay_with semantics (e.g. that l402 is the token:preimage after paying the Lightning invoice) beyond what the schema already documents.

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

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

States a specific verb ('Decode') plus the exact resource ('raw Bitcoin transaction (hex)') and enumerates the decoded fields returned (txid, wtxid, size, vsize, weight, inputs, outputs, SegWit/RBF). This clearly separates it from siblings such as bitcoin_transaction_status (status lookup by id), bitcoin_decode_psbt, and bitcoin_decode_script, which operate on different artifacts.

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 rather than stated: the tool applies when you already hold raw transaction hex, and 'Nothing is broadcast' hints at a safe inspection step. There is no explicit when-to-use/when-not or named alternative (e.g. use bitcoin_transaction_status if you only have a txid), leaving routing 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, idempotent, closed-world behavior, so the description's main added value is the payment contract: cost of 3 sats / US$0.003 per call and the data provenance ('Bitcoin Core estimatesmartfee on this node'). It does not describe what an unpaid call returns (e.g., a 402 challenge), which the schema only hints at via the l402 parameter.

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 what is returned and the confirmation-target list; the price is placed last where it belongs. The nine-number block list is dense but each value conveys real 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 no output schema, the description carries the burden of describing returns, and it does: per-target sat/vB values, mempool size, and minimum relay fee. Combined with the schema's payment parameters and the annotations' safety profile, an agent has enough to call this correctly and interpret the result.

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 l402 and pay_with are already documented in the parameter descriptions. The description adds nothing about either parameter, leaving it at the baseline for a fully described 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?

Specific verb-and-resource: it returns current Bitcoin fee estimates in sat/vB for nine named confirmation targets, plus mempool size and minimum relay fee. The 'right now' framing and the estimatesmartfee source make it distinguishable from the historical/ETA siblings, though it never names bitcoin_fee_history or bitcoin_transaction_eta directly.

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 'right now' and the explicit per-call price, which tells the agent this is a paid, point-in-time lookup. There is no statement of when to prefer it over bitcoin_fee_history (historical), bitcoin_transaction_eta, or bitcoin_mempool_blocks, so routing still requires 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 read-only, idempotent and closed-world, so the description's added value is the commercial behavior: every call is billed at 5 sats / US$0.005 USDC, and the lightning path returns a BOLT11 invoice plus token that must be replayed as '<token>:<preimage>'. That is material context an agent cannot get from the annotations. No rate limits or failure/expiry behavior for the payment token is described.

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?

Content is front-loaded: what data comes back first, then the payment mechanics. It is dense but wastes little; the parenthetical source and the price sentence both earn their place. Slightly long sentences reduce scannability.

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 enumerates the per-block fields plus the aggregate averages and trend, so an agent knows what comes back. Combined with full schema coverage and annotations covering safety, the only gap is response envelope/pagination, which is minor for a fixed 12-block payload.

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 both optional parameters (l402, pay_with) are documented in the schema, including the enum. The description adds nothing about parameter semantics beyond the general per-call pricing statement, 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?

"Fee rates actually paid in the last 12 Bitcoin blocks" names a specific verb-like scope (paid fees), the exact resource (last 12 blocks) and enumerates the returned fields (10th–90th percentile sat/vB, total fees, tx count, fullness, time, averages, trend), with the data source (getblockstats) named. The word "actually paid" implicitly separates it from bitcoin_fee_estimates, but no sibling is 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?

Usage is only implied: an agent can infer this is for historical/realized fee context rather than forward-looking estimates. There is no explicit statement of when to prefer this over bitcoin_fee_estimates, bitcoin_block_stats or bitcoin_latest_block, and no exclusions or prerequisites beyond the payment 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 cover the safety profile (readOnlyHint, idempotentHint, openWorldHint=false), so the bar is lower. The description adds genuinely new behavioral context that annotations cannot convey: this is a paid, per-call endpoint with a stated price (3 sats / US$0.003 USDC), which materially changes how an agent should plan calls. It stops short of explaining the unpaid-response flow or failure modes, so it is not a 5.

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

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

Two sentences, front-loaded with the substantive field list, followed by pricing. No filler. Slight redundancy between the title and the opening phrase, but the sentences each carry distinct information.

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

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

There is no output schema, so the enumerated field list effectively documents the return payload — an important contribution. Payment mechanics are covered between the price sentence and the l402/pay_with schema descriptions. The only gap is absent guidance on sibling selection, which is a usage rather than completeness issue.

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 both parameters (l402, pay_with) are documented in the schema, so the baseline of 3 applies. The description reinforces the payment model but adds no syntax or semantics for either parameter beyond what the schema states.

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 (the latest Bitcoin block) and enumerates the fields returned — height, hash, age, tx count, fees, fee-rate percentiles, size, weight, subsidy — so an agent knows exactly what it gets. It does not explicitly distinguish itself from near-siblings like bitcoin_block_header or bitcoin_block_stats, which keeps it below 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?

The word 'latest' implies a freshness scope, but there is no statement of when to choose this over bitcoin_block_header, bitcoin_block_stats, or bitcoin_mempool_blocks, and no exclusions or prerequisites. The agent must infer routing from the field list 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 already establish read-only, idempotent, closed-world behavior, and the description adds genuinely non-redundant operational context: the tool is paywalled at 20 sats or US$0.02 USDC per call, and pay_with='lightning' returns a BOLT11 invoice plus token instead of an x402 payment request. It stops short of describing failure modes (e.g., what happens on an expired invoice or unpaid call), so it is not a full 5.

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

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

Two dense sentences with the returned data front-loaded and pricing/payment mechanics second. Every clause carries information; no filler or restatement of the title. It could be marginally tighter but is well within an appropriate size for this tool.

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

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

For a zero-required-parameter, read-only, no-output-schema endpoint, the description covers what comes back, that it is node-scoped, and the full payment flow. The main missing element is routing guidance relative to the overlapping sibling tools, which is a usage concern more than a completeness one.

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 l402 and pay_with are already documented in the schema, and the enum on pay_with is structured. The description reinforces the payment/price context that motivates these parameters but adds no syntax or format detail beyond what the schema states — the baseline 3 for fully covered schemas.

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 enumerates the specific data returned (fee rates across 1 block–1 day, mempool, 24h whale transactions, AML cases, implied BTC/USD), which is far more informative than the title alone. It reads as a node-scoped market snapshot, but it never explicitly contrasts itself with siblings like bitcoin_address_risk or whale_geopolitics_report, which overlap on the whale/AML dimension.

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 statement of when to call this versus the sibling tools, and no prerequisites beyond the payment mechanics. The 'from this node' qualifier hints at scope, but an agent gets no routing guidance for choosing between this pulse endpoint and the address-risk or geopolitics reports.

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. The description adds important context beyond annotations: it is a paid call, the price is 5 sats or US$0.005, and it lists the returned block and histogram fields. It does not cover rate limits or error 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 description is information-dense and front-loads the main purpose before listing returned fields and payment terms. The long field list is justified by the lack of an output schema, though the prose is dense.

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, so the description carries the burden of explaining return values, and it does so by naming the next-4-block metrics and whole-mempool histogram. It also includes payment cost and payment options, making it sufficiently complete for this 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%, so both optional parameters (l402 and pay_with) are already documented in the schema. The description only implies paid access and does not add parameter-specific semantics beyond what the schema provides.

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: projected next Bitcoin blocks from the live mempool. It also enumerates the exact per-block metrics and fee histogram, making the tool's purpose clearly distinct from sibling fee and status tools.

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 'live mempool' and 'next 4 blocks', which signals next-block fee planning. However, it does not explicitly say when to use this instead of siblings such as bitcoin_fee_estimates or bitcoin_fee_history.

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 readOnlyHint, idempotentHint and closed-world behavior, so the safety profile is covered. The description adds genuinely non-obvious context: the call is metered, the price is 5 sats or US$0.005 USDC, data provenance is coinbase tags, and 'lightning' returns a BOLT11 invoice plus token rather than an x402 request. It does not cover failure modes on unpaid calls or whether results are cached per block, leaving a small 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?

Two sentences with the payload description front-loaded and payment terms trailing, which matches how an agent decides whether to call. The only waste is the mild repetition in 'Paid per call. Price: ... per call.' Otherwise 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?

With no output schema, the description takes on the job of describing returns and does so: per-pool block counts and share, plus the 10 latest blocks with pool attribution. Payment mechanics and price are also covered. What remains unstated is response shape specifics (ordering, units of share) and behavior when the invoice has not yet been paid.

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 optional parameters, so the baseline is 3. The description reinforces why l402 and pay_with exist by disclosing the per-call price and the two acceptance rails, but it adds no syntax or sequencing detail (for example, the order of invoice-then-token) beyond what the schema fields already state.

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: mining pools behind the last 144 Bitcoin blocks, derived from coinbase tags, returning per-pool block counts and share plus the 10 latest blocks. That is far more precise than the title alone. It does not explicitly name an alternative or sibling (e.g. bitcoin_latest_block, which also surfaces recent blocks), so it stops short of full 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?

The scope 'last 144 blocks (about 24 hours)' implicitly tells the agent this is a rolling 24-hour pool-distribution view, which is a reasonable usage hint. However, there is no explicit when-to-use/when-not-to-use statement and no routing to competing tools such as bitcoin_latest_block or bitcoin_block_stats. The agent must infer fit from the scope 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 already declare readOnlyHint=true, openWorldHint=false, and idempotentHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: it is a paid tool at 3 sats / US$0.003 USDC per call, which affects how an agent should invoke it. It stops short of describing payment flow mechanics or response shape, so a 3 fits.

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?

Information is front-loaded: the returned payload is listed first and the pricing constraint last. The enumeration is dense but every item earns its place; the pricing sentence is compact and unambiguous.

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 burden of describing return values and does so explicitly, covering all five reported metrics plus their sub-fields. The only gap is the payment workflow (when to supply l402 vs pay_with), which the schema largely handles, so it is nearly complete for a zero-parameter read tool.

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

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

Schema description coverage is 100%, so both parameters (l402 token:preimage and the pay_with enum) are already documented in the schema. The description adds no meaning about how payment modes interact with the returned data, so baseline 3 is appropriate.

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

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

The description names the specific resource and enumerates exactly what it returns: block height, difficulty, estimated hashrate, next difficulty adjustment (blocks left, estimated change) and next halving (blocks left, estimated date). That distinguishes it from siblings like bitcoin_latest_block, bitcoin_block_stats, and bitcoin_now, which cover narrower or different slices, though it never explicitly says what makes it different from those.

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 or when-not-to-use guidance and no named alternative. The only usage-adjacent content is the payment note ('paid per call'), which tells the agent nothing about selecting this tool over bitcoin_block_stats or bitcoin_now.

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 readOnly, idempotent and openWorld=false, and the description adds what they cannot: data provenance ("from this node's own Bitcoin Core"), a paid per-call model, and the exact price in sats and USDC. It omits payment failure/expiry behavior, which the schema only partly addresses.

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 payload enumeration is front-loaded in the opening clause and payment terms are compactly stated in two short sentences with no filler. The first sentence is dense but every listed item tells the agent what is returned.

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 carry the return-value burden, and it enumerates every section including the fee range (1 to 1008 blocks) and halving/retarget details. Only response format and payment-failure handling are unstated, which is minor for a zero-required-parameter aggregate read.

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 both parameters including the enum are fully documented in-schema, so the description cannot add much. It contextualizes the payment parameters by stating the per-call price, but adds no syntax or sequencing detail. 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?

"Bitcoin right now in one call" names the resource and enumerates the four payloads (fee estimates, mempool size, latest block, network status), so an agent knows exactly what it returns. It differentiates from single-topic siblings only implicitly via "in one call" rather than naming them, keeping it 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?

No explicit when-to-use or when-not guidance and no sibling is named, despite bitcoin_fee_estimates, bitcoin_mempool_blocks, bitcoin_latest_block and bitcoin_network_status each covering a subset. "In one call" implies the aggregation use case, which is enough for implied usage but leaves routing to inference.

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

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

Annotations already cover read-only, idempotent and closed-world behavior, so the bar is lower; the description still adds meaningful context beyond them with the exact-match-only limitation (no fuzzy or probabilistic matching) and the free/cost signal. It stops short of describing what a hit versus a miss returns, but the limitation disclosure is genuinely useful.

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 clauses, front-loaded with the cost and the core question, followed by the scope limit and the routing alternative. Nothing is redundant or 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?

For a single-parameter, read-only screening tool whose annotations carry the safety profile, the definition covers purpose, scope, and routing completely. The only gap is that with no output schema present, the description does not indicate the shape of the answer (boolean verdict vs. match details), which an agent calling it would benefit from.

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

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

Schema coverage is 100% and the schema already documents the single address parameter including accepted prefixes (bc1..., 1..., 3...). The description adds no syntax, format, or batching 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?

States a specific check ('Is this Bitcoin address on the OFAC SDN sanctions list or a known ransomware payment address?') with an explicit scope limit ('Exact list matches only'). It also names the sibling it is not, so an agent can select between it and bitcoin_address_risk without reading either schema.

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

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

Gives explicit when-to-use ('Exact list matches only') and an explicit alternative with the condition that selects it ('For ownership clusters, sweeper bots and laundering patterns use bitcoin_address_risk'). The 'Free' marker adds a cost-based selection signal.

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

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

Annotations cover safety, but the description adds important context beyond them: the result is heuristic not proof, it draws from this node's last 30 days of logged cases, and the call is paid (50 sats or US$0.05 USDC). These details materially affect interpretation and invocation.

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 front-loaded with purpose and packs useful details into one dense sentence. It is efficient and every clause adds value, though the long sentence could be split for easier scanning.

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 explains what is returned (score, level, rules fired, or a clear no-case). It also covers data provenance, time window, heuristic caveat, and payment cost. Together with annotations, an agent has enough to call and interpret the tool correctly.

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

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

Schema coverage is 100%, so all three parameters are documented in the input schema. The description does not add meaning beyond what the schema provides for txid, pay_with, or l402; it only mentions the call price in passing.

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 clear verb-resource pair: AML check for one Bitcoin transaction. It also specifies the output shape (score, level, rules fired) and the scope (single transaction). It distinguishes by scope from address-level and batch siblings, but doesn't name those alternatives 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?

The single-transaction scope and 'Heuristic, not proof' caveat imply when to use it, but there is no explicit when-to-use or when-not guidance, nor are alternatives like bitcoin_address_risk or bitcoin_aml_live named. Usage is only inferred.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotent, not open-world), so the bar is lower. The description adds genuinely useful non-schema behavior — that confirmed transactions in the last 6 blocks report confirmations, and that the call is metered (5 sats / US$0.005 per call). It does not discuss error behavior for unknown txids or how unconfirmed vs. deep-confirmed data differ beyond that one clause.

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, both front-loaded with the substantive output list before the payment note; nothing is buried. Minor redundancy in 'Paid per call. Price: ... per call,' which says the same thing twice.

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, so the description has to carry the return-value burden and does: it enumerates the four result components plus the confirmations case. Payment flow and pricing are covered. The only real gap is failure/edge behavior (unknown txid, transactions older than the 6-block window) for a three-parameter paid 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%, so txid, l402, and pay_with are already documented at the parameter level; baseline 3 applies. The description's 'paid per call' and price statement give useful context for the payment parameters but add no syntax or format detail beyond the schema.

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

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

The description names a concrete resource (a Bitcoin transaction) and enumerates exactly what the tool reports: effective cluster-chunk fee rate, projected block, next-block fee rate, and the RBF/CPFP fee needed to accelerate. That is far more specific than a generic 'ETA' tool. It does not, however, explicitly distinguish itself from the sibling bitcoin_transaction_status, which an agent could easily mistake for this.

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: an agent can infer this is the tool for 'when will my transaction confirm and what fee fixes it'. There is no statement of when NOT to use it, no pointer to bitcoin_transaction_status or bitcoin_fee_estimates as alternatives, and no mention of what happens for very old or unknown transactions.

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 readOnly, idempotent, and closed-world behavior, so the description needn't restate safety. It does add two things the annotations cannot convey: the tool is pay-per-call (5 sats or US$0.005 USDC), which implies an L402/x402 payment handshake, and coverage is limited to the mempool plus the last 6 blocks. It stops short of saying what happens for older transactions or failed lookups.

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, both earning their place: purpose with return-state detail first, pricing second. The parenthetical field list is dense but informative. The nested clauses in the first sentence make it slightly harder to scan, but nothing 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?

With no output schema, the description carries the burden of describing returns, and it does so by enumerating mempool fields (fee rate, age, RBF, estimated blocks) and confirmations for confirmed transactions. What is missing is the boundary case: whether a tx older than 6 blocks returns an error, an empty result, or falls back to another 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%, so all three parameters, including the l402 token format and the pay_with enum, are already documented in the schema. The description reinforces the payment context that makes l402/pay_with meaningful but adds no new syntax or format detail beyond it. 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: the status of exactly one Bitcoin transaction, 'as seen by this node', with the two possible outcome states (mempool vs confirmed in the last 6 blocks) spelled out. This cleanly separates it from siblings such as bitcoin_decode_transaction (which parses a raw tx) or bitcoin_transaction_eta (which projects timing).

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 rather than stated: you call it when you have a txid and want to know its current state. There is no explicit when-to-use guidance against alternatives like bitcoin_transaction_eta or bitcoin_decode_transaction, nor any statement of when not to use it (for example, for transactions confirmed more than 6 blocks ago).

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

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

Annotations cover the safety profile (readOnly, idempotent, closed-world), and the description adds the crucial non-obvious behavior: this is a paid call, priced at 10 sats or US$0.01 USDC, with two settlement paths. It also discloses the result cap of 50, ordering, and the returned field set. It stops short of describing failure modes (unpaid call response, empty-window behavior), so it is not a 5.

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

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

Front-loaded with the core definition, then the return shape, then price — a sensible order with no filler. The parenthetical field list is dense but earns its place given there is no output schema; the only minor cost is that it reads as one long sentence.

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-required-parameter, read-only feed with no output schema, the description covers scope, limit, ordering, returned fields, window totals, and payment terms — enough to call it correctly. Missing only edge-case behavior such as an empty window or what an unpaid invocation returns.

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; however, the description supplies the payment price that explains why and when the l402 and pay_with parameters matter, which is meaning the schema does not convey. The '<token>:<preimage>' flow and enum choices themselves are already documented 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 resource with explicit thresholds and scope: 'Bitcoin transactions of US$100,000 or more this node saw in the last 10 minutes', plus result cap and ordering ('up to 50, largest first'). This clearly separates it from siblings like bitcoin_aml_live (scoring) and whale_geopolitics_report (analysis), which an agent can distinguish 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?

Usage is implied by the live 10-minute window and whale threshold, but the description never says when to pick this over whale_geopolitics_report or bitcoin_aml_live, nor what happens when the window is empty. There is no explicit when-to-use or when-not-to-use guidance.

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

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

Goes well beyond the annotations: it discloses the epistemic limits ('Missing does not prove spent', no cryptographic unspentness proof or spendability guarantee), a pre-charge validation rule ('all-absent batches rejected before charging'), and a concrete price (20 sats / US$0.02 USDC). These are exactly the caveats an agent needs to avoid over-claiming spend status, and they are consistent with readOnlyHint=false being driven by billing rather than data mutation.

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 scope and return content, then the caveats, then the price. Every clause carries information; nothing is redundant filler.

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

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

For a paid, open-world, read-but-billed tool with an output schema already present, the description covers scope, returned fields, epistemic caveats, rejection behavior and cost. An agent can decide to call it, form valid input, and interpret results without further clarification.

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 all three parameters are already documented in the schema, including the l402 token format and the pay_with enum. The description restates the outpoint format and the uniqueness/cardinality rule but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource — batch status for one to 25 unique Bitcoin outpoints (txid:vout pairs) — and enumerates exactly what is reported (chainstate, sequential mempool observations, value, script, confirmations, coinbase flag). The outpoint-based scope cleanly distinguishes it from the address-oriented siblings like bitcoin_address_risk and watch_bitcoin_address.

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 the scope and cardinality constraint (1-25 unique outpoints) and by the note that all-absent batches are rejected, but the description never says when to prefer this over sibling tools such as bitcoin_batch_risk or bitcoin_address_risk, nor when a single-outpoint check is inappropriate. No explicit when-not guidance is offered.

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 the safety profile is covered. The description adds genuinely useful context beyond them: it is "Free", i.e. no payment or x402 settlement is required to call it, which matters for a tool that advertises paid siblings.

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 no waste, and the most decision-relevant fact ("Free.") is front-loaded before the content list. 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?

With no input parameters and no output schema, the description carries the burden of describing returns, and it does list prices, accepted payment methods, and terms. It stops short of saying the result is a list of tools with their names/endpoints, but it is adequate for a zero-parameter read tool.

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

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

The tool takes zero parameters, so the baseline of 4 applies; there is no parameter syntax for the description to compensate for. Schema coverage is 100% and no parameters exist to document.

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

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

Specific verb ("Lists") plus a precise resource ("Diamond's paid Bitcoin intelligence tools") and even names the fields returned: prices in sats and USD, payment methods, terms. It is clearly distinguishable from the sibling tools, which are the paid intelligence tools themselves rather than a catalog of them.

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 rather than stated: an agent can infer this is the discovery step before invoking one of the paid siblings, but the description never says "use this first" or names an alternative or any exclusion. No explicit when-to-use or when-not-to-use guidance.

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

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

Annotations already cover safety (readOnly, idempotent, closed-world), so the description's real contribution is disclosing the paid-per-call model with concrete pricing (2 sats or US$0.002 USDC), which an agent cannot infer from the schema. It also discloses the returned fields in the absence of an output schema. It does not explain failure behavior for malformed or expired invoices, nor the L402 payment/retry loop, which is left to the 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?

Front-loaded with the action and the returned fields, followed by a short pricing note; two sentences with no filler. The pricing sentence repeats 'per call' twice, a small redundancy that keeps it from a 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?

With no output schema, the description correctly fills that gap by listing the decoded fields, and it surfaces the payment cost. Remaining gaps are minor: no note on how the l402/pay_with flow changes the response, and no error behavior for invalid invoices.

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%, covering invoice, pay_with, and the l402 token format, so the schema carries parameter meaning. The description adds nothing about the parameters themselves, 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 ('Decode a Lightning BOLT11 invoice') and enumerates exactly what is extracted: amount, description, payee node, payment hash, creation/expiry, expiry status, route hints. That distinguishes it from the many bitcoin_decode_* siblings, which decode transactions, scripts and PSBTs rather than invoices.

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 enumerated output fields implicitly tell an agent when this is useful (inspecting an invoice before paying), but there is no explicit when-to-use, when-not-to-use, or named alternative. Nothing states prerequisites such as needing a valid lnbc-prefixed string or how this relates to the payment flow.

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 idempotency and openness, and the description adds genuinely non-derivable context: the computation uses actual ancestor base fees, ceiling arithmetic and observed relay/mempool floors, which tells an agent the output is empirical rather than conservative. It also discloses the per-call price (20 sats or US$0.02 USDC), a critical pre-invocation fact absent from annotations. It could go further on how the payment/L402 handshake proceeds, but the core behavioral profile is well covered.

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

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

Three dense sentences, front-loaded with what the tool computes before the encoding details and the exclusions. The telegraphic 'package=...' fragment is efficient in context, and no sentence is filler. Slightly clipped prose costs it a point 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 an output schema present, return values need not be explained, and the description correctly omits them. For a paid, single-parameter computational tool, the combination of scope, exclusions, input encoding and price is sufficient to call it correctly. Only the payment flow mechanics are left largely to 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 parameter baseline is 3. The description restates the package grammar (txid:target_sat_vb:child_vbytes[,child_vbytes...]) and the 25-size cap, both of which already appear in the schema, adding no new meaning. It says nothing about the payment parameters beyond what the schema documents.

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 computation: CPFP fee-budget scenarios for a mempool transaction plus its ancestors, and immediately pins down the input encoding. It is clearly distinguishable in kind from siblings like analyze or score, though it never names a sibling to contrast with. Purpose is unambiguous.

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-not guidance: 'Not transaction construction, package-policy validation, broadcast or a confirmation guarantee' cleanly fences off four adjacent capabilities an agent might otherwise assume. What's missing is positive routing — it never says which sibling (e.g. analyze or check_outputs) to use when the agent actually wants construction or policy validation.

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 closed-world behavior, so the safety bar is lower. The description adds genuinely new context beyond them: 'Free' and 'Creates no payment' tell the agent there is no charge or payment side effect, which is the key behavioral fact for a price-comparison tool. It does not discuss what happens when the budget excludes all services.

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

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

Three short sentences, front-loaded with the 'Free' fact and the core action. The enumeration of task categories is somewhat redundant with the schema enum, but it is compact and readable 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 only two parameters, an output schema, and full annotations, the description covers what the tool does, that it is free, and that it takes an optional budget. The only meaningful gap is fallback behavior when no service matches the task/budget, which is a minor omission given the output schema exists.

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 50%: max_usdc is documented in the schema and the description reinforces it ('compares the published per-call price with an optional budget'). The task parameter has no schema description, and the description's list of categories largely restates the enum values, adding only human-readable labels such as 'daily reports' for 'daily_report'.

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 ('Choose a Diamond tool') and enumerates the task categories it routes over, which matches the enum in the schema. It is clearly a recommendation/selection tool rather than a data-fetching one, though it does not explicitly contrast itself with siblings like diamond_catalog or 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?

Usage is implied: an agent should call this to pick a Diamond service by task and price before invoking it, and the budget comparison hints at pre-purchase decision-making. However, no sibling is named as an alternative and there is no explicit when-not guidance (e.g., what to do if nothing fits the budget).

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, idempotentHint=true; the description adds real value beyond them by disclosing the per-call price (300 sats / US$0.25 USDC), the sources combined (public list matches and node observations), and the explicit limitations of a clean result. It does not explain the payment/invoice mechanics or what happens on payment failure, which would complete the picture for a paid 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?

Four tight sentences, front-loaded with purpose, then sourcing, then the caveat, then price. Every sentence carries information, though the price sentence could be merged or moved if a structured pricing field existed.

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 sketch the return content; 'risk level and findings' and 'flags require review' give a workable impression of the response. Given one required parameter and full schema coverage, the remaining gap is the exact response shape and payment error behavior rather than anything blocking invocation.

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

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

Schema description coverage is 100%, so the address, pay_with enum, and l402 token fields are already documented in the schema. The description adds no format or behavioral detail about those parameters, 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?

"Return Diamond's existing heuristic risk level and findings for one Bitcoin address" states a concrete verb and resource, plus the scope ('one address', 'existing heuristic' rather than live analysis). However, the name 'score' is generic and the description never distinguishes this from closely named siblings like bitcoin_address_risk, bitcoin_sanctions_screen, or watch_bitcoin_address.

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 the description (single-address lookup) and the caveat 'a clean result does not certify safety, legal compliance or ownership' hints at how to interpret results. But it gives no explicit when/when-not guidance and no routing to the obvious overlapping siblings, which an agent would need to choose correctly.

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 annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds that the search is free and what content is searchable, but does not describe result limits, pagination, or ranking 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?

Two short sentences with no wasted wording, and the free-cost signal is front-loaded. The searchable scope is stated immediately after.

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 simple one-parameter search tool with annotations and an output schema, the description is largely complete. The main gap is sibling routing, since it does not explain when to prefer this over diamond_catalog.

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

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

Schema description coverage is 100%, so the single query parameter is already documented as keywords for Diamond's service catalog. The description adds a little context about what those keywords cover, but no syntax or formatting guidance beyond the schema.

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

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

The description uses a specific verb and resource: search Diamond's service catalog, including tools, use cases, input descriptions, and prices. It is clear what is being searched, but it does not explicitly distinguish this from the sibling diamond_catalog tool.

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 that the search is free, which is useful context, but gives no guidance on when to use this tool versus diamond_catalog, recommend, or other siblings. There are no exclusions or alternative-selection rules.

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 non-read-only, open-world, idempotent. The description adds genuinely new behavior: a trust assumption ('Verify against a trusted header chain') and a cost model ('20 sats or US$0.02 (USDC) per call'), both of which change how an agent should invoke and budget this. No conflict with readOnlyHint=false, since the call is paid and produces an artifact.

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

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

Five short front-loaded statements: purpose, locator format, trust model, limitation, price. No filler, no restatement of the title, and the highest-value constraints come first.

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

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

With an output schema present and full schema coverage, the description only needs purpose, trust model, guarantees, and cost — all delivered. The one open thread is how the 'trusted header chain' is obtained or supplied, which an agent may still wonder about.

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 adds a compact locator grammar ('blockhash:txid[,txid...]') and the 'retained block' constraint that the schema prose only implies. It says nothing about l402 or pay_with semantics, leaving those entirely to 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 artifact ('Generate a verified Bitcoin Core Merkle inclusion receipt') plus scope ('one to five transactions in one retained block'). The locator notation makes the resource identity unambiguous, so an agent can tell this apart from the sibling risk/analysis 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?

The description bounds the use case tightly (one block, 1-5 txids) and states what the result does NOT cover ('Does not establish unspentness or irreversible finality'), which helps an agent decide this isn't a settlement/finality check. It never names an alternative sibling or a when-not-to-call condition explicitly, keeping it short of 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 only declare readOnly=false, idempotent=false, openWorld=false; the description adds genuinely new behavioral facts: a per-call price (1000 sats / US$1 USDC), a 30-day lifetime, the delivery channels, and that feed links are returned. It stops short of explaining the payment handshake order (invoice then l402 token re-call) or what happens to an existing watch after 30 days.

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 the core behavior and closing with the commercial constraint; every clause carries information (duration, trigger, channels, return value, cost) with no filler.

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

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

With no output schema, the description correctly states the return value (feed links), and the schema supplies the payment-mode parameters. The only remaining gap is the sequencing of the paid flow (call, receive invoice, pay, retry with l402), which an agent must infer.

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 every parameter including the l402 token format and the x402/lightning enum is already documented in the schema; the description adds only the price context, which is not parameter-level detail. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a precise verb and resource (alerts/watch on a Bitcoin address) plus scope (30 days, every confirmed transaction paying to or spending from it), which is unmistakably distinct from the risk-scoring sibling bitcoin_address_risk. An agent can identify the operation 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?

The description conveys what triggers the alert and for how long, so the use case is implied, but it never says when to choose this over siblings or when not to use it, and no prerequisite conditions are stated beyond the price.

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 readOnlyHint=true, openWorldHint=false and idempotentHint=true, so the safety profile is covered. The description adds a genuinely useful behavioral fact not present in structured fields: the cost per call (1000 sats or US$0.8 USDC) and that the output is JSON, which matters for an agent deciding whether to spend.

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 tight sentences: the substantive content listing comes first and the commercial terms second, with no filler. Front-loading is correct and every clause carries information, though the report-content enumeration is dense rather than elegant.

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 read-only report tool with no output schema, the description adequately conveys what is returned and what it costs. The date range and payment-token mechanics live in the schema, and the price lives in the description, so the two together are sufficient for a correct call.

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 each parameter (date, l402, pay_with) is documented in the schema itself, including the 90-day window and the '<token>:<preimage>' format. The description adds no parameter-level detail beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description names a specific resource (a one-day report) and enumerates its contents: whale flows vs world news, lagged correlations, laundering patterns, headlines, analyst brief. This is far more concrete than a generic 'report' tool. It does not explicitly differentiate from siblings like bitcoin_market_pulse, but the enumerated content makes its scope inferable.

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 explicit when-to-use or when-not-to-use guidance, and no sibling is named as an alternative for adjacent needs (e.g., bitcoin_market_pulse for price data). The only contextual clue is the pricing line, which implies a paid, deliberate call rather than routine use.

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