things_update_todo

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

No annotations are provided, so the description carries the full burden for a mutation tool, and it discloses almost nothing behavioral: no permission or auth requirements, no statement on whether unspecified fields are cleared or preserved, no reversibility warning, no return-value description. The text is also truncated, so even the intended scope of the change is incomplete.

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 text is short and front-loads the verb and resource, but it terminates mid-word ('start dat...'), making the definition structurally incomplete rather than merely concise. An agent cannot rely on a sentence that breaks off before listing all mutable fields.

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 annotations, no output schema, and an empty input schema, the description needed to carry nearly everything and instead is truncated. Critical details such as how parameters are supplied and what happens to unset fields are missing.

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?

The input schema declares zero properties despite the description referencing fields (id, title, notes, deadline, start date) that must logically be passed. The description names those fields, which adds meaning, but it contradicts the empty schema, leaving an agent unsure how to actually supply the arguments.

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 a specific verb and resource ('Changes a to-do of Things 3') and names the upstream sibling (things_list_todos) that supplies the id, which distinguishes it from things_create_todo and things_complete_todo. The only weakness is that the sentence is cut off mid-word ('start dat...'), so the full field set is never stated.

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?

It gives implied usage guidance by pointing at things_list_todos as the source of the to-do id, which is genuinely helpful for invocation order. It does not state when not to use it, whether existing fields are preserved when omitted, or how it differs from todo_complete_task/todo_create_task beyond the verb.

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