nexus_update_milestone

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

With no annotations provided, the description carries full burden for behavioral disclosure but offers minimal information. 'Update a milestone' implies a mutation operation but doesn't specify permissions required, whether changes are reversible, rate limits, or what happens to unspecified fields. The description doesn't mention that only milestoneId is required while other fields are optional partial updates, leaving critical behavioral aspects undocumented.

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 extremely concise at just three words, which could be appropriate if it contained sufficient information. However, this brevity results in under-specification rather than efficient communication. While front-loaded, the single sentence fails to convey necessary context, making the conciseness more of a deficiency than a virtue.

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 mutation tool with 7 parameters, no annotations, and no output schema, the description is severely incomplete. It doesn't explain the tool's purpose beyond the obvious, provides no behavioral context, and offers no guidance on usage. The agent would need to infer everything from the parameter schema alone, which is insufficient for safe and effective tool invocation in a complex system with multiple related tools.

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 already documents all 7 parameters thoroughly. The description adds no parameter information beyond what's in the schema - it doesn't explain relationships between parameters (like addProjects/removeProjects being mutually exclusive operations) or provide usage examples. With complete schema documentation, the baseline score of 3 is appropriate.

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 'Update a milestone' is a tautology that restates the tool name without adding meaningful context. It lacks specificity about what aspects of a milestone can be updated or how this differs from sibling tools like nexus_update_milestone_task or nexus_update_project. The description fails to distinguish this tool from other update operations in the system.

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?

No guidance is provided about when to use this tool versus alternatives. The description doesn't mention prerequisites, appropriate contexts, or relationships with sibling tools like nexus_update_milestone_task (for task-level updates) or nexus_list_milestones (for viewing). Without any usage context, an agent cannot make informed decisions about tool selection.

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