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

No annotations are provided, so the description carries the burden; it explains the underlying protocol fact that 'every spend publishes the grant it spent' and that recovery is possible from wire JSON or redeem script hex. This makes the read-only, non-database source of data transparent. It stops short of describing failure modes or exact output, but the operation's behavior is clearly disclosed.

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 opens with the purpose, then the use case, then the protocol justification, then input guidance — a sensible front-loaded order. Each sentence contributes new information, though it is slightly longer than strictly necessary. No filler or repetition of schema field names.

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/recovery tool with no annotations and no output schema, it explains the input options, the conditions under which to use it, and why recovery works. It does not describe the shape of the returned grant state or behavior when inputs are missing or invalid, so an agent still must infer some result semantics. This gap keeps it from being complete, but it covers the essential call-time decisions.

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 schema already documents all three parameters (100% coverage), so the baseline is a 3. The description adds value by clarifying that `transaction` and `redeemScriptHex` are alternatives and by specifying wire-JSON format for the transaction. This exceeds what the schema descriptions alone provide.

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

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

States a specific verb ('Read'), a specific resource ('a grant's full state'), and the recovery source ('any transaction that spent it'). It also names the intended outcome ('work out where it went'), which clearly distinguishes it from the build/check/grant sibling 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?

Explicitly defines the trigger: 'Use this when a grant's recorded state is stale, wrong, or lost and its address turns up empty.' It also tells the agent what inputs are acceptable in which situation ('transaction as wire JSON, or just the redeem script hex'). It does not name alternative tools, but the trigger condition is specific enough to route away from the siblings.

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