bot-check: Bitcoin Self-Custody & WorkSats MCP

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

Annotations cover read-only/idempotent/non-destructive, so the bar is lower, yet the description adds real operational context: a free-tier cap of 2 calls/day per IP and the exact fallback payment mechanisms (WorkSats crd_ token, L402 header, Base USDC x402TxHash). It also discloses a security constraint (never send private keys or seed phrases) and what fields the verification result contains.

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

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

Front-loaded with the core action and address types, followed by a short safety line and a dense but useful payment sentence. Every sentence carries information, though the payment sentence packs three mechanisms and a rate limit together a bit tightly.

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 lists what is returned (network, type, witness version, scriptPubKey hex). Combined with the address-format coverage, safety warning, and rate-limit/payment detail, an agent has everything needed to call this correctly, including on the paid path.

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 baseline is 3; the description still adds value by grouping the payment parameters into a coherent narrative (crd_ token vs. L402 header vs. x402TxHash) and by framing network as an expected-value check. It notably mentions an L402 header that isn't a schema parameter, which helps an agent understand the full payment surface.

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

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

States a specific verb and resource (verify a Bitcoin address) and enumerates the address encodings/script types it handles (Bech32m P2TR, Bech32 P2WPKH/P2WSH, Base58 P2PKH/P2SH), plus the concrete outputs (network, type, witness version, scriptPubKey hex). An agent can immediately distinguish this from check_descriptor and check_psbt, 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 clear: this is the tool for validating an address string, with a safety boundary about never submitting secrets. It also explains the payment path once the free tier is exhausted. It stops short of explicitly saying when not to use it or naming sibling alternatives for descriptor/PSBT work, so a 4 rather than 5.

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so the safety profile is covered; the description adds real value by disclosing that a missing checksum is computed rather than rejected, that sample addresses and scriptPubKeys are derived, and by imposing a secret-material prohibition that no annotation conveys. It does not mention the credit/x402 cost model or rate limits, which is the remaining gap.

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

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

One dense sentence that front-loads the verb, resource and supported types, followed by a short safety imperative. Nothing is redundant and the security warning is placed last for emphasis without 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?

With no output schema, the description carries the burden of explaining returns, and it does so adequately: checksum verification/computation, derivation path and xpub checks, and derived sample addresses and scriptPubKeys. Payment and credit parameters are handled in the schema. Only the failure mode (what a rejection looks like) is left unstated.

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

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

Schema description coverage is 100%, so all five parameters (including the enum on network and the 0..5 bound on deriveCount) are already documented in structured form. The description only indirectly gestures at network and deriveCount via 'derives sample addresses', adding no syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

The description names a specific verb (validate) and resource (Bitcoin output descriptor), enumerates the supported descriptor types, and states exactly what the check entails (BIP380 checksum, derivation paths, xpubs, sample addresses/scriptPubKeys). This cleanly separates it from check_bitcoin_address and check_psbt, 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 clear: you bring a descriptor string and get validation plus optional derived samples. It also draws a hard input boundary with 'Never send xprv, WIF, or seed phrases.' It does not, however, explicitly say when to prefer this over check_bitcoin_address or check_psbt, so the agent must infer the routing.

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

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

Beyond the read-only hint, the description discloses deep behavioral traits, listing specific checks (sighash types, taproot/witness scripts, fee risks). Crucially, it includes a vital security warning ('Never send private keys'), which is non-trivial behavioral context.

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

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

The description is dense with information but highly efficient. It front-loads the core technical functionality and uses a concise structure to deliver both the technical scope and the necessary security warning.

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

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

Given the complexity of Bitcoin PSBT and the associated parameters, the description is remarkably complete. It covers the data input, the specific validation steps performed (fee, change, scripts), and the safety protocols the user must follow.

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?

