Update Kanban task

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a mutation that's not destructive. The description adds useful context: 'writing redacted receipts' and the status restriction on 'running' (set by dispatcher). However, it doesn't disclose side effects like whether unassigning via empty string affects claim state, or how the completion path interacts with complete_task beyond forwarding. The 'redacted receipts' detail is a genuine addition but could go further.

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, reasonably dense sentence that front-loads the verb, resource, fields, and one behavioral trait (redacted receipts). No wasted words. It could arguably be more compact but is efficient and informative.

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?

Given there's an output schema, the description need not explain return values. The tool is a straightforward mutation with 1 required param, clear annotations, and rich schema descriptions. The main gap is not explaining field interdependencies (like whether completion paths for 'done' status require summary/result/metadata), but annotations and schema coverage carry most of the burden. Adequate for its complexity.

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 each of the 11 parameters well (id format, status enum, board slug pattern, assignee empty-string semantics). The description adds minimal beyond the schema - it lists which fields can be updated but doesn't clarify interaction semantics (e.g., does setting status to 'done' require result, does 'blocked' require block_reason). Since coverage is high, baseline 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 clearly states it's a 'Typed PATCH wrapper that updates status, assignee, priority, title, body, result, or completion summary for one Kanban task.' This is specific verb+resource+fields and distinguishes it from sibling tools like hermes_kanban_task_create, task_specify, and task_decompose. It could slightly improve by noting it differs from bulk_update, but it does convey the single-task scope.

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 mentions 'writing redacted receipts' which gives some sense of what happens, and the status schema notes 'running is not allowed because status is set by the dispatcher/claim path.' However, there's no explicit when-to-use vs when-not-to-use guidance (e.g., when to choose bulk_update vs this, or when completion summary should be used). The 'completing a task' hint in result and the summary-to-complete_task reference imply some flow, but no exclusions or alternative tool references are given.

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