Create a durable work item with acceptance criteria, dependencies, risks, and open questions to track and coordinate tasks across isolated coding agents.
Create a durable work item with acceptance criteria and optional dependencies on existing work.
| Name | Required | Description | Default |
|---|---|---|---|
| risks | No | ||
| dependsOn | No | ||
| objective | Yes | ||
| sourceSession | No | ||
| acceptanceCriteria | Yes | ||
| unresolvedQuestions | No |
Changes observed during successful MCP inspections.
v0.3.2Input schema / properties / dependsOnAdded value: +{
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}v0.2.18Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a mutation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds 'durable' (implying persistence) and mentions dependencies on existing work, which suggests validation. However, it doesn't detail side effects, authorization requirements, or what happens if dependencies are missing. Given the annotations cover the safety profile, the description adds some value but not rich behavioral context.
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, front-loaded sentence with no wasted words. It states the core purpose immediately and then adds the key qualifiers (acceptance criteria, optional dependencies).
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 create tool with six parameters, no output schema, and minimal annotations, the description is too thin. It doesn't state what the tool returns (e.g., created item ID), what happens on failure, or any constraints on dependencies (e.g., they must already exist). An agent would need more information to call this correctly, especially given the optional fields are only partially hinted at.
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. It mentions acceptance criteria and optional dependencies, mapping to acceptanceCriteria and dependsOn, but leaves risks, sourceSession, and unresolvedQuestions unexplained. With six parameters and no schema descriptions, this is insufficient for an agent to know how to populate all fields correctly.
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 clearly states a specific verb ('Create') and resource ('durable work item'), and highlights key attributes (acceptance criteria, optional dependencies). This distinguishes it from sibling tools like work_list, work_get, and work_verify without needing to inspect schemas.
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 context is clear: this is the creation tool for work items. It doesn't explicitly state exclusions or alternatives, but the sibling names make the purpose obvious. A small gap is not mentioning when to prefer work_update or work_verify instead, but for a create tool the usage is straightforward.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.