Creates a new version milestone in Backlog using a required name plus optional project, start date, description, and release due date.
Creates a new version milestone
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Version name | |
| projectId | No | Project ID | |
| startDate | No | Start date of the version | |
| projectKey | No | Project key | |
| description | No | Creates a new version milestone | |
| releaseDueDate | No | Release due date of the version |
Changes observed during successful MCP inspections.
v0.15.1v0.13.1v0.11.0Input schema / properties / organizationAdded value: +{
+ "description": "Optional organization name. Use list_organizations to inspect available organizations.",
+ "type": "string"
+}v1.0.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and idempotentHint=false, so an agent knows this writes and is not idempotent, yet the description never warns that repeated calls may create duplicate milestones nor describes permission requirements. For a non-idempotent mutation with no output schema, the description adds no behavioral context beyond 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?
A single front-loaded sentence with no filler, but it is under-specified rather than economical; there is room for one more sentence of routing guidance that would earn its place.
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 six-parameter, non-idempotent creation tool with no output schema, the description omits how the project is scoped (projectId vs projectKey), what happens on name collision, and what is returned. That is more than an agent can safely infer.
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% with six documented parameters, so the schema carries the semantics and baseline 3 applies. The tool description provides no additional meaning, such as when to use projectId versus projectKey or expected date formats.
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 phrase 'Creates a new version milestone' names a verb and a resource, so the basic action is legible, but it adds nothing beyond the tool name expanded into a sentence and never distinguishes this from update_version_milestone or get_version_milestone_list. It sits at the line between a clear purpose and a tautology.
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?
There is no statement of when to use this tool versus its siblings, no prerequisite (e.g. a project must be selected first), and no mention of the update/get counterparts in the sibling list. Usage is only inferable from the verb 'creates'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.