Github Update Milestone

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

The description discloses a critical behavioral trait: 'Only the fields supplied are sent, so closing one leaves its title and due date alone.' This partial-update behavior goes beyond what annotations (readOnlyHint=false, destructiveHint=false) provide and is valuable for correct invocation. It does not contradict any annotations. It does not cover other aspects like error handling, but the key nuance is disclosed.

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 a single, efficient sentence that front-loads the core action ('Changes a milestone in place') and immediately adds the key behavioral note. There is no wasted wording or redundancy with the schema or annotations.

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 simple update tool, the description covers the essential behavior (partial update) and the fact that it modifies an existing milestone. It doesn't explain how the milestone is identified (via title and repo), but that is provided in the schema. Since an output schema exists, return values are not needed. The description is adequate, though it could mention the requirement that the milestone already exists.

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 description adds meaning to parameters like state, title, and due_on by explaining that only supplied fields are updated. This partial-update context is not evident from the schema alone and helps agents understand how parameters interact. Schema coverage is 71%, so the description partially compensates for the gap, though it doesn't detail every parameter.

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 action: 'Changes a milestone in place.' This is a clear verb+resource pair and the phrase 'in place' distinguishes it from creation. However, it doesn't explicitly mention that the milestone is identified by its title, which is a key differentiator from create_milestone, though the name implies update.

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 usage (modifying an existing milestone) via 'changes a milestone in place,' but it does not explicitly contrast with alternatives like github_create_milestone or github_delete_release. There is no guidance on when not to use it or mention of prerequisites such as the milestone already existing. Usage is implied rather than explicit.

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