Kellian

Arm or renew the maker dead-man: lapse cancels the wallet book

kellian_orderbook_heartbeat

Arm or renew the dead-man heartbeat for this wallet. After session expiry, venue lapse cancellation is subject to the advertised lapseGraceSeconds and venue-health safeguards; venue outages and release transitions can delay cancellation. Post with disarm=true to end the session without cancelling. Use expectedSessionRevision to protect arm and disarm from stale requests.

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": {
      "walletAddress": "<walletAddress>",
      "walletSignature": "<walletSignature>",
      "signatureTimestamp": "<signatureTimestamp>",
      "proofNonce": "<proofNonce>",
      "idempotencyKey": "<idempotencyKey>"
    },
    "name": "kellian_orderbook_heartbeat"
  }
}

Input Schema

Name	Required	Description
`disarm`	No
`chainId`	No	Compiled protocol release chain ID (Base 8453).
`proofNonce`	Yes	Required single-use nonce for the wallet proof. Fetch from POST /api/auth/nonce; consumed on verification so the proof cannot be replayed.
`ttlSeconds`	No	Session lifetime per beat. Post again before it elapses. Pick a TTL several times your beat interval so ordinary jitter cannot cancel your book.
`walletAddress`	Yes	Wallet address the heartbeat protects
`idempotencyKey`	Yes	Stable retry key. Reuse only with byte-equivalent tool arguments.
`walletSignature`	Yes	Action-bound wallet proof. Sign the canonical 'problee-mcp-auth:…' challenge (binds agent, apiKey, tool, scope, chain, resource, payloadHash, nonce, timestamp).
`signatureTimestamp`	Yes	Unix timestamp (seconds) used in the signed challenge message
`expectedSessionRevision`	No	Change only this observed revision. A missing session is revision 0. Successful arm or disarm advances once; only an already explicitly disarmed successor acknowledges an identical retry. Arm retries conflict. A different session returns HEARTBEAT_SESSION_CONFLICT; never rebase an exit.

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

AddedNov 5, 2026

TDQS

A3.6/5.0

Behavior3/5

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

Annotations already declare this is a non-read-only, non-idempotent mutation, so the bar is lower, but the description still adds real consequence information: failing to renew eventually cancels the wallet's book, subject to lapseGraceSeconds and venue-health safeguards, and outages or release transitions can delay that cancellation. That caveat is genuinely useful. It stops short of stating auth/permission requirements or what the response confirms on success.

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?

Four short sentences, front-loaded with the action, then the lapse caveat, then the two operative parameter behaviors. The only weak phrasing is 'the advertised lapseGraceSeconds', which points at a value the agent cannot see here.

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?

For a 9-parameter authenticated mutation with an output schema and annotations, this covers the essentials an agent needs: the consequence of not renewing, the timing caveat that cancellation may be delayed, the disarm exit path, and the concurrency guard. Missing pieces are minor, such as how the tool relates to the heartbeat-status sibling and where lapseGraceSeconds is discoverable.

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

Parameters3/5

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

Schema coverage is 89%, so most parameters are already well documented and the baseline is 3. The description adds framing rather than new mechanics: expectedSessionRevision is explained as a stale-request guard, and disarm as a way to end the session without cancelling, which supplements the bare boolean in the schema. It adds little for the remaining wallet proof parameters, which the schema already covers in depth.

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?

Specific verb (arm/renew) plus specific resource (the dead-man heartbeat for this wallet), and the title reinforces that lapse cancels the wallet book. It is clearly distinguishable from read-only siblings like kellian_orderbook_heartbeat_status, though it never names that sibling explicitly.

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?

Gives concrete conditional usage: post with disarm=true to end the session without cancelling, and use expectedSessionRevision to guard against stale requests. It implies the recurring-beat pattern without spelling out when to choose this over the status tool or a cancel_all_orders call, so it stops short of full alternative routing.

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

All Kellian tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?