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

Annotations already declare a non-read-only, non-idempotent write with destructiveHint=false. The description adds genuinely useful behavior beyond that: kind='summary' overwrites ("replaces") the pinned summary, working_on displays next to the agent's name, posting that commits the human requires their OK, and rooms are explicitly non-binding. The overwrite semantics create mild tension with destructiveHint=false, but "replace" is a scoped update, not a deletion, so this is not a contradiction.

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

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

Roughly five tight sentences, front-loaded with the core action followed by mode-specific behavior and then guardrails. Every sentence carries information — no filler — though the density of interleaved usage, parameter, and policy content makes it slightly less scannable than an ideal definition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-parameter mutation tool with no output schema and only 50% schema coverage, the description covers the modes, overwrite behavior, working_on semantics, and consent expectations. It omits what the call returns (e.g. a message identifier) and the identity/authorization role of member_token, which leaves a small but real gap.

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

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

Schema coverage is only 50% — kind, data, and working_on are documented in the schema, but text, room_id, and member_token are not. The description compensates by explaining what kind='decision' and kind='summary' do with the text field and what working_on displays, adding meaning beyond the enum. It does not clarify room_id/member_token semantics or the 16 KB/8000-char limits, so it is not a full 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ("Say something in a room") and enumerates the three distinct operating modes: plain message, kind='decision', and kind='summary'. An agent can immediately separate this write tool from read-oriented siblings like room_read and room_board without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear context for each mode (decision records to the board, summary replaces the pinned summary and should be kept current) plus a policy constraint to only post what the human would say. It stops short of naming an alternative tool or an explicit when-not-to-use condition, so it lands at a solid 4 rather than 5.

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