sign_btc_multisig_psbt

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

Annotations indicate destructiveHint=true and idempotentHint=true. The description adds rich behavioral details: decodes PSBT, validates bip32_derivation as a security check, forwards to Ledger for output walkthrough, splices signatures, and returns partial PSBT. It explains the size limit and that signing is irreversible. No contradiction with annotations; it significantly supplements them.

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 a single paragraph but efficiently packs all necessary information. It front-loads the core purpose ('Co-signer flow') and then logically flows through steps, constraints, and security notes. Every sentence adds value without redundancy. For the complexity of the tool, it is remarkably concise.

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 tool's complexity (multi-sig signing with Ledger, security checks), the description is complete. It references the prerequisite registration tool, explains the workflow, user verification step, return value (partial PSBT), and limitations (no finalization). It covers all essential aspects without needing 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?

Input schema has 100% description coverage with both parameters well-documented. The description adds extra context beyond the schema, such as the validation step (bip32_derivation check) and the requirement that the wallet must be registered. While the schema already provides the basics, the description enhances understanding with workflow details, justifying a score above 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 clearly states the tool is for co-signing a multi-sig PSBT by adding our Ledger signature. It specifies the initiators (Sparrow, Specter, etc.) and distinguishes from siblings like finalize_btc_psbt by explicitly noting we do not finalize or broadcast. The verb 'sign' and resource 'BTC multisig PSBT' are exact, and it differentiates from other signing 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?

It explicitly says when to use: when an external initiator produces a PSBT needing our signature. It also tells when not to use: we don't finalize or broadcast, and it only works for wallets registered via register_btc_multisig_wallet. The description includes prerequisites (registered wallet, PSBT with bip32_derivation) and user responsibilities (verify outputs on-device). Clear context with exclusions.

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