ai-agent-channel

set_work_status

Update the work status of an existing message as it moves through its lifecycle, without sending a new message. Sender or recipient can change status, with peer confirmation for done.

Instructions

Update the work_status of an EXISTING message as the work moves through its lifecycle — do not send a new message just to change status. Either party (sender or recipient) may call this; third roles are rejected. Transitions: any value can be set from any state, with ONE exception — 'done' requires the current status to be 'done_local' and must be set by the OTHER role than whoever declared done_local. Semantics: 'done_local' = the executor finished on their side; 'done' = completed AND confirmed by the other role (peer confirmation — the channel cannot verify merges or production). 'done' is not a dead end: if an issue resurfaces, move the status back (audited) or reopen the obligation. 'needs_you' is relative to the SETTER: it always means the ball is at the other participant than whoever set it (it surfaces in THEIR channel_status). Re-setting the current value by the other role is a real, audited transition (it moves the ball back); by the same role it is a no-op. For 'blocked' on another message, pass blocked_by=; the blocker MUST be an unresolved action_required message (otherwise nothing could ever resolve it and your task would block forever — rejected). Blocked on something without a resolvable message (human decision, external run) — use 'blocked' with a note and lift it manually. Every transition is logged to message_history.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`note`	No
`blocked_by`	No
`message_id`	Yes
`work_status`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 12, 2026

TDQS

A4.8/5.0

Behavior5/5

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

With no annotations provided, the description carries the full burden and does so: it discloses role-based authorization, the peer-confirmation model behind 'done', that the channel cannot verify merges/production, reversibility (status can move back, audited), and that every transition is logged to message_history. These are non-obvious behavioral traits an agent could not infer from the schema.

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-loaded with the core action and the send_message exclusion, and every sentence conveys distinct rules rather than restating the name. It is a dense single paragraph that would scan better with light grouping, but there is little waste.

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 stateful mutation tool with no annotations and 0% schema coverage, the description covers authorization, legal transitions, the done/peer-confirmation nuance, blocking semantics, reversal, and audit logging. Output schema exists, so return values need not be explained; nothing essential for correct invocation appears missing.

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 0%, so the description must compensate; it explains blocked_by's referent and hard constraint in detail, and describes the semantic weight of work_status values ('done_local' vs 'done', 'needs_you' being relative to the setter). It does not explicitly define the 'note' parameter or message_id format, leaving slight gaps, so 4 rather than 5.

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 ('Update the work_status of an EXISTING message') and immediately distinguishes itself from the nearest sibling by warning 'do not send a new message just to change status.' Combined with the transition semantics, an agent can tell exactly what this does versus send_message or resolve_message.

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?

Explicitly states who may call it (either party, third roles rejected), the transition rules including the one exception for 'done', and routes the blocked_by case ('the blocker MUST be an unresolved action_required message') versus the non-resolvable case (use 'blocked' with a note). This is unusually complete when-to-use guidance with exclusions.

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