add_omnifocus_task

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

With no annotations, the description must disclose behavioral traits but only states the action. It does not mention side effects, validation requirements, error behavior, or whether the task is created synchronously. For a mutation tool, this is a significant gap.

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 description is a single, clear sentence with no wasted words. It is front-loaded with the action and resource, which is ideal for conciseness. However, this brevity comes at the cost of completeness.

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?

Given the tool's complexity (11 parameters, mutation, no annotations, 0% schema coverage), the description is severely incomplete. It provides no context about parameter relationships, return values, or operational constraints. Even with an output schema, the description fails to cover essential context for correct usage.

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 schema has 11 parameters with 0% description coverage, and the tool description provides no parameter information at all. It does not even mention the required 'name' field or any optional fields, leaving the agent to infer semantics entirely from parameter names and defaults.

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 'Add a new task to OmniFocus' clearly identifies the action (add) and resource (task in OmniFocus). It is distinct from sibling tools like batch_add_items (batch addition) and add_project (project creation), making the purpose unambiguous.

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?

There is no guidance on when to use this tool versus alternatives such as batch_add_items or add_project. No mention of prerequisites like project existence, or whether this tool should be preferred for single-task creation. The description simply states the action without contextual usage direction.

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