Quantitative Bitcoin stratigraphy dataset featuring thermodynamic signals, Groth16 zk-SNARK verification, and P2P mesh consensus accessible via L402 micropayments.
Scored across 8 tools
Each tool has a clearly distinct purpose: mesh.status for node health, proof.ground for creating receipts, proof.list/status/submit/verify for different aspects of proof lifecycle and verification, stratigraphy.get/list for telemetry retrieval and catalog discovery. The descriptions explicitly cross-reference to prevent misuse, leaving no ambiguity.
All tool names follow a consistent 'resource.action' pattern with snake_case (e.g., proof.verify, stratigraphy.list). This uniform convention makes the toolset predictable and easy to navigate.
With 8 tools covering mesh health, proof submission/verification/querying, and telemetry retrieval, the server is well-scoped. Each tool serves a specific function without redundancy, and the count is appropriate for the domain.
The tool surface covers the full lifecycle for proofs (submit, verify, list, status, ground) and comprehensive telemetry access (get, list). The absence of a deletion tool is explicitly intentional, and all necessary retrieval and discovery operations are present, leaving no critical gaps.
PURPOSE: Retrieves current peer topology, propagation, cross-validation, and quorum health for the mesh node. USAGE: Use to inspect peer connectivity and consensus readiness. Do NOT use for individual proof validation or telemetry retrieval; use proof.verify or stratigraphy.get instead. PARAMETERS: No input properties are accepted. BEHAVIOR: Observes current in-process mesh service metrics without changing proof or telemetry state. Rate limit: 60 req/min per IP shared across /mcp. RETURNS: Object containing nodePubkey, activePeerCount, configuredPeerCount, topologyHealth, crossValidationSuccessRate, averagePropagationLatencyMs, and quorumThreshold. ERRORS: -32602 (Invalid Parameters) when any input property is supplied; HTTP 429 (Rate Limit) when the shared limit is exceeded. No 402 payment required.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| nodePubkey | Yes | Lowercase hexadecimal Nostr public key identifying this mesh node. |
| topologyHealth | Yes | Current consensus topology health classification. |
| activePeerCount | Yes | Number of recently validated nodes, including the local node. |
| quorumThreshold | Yes | Minimum unique node attestations required for consensus. |
| configuredPeerCount | Yes | Number of remotely configured trusted peers. |
| crossValidationSuccessRate | Yes | Lifetime ratio of successful peer cross-validation attempts. |
| averagePropagationLatencyMs | Yes | Mean round-trip propagation latency for successful attestations. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description goes further by stating it 'observes current in-process mesh service metrics without changing proof or telemetry state' and disclosing the shared rate limit. This adds meaningful behavioral context beyond the structured annotations without contradicting 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 organized into clear labeled sections: PURPOSE, USAGE, PARAMETERS, BEHAVIOR, RETURNS, and ERRORS. Every section adds necessary information, and the purpose is front-loaded so an agent immediately knows the tool's role.
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 parameterless, read-only tool, this description covers purpose, usage boundaries, behavior, rate limits, return fields, and error conditions. Nothing an agent needs to invoke it correctly is missing, and the output schema and annotations cover the rest.
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?
There are zero parameters, so the baseline is 4. The description explicitly says 'No input properties are accepted' and documents the -32602 error for supplying any property, which adds value beyond the input schema's empty properties declaration.
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 opens with a specific verb and resource: 'Retrieves current peer topology, propagation, cross-validation, and quorum health for the mesh node.' It clearly distinguishes this from the sibling tools by name in the usage section, so an agent can reliably tell what this tool owns.
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 states when to use the tool ('inspect peer connectivity and consensus readiness') and when not to use it, naming the exact alternatives: proof.verify and stratigraphy.get. This removes ambiguity about tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PURPOSE: Creates a signed epistemic anchor receipt for agent context grounded in the current Bitcoin tip. USAGE: Use to ground agent context and obtain a verifiable receipt. Do NOT use for raw ZK proof verification; use proof.verify instead. PARAMETERS: Accepts contextHash as a 64-character case-insensitive hexadecimal SHA-256 digest, agentId as a trimmed 1-256 character string, and an optional metadata object. BEHAVIOR: Validates context and checks Bitcoin tip and signing readiness before requesting payment; after 250-sat L402 settlement, returns a signed receipt without a second HTTP payment. Rate limit: 60 req/min per IP shared across /mcp. RETURNS: Object containing receipt with signed payload, Merkle proof, NIP-78 signature, normalized contextHash and agentId, blockHeight, blockHash, and timestamp; verify it through /api/v1/zk/verify. ERRORS: -32602 (Invalid Parameters) for malformed context, HTTP 402 (Payment Required) with a 250-sat invoice when unpaid, 429 (Rate Limit), or 503 when Bitcoin tip or signing is unavailable.
| Name | Required | Description | Default |
|---|---|---|---|
| agentId | Yes | Trimmed client or agent identifier string from 1 to 256 characters. | research-agent-7 |
| metadata | No | Key-value JSON object containing arbitrary metadata. | |
| contextHash | Yes | 64-character case-insensitive hexadecimal SHA-256 digest string; normalized to lowercase. | 4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f4f |
| Name | Required | Description |
|---|---|---|
| receipt | Yes | Full signed receipt; send unchanged to POST /api/v1/zk/verify as attestation. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are present (readOnlyHint:false, idempotentHint:false, destructiveHint:false), and the description adds substantial behavioral context beyond them. It discloses the payment flow (250-sat L402 settlement, no second HTTP payment), validation of Bitcoin tip and signing readiness, rate limits (60 req/min shared across /mcp), and error conditions (402, 429, 503, -32602). No contradiction with annotations.
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 structured with labeled sections (PURPOSE, USAGE, PARAMETERS, BEHAVIOR, RETURNS, ERRORS) that front-load purpose and make scanning easy. Length is justified by the tool's complexity (payment, verification, multiple error modes). No redundant sentences; each section adds necessary information.
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?
Despite having an output schema, the description still summarizes the return object's fields and gives a verification endpoint, which is useful. It also covers parameter validation and error handling, making the tool safe to invoke without external documentation. The addition of rate limits and settlement details completes the invocation context.
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%, and each parameter is already documented in the schema with details like the pattern, min/max lengths, and normalization. The description simply repeats these facts in the PARAMETERS section without adding new semantic meaning, so the baseline of 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 opens with 'Creates a signed epistemic anchor receipt for agent context grounded in the current Bitcoin tip', which states a specific verb, resource, and scope. It also explicitly distinguishes this tool from proof.verify by naming the alternative for raw ZK proof verification, allowing an agent to select it correctly without opening schemas.
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 USAGE section states 'Use to ground agent context and obtain a verifiable receipt' and explicitly says 'Do NOT use for raw ZK proof verification; use proof.verify instead.' This provides clear when-to-use and when-not-to-use guidance with the specific alternative. No ambiguity remains about which sibling to choose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PURPOSE: Lists and filters proof attestations held in the node's bounded process-memory index. USAGE: Use exclusively to query or filter arrays of indexed attestations. Do NOT use to fetch an individual proof or snapshot's status by identifier; use proof.status instead. PARAMETERS: limit is an integer from 1 to 100 with default 20; offset is an integer from 0 to 1000 with default 0; status is one of verified, cached, pending, or invalid. BEHAVIOR: Filters the process-memory index, orders matches newest first, applies offset and limit, and calculates mesh quorum without durable database writes. Rate limit: 60 req/min per IP shared across /mcp. RETURNS: Object containing attestations with proofHash, snapshotDigest, status, submittedAt, attestationCount, and meshQuorum, plus total before pagination. ERRORS: -32602 (Invalid Parameters) for invalid fields, ranges, or status values; HTTP 429 (Rate Limit) when the shared limit is exceeded. No 402 payment required.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of records to return (integer, 1-100). | |
| offset | No | Zero-based pagination skip offset count. | |
| status | No | Filter records by attestation lifecycle state: verified, cached, pending, or invalid. | verified |
| Name | Required | Description |
|---|---|---|
| total | Yes | Total number of indexed attestation records matching the optional status filter before the limit is applied. |
| attestations | Yes | Recent indexed proof attestations ordered from newest to oldest. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds substantial behavioral context: bounded process-memory index, newest-first ordering, offset/limit handling, mesh quorum calculation, no durable database writes, and a shared rate limit. No contradiction exists between the description and annotations.
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 organized into labeled sections with no wasted sentences. It front-loads purpose and usage, then covers parameters, behavior, returns, and errors in a compact format that an agent can parse quickly.
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 listing tool with an output schema, the description still covers return fields, pagination totals, error codes, rate limiting, and shared-limit behavior. An agent has everything needed to select, invoke, and interpret results from this tool correctly.
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% and each parameter already has type, range, default, and enum documentation. The description restates the constraints in prose but does not add meaning beyond the schema, so the baseline of 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?
States a specific verb and resource: 'Lists and filters proof attestations held in the node's bounded process-memory index.' It clearly distinguishes itself from proof.status, which is the sibling for fetching individual status, so an agent can understand the scope without opening the schema.
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?
Provides explicit usage direction: 'Use exclusively to query or filter arrays of indexed attestations' and directly warns against using it for individual status, routing to 'proof.status instead.' This leaves no ambiguity about when to choose this tool over its sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PURPOSE: Retrieves process-memory lifecycle and mesh-quorum status for one proof or snapshot identifier. USAGE: Use exclusively to fetch a single attestation's status by its proofHash or snapshotDigest. Do NOT use to search, filter, or list multiple attestations; use proof.list instead. PARAMETERS: Exactly one of proofHash or snapshotDigest must be supplied; proofHash accepts a 64-digit hexadecimal digest with optional 0x prefix or an IPFS CID, while snapshotDigest accepts a decimal field digest, 64-digit hexadecimal digest, or IPFS CID. BEHAVIOR: Looks up bounded process-memory status and compares its attestation count with the current mesh quorum threshold; an unknown identifier is reported as pending rather than as not found. Rate limit: 60 req/min per IP shared across /mcp. RETURNS: Object containing status as verified, cached, pending, or invalid, plus verifiedAt, attestationCount, and meshQuorum. ERRORS: -32602 (Invalid Parameters) unless exactly one valid selector is supplied; HTTP 429 (Rate Limit) when the shared limit is exceeded. Unknown identifiers do not produce 404. No 402 payment required.
| Name | Required | Description | Default |
|---|---|---|---|
| proofHash | No | Canonical IPFS CID or hex digest identifier string. | 186b68214d3bfa5566dde64f3c66746e1bad3fdad7a01e158e6e8a730023302e |
| snapshotDigest | No | Decimal field digest, 64-digit hexadecimal digest, or IPFS CID identifier string. | 186b68214d3bfa5566dde64f3c66746e1bad3fdad7a01e158e6e8a730023302e |
| Name | Required | Description |
|---|---|---|
| status | Yes | Lifecycle state: verified after cryptographic validation, cached on a repeated valid verification, pending while unverified or in progress, or invalid after rejection. |
| meshQuorum | Yes | Whether the observed attestation count meets the current mesh quorum threshold. |
| verifiedAt | Yes | ISO 8601 UTC date string format. |
| attestationCount | Yes | Number of Nostr NIP-78 attestations observed on the submitted snapshot. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the bar is higher. The description goes well beyond this by disclosing that unknown identifiers are reported as pending rather than not found, the shared 60 req/min rate limit, and the mesh-quorum comparison behavior. No annotation contradiction exists.
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 labeled structure (PURPOSE/USAGE/PARAMETERS/BEHAVIOR/RETURNS/ERRORS) front-loads the most critical information and every sentence earns its place. No filler or repetition of schema data; it packs a large amount of decision-relevant detail into a compact, scannable format.
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 output schema exists, the description need not detail return structures, yet it still summarizes them. It covers purpose, usage, parameter constraints, behavioral quirks, rate limits, error codes, and edge cases (unknown identifiers not producing 404). Nothing an agent needs to correctly select and invoke the tool is missing.
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 adds genuine value by clarifying the exactly-one constraint, by explaining the semantic difference between proofHash (hex or CID) and snapshotDigest (decimal field digest, hex, or CID), and by specifying that unknown identifiers map to pending rather than not found. It slightly exceeds the baseline but still relies on schema patterns for exact formats.
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 opens with a specific verb and resource: 'Retrieves process-memory lifecycle and mesh-quorum status for one proof or snapshot identifier.' This clearly states the exact operation and scope, and the 'one identifier' phrasing distinguishes it from listing tools like proof.list without any ambiguity.
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 USAGE section explicitly states when to use the tool ('Use exclusively to fetch a single attestation's status'), provides a direct exclusion ('Do NOT use to search, filter, or list multiple attestations'), and names the correct alternative ('use proof.list instead'). This is textbook guidance rivaling the calibration example.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PURPOSE: Verifies Groth16/Poseidon BN254 coordinates, indexes their lifecycle in process memory, and attempts Nostr NIP-78 publication for a valid proof. USAGE: Use to submit proof coordinates for lifecycle lookup and optional Nostr publication. Do NOT use when only validating an encoded proof against telemetry data; use proof.verify instead. PARAMETERS: proof is an object containing pi_a as three decimal strings, pi_b as three pairs of decimal strings, and pi_c as three decimal strings; publicSignals is exactly five decimal strings ordered as blockHeight, thermodynamicHash, timestamp, valuationSat, and snapshotDigest; snapshotDigest accepts a decimal field digest or IPFS CID and, when supplied, must equal publicSignals[4]. BEHAVIOR: Validates and indexes Groth16/BN254 ZK proof attestations through a bounded process-memory lifecycle; records can be refreshed or evicted, so the index is neither durable nor append-only. Valid proofs may be published as NIP-78 attestations. This MCP API exposes no deletion tool. Rate limit: 60 req/min per IP shared across /mcp. RETURNS: Object containing proofHash, status as verified or invalid, submittedAt, and attestationStatus describing Nostr publication or why it was not attempted. ERRORS: -32602 (Invalid Parameters) for malformed coordinates, signals, fields, or a snapshotDigest mismatch; HTTP 429 (Rate Limit) when the shared limit is exceeded; cryptographic rejection is returned as status invalid and publication failure is reported by attestationStatus. No 402 payment required.
| Name | Required | Description | Default |
|---|---|---|---|
| proof | Yes | Groth16/Poseidon zk-SNARK proof coordinates over the BN254 curve. | |
| publicSignals | Yes | Public signals ordered as blockHeight, thermodynamicHash, timestamp, valuationSat, and snapshotDigest. | |
| snapshotDigest | No | Decimal field digest or IPFS CID that must equal publicSignals[4] when supplied. | 1 |
| Name | Required | Description |
|---|---|---|
| status | Yes | Immediate Groth16 verification result for the submitted proof and public signals. |
| proofHash | Yes | 0x-prefixed lowercase hexadecimal SHA-256 digest of the canonical proof. |
| submittedAt | Yes | ISO 8601 UTC date string format. |
| attestationStatus | Yes | Nostr NIP-78 publication result: broadcast_confirmed, broadcast_failed, not_configured, or not_broadcast_invalid_proof. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only broadly signal readOnly=false, idempotent=false, and destructive=false. The description adds substantial behavioral context: records live in process memory, can be refreshed or evicted, are neither durable nor append-only, valid proofs may be published to Nostr, rate limits are shared across /mcp, and no deletion endpoint exists. It also clarifies error semantics and that publication failure is surfaced through attestationStatus.
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 long but organized into labeled sections (PURPOSE, USAGE, PARAMETERS, BEHAVIOR, RETURNS, ERRORS), making it skimmable and front-loaded with purpose. Each section provides operationally relevant information for a complex tool, and there is no filler or redundant prose.
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 tool with nested parameters, side effects, external publication, lifecycle behavior, and multiple error modes, the description covers everything an agent needs: usage boundary, parameter shapes, invariants, return fields, error codes, rate limits, and payment requirements. Combined with the rich schema and annotations, nothing essential is missing.
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%, and the schema already documents proof structure, the five-signal ordering, and the snapshotDigest equivalence constraint. The description summarizes these constraints clearly, but it does not add meaning beyond what the schema already provides. Per the high-coverage 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 states a specific action set: verifies Groth16/BN254 coordinates, indexes them through a lifecycle, and attempts Nostr NIP-78 publication. It clearly differentiates from proof.verify by naming the sibling in the usage section, so an agent can distinguish submission from pure validation without inspecting the schema.
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 USAGE section explicitly says when to use this tool ('submit proof coordinates for lifecycle lookup and optional Nostr publication') and when not to ('Do NOT use when only validating an encoded proof against telemetry data; use proof.verify instead'). This is direct alternatives-and-exclusions guidance with nothing left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PURPOSE: Verifies a base64url-encoded Groth16/Poseidon BN254 proof against typed public claims and a telemetry snapshot. USAGE: Use to validate a proof against snapshot data. Do NOT use to submit proof coordinates for optional Nostr publication; use proof.submit instead. PARAMETERS: proof is a non-empty base64url proof string; publicInputs is an object with non-negative integer blockHeight, non-empty string snapshotDigest, non-empty string thermodynamicHash, non-negative integer timestamp, and non-negative integer valuationSat; verificationKeyId is a non-empty string; data is a telemetry object or an array of telemetry objects. BEHAVIOR: Checks the snapshot digest, semantic claims, verification-key identifier, and Groth16 proof in memory, and updates bounded process-memory verification and lifecycle indexes without durable database storage. Rate limit: 60 req/min per IP shared across /mcp. RETURNS: Object containing valid, verifiedAt, and computationTimeMs; proof, snapshot, semantic, or key mismatches produce valid false. ERRORS: -32602 (Invalid Parameters) for malformed or missing input properties; HTTP 429 (Rate Limit) when the shared limit is exceeded. No 402 payment required.
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | Telemetry snapshot payload object or array of objects containing canonical state values. | |
| proof | Yes | Base64url-encoded Groth16/Poseidon BN254 proof string without padding. | eyJwaV9hIjpbIjEyMyIsIjQ1NiIsIjEiXX0 |
| publicInputs | Yes | Object containing five typed public statement inputs committed by the proof. | |
| verificationKeyId | Yes | SHA-256 verification-key identifier string formatted with 'sha256:' prefix. | sha256:4c095e183ea45a9d |
| Name | Required | Description |
|---|---|---|
| error | No | Human-readable verification error message when verification cannot validate the proof. Example: 'Verification key identifier does not match the proof.'. |
| valid | Yes | Whether the proof is valid and bound to the snapshot. |
| verifiedAt | Yes | ISO 8601 UTC date string format. |
| computationTimeMs | Yes | Server-side proof verification duration in milliseconds. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Although annotations already declare readOnlyHint and idempotentHint, the description adds valuable behavioral context: it checks snapshot digest, semantic claims, verification-key ID, and Groth16 proof in memory; updates only bounded process-memory indexes without durable database storage; and shares a 60 req/min per-IP rate limit across /mcp. This goes well beyond the annotations.
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 well-structured with clear PURPOSE/USAGE/BEHAVIOR/RETURNS/ERRORS sections and is front-loaded with the most important information. The PARAMETERS section is slightly redundant given the rich schema, but overall the organization helps an agent parse the definition quickly.
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 is complete for a tool of this complexity: it covers behavior, side effects, return value shape, failure semantics, error codes, rate limits, and even explicitly states no 402 payment is required. Combined with the output schema and annotations, nothing essential is missing for correct invocation.
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 input schema already describes every parameter in detail (100% coverage), so the baseline is 3. The PARAMETERS section summarizes the schema but does not add meaningfully new semantics beyond what the schema provides, such as types, minimums, or minLength constraints.
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 verb and resource: it 'Verifies a base64url-encoded Groth16/Poseidon BN254 proof against typed public claims and a telemetry snapshot.' This is far more specific than the title and clearly distinguishes the tool's core function from related proof 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?
The description gives explicit usage direction: 'Use to validate a proof against snapshot data' and an explicit exclusion with an alternative: 'Do NOT use to submit proof coordinates for optional Nostr publication; use proof.submit instead.' This fully resolves when to choose this tool over its closest sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PURPOSE: Retrieves Bitcoin Stratigraphy telemetry records by recent-day count, date, block height, or inclusive date and block ranges. USAGE: Use to fetch telemetry records and selected thermodynamic metrics. Do NOT use for catalog coverage discovery; use stratigraphy.list instead. PARAMETERS: days is an integer from 1 to 365; date is YYYY-MM-DD; blockHeight is a non-negative integer; metrics is a unique non-empty array containing target_multiplier, difficulty_epoch_progress, or thermodynamic_signal; startDate and endDate are inclusive YYYY-MM-DD bounds; startBlock and endBlock are inclusive non-negative integer bounds; limit is an integer from 1 to 100 with default 10. BEHAVIOR: Reads the local telemetry dataset without database writes. Only one of days, date, or blockHeight may be supplied, and none may be combined with range selectors; lower bounds cannot exceed upper bounds. Rate limit: 60 req/min per IP shared across /mcp. RETURNS: Object containing records, an array of matching telemetry entries, limited and optionally projected by metrics; an unmatched query returns an empty array. ERRORS: -32602 (Invalid Parameters) for invalid fields, selector combinations, bounds, or ranges; HTTP 429 (Rate Limit) when the shared limit is exceeded; dataset retrieval failures return an MCP tool error. No 402 payment required.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Calendar date selecting one telemetry day, formatted as YYYY-MM-DD in UTC. | 2026-09-09 |
| days | No | Count of recent days of telemetry to fetch (integer, 1-365). | |
| limit | No | Maximum number of records to return (integer, 1-100). | |
| endDate | No | Inclusive upper date bound formatted as YYYY-MM-DD in UTC (must be >= startDate). | 2026-09-18 |
| metrics | No | Array of specific telemetry metric key strings to project into returned records. | |
| endBlock | No | Inclusive upper block height bound (non-negative integer, must be >= startBlock). | |
| startDate | No | Inclusive lower date bound formatted as YYYY-MM-DD in UTC. | 2026-09-01 |
| startBlock | No | Inclusive lower block height bound (non-negative integer). | |
| blockHeight | No | Indexed Bitcoin block height selecting one telemetry record (non-negative integer). |
| Name | Required | Description |
|---|---|---|
| records | Yes | Validated telemetry records matching the requested range. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description reinforces this with 'Reads the local telemetry dataset without database writes' and adds substantial extra behavior: rate limiting (60 req/min shared), selector exclusivity, empty-array behavior on unmatched queries, and specific error codes. It also notes no payment is required, going beyond annotations.
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 lengthy but organized into clear labeled sections (PURPOSE, USAGE, PARAMETERS, BEHAVIOR, RETURNS, ERRORS) and front-loads purpose and usage. Every section carries distinct information; the verbosity is justified by the tool's complexity (9 parameters, multiple selectors, and constraints). It is not tautological or wasteful.
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 tool with this many parameters and selection modes, the description covers everything an agent needs: purpose, usage boundaries, parameter constraints, behavioral specifics, return shape, and error handling. The output schema exists, so return details are optional, but the description still clarifies the records array and projection behavior. No critical information is missing.
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 every parameter (100% coverage), so the baseline is 3. The description's PARAMETERS section mostly paraphrases the schema but adds the critical mutual-exclusivity rule among days/date/blockHeight and range selectors, plus the lower/upper bound constraint, which the schema does not convey. That extra semantic adds genuine value beyond schema.
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 opens with a specific verb and resource: 'Retrieves Bitcoin Stratigraphy telemetry records' and enumerates the exact selection keys (recent-day count, date, block height, or inclusive date and block ranges). It explicitly names the sibling tool it is not ('Do NOT use for catalog coverage discovery; use stratigraphy.list instead'), so an agent can unambiguously distinguish it from stratigraphy.list without inspecting schemas.
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 USAGE section explicitly states when to use this tool ('Use to fetch telemetry records and selected thermodynamic metrics') and when not to, naming the alternative (stratigraphy.list). It also details selector exclusivity rules and bound constraints, leaving no ambiguity about invocation conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PURPOSE: Lists complete Bitcoin Stratigraphy catalog coverage and available metric paths. USAGE: Use to discover snapshot, date, block, and metric coverage. Do NOT use for fetching telemetry records; use stratigraphy.get instead. PARAMETERS: No input properties are accepted. BEHAVIOR: Summarizes the local catalog without modifying records. Rate limit: 60 req/min per IP shared across /mcp. RETURNS: Object containing totalSnapshots, oldestBlock, newestBlock, availableMetrics, and dateBounds with startDate and endDate. ERRORS: -32602 (Invalid Parameters) when any input property is supplied; HTTP 429 (Rate Limit) when the shared limit is exceeded; catalog retrieval failures return an MCP error. No 402 payment required.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| dateBounds | Yes | Inclusive ISO date bounds of the available snapshots. |
| newestBlock | Yes | Highest block height in the deterministic daily snapshot index. |
| oldestBlock | Yes | Lowest block height in the deterministic daily snapshot index. |
| totalSnapshots | Yes | Total number of daily stratigraphy snapshots currently available. |
| availableMetrics | Yes | Telemetry metric paths available in each stratigraphy snapshot. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, but the description adds meaningful context: it 'summarizes the local catalog without modifying records,' the shared 60 req/min rate limit across /mcp, and specific error behaviors including HTTP 429 and -32602. No contradiction with annotations.
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 organized into labeled sections (PURPOSE, USAGE, PARAMETERS, BEHAVIOR, RETURNS, ERRORS) with every sentence earning its place. Critical routing information is front-loaded, and there is no redundant filler.
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 zero-parameter list tool, the description covers what the tool returns (totalSnapshots, oldestBlock, newestBlock, availableMetrics, dateBounds), rate limits, and error cases. The output schema exists to define return structure further, so no essential context is missing.
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?
With zero parameters, the rubric baseline is 4. The description reinforces that no input properties are accepted and clarifies that supplying any will trigger a -32602 error, which adds behavioral meaning beyond the schema's basic 'No input parameters required.'
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 verb ('Lists complete Bitcoin Stratigraphy catalog coverage and available metric paths') tied to a clear resource. It explicitly distinguishes itself from stratigraphy.get, so an agent can tell them apart.
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 explicitly says when to use the tool (discover snapshot, date, block, and metric coverage) and when not to (fetching telemetry records), naming the alternative tool stratigraphy.get. This leaves no ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
mesh.statusproof.groundproof.listproof.statusproof.submitproof.verifystratigraphy.getstratigraphy.list
Add one secure layer between your agents and this server.