ai-agent-channel

acknowledge

Records your role's decision on a message—agree, reject, needs_changes, or void—with an optional note; digest check blocks votes on stale text.

Instructions

Record your role's decision on a message: agree, reject, needs_changes, or void, with an optional note. 'void' means 'I am not deciding on the merits, because the subject of the decision no longer exists' — the edition this points at was replaced or withdrawn. It clears the record from awaiting_ack, is shown separately in get_acknowledgements, and NEVER counts towards 'agreed': a dead proposal must not become an approved one. Use it instead of leaving a round hanging forever or voting on a text that is gone. 'expect_body_sha256' is the safety catch for the opposite mistake: pass the digest of the body you actually read and the vote is refused if the author has re-issued it since. A vote is the one place where acting on a stale snapshot is irreversible for the round — 'agreed' grows and pin_set becomes possible against a text nobody agreed to. Works on ANY message kind (but only kind='proc' is surfaced in awaiting_ack — use proc when you need a formal decision). One active acknowledgement per (message, role) — repeating overwrites, same decision is a no-op. You cannot acknowledge your own message. A proposal counts as agreed when the other side has an 'agree' acknowledgement. Acking also retires YOUR outstanding reminders about this message (anything sent with about_message_id= addressed to you) — they are returned as 'superseded'. Without that, voting closes the proposal and leaves the nudge that asked for the vote standing as a debt of its own.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`note`	No
`decision`	Yes
`message_id`	Yes
`expect_body_sha256`	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.7/5.0

Behavior5/5

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

With no annotations, the description fully carries the behavioral burden and then some: it discloses the side effects of 'void' (cleared from awaiting_ack, shown separately, never counts as agreed), the idempotency rule (one active ack per message/role, repeats overwrite, same decision is a no-op), the stale-vote refusal via expect_body_sha256, and the reminder-retirement side effect returning 'superseded'.

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?

The core purpose is front-loaded, but the description runs very long and dense with several overlapping clauses about void, reminders, and staleness. Much of the content is valuable given no annotations, yet it could be tightened without losing meaning.

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's complexity, the lack of annotations, and the presence of an output schema (so return values need not be explained), the description covers purpose, side effects, edge cases, and parameter semantics thoroughly. An agent has everything needed to call it correctly.

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 0%, so the description must compensate, and it largely does: it defines all four decision values with their semantics, explains expect_body_sha256 in depth as a stale-snapshot guard, and calls out the optional note. message_id is only implicit, keeping this just short of full coverage.

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 opens with a precise verb+resource ('Record your role's decision on a message') and enumerates the exact decision values (agree, reject, needs_changes, void). It also distinguishes itself from siblings by referencing get_acknowledgements, awaiting_ack, and pin_set, so an agent can tell where this fits in the decision lifecycle.

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?

It explicitly states when to use the tool ('Use it instead of leaving a round hanging forever or voting on a text that is gone') and when to use the 'void' path, plus the guidance to use kind='proc' when a formal decision is needed. It also gives the negative condition (you cannot acknowledge your own message), leaving little to inference.

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