Create a new task or update an existing task's title and due date by supplying a task ID. Keeps task lists current with automatic, reversible changes.
Create a task, or update an existing one's title/due date when task_id is given.
Decision 8 classifies this as automatic and reversible, unlike deletion, so it needs no approval step.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | ||
| due_at | No | ||
| task_id | No |
Changes observed during successful MCP inspections.
v0.2.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The second sentence adds behavioral context beyond annotations by stating the operation is automatic, reversible, and requires no approval. It also clarifies that updates only affect title and due date, which is useful for the agent. This does not contradict the readOnlyHint, destructiveHint, or idempotentHint 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?
The description is brief and front-loads the core behavior in the first sentence. However, the 'Decision 8' reference is cryptic and unexplained, making the second sentence less useful than it could be.
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 description covers the essential create/update logic and the role of task_id, which is enough for basic invocation. Yet it omits return-value expectations, error behavior, and any guidance on how task_id should be obtained; the unexplained 'Decision 8' reference also leaves a gap.
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?
With 0% schema description coverage, the description compensates partly by explaining that task_id selects update mode and that title and due date are the fields manipulated. It does not explain due_at's ISO format or the meaning of null/omitted due_at, leaving the agent to rely on the schema for those details.
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 the tool creates a task or updates an existing task's title/due date when task_id is provided. It names the specific resource and action, though it does not explicitly distinguish itself from sibling tools like task_complete or task_schedule.
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 gives internal routing guidance: create when task_id is absent, update when task_id is present. However, it does not explain when to choose this tool over alternatives or when not to use it, leaving sibling selection implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.