ai-agent-channel

send_message

Send role-addressed messages to coordinate coding-agent sessions, with tracked obligations, proposals, replies, and work statuses.

Instructions

Send a message. 'to' is one role, a LIST of roles, or '' on its own (every other role); sending to yourself is refused. A multi-recipient message is ONE message (one body, id, thread and set of acknowledgements; read state is per recipient). Only kind='proc' and kind='status' may go to several roles on their own; a reply (reply_to) of another kind to a multi-recipient message may go to several roles, but only to that message's sender and recipients. action_required=true is refused for several recipients (a debt has one owner). 'addenda' ({role: text}) adds a per-recipient tail, seen as 'addendum'. 'kind' is bug/feat/proc/status/question/answer ('answer' with reply_to); 'work_status' is proposed/in_progress/done_local/needs_you/done/blocked, moved later with set_work_status. A formal decision → kind='proc' (surfaces in awaiting_ack); work to do → action_required=true (surfaces in open_obligations, closed via resolve_message). kind='proc' REQUIRES two explicit answers (omitting either is refused, null is valid): (1) 'pin_key' — the pin this proposal changes, or null. A proposal with a pin_key is found by list_messages(pin_key=...), retired by the pin_set it settles, and refused while another round on that key is open. 'voters' then declares whose 'agree' pin_set will require: '' or a list of roles; others still receive it and may vote but do not block. In a hosted channel a pin proposal must be addressed to every other role and 'voters' is required; in stdio mode neither is enforced, and without 'voters' pin_set accepts a fresh 'agree' from any other role. (2) 'about_message_id' — the message this one is about (a nudge), or null. A nudge stays out of awaiting_ack and is retired when its target is voted on, superseded or deleted. decision_requested=false opens a proposal for reading, not voting (it stays out of awaiting_ack). 'topic' is at most 80 characters; addenda values at most 4000. For a body too long for one call, use upload_content + seal_content and pass body_ref= instead of 'body'. Returns {id, created_at}, plus 'recipients' and 'voters' when set.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`to`	Yes
`body`	No
`kind`	No
`topic`	Yes
`voters`	No
`addenda`	No
`pin_key`	No
`body_ref`	No
`reply_to`	No
`work_status`	No
`action_required`	No
`about_message_id`	No
`decision_requested`	No

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, the description carries full disclosure burden and meets it: it states refusals (sending to self, action_required with multiple recipients, proc without both explicit answers), validation limits (topic ≤ 80, addenda ≤ 4000), multi-recipient single-message semantics, pin/nudge retirement behavior, and the return shape {id, created_at}. No contradictions exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Information density is high and every sentence earns its place, but the delivery is a single dense run-on paragraph with no line breaks, bullets, or section headers. Front-loading is good ('Send a message'), yet the wall-of-text format makes the critical validation rules hard to scan. Appropriate length, poor structure.

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 tool with 13 parameters, complex cross-field validation, and subtle state-machine behavior, the description is remarkably complete. It covers edge cases, refusal conditions, hosted-channel vs stdio mode differences, and return values (which the output schema also documents). Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, and the description fully compensates. Every parameter is explained: 'to' (role/list/'*'), 'kind' with its enum values, 'work_status' with its six states, 'pin_key', 'voters', 'about_message_id', 'addenda', 'body_ref', 'action_required', and 'decision_requested' — including constraints and interplay between them.

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?

Opens with a specific verb+resource ('Send a message') and immediately establishes scope through role semantics. The description makes the tool's purpose unmistakable and clearly distinguishes it from siblings like upload_content, set_work_status, and mark_read by explicitly referencing them and their different functions.

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?

Provides extensive when-to-use guidance: explains which kinds allow multi-recipient sends, when action_required is refused, when decision_requested should be set false, and points to alternatives like upload_content + seal_content for long bodies and set_work_status for later status changes. This exceeds mere context and gives actionable selection criteria.

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