Add task

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

Beyond the annotations (which only establish this as a non-read-only, non-destructive write), the description discloses a genuine behavioral trait: the tool performs no duplicate detection, so creating a task with an existing similar name can produce a duplicate unless the agent runs the pre-check. This meaningfully exceeds annotation coverage.

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 sentences with zero filler. The primary action is front-loaded, and the conditional dedup instruction earns its place as the single most important operational caveat. Every word carries signal.

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 13-parameter, 1-required write tool, the combination of a fully self-documenting schema, annotations, an output schema, and the dedup guidance leaves nothing needed to invoke the tool correctly unexplained. The only marginal gap is explicit routing to batch_add_items for bulk creation.

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 100% — all 13 parameters (name, note, tags, tagIds, dates, idempotencyKey, parentTaskId, etc.) are individually documented. Per the baseline, the description need not add parameter detail. Its dedup note relates to the name parameter but supplies workflow guidance rather than new semantics.

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 states a specific action with a clear verb and resource: 'Add a new task to OmniFocus.' This distinguishes it from sibling tools like add_project, edit_item, or batch_add_items, and the duplicate-check instruction signals this is the single-task creation entry point.

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 gives an explicit precondition: before creating a possibly-duplicate task, call find_similar_tasks with the same name and reuse the returned id on a strong match. This is clear when-to-use guidance, but it does not name exclusions or alternatives such as batch_add_items for bulk creation.

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