create-todo-checklist-item

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

Annotations declare destructiveHint=true and openWorldHint=true, so the safety profile is already conveyed; the description adds real value by stating the isChecked default and that the created item is returned with its id. It does not mention the confirm-gate behavior, but the schema's confirm parameter already documents it thoroughly, so this is a minor gap rather than a contradiction.

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 useful content (the TIP and the sibling alternative) is front-loaded and compact, with no filler. The opening line restates the name, but it functions as a hook before the substantive guidance, so waste is minimal.

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?

With no output schema, the description correctly tells the agent what comes back (the new item with its id). It covers the nested body object, the default, and the alternative creation path; only the confirmation-gate nuance is left entirely to the schema.

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 83%, giving a baseline of 3, and the description earns an extra point by supplying a concrete body shape ({ displayName: "..." }) and clarifying that isChecked defaults to false — a default the schema does not state. It adds nothing for todoTaskId/todoTaskListId, but those are already richly described in 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 names a specific verb and resource ("Create a new checklistItem object") and immediately clarifies the domain meaning: "Adds a step (checklist item) to an existing To Do task." It also distinguishes itself from the sibling create-todo-task by explaining that bulk steps belong there instead.

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 states the triggering condition (task already exists, adding one step) and names the explicit alternative path ("pass checklistItems in the create-todo-task body instead"). Combined with the sibling tools list-todo-checklist-items / update-todo-checklist-item, the routing is unambiguous.

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