Add to-do list

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

Goes well past the annotations (non-read-only, non-idempotent, non-destructive, open-world) by disclosing that each task_id is returned, that a date without a time is due at 5 PM, the 9 AM reminder behavior driven by notification settings, that times follow the Cloud Browser time zone, that nobody else is notified, and how to undo. This is exactly the context annotations cannot carry.

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?

Two short paragraphs, front-loaded with the core action before defaults and side effects. The opening phrase 'To-do list card with tasks...' partially restates the following sentence, a small redundancy that keeps it from a 5.

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?

Despite having no output schema, the description states the return value (each task_id) and covers scheduling defaults, notification side effects, timezone, and undo. Combined with a fully documented schema, an agent has everything needed to call it correctly.

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 100%, so the baseline is 3, but the description adds semantics the schema lacks: the 5 PM default when due_time is omitted and the Cloud Browser time zone governing times. The unchecked-initial-state detail also clarifies what the tasks payload becomes.

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 — creates one to-do list card with all its tasks — and pins the destination to the board's Unsorted panel. This clearly separates it from sibling mutations like add_column, add_note, and add_link, which target different card types.

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?

Explains the operative context: the list always lands in Unsorted rather than a chosen column, tasks arrive unchecked, and the undo path is moving the list to the trash in Milanote. It stops short of naming an explicit alternative tool or a when-not-to-use condition, but the placement and reversibility guidance is concrete.

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