update_milestone

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

The description adds value beyond the annotations by clarifying the 'reversible open/closed state' (telling the agent the state change is reversible, so toggling is safe) and explicitly stating the tool cannot delete milestones, which clarifies the destructive boundary. The idempotentHint=true annotation is consistent with an update operation. It does disclose the key behavioral characteristics without contradicting anything in the annotations.

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 two sentences with zero wasted words. The first sentence conveys the purpose and scope of updates, and the second sentence explicitly sets the boundary (cannot delete). Every word adds value, and the information is front-loaded with the key verb and resource.

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 an update tool with 8 parameters, the description covers the main semantics of the risky/ambiguous parameters (state reversibility, dueOn UTC format) and sets clear expectations about scope. It doesn't explain return values, but there's no output schema so this is a minor gap. The tool is relatively straightforward, and the combination of annotations (idempotentHint=true, destructiveHint=false) plus description provides reasonable completeness.

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 description coverage is only 13% (essentially just the repository field), so the description must compensate. It does by listing the updatable fields (title, description, state, dueOn) and clarifying that due date is in UTC format ('UTC due date'). This provides meaningful guidance beyond the raw schema, though it doesn't elaborate on the specific constraints of each field beyond what the schema enforces.

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 ('Update') with a clear resource ('existing milestone') and enumerates the modifiable fields: title, description, reversible open/closed state, and UTC due date. It also explicitly distinguishes the tool from deletion by stating 'This tool cannot delete milestones.' This clearly differentiates it from sibling tools like create_milestone and update_release.

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 description implies the tool is for updating existing milestones by naming the specific fields that can be changed, and explicitly states it cannot delete milestones, which guides the agent away from using this tool for deletion. However, it doesn't explicitly name alternative tools for creating milestones, and doesn't specify when NOT to use this tool beyond the deletion caveat.

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