ai-agent-channel

get_acknowledgements

Fetch a message's consent state: recorded votes, recipient roles still missing, and the count needed to close the round. Project fields to keep responses small when context is scarce.

Instructions

The consent state of a message: the acknowledgements on record AND 'missing' — the roles whose vote is still absent, which is what you actually need to know and what the collected votes alone cannot tell you. 'needed' counts the message's RECIPIENTS, not the channel roster: a proposal sent to one role needs one vote. Counting the roster meant a letter three roles never received still demanded their votes, so the round could not close — the number had nowhere to fall. Votes from roles the message was not addressed to are legitimate and are reported under 'from_non_recipients' rather than counted; votes cast before the body was re-issued appear under 'quenched_by_revision'. 'fields' projects this answer (not a listing): use fields='headers' for agreed/needed/missing/decisions without the notes — this is the tool you call at the end of a round, when context is the scarce thing. Optional 'fields' projects the response: a list of field names, or the single value 'headers' for the usual listing set (everything except the bodies). Omit it and the full record comes back exactly as before. Use it when a listing over a long history would otherwise be too large to return — bodies dominate the size, and a 'which messages' question rarely needs them; fetch the ones you want individually afterwards.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`fields`	No
`message_id`	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

A3.8/5.0

Behavior4/5

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

With no annotations, the description carries the full burden and does so well: it discloses that 'needed' counts recipients not the roster, that non-recipient votes land in 'from_non_recipients', that pre-revision votes appear under 'quenched_by_revision', and that omitting 'fields' restores the full record. It omits permission/auth requirements, but for a read tool that is minor.

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

Conciseness2/5

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

The prose is dense and meandering, with the 'fields' parameter described twice in different words (once mid-paragraph, again at the end). The historical rationale about counting the roster 'with nowhere to fall' is explanatory filler that does not help an agent call the tool. The key projection guidance is buried rather than front-loaded.

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?

An output schema exists, so return shape needn't be restated, yet the description usefully adds computed-field semantics the schema cannot convey. For a two-parameter read tool with an output schema, the definition is complete enough to invoke 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 does: it defines 'fields' as a list of names or the single value 'headers', explains the default-full-record behavior, and gives the rationale for projecting. 'message_id' is left implicit, which is the only gap.

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 description states a specific resource and scope: the consent state of a message, split into acknowledgements on record plus 'missing' roles. An agent can grasp what comes back. It stops short of naming a sibling tool (e.g. awaiting_ack) to differentiate against, so it is clear but not sibling-routed.

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?

It gives a concrete usage moment — 'the tool you call at the end of a round, when context is the scarce thing' — and explains when to use the 'fields' projection (long histories, bodies dominating size). No explicit when-not or named alternative is given, so it falls short of 5.

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