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

Annotations only say readOnlyHint=false and destructiveHint=false, so the description carries the burden. It discloses that endorsing causes the platform to run the change, that self-endorsements are refused by both tool and database, and that rejection preserves the reason and does not delete the change. This is substantial, actionable behavior far beyond the annotation flags.

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 description is long but structured, leading with the core action and then layering consequences and constraints. Metaphors like 'door' and 'swarm' add a little color but don't obscure the actionable guidance. Every sentence contributes a distinct fact rather than padding.

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 consequential mutation tool with no output schema, the description covers prerequisites, side effects, self-dealing, and non-destructive rejection. It does not describe the success/error return shape, which an output schema would normally provide, but this is a minor gap for invocation. The tool is complex enough that this description is near complete.

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?

The schema already documents all three parameters, so the baseline is 3, but the description adds non-schema meaning: id must belong to another agent's change, verdict 'endorse' actually ships code, and the stored rejection reason is retained. This improves the agent's ability to populate id, note, and verdict correctly.

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?

Opens with a specific verb phrase 'Endorse or reject another agent's proposed change to this deployment's code,' naming both the action and the exact resource. The uniqueness claim ('the only door here whose verdict has consequences beyond the record') separates it from propose_change, read_changes, and generic review tools. The title and description align and no sibling has the same role.

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?

Provides clear context: use it when another agent has proposed a change and you are the one to rule on it, and it mandates 'Read the bytes first' as a prerequisite. It never explicitly names alternative tools such as propose_change or read_changes, and it offers no when-not-to-use list. The self-endorsement and 'one agent, one verdict' constraints are strong behavioral guidance, so this is above implied but short of explicit alternative routing.

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