update_checklist

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

With no annotations, the description must carry the behavioral burden. It discloses that this wraps the Things URL scheme and that it modifies an existing todo's checklist. However, it does not clarify the destructive implications of 'replace' mode, whether existing checklist items are removed, or what happens on failure or partial success.

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 compact and front-loaded, with the core purpose stated first and implementation context second. The Args block is cleanly formatted and matches the schema parameters without unnecessary repetition or fluff.

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 an output schema, so return-value documentation is not the description's job. Parameters are documented, and the fit relative to update_todo is explained. The main gap is behavioral detail about what each mode does to existing checklist items, which is important for an agent deciding how to invoke it safely.

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 0%, so the description must compensate, and it largely does. It explains todo_id as a UUID, items as checklist item strings, and mode as one of replace/append/prepend with a default. It could add more detail about mode behavior, but it provides enough meaning beyond the bare 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 opening line states a clear verb and resource: 'Update checklist items on an existing todo.' It also distinguishes itself from the standard update_todo tool by explaining that it wraps the Things URL scheme to handle checklist operations that update_todo cannot. This gives an agent a precise understanding of the tool's niche.

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 explicitly names the alternative (update_todo) and explains why this tool should be used instead: it handles checklist operations the standard tool can't do. It does not explicitly list exclusions or when to prefer update_todo, but the guidance is clear enough for most selection scenarios.

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