Move a task

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

While annotations declare readOnlyHint=false and idempotentHint=false, the description adds substantial behavior beyond them: the default semantics of omitting parent (top level) and previous (first among siblings), the combined-omission consequence (very top of list), and the fact that positions are opaque API-maintained strings. It also discloses the cross-parameter constraints and the return value ('Returns the task with its new position'). None of this is in the 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 dense but every sentence earns its place: core action, omission defaults with a consequence clause, exclusivity rationale, constraints, and return value. It is front-loaded with the purpose in the first sentence and contains no repetition of schema content or 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?

The tool has no output schema, so the return-value statement is essential and present. Given the complexity of three orthogonal movement modes, default behaviors, and three constraints, the description covers everything an agent needs to invoke it correctly: purpose, parameter interaction semantics, constraints, and result. No meaningful gap remains.

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% with solid per-parameter docs, so the baseline is 3 and the schema already carries the heavy lifting. The description adds interaction-level meaning the schema cannot: how omitting parent and previous combine to place the task at the very top, and the constraint that parent and previous must reside in the destination list. This elevates it above baseline, though it complements rather than rescues 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 opens with 'Moves a task' and precisely enumerates the three movement dimensions (under a parent, after a sibling, into another list), which is a specific verb+resource statement that distinguishes it from every sibling. Crucially, it explains why update_task cannot achieve this ('parent/position are read-only fields'), making the differentiation from the closest sibling explicit.

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 states 'This is the ONLY way to change hierarchy or order,' an explicit when-to-use directive backed by the read-only-fields rationale. It also gives when-not conditions: parent/previous must belong to the destination list and assigned/recurrent tasks cannot be moved between lists. The alternative route (update_task) is implicitly excluded by the read-only fields explanation, which is sufficient guidance.

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