Skip to main content
Glama
chia-mcp

chia-mcp

Official
by Chia-Network

trace_coin_lineage

Read-only

Traces a coin's lineage back to its farming reward origin by following parent_coin_info links; returns the ancestor chain with flags for origin reached or max depth.

Instructions

Trace a coin's lineage back to its origin (typically a farming reward coin). Follows parent_coin_info links via repeated get_coin_record_by_name calls, returning the full chain of ancestor coins as an array ordered from the queried coin to its oldest ancestor. Stops when a coin record has coinbase: true (the farming reward flag set by consensus) or at max_depth (default 20, max 100). The response includes: reached_origin (boolean, true if a coinbase farming reward was found at the end of the chain), truncated_at_max_depth (boolean, true if max_depth was reached without finding the coinbase origin). If a parent coin record is not found mid-chain, a { status: 'NOT_FOUND' } entry is added to the lineage array and tracing stops (reached_origin will be false). Note: farming reward coins do NOT have all-zero parents — their parent ID is derived from the genesis challenge and block height. Works with any full node (Coinset, local, or simulator). Deep lineages against Coinset may trigger rate limiting; a local node has no rate limits.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "trace_coin_lineage"
  }
}

Input Schema

NameRequiredDescriptionDefault
coin_idNoThe coin ID to trace (0x-prefixed, 32 bytes hex). Also accepted as coin_name.
coin_nameNoAlias for coin_id — matches the field name used by similar tools (get_mempool_items_by_coin_name, get_memos_by_coin_name).
max_depthNoMaximum number of ancestors to trace (default 20, max 100)

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.2

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only declare readOnlyHint=true, so the description has to carry the rest, and it does. It discloses the termination conditions (coinbase: true or max_depth), the return semantics of reached_origin and truncated_at_max_depth, the NOT_FOUND mid-chain behavior, and the non-obvious fact that farming reward coins do not have all-zero parents. It also warns about Coinset rate limiting on deep lineages.

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?

The purpose and traversal mechanism come first, followed by termination rules, response fields, and operational caveats. It is long but dense, and each sentence carries distinct information. The response-field breakdown could be tightened since there is no output schema, but nothing is padding.

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

Completeness5/5

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

Without an output schema, the description compensates by enumerating the returned fields (lineage array, reached_origin, truncated_at_max_depth, NOT_FOUND entries) and their ordering from queried coin to oldest ancestor. For a recursive traversal tool with edge cases, that is enough for an agent to call it correctly and interpret the result.

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 the baseline is 3, but the description still adds meaning beyond the schema. It explains what max_depth truncation means for the result (truncated_at_max_depth=true) and describes the coin_id/coin_name alias relationship as an interop convenience. Those details go beyond the raw pattern/default text in the schema.

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

Purpose5/5

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

The description opens with a specific verb-and-resource pair: 'Trace a coin's lineage back to its origin', and it clarifies what 'origin' actually means (a farming reward coin). That disambiguates the tool from the raw lookup siblings such as get_coin_record_by_name, which the description identifies as the underlying primitive rather than the alternative.

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

Usage Guidelines4/5

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

It gives clear context for when this tool applies: you need the full ancestor chain, not just one record. It also states deployment conditions ('Works with any full node (Coinset, local, or simulator)') and a rate-limit caveat for Coinset. It does not explicitly tell the agent to prefer this over calling get_coin_record_by_name in a loop, so that guidance is only implied.

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