Marks multiple OmniFocus projects as reviewed in one operation, advancing their next review dates and eliminating repetitive individual updates.
Mark multiple projects as reviewed in a single operation (advances their next review dates)
| Name | Required | Description | Default |
|---|---|---|---|
| projectIds | No | Array of project IDs to mark as reviewed | |
| projectNames | No | Array of project names to mark as reviewed (alternative to projectIds) |
Changes observed during successful MCP inspections.
v2.1.1Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose the key side effect: next review dates are advanced. It omits the rest of the mutation profile — whether it is idempotent, what happens with unknown IDs, whether partial failures are reported, and what permissions or auth it needs.
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?
One sentence, front-loaded with verb and object, with the behavioral consequence in a tight parenthetical. Nothing wasted and nothing buried.
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 two-parameter batch mutation with no annotations and no output schema, the description covers purpose and effect but leaves return behavior and the ID-vs-name selection rule unexplained. Adequate, but an agent still has to guess at batch semantics.
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 baseline is 3. The description adds nothing about the mutual exclusivity/priority of projectIds vs projectNames, which is the one ambiguity an agent could get wrong here.
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+resource ("Mark multiple projects as reviewed") and adds the consequential effect ("advances their next review dates"), which lets an agent distinguish it from generic mutators like batch_edit_items or edit_item. It does not explicitly name siblings, so it stops short of a 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?
No when-to-use or when-not-to-use guidance. Nothing says to pair it with get_projects_for_review (the obvious read-side sibling) or explains why an agent would pick this over batch_edit_items for changing project state.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.