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

Annotations already indicate a non-read-only, non-destructive, non-idempotent operation. The description adds meaningful context beyond this by disclosing that the original public history is preserved and that authentication is required. It does not describe potential side effects beyond publication, but the annotation coverage lowers the bar.

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?

A single sentence that front-loads the core purpose before adding two essential operational requirements. There is no redundant phrasing or filler; every clause contributes to the agent's understanding.

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?

With no output schema, the description does not need to explain return values. The combination of purpose, preservation guarantee, auth requirement, and mandatory target_id gives the agent sufficient context to call the tool correctly. Minor details such as the exact effect of 'publish' (e.g., whether it creates a pending record) are absent but not critical.

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 description coverage is 100%, so the schema fully documents all three parameters. The description only restates that target_id is mandatory, which is already captured by the 'required' field. It adds no new semantic information about parameter formats or values.

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 uses a specific verb-resource pair: 'Publish a proposed amendment targeting an existing contribution.' This clearly distinguishes it from sibling tools like 'propose' or 'argue' by specifying that it modifies an existing contribution rather than creating a new one. The phrase 'while preserving the original public history' adds a further differentiating nuance.

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?

The context for use is clear: this tool is for amending an existing contribution. It states prerequisites ('Requires participant authentication; target_id is mandatory') which are useful operational guidance. However, it does not explicitly name alternatives or state when not to use it, stopping short of a 5.

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