update_task

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

Goes well past the annotations by disclosing the exact write footprint (single character, frontmatter and rest of file untouched), the repeat-set-is-a-no-op behavior that explains idempotency, and the concrete failure modes hash_conflict and task_text_mismatch tied to the guard parameters. Nothing here contradicts destructiveHint=true; it clarifies how minimal the mutation actually is.

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 compact sentences, front-loaded with the operation and its write footprint, then the optional guards, then the no-op edge case. Every sentence carries distinct information with no filler.

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?

Covers the mutation's blast radius, concurrency guards, and edge-case semantics, which is what an agent needs to call it safely. With no output schema, it does not say what the call returns (e.g. new hash or status), leaving a minor 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it ties path + line to list_tasks as their source and explains the distinct roles of expectText (line-text guard) versus prevHash (whole-note compare-and-swap). Only the state parameter's accepted values are left entirely to the schema.

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?

States a specific verb and resource ('Set the state of one Markdown checkbox identified by path + line') and pins the scope precisely: exactly one character is rewritten, everything else stays byte-identical. That distinguishes it cleanly from siblings like replace_in_note or patch_note, which edit larger regions.

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?

Directs the agent to obtain path + line 'from list_tasks' and explains when to pass expectText (line changed) versus prevHash (full compare-and-swap). It gives clear positive usage context but never names exclusions or alternatives, e.g. when to prefer replace_in_note or patch_note instead.

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