aziel-runtime

Refresh QNM rollup presence

mesh_heartbeat

Refresh a node's 5-minute TTL to keep it live on the mesh roster. Requires node_id from mesh_join; confirm or dry_run required.

Instructions

Refresh one existing node's 5-minute QNM TTL (POST /v1/mesh/heartbeat) — not a first join. Use this when you already have a node_id from mesh_join and transmission radios are LIVE. Do not use it for first-time registration or dropping the node; use mesh_join or mesh_leave instead. Write: refreshes the strict 5-minute TTL (not idempotent). Miss the window and the node is dropped from the live roster. Radios off refuses MESH-OFF. Unknown or expired node_id refuses MESH-UNKNOWN-NODE — join again; no account resurrection. node_id is required. presence may replace the class (live|locked|isolated). Optional tip_hash and prev are 64 hex only (Split the wires + REHEAL: presence + tip hash; no body/diff/vote-to-fix). OPERATOR-OVERRIDE 2026-09-17 armed neighbor_heal. Mutation requires confirm=true (runtime gate) or dry_run=true (preview only, no write). confirm and dry_run stay optional on inputSchema.required. Returns updated presence and TTL. Body on this plane refuses MESH-NO-BYTES. Same prev + two tips refuses MESH-EQUIVOCATION. Vote-to-fix still refuses MESH-NO-NEIGHBOR-HEAL.

Input Schema

TableJSON Schema

Name	Required	Description
`prev`	No	Optional 64-hex prev the receiver already holds. Same prev + a different tip_hash isolates this node (MESH-EQUIVOCATION).
`confirm`	No	Documented confirmation flag. Optional in inputSchema.required (connector refresh must not break). tools/call still refuses MCP-CONFIRM-REQUIRED when confirm is missing or false unless dry_run=true (preview, no write).
`dry_run`	No	Optional preview flag. When true, return a would-mutate preview and do not write. Alternative to confirm=true. Does not mutate.
`node_id`	Yes	Required node id returned by mesh_join.
`presence`	No	Optional replacement presence class. Other values refuse MESH-BAD-INPUT.
`tip_hash`	No	Optional 64-hex tip hash on the fast tick. Fixed-size. No body. Split the wires.

Output Schema

TableJSON Schema

Name	Required	Description
`code`	No	FragGate or fabric code when present: FG-OK, FG-HALLUC-TOOL, FG-STUB, FG-LOCAL-ONLY, FG-UNKNOWN-OP, FG-GATE-REFUSE, FG-LAMB-REFUSE, or a module refuse such as MESH-* / AKM-*.
`door`	No	Door name. The public door is fraggate.
`ran_in`	No	Execution locale (for example aziel-runtime) when present.
`result`	No	FragGate body: ok, code, door, slug, op, engine_digest, ran_in, provenance, refusal, limitations, receipt, plus the engine result. Unknown names refuse FG-HALLUC-TOOL; stubs refuse FG-STUB.
`status`	No	HTTP-like status when present on wrappers (200 ok; 400+ error / refuse).
`display`	No	Human-facing envelope. Show title and summary, then take the next input.
`receipt`	No	Optional receipt, ledger tip, or TemporalLock/ForgeReceipts exit when the door stamped one.
`refusal`	No	Explicit refuse object, code, or message when the door or engine refused.
`engine_op`	No	Resolved engine op when present (often inside result).
`ledger_tip`	No	Ask/refuse ledger tip when the door stamped one.
`provenance`	No	Provenance / input packet when the pipeline attached one.
`session_id`	No	Raw session id when session plumbing was used. Hidden unless the user asked for the chain.
`engine_slug`	No	Resolved engine slug when present (often inside result).
`limitations`	No	Capability limitations or Remain-OFF notes when present.
`engine_digest`	No	64-hex engine_digest when a true in-process engine ran (often inside result).

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv2.0.2Sep 18, 2026

changedInput schema / description

Previous value: -"node_id is required. Missing node_id refuses MESH-BAD-INPUT."New value: +"node_id is required. Missing node_id refuses MESH-BAD-INPUT. Mutation requires confirm=true or dry_run=true."

addedInput schema / properties / confirm

Added value: +{
+  "description": "Documented confirmation flag. Optional in inputSchema.required (connector refresh must not break). tools/call still refuses MCP-CONFIRM-REQUIRED when confirm is missing or false unless dry_run=true (preview, no write).",
+  "type": "boolean"
+}

addedInput schema / properties / dry_run

Added value: +{
+  "description": "Optional preview flag. When true, return a would-mutate preview and do not write. Alternative to confirm=true. Does not mutate.",
+  "type": "boolean"
+}

Changed2 schema fields changedv2.0.1Sep 14, 2026

addedInput schema / properties / prev

Added value: +{
+  "description": "Optional 64-hex prev the receiver already holds. Same prev + a different tip_hash isolates this node (MESH-EQUIVOCATION).",
+  "type": "string"
+}

addedInput schema / properties / tip_hash

Added value: +{
+  "description": "Optional 64-hex tip hash on the fast tick. Fixed-size. No body. Split the wires.",
+  "type": "string"
+}

Addedv1.6.2Sep 12, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false), the description discloses concrete behavioral traits: the refresh is not idempotent, a missed 5-minute window drops the node, radios-off refuses MESH-OFF, expired node_id refuses MESH-UNKNOWN-NODE with no account resurrection, mutation requires confirm=true or dry_run=true, and various body/equivocation/heal refusals. This is rich, specific behavioral context.

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 description is long but densely informative, with purpose and usage front-loaded in the first two sentences. The later sentences cover refusal conditions and mutation gates that are essential for correct invocation, so they earn their place. Some domain jargon ('Split the wires', 'REHEAL', 'armed neighbor_heal') is unexplained, which slightly reduces clarity, but the overall structure is logical and purposeful.

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?

Given the tool has 6 parameters, critical mutation semantics, and a complex refusal-code surface, the description covers everything an agent needs to invoke it correctly: prerequisites, alternatives, mutation gates, per-parameter constraints, and failure behavior. An output schema exists, so the absence of a return-format explanation is not a 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 description coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: node_id comes from mesh_join, presence replaces the live|locked|isolated class, tip_hash is on the fast tick with no body, and same prev plus two tips causes MESH-EQUIVOCATION. It also clarifies that confirm/dry_run remain optional in the schema but are runtime-required for mutation, which materially improves parameter understanding.

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 states a specific verb and resource: 'Refresh one existing node's 5-minute QNM TTL (POST /v1/mesh/heartbeat) — not a first join.' This clearly distinguishes it from the sibling tools mesh_join and mesh_leave by explicitly saying what it is not, so an agent can select it correctly 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.

Usage Guidelines5/5

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

The description gives explicit when-to-use guidance: 'Use this when you already have a node_id from mesh_join and transmission radios are LIVE.' It also names exclusions and alternatives: 'Do not use it for first-time registration or dropping the node; use mesh_join or mesh_leave instead.' This fully covers the selection decision.

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