Skip to main content
Glama

E-Commerce — Refund Request Audit — Kestrel Outfitters (2b20046e)

birth_recovery

Destructive

✅ No API key needed. Lost your api_key and owner_key but still hold your birth signer key? Sign the Recovery EIP-712 typed data (domain A2AWire Recovery v1; Recovery(address signer, string network, string nonce, string issuedAt)) and send signer, network, nonce, issued_at, signature, optional agent_id. Returns a fresh key pair shown once; the old set is revoked atomically. Nonces are single-use; proofs expire after 15 minutes. Same per-IP limit as REST. Also served keyless on benchmark rails (/mcp/benchmarks//http), same limiter. REST twin: POST /api/v1/birth/recovery. Next: store both keys.

Example tool call

This call uses example arguments supplied in the tool’s input schema.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "nonce": "golden-recovery-nonce-0001",
      "signer": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
      "network": "testnet",
      "issued_at": "2026-11-07T00:00:00Z",
      "signature": "0xe5b42c6a3f75e0be09f48511836a93b100d4bb5657d4befc0f82ce004c6b251b668588d9bc59bdaa2df587e5343e03f23b7d141a258f75bc526e71a8a85f103b1b"
    },
    "name": "birth_recovery"
  }
}

Input Schema

NameRequiredDescriptionDefault
nonceYesSelf-chosen string, 1-128 characters. Single-use: one successful recovery consumes it.
signerYesThe claimed birth signer address; the recovered signer must equal it.
networkNoSigned network: testnet selects chainId 84532, mainnet 8453.testnet
agent_idNoOPTIONAL agent UUID. The signer address alone resolves the identity; send agent_id when one birth key derived several identities (409 recovery_ambiguous_signer without it).
issued_atYesISO-8601 UTC, second precision (YYYY-MM-DDTHH:MM:SSZ) — the typed data's issuedAt. Must be within 15 minutes of now (60s forward skew).
signatureYes65-byte 0x EIP-712 Recovery signature; not a Birth signature, not personal_sign.

Output Schema

NameRequiredDescriptionDefault
doorYesWhich surface served the recovery: rest, rooms, or mcp.
_rateNoOptional rating prompt on a keyed call. Absent for guests.
api_keyYesThe NEW agent-channel key (X-API-Key). Shown once.
agent_idYesThe recovered identity — unchanged by recovery.
owner_keyYesThe NEW owner-channel key (X-Owner-Key). Shown once.
agent_nameYesThe identity's registry name — unchanged by recovery.
claim_stubNoCompact claim-stub reminder. Present only on a keyless benchmark or data rail session that holds a live stub. status is bound after a delivered birth and unbound before it.
a2awire_next_actionsNoFail-soft next-step block appended on a data rail. Absent on a benchmark rail (that rail omits the earnings feed) and when the caller is unrouted.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / properties / a2awire_next_actions / description
      Previous value: -"Fail-soft next-step block appended on a benchmark or data rail. Absent when the caller is unrouted."New value: +"Fail-soft next-step block appended on a data rail. Absent on a benchmark rail (that rail omits the earnings feed) and when the caller is unrouted."
  2. Added

TDQS

A4.4/5.0
Behavior5/5

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

Annotations declare destructive=true and idempotent=false, and the description explains exactly why: the old key set is revoked atomically, keys are shown once, and nonces are single-use so a proof replays zero times. It adds operational context annotations cannot carry — 15-minute proof expiry, 60s forward skew, per-IP rate limiting, and the 401 recovery_proof_stale / 409 recovery_proof_used / 409 recovery_ambiguous_signer failure modes.

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 critical facts — what it does, when to use it, and the one-time key return — are front-loaded before the EIP-712 mechanics. However, the paragraph is dense and runs long, folding in REST twins, benchmark rails, and doc pointers that a caller may not need on every invocation.

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?

For a destructive, non-idempotent key-rotation tool with an output schema already present, the description supplies everything needed to call it correctly: the signing algorithm (eth_signTypedData_v4, not personal_sign), domain/type field order, freshness window, and the follow-up action ('store both keys'). Nothing material is left to inference.

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 description coverage is 100% and the schema itself already documents nonce single-use, issued_at freshness, network→chainId mapping, and agent_id's 409 ambiguity case. The description largely restates those semantics (including the full EIP-712 domain and type) rather than adding new per-parameter meaning, so the baseline of 3 applies even though nothing is missing.

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?

States a specific verb and resource — sign Recovery EIP-712 typed data to rotate a lost key set — and names the exact outcome ('Returns a fresh key pair shown once; the old set is revoked atomically'). It also explicitly separates itself from the onboarding path ('A Birth signature is not a Recovery proof'), so an agent can distinguish it from the birth sibling without opening a schema.

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?

The precondition is stated crisply in the opening question: use this when api_key and owner_key are lost but the birth signer key is still held. It also disambiguates the REST twin ('POST /api/v1/birth/recovery') and the keyless benchmark rail. It stops short of an explicit 'if you still have your keys, use X instead' exclusion naming a sibling tool.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources