get_flagged_tasks

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'optional project filtering' and implies retrieval of flagged tasks, but lacks details on permissions, rate limits, pagination, or what 'flagged' means in OmniFocus context. For a read operation tool with zero annotation coverage, this leaves significant gaps in understanding how it behaves.

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, efficient sentence that front-loads the core purpose ('Get flagged tasks from OmniFocus') and adds a useful detail ('with optional project filtering'). There is no wasted language, and it's appropriately sized for a simple retrieval tool.

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 low complexity (2 parameters, no output schema, no annotations), the description is adequate but not complete. It covers the basic purpose and hints at filtering, but lacks details on return format, error handling, or behavioral traits. For a read operation, this is minimally viable but could be more informative.

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%, so the input schema already documents both parameters thoroughly. The description adds minimal value by mentioning 'optional project filtering,' which aligns with the 'projectFilter' parameter, but doesn't provide additional context beyond what the schema states. This meets the baseline for high schema coverage.

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 clearly states the action ('Get flagged tasks') and resource ('from OmniFocus'), making the purpose immediately understandable. It distinguishes this tool from siblings like 'get_inbox_tasks' or 'get_tasks_by_tag' by specifying 'flagged tasks' as the target. However, it doesn't specify whether this retrieves all flagged tasks or only active ones, which would make it a perfect 5.

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 implies usage through 'optional project filtering,' suggesting this tool is for retrieving flagged tasks with possible project-based narrowing. However, it doesn't explicitly state when to use this versus alternatives like 'filter_tasks' or 'get_custom_perspective_tasks,' nor does it mention prerequisites or exclusions. The guidance is present but not comprehensive.

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