task_item

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

With no annotations, the description carries the full burden and does so well: it discloses the archival side effect of closing the last open item, the reopen-on-reopen behavior, and atomicity ('An unknown uid refuses the whole call, and nothing is written'). It omits permission/auth requirements and any return-shape detail beyond 'archived in the result'.

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?

Front-loaded with the core action, then a compact per-parameter glossary that maps cleanly to the schema properties. Each sentence carries information; the only mild redundancy is restating 'They apply together, or not at all' after the unknown-uid atomicity note.

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 5-parameter, unannotated, no-output-schema mutation tool the description is strong on state/comment/related semantics and side effects, but leaves the required uid parameter undefined and gives no sense of the returned payload beyond the 'archived' flag.

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 0%, so the description must compensate; it thoroughly explains item (key format, examples i3/3), state (enum-like values), comment, and related (comma-separated uids, failure semantics). But the required parameter uid is never defined anywhere, leaving a required field undocumented.

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: 'Update one item of a task' and enumerates the three updatable facets (state, comment, related). An agent can tell it apart from task_add and task, though it never explicitly names or routes to the sibling task_comment, which overlaps with the comment facet.

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?

Provides a hard precondition ('Give at least one of state, comment and related') and describes the archival/reopen consequences of state transitions. However, it never states when to prefer this tool over task_comment or task_add, so selection guidance is implied rather than explicit.

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