Skip to main content
Glama
chia-mcp

chia-mcp

Official
by Chia-Network

get_puzzle_and_solution

Read-only

Retrieve the CLVM puzzle and solution for a spent coin by passing its coin ID and exact spent_block_index; use get_coin_record_by_name first to obtain the required height.

Instructions

Get the puzzle (CLVM program) and solution for a coin that was spent at a specific height. The puzzle defines the coin's spending rules, and the solution is the input that satisfied those rules. Only works for coins that have been spent. ⚠️ height MUST be the coin's spent_block_index — call get_coin_record_by_name first to obtain it. Passing the current height or confirmed_block_index fails with INVALID_HEIGHT_FOR_COIN (upstream nodes) or PUZZLE_SOLUTION_FAILED (Coinset — which returns this code for ALL failure cases including wrong height and unspent coins).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "coin_id": "<coin_id>",
      "height": "<height>"
    },
    "name": "get_puzzle_and_solution"
  }
}

Input Schema

NameRequiredDescriptionDefault
heightYesMust be exactly the spent_block_index from the coin's record (get_coin_record_by_name) — NOT the current chain height and NOT confirmed_block_index. Any other value fails with INVALID_HEIGHT_FOR_COIN.
coin_idYesThe coin ID of the spent coin (0x-prefixed, 32 bytes hex)

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.2

TDQS

A4.2/5.0
Behavior4/5

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

Annotations only declare readOnlyHint=true; the description adds substantial behavioral context beyond that: the spent-coin precondition, the required height semantics, and the divergent failure codes between upstream nodes (INVALID_HEIGHT_FOR_COIN) and Coinset (PUZZLE_SOLUTION_FAILED for all failures). The only gap is it does not describe the shape or size of the returned puzzle/solution payload.

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

Conciseness4/5

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

Front-loaded with the operation, then the critical height constraint and failure modes. The parenthetical error-code catalogue is dense but earns its place by preventing a common mis-call; nothing is redundant, though it edges toward verbose.

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

Completeness4/5

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

No output schema exists, so the description correctly explains what 'puzzle' and 'solution' mean in CLVM terms and warns the result only exists for spent coins. It is nearly complete; a note on return size or whether the puzzle is serialized hex would close the remaining gap.

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

Parameters4/5

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

Schema coverage is 100%, so baseline is 3, but the description reinforces and clarifies the height parameter with an error-code mapping (INVALID_HEIGHT_FOR_COIN) that the schema does not carry in full. The coin_id parameter is left entirely to the schema, which is acceptable given its regex pattern.

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

Purpose4/5

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

States a specific verb and resource ('Get the puzzle (CLVM program) and solution') and defines both domain terms so the agent knows what it receives. It does not distinguish itself from the sibling get_puzzle_and_solution_with_conditions, so it falls short of full sibling differentiation.

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

Usage Guidelines5/5

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

Explicit when-to-use guidance: 'Only works for coins that have been spent,' plus a prerequisite instruction to call get_coin_record_by_name first to obtain spent_block_index. It also describes the when-not conditions (current height, confirmed_block_index, unspent coins) and names the resulting failure codes.

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