update-todo-checklist-item

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

Annotations already declare destructiveHint=true, readOnlyHint=false and openWorldHint=true, so the mutation risk signal is carried structurally. The description adds the ID-chain requirement and the per-field effect of isChecked/displayName, but says nothing about the confirm gate, reversibility, or what a rename overwrites. Useful additions, but modest beyond 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 general statement is front-loaded and the TIP sentence adds actionable detail in two lines with no filler. Slight overlap between the opening sentence and the TIP's 'Updates a step' restatement, but overall tight and well ordered.

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 7-parameter nested-body mutation tool with 86% schema coverage and annotations covering the safety profile, the description supplies the missing 'how/why' (which fields to set and where the ID comes from). No output schema exists, but return shape isn't explained, leaving a minor gap for a tool with excludeResponse/includeHeaders options.

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 86%, so the baseline is 3. The description goes further by tying concrete body payloads to intent (body: { isChecked: true } to check off, displayName to rename) and by pointing at list-todo-checklist-items as the source of checklistItemId. That adds practical semantics beyond the field-level schema descriptions.

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 ('Update') and resource ('properties of a checklistItem object'), then disambiguates with concrete operations (check off, uncheck, rename). The sibling set includes create-todo-checklist-item and delete-todo-checklist-item, and the 'check/uncheck/rename' framing makes the mutation scope unmistakable. An agent can tell exactly what this does without opening the schema.

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?

Gives explicit usage context ('Use this to check a step off... uncheck... rename') and a prerequisite (checklistItemId from list-todo-checklist-items). It does not explicitly exclude or contrast with create/delete siblings, but the operation examples make the intended use clear. Clear context, no hard exclusions.

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