Although schema coverage is 100%, the description adds high-value semantic information by specifying the accepted input formats (base64 or hex). It also frames the optional payment-related parameters within the context of the inspection's risk analysis.

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 ('Inspect') applied to a complex resource (Bitcoin PSBT, BIP174). It clearly distinguishes its function by emphasizing the goal: verifying data and flagging risks before the signing process.

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 tool explicitly states its use case is inspection 'before signing,' providing a clear operational context for when to use it. While it doesn't explicitly list alternatives, its specific technical functions (fee checks, script analysis) inherently define its purpose better than simpler tools like 'check_bitcoin_address'.

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 non-read-only, non-destructive, non-idempotent, closed-world behavior, and the description adds useful semantics such as escrow for bounty_create and double-spend protection rationale for rotate/merge. It does not disclose what happens to the parent token on split, whether rotate invalidates old tokens, or what mint requires beyond a confirmed txHash.

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?

One sentence front-loads the resource, which is good, but it becomes a long run-on clause chain. The parenthetical list of verification modes (`sha256`, `descriptor_derive`, `address_script`, `psbt_feerate`, `json_schema`) merely repeats the enum already present in 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?

For an 11-parameter, nested-object, multi-action tool with no output schema, the description gives a workable action map but omits what each action returns, the fee's effect on balances, and how verification_params is structured. Annotations carry only hints, so more behavioral detail would have been warranted.

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 every parameter including the `verification_params` object is already documented in structured form. The description maps some actions to their governing parameters but adds little 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?

The description states a specific resource (WorkSats bearer credits, `crd_...`) and enumerates concrete operations — balance, split, rotate, merge, mint, bounty_create, stats — so an agent knows exactly what the tool covers. It does not explicitly distinguish itself from the task-oriented siblings (worksats_get_task, worksats_solve_task), though the credit-vs-task split is implied by the action list.

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?

Each action is given context for when it applies: rotate/merge exist 'so the sender cannot double-spend', mint is for 'L402 or x402 Base USDC', bounty_create is 'to escrow credits for a verifiable task'. What's missing is explicit routing versus siblings or when not to use a given action.

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

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

The description provides deep behavioral context that is not in the annotations, including the API endpoint being used (`GET /v1/tasks/next`) and naming a specific task type (`descriptor_checksum_and_derive`). It also mentions the output format of the result (`crd_...`).

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 highly efficient, combining the fetch mechanism, task types, external API calls, and the subsequent action required to complete the workflow into two dense, informative sentences.

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?

The description provides more than enough information to be useful, covering not only the 'what' and 'how' of the tool but also the necessary 'what next' steps for the AI agent to successfully interact with the WorkSats ecosystem.

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%, which sets a baseline score of 3. The description adds minor value by clarifying that the `type` parameter filters between buyer-funded tasks and deterministic house micro-tasks.

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 clearly defines the purpose as fetching either a buyer-funded bounty task or a deterministic house micro-task. It specifies the source (WorkSats clearinghouse) and the types of tasks handled.

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 provides explicit workflow guidance by stating that after fetching the task, the agent must call the sibling tool `worksats_solve_task` to complete the process and mint credits. This is crucial for using the tool correctly within the ecosystem.

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=false, idempotentHint=false, destructiveHint=false and closed-world, so the mutating one-shot nature is structured data. The description adds the useful outcome that the call mints a bearer credit token, but says nothing about what happens to the ticket on a wrong answer, whether attempts are consumed, or whether the same ticket can be resubmitted.

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 action and outcome before the parameter branching. The parenthetical field list in sentence two is dense but every item maps to a real branch; no filler text.

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 an 11-parameter, nested-object tool with no output schema, the description covers input selection well and names the returned token format (`crd_...`). It leaves gaps on failure modes and on exactly what the minted token grants, which matters given the absence of an output schema.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds genuine synthesis the schema lacks: it groups the 11 flat parameters into house-task vs bounty-task vs mode-specific (`descriptor_derive`, `address_script`, `psbt_feerate`, `json_schema`, `sha256`) sets, which the per-property descriptions state only in isolation.

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 (submit), a specific resource (a solved WorkSats task ticket `tsk_...`), and the concrete outcome (minting a signed bearer credit token `crd_...`). This clearly separates it from siblings like `worksats_get_task` (fetch a ticket) and `worksats_credits` (read balance).

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

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

Explicitly branches on task type: house tasks require `checksum`/`scriptPubKeys`, bounty tasks require `answer` or mode-specific fields. That is real conditional guidance, though it never states the prerequisite ordering (call `worksats_get_task` first) or what to do when a submission fails.

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