Update a milestone by its unique identifier with partial updates; include only the fields you need to change.
Update a milestone. Update a milestone using its unique identifier.
This endpoint supports partial updates, so you only need to include the fields you want to change.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | ||
| path | Yes |
Changes observed during successful MCP inspections.
v1.0.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, and openWorldHint=true, covering the safety profile. The description adds valuable behavioral detail about partial updates, but it does not explain what makes this destructive, whether omitted fields are preserved or cleared, or what permissions are required — leaving gaps despite the lower bar set by 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 short and front-loaded with the purpose, but the first two sentences are redundant ('Update a milestone. Update a milestone using its unique identifier.'). It could be more concise and better structured, though no sentence is entirely wasted.
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 destructive mutation tool with a nested body, no output schema, and 0% top-level schema description coverage, the description is insufficient. It fails to name the identifier parameter, list updatable fields, clarify destructive behavior, or explain how partial updates interact with omitted fields. An agent would need to inspect the schema to invoke it correctly.
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 reported as 0% for the top-level parameters (path and body), so the description must compensate, but it says nothing about the milestoneId or any of the updatable fields (name, ends_at, description, milestone_type_id). The nested schema does contain field-level descriptions, which prevents the score from being lower, but the description adds no parameter meaning beyond the structured data.
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?
States a specific verb ('Update') and resource ('a milestone'), plus the mechanism ('using its unique identifier'). This distinguishes it from collection-level operations like get_milestone_collection, but it does not explicitly contrast with post_milestone (create) or delete_milestone, leaving sibling differentiation implicit.
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 explains that partial updates are supported and that only changed fields need to be included, which is useful usage context. However, it gives no guidance on when to choose this tool over alternatives like post_milestone or put_application, and no exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.