subtask_update

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

The description adds meaningful behavior beyond the annotations: it explains that depends_on and blocks replace the existing set, that [] clears them, and that transitioning to started/finished with unmet prerequisites requires force. This aligns with the idempotentHint and does not contradict the readOnlyHint or destructiveHint 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?

Three short sentences are front-loaded with the core update purpose and packed with dependency and force semantics. The phrase 'blocks the inverse' is terse but economical; it earns its place without padding.

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 mutation tool with no output schema, the description covers the main update targets, set-replacement behavior for both dependency arrays, clearing via [], and the force condition. It is slightly incomplete because it does not name sort_order explicitly or clarify the division of labor with subtask_reorder, but the remaining gaps are small.

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 only 43% schema coverage, the description compensates by explaining the semantics of depends_on/blocks replacement and the force requirement, and by summarizing title/status/position. However, it refers to 'position' rather than the actual sort_order property and leaves force policy details 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?

The description states a concrete verb and resource ('Update a subtask') and enumerates the mutable aspects: title, status, position, plus depends_on/blocks. It does not explicitly distinguish itself from the sibling subtask_reorder, which also concerns position, and 'position' is not the schema's parameter name (sort_order).

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?

No guidance is given on when to call this tool versus alternatives such as subtask_create, subtask_reorder, subtask_delete, or task_update. The only conditional guidance is about force for unmet prerequisites, which is a behavior rule rather than a usage-selection rule.

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