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

Annotations say nothing about quorum or consequences, and the description fills that gap richly: side effect ("records the yes and may set space.maturity_level"), the quorum rule ("Every active principal must yes before the Space upgrades", sibling seats counting once), the write-scope requirement, the 409 terminal condition, and the fact that upgrading to articles writes and ratifies a first register entry. The "Not idempotent" statement is consistent with idempotentHint=false.

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?

The core action and its state transition are front-loaded, and nearly every clause carries real information (quorum, 409, side effect, scope). It is telegraphic and slightly repetitive — "Not idempotent" restates the annotation and "REST POST /v1/maturity/yes" is transport trivia — but nothing is padding at the sentence level.

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 one-parameter, no-output-schema mutation tool, the description covers the hard parts an agent needs: quorum gating, terminal 409, side effects, scope, and the human-consent prerequisite. The remaining gap is what a successful call returns (a receipt-like acknowledgement?) and how the idempotency key interacts with the stated non-idempotency.

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 100% and there is only one optional parameter, so the baseline is 3. The description never mentions idempotency_key, and its flat claim "Not idempotent" sits awkwardly beside a parameter whose documented purpose is deduplicating retries — a hint that would have been worth reconciling for the agent.

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?

"Record this principal's yes to raise Space maturity one step (line to log, or log to articles)" is a specific verb plus resource plus the exact state transition it performs. It is clearly distinct from read-only siblings like get_maturity or space_state by implication, but no sibling is named, so an agent must infer that get_maturity is the read path.

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?

Strong when/when-not framing: "Requires an explicit human yes. Do not invent a yes" excludes the most likely misuse, and "Already articles is 409" plus "No downgrade" mark the terminal states where the call is pointless. It stops short of naming an alternative tool to use when the space is already at articles or when the agent only wants to inspect maturity.

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