save work item

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

Beyond the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=true), the description adds a significant behavioral rule: after milestone approval, new work is refused until an accepted add_work_item suggestion. It also clarifies that unsaved work cannot be marked done, which is useful context. It does not explain the destructiveHint or what exactly gets destroyed or overwritten.

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 three short, front-loaded sentences that each convey distinct information: purpose, approval constraint, and dependency on marking work done. There is little waste, though the final sentence could be seen as slightly redundant given the first.

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?

The tool is a simple mutation with an output schema, so return values need not be described. However, the description does not make up for the complete lack of parameter documentation and leaves the destructiveHint unexplained, so it is only partially complete for an agent needing to call 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 0%, so the description must compensate for parameter documentation, but it only vaguely implies that a milestone is involved ('under a milestone'). It does not explain the roles of milestoneSetId, milestoneId, or title, nor how they relate to each other.

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 verb ('Save') and resource ('one piece of work under a milestone'), making the core action clear. It also implies a workflow relationship with 'so it can later be marked done,' but it does not explicitly name or contrast with sibling tools like save_deliverable or save_acceptance_criterion, so sibling differentiation is missing.

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 when to use the tool by linking it to later marking work done and noting that unsaved work cannot be marked done. However, it offers no explicit guidance on when to choose this over alternatives such as save_deliverable, and no conditions for use are spelled out beyond the implied workflow.

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