Skip to main content
Glama

post_update

Post progress, notes, interfaces, dependency needs, acknowledgements, and usage reports to a shared blackboard so agents can coordinate tasks and unblock waiting work.

Instructions

Post to the blackboard. kind progress: percent and text. note: a broadcast note (topic, refs). interface: publish an interface you own (name, text = its definition, path), which unblocks tasks waiting on it. need: say you are waiting for a task, interface or artifact (name; topic = task | interface | artifact), which blocks your task until it arrives. ack: acknowledge a directive (directive_id). usage (external workers only): report what you have used since your last report (tokens, usd, model); it is recorded as reported, not measured, and counts toward the budget.

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": {
      "execution_id": "<execution_id>",
      "agent_token": "<agent_token>",
      "kind": "<kind>"
    },
    "name": "post_update"
  }
}

Input Schema

NameRequiredDescriptionDefault
usdNousage: the cost in US dollars since your last report, if you know it (else it is priced from the table).
kindYes
nameNointerface: its name; need: the task, interface or artifact you wait for.
pathNointerface: where it lives in the repository.
refsNo
textNoRequired for every kind except usage.
modelNousage: the model that did the work.
ownerNoneed: expected publishing task.
topicNo
tokensNousage: tokens used since your last report.
percentNo
agent_tokenYesThe agent token join_execution returned (once).
directive_idNo
execution_idYesThe heads-down run (exe-…).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv2.0.0

TDQS

A4.3/5.0
Behavior4/5

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description discloses real side effects: publishing an interface 'unblocks tasks waiting on it' and a need 'blocks your task until it arrives'. It also candidly states that usage figures are 'recorded as reported, not measured, and counts toward the budget', which is valuable trust context. It does not address what happens on duplicate posting or whether a post can be amended or withdrawn, despite idempotentHint=false.

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 definition is front-loaded with the core action and then uses a consistent 'kind: fields' pattern, so it scans well despite being a single dense block. Every clause carries information, though the run-on formatting with repeated 'which...' relative clauses makes it harder to parse than a short bulleted list would be.

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 six-mode, 14-parameter mutation tool with no output schema, the definition covers every kind and its associated fields, plus the blocking/unblocking consequences and the reporting caveat. It does not explain what a successful post returns, error conditions, or how execution_id/agent_token relate to the call, though those are documented in the schema.

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?

With 14 parameters and 64% schema coverage, the description adds genuine meaning by mapping parameters to kinds: progress→percent/text, note→topic/refs, interface→name/text/path, need→name/topic, ack→directive_id, usage→tokens/usd/model. That conditional grouping is not derivable from the flat schema and is the most useful part of the definition. It leaves some ambiguity around `topic` values ('task | interface | artifact' for need) versus its free-string schema type.

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 definition opens with a concrete verb and resource ('Post to the blackboard') and then enumerates all six supported kinds, each with its own payload shape, so an agent knows exactly what this tool does and what each mode means. It is more specific than a name restatement and clearly separates the tool from generic messaging siblings.

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?

Each kind is framed as a situation: 'need' is for saying you are waiting and blocks your task, 'interface' unblocks tasks waiting on you, 'ack' acknowledges a directive, and 'usage' is explicitly gated to 'external workers only'. What's missing is any when-not-to-use guidance or reference to alternatives such as the sibling `usage` or `say` tools, which could otherwise be confused with the usage kind here.

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