complete_task

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains that notes is a terse frontmatter one-liner and that a fuller summary should be written into the '## Completion Notes' body section separately. It also clarifies that the tool works from any status, which proactively prevents the agent from assuming a prerequisite. It does not detail side effects beyond status change, but it covers the key behavioral nuances.

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?

Three sentences, zero filler. The primary purpose is front-loaded, followed by parameter nuance and workflow guidance. Every sentence earns its place without redundant restatement of the tool name or schema.

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 simple two-parameter tool with an output schema present, the description is complete: it defines the action, explains the notes parameter, clarifies the optional prerequisite, and tells the agent the next step. No critical context for correct invocation is missing.

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 adds meaningful semantics for notes by specifying it is a 'terse one-liner for the frontmatter field' and directing fuller details elsewhere. task_id is left to inference, but its purpose is obvious from the name and the required-parameter context.

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 opens with a specific verb and resource: 'Mark a task as completed with notes on what was done.' It clearly distinguishes this from sibling workflow tools by framing itself as the middle step between start_task and verify_task, so an agent can identify its role without ambiguity.

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 provides explicit sequencing context: 'Ideally call start_task first, but this works from any status' and 'After this, call verify_task with evidence to finalise.' This tells the agent when in the workflow to use the tool, but it does not explicitly state when not to use it relative to complete_spike or update_ticket.

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