Skip to main content
Glama

KanbanMCP

Check in on a claim

heartbeat
Idempotent

Keeps your claim alive, a reading claim too. Call it about every 5 minutes. A comment with your runId counts too. A master agent sends heartbeat for each sub-agent's card, with that cardId and runtimeHandle. Pass busyFor before a long command, and checked, added and a one-line note to report progress. In a batch, one beat keeps every card.

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": {
      "cardId": "<cardId>"
    },
    "name": "heartbeat"
  }
}

Input Schema

NameRequiredDescriptionDefault
noteNoOne line on your progress.
addedNoNew checklist items.
prUrlNoPull request URL (https), saved on the card you hold.
runIdNoRun id from claim_next.
cardIdYesCard id, number (12) or key (WEB-12).
boardIdNoBoard id or slug.
busyForNoMinutes a long command will take.
checkedNoChecklist items you finished: positions (from 1) or texts.
personaNoThe persona to act as.
runtimeHandleNoA short name for this agent or sub-agent. Use a different one for each sub-agent.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4/5.0
Behavior4/5

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

Annotations declare non-read-only, idempotent, non-destructive, closed-world. The description adds the crucial liveness requirement (heartbeat every ~5 minutes), the busyFor signaling pattern for long commands, and multi-agent semantics where a master beats for each sub-agent's card. It stops short of stating what happens when a heartbeat is missed (claim expiry), which is the key operational risk.

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?

Front-loads the core purpose and packs dense operational guidance into a handful of short fragments. Some clauses ('a reading claim too') are terse to the point of ambiguity, but there is little wasted text for a 10-parameter lifecycle tool.

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 10-parameter, no-output-schema keepalive tool spanning single-agent, batch, and master/sub-agent modes, the description covers cadence, progress reporting, and batching adequately. The main gap is the consequence of failing to beat, which an agent needs to prioritize the call.

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 adds real usage meaning beyond the schema: when to use busyFor, that checked/added/note report progress, that runId doubles as a comment, and that runtimeHandle differs per sub-agent in a batch. This goes past simple field restatement.

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?

The opening 'Keeps your claim alive, a reading claim too' states a specific verb and resource and is clearly distinct from siblings like claim_next (acquire) and release (release). The phrase 'a reading claim too' is cryptic, but the core keepalive semantics are unambiguous.

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 explicit cadence ('about every 5 minutes'), a trigger for the busyFor parameter ('before a long command'), and an alternative path ('a comment with your runId counts too'). It also covers the batch case ('one beat keeps every card'), though it does not name sibling tools directly.

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