Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@OmniFocus MCP Server Create a task 'Review Q3 budget' due Friday in Work folder."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
✔️ Turn prompts into projects.
Feature-complete Model Context Protocol server for OmniFocus. Full read/write access to tasks, projects, folders, tags, and perspectives — 51 tools, 2 resources, and 3 prompts.
Uses Omni Automation (OmniJS) under the hood, executing scripts via JXA and osascript. This is why macOS is required.
Related MCP server: OmniFocus Operator
"Create a project called 'Q3 Launch' in my Work folder with subtasks for design review, copy writing, and QA — all due next Friday, assigned sequentially."
"What's overdue? Flag anything due this week that isn't flagged yet."
"Move all tasks tagged 'waiting' in the 'Website Redesign' project to a new 'Blocked' project."
"Run my weekly review — go through stale projects, process inbox, and summarize what needs attention."
"How many tasks do I have tagged 'errand'? List the ones that are available."
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"omnifocus": {
"command": "npx",
"args": ["-y", "omnifocus-mcp-server"]
}
}
}claude mcp add omnifocus -- npx -y omnifocus-mcp-serverOr add to .claude/settings.json:
{
"mcpServers": {
"omnifocus": {
"command": "npx",
"args": ["-y", "omnifocus-mcp-server"]
}
}
}Add to .cursor/mcp.json in your project or ~/.cursor/mcp.json globally:
{
"mcpServers": {
"omnifocus": {
"command": "npx",
"args": ["-y", "omnifocus-mcp-server"]
}
}
}Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"omnifocus": {
"command": "npx",
"args": ["-y", "omnifocus-mcp-server"]
}
}
}Add to ~/.codex/config.toml:
[mcp_servers.omnifocus]
command = "npx"
args = ["-y", "omnifocus-mcp-server"]Add to ~/.gemini/settings.json:
{
"mcpServers": {
"omnifocus": {
"command": "npx",
"args": ["-y", "omnifocus-mcp-server"]
}
}
}macOS (OmniFocus is macOS-only)
OmniFocus 4 (or OmniFocus 3 with Omni Automation support)
Node.js >= 18
Automation permission granted in System Settings > Privacy & Security > Automation
This server has full read/write access to your OmniFocus database. It can create, modify, and delete tasks, projects, folders, and tags. Only connect it to AI clients and models you trust.
No data leaves your machine — all communication happens locally via osascript.
Tool | Description |
| List tasks with filters for status, flags, tags, projects, date ranges, and text search |
| Get task details by ID, optionally including subtask hierarchy |
| Create a task in inbox or a project, with tags, dates, and recurrence |
| Update task properties (name, note, dates, flags, recurrence) |
| Mark a task as completed |
| Re-open a completed task |
| Mark a task as dropped (cancelled) |
| Permanently delete a task |
| Move tasks to a different project, parent task, or inbox |
| Duplicate tasks, optionally into a different project |
| Set, add, or remove tags on a task |
| Add an absolute or due-relative notification |
| Remove a notification from a task |
| List all notifications on a task |
| Append text to a task's note |
| Get all inbox tasks |
| Get all available flagged tasks |
| Get tasks completed today |
| Count tasks matching filters — use instead of |
| Convert a task into a project, preserving subtasks |
| Create multiple tasks at once with subtask hierarchies |
| Complete multiple tasks at once |
| Delete multiple tasks at once |
Tool | Description |
| List projects with filters for status, folder, and text search |
| Get project details by ID or name |
| Create a project with folder, sequential, SAL, tags, and review options |
| Update project properties |
| Mark a project as done |
| Mark a project as dropped (cancelled) |
| Move a project to a different folder |
| Permanently delete a project |
| Get all tasks in a project |
| Get projects due for review |
| Mark a project as reviewed |
Tool | Description |
| List all folders |
| Get folder details including child folders and projects |
| Create a folder (supports nesting) |
| Update folder name or status |
| Permanently delete a folder |
Tool | Description |
| List all tags |
| Get tag details including child tags |
| Create a tag (supports nesting and allowsNextAction) |
| Update tag properties |
| Permanently delete a tag |
Tool | Description |
| List perspectives (built-in and/or custom) |
| Get tasks shown in a specific perspective |
Tool | Description |
| Get counts of inbox items, projects, tags, folders, and task statistics |
| Search across all items (tasks, projects, folders, tags) by name or note |
| Dump the entire database in a single call |
| Explicitly save the database to disk |
| Trigger an OmniFocus sync to push local changes to OmniSync and pull updates from other devices. Call once at the end of a chain of mutations. The |
URI | Description |
| Database summary with counts |
| List of all perspectives |
Prompt | Description |
| Walk through your GTD weekly review: check projects due for review, process leftover inbox items, reassess flagged tasks, and get a structured summary. Marks projects as reviewed when done. |
| Process inbox items one-by-one using GTD methodology — delete non-actionable items, do anything under 2 minutes, and organize the rest into projects with tags and dates. |
| Build a prioritized plan for today based on due dates, flagged items, and what you've already completed. Surfaces overdue tasks and estimates your workload. |
Make sure Automation permissions are granted. Go to System Settings > Privacy & Security > Automation and ensure your terminal app (Terminal, iTerm, etc.) is allowed to control OmniFocus.
If you're developing locally, multiple MCP server processes may be running (from Claude Desktop, Claude Code, etc.). Kill them all and restart:
pkill -f "omnifocus-mcp-server"
# or if running from source:
pkill -f "omnifocus/mcp/dist/index.js"npx cacheIf npx is running an old version, clear the cache:
npx clear-npx-cache
# then re-run your MCP clientOmniFocus 3 works if Omni Automation is enabled. Go to OmniFocus > Preferences > General and check "Omni Automation". Some features (like certain perspective types) may behave differently.
Each tool call runs an osascript process to communicate with OmniFocus. This typically takes 200-500ms per call. Batch tools (batch_create_tasks, batch_complete_tasks, batch_delete_tasks) are much faster for bulk operations than calling individual tools in a loop.
npm install
npm run build # Compile TypeScript
npm run dev # Run with tsx (hot reload)
npm test # Run unit tests
npm run test:watch # Watch modeTests against a real OmniFocus instance (creates and cleans up test items):
OMNIFOCUS_LIVE=1 npm run test:integrationPRs welcome. Please run npm test before submitting and include tests for new tools.
MIT
Add a notification/reminder to a task
| Name | Required | Description | Default |
|---|---|---|---|
| taskId | Yes | The task ID | |
| type | Yes | Notification type | |
| absoluteDate | No | For 'absolute' type: ISO 8601 date for notification | |
| relativeOffset | No | For relative types: offset in seconds (negative = before) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits beyond the basic action. It lacks details on side effects (e.g., whether existing notifications are overwritten), authentication needs, or limits. The conditional parameter behavior is implied by schema but not explained in the description.
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 sentence, which is concise but not particularly informative for the tool's complexity (4 parameters, mutation). It is minimally adequate but not structured to highlight key details.
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?
No output schema exists, yet the description does not mention return values (e.g., success status, created notification ID). For a mutation tool with multiple parameters, this leaves a significant gap in understanding the tool's full behavior.
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 parameters are already well-documented in the schema. The description adds no additional meaning beyond what the schema provides. Baseline score of 3 is appropriate.
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 ('Add') and the resource ('notification/reminder to a task'), which distinguishes it from sibling tools like 'remove_task_notification' and 'list_task_notifications'. However, it does not specify what the notification entails (e.g., reminder types), leaving some ambiguity.
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 provides no guidance on when to use this tool versus alternatives, such as under what conditions to choose 'add_task_notification' over other notification-related tools. No when-to-use or when-not-to-use context is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Append text to an existing task's note
| Name | Required | Description | Default |
|---|---|---|---|
| taskId | Yes | The task ID | |
| text | Yes | Text to append to the note |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies additive behavior ('append') which is non-destructive, but does not disclose failure modes (e.g., if taskId is invalid) or any side effects. With no annotations, the description carries the full burden; it is minimally transparent.
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 extremely concise (8 words, single sentence) with no redundant information. It earns its place but could be slightly more informative without losing conciseness.
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 simple append operation with no output schema, the description covers the core action. However, it does not mention return value (e.g., success/failure) or error conditions, leaving some uncertainty.
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% and both parameters (taskId, text) are clearly described. The description adds no additional meaning beyond what the schema provides, so baseline score applies.
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?
Description clearly states the verb 'append' and resource 'text to an existing task's note'. It is specific and distinguishes from sibling tools like create_task or update_task which handle full task creation/updating.
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 guidance on when to use this tool versus alternatives, nor any context about prerequisites (e.g., task must exist). The description is purely functional without usage advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Complete multiple tasks at once. More efficient than completing one by one.
| Name | Required | Description | Default |
|---|---|---|---|
| taskIds | Yes | Array of task IDs to complete | |
| sync | No | Trigger an OmniFocus sync after the batch completes (default false). Skips on error. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states the generic action without disclosing behavior such as partial success, error handling, or atomicity. The sync parameter is mentioned in the schema but not in the description.
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 very concise with two sentences and no redundant information. However, it is front-loaded with the key action, which is good, but lacks depth.
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?
With no output schema, no annotations, and only two simple parameters, the description fails to provide context about return values, error conditions, or prerequisites. Compared to sibling batch tools, there is no contrast or usage guidance.
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 input schema already describes both parameters (taskIds and sync) with coverage of 100%. The description adds no additional parameter-level information beyond the schema.
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 explicitly states 'Complete multiple tasks at once' with a clear verb and resource, and it distinguishes from the sibling 'complete_task' by emphasizing batch efficiency.
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 hints at when to use it ('more efficient than completing one by one') but does not specify when not to use it or explicitly name alternatives like 'complete_task' for single tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create multiple tasks at once, with support for subtask hierarchies. Much more efficient than creating tasks one by one.
| Name | Required | Description | Default |
|---|---|---|---|
| tasks | Yes | Array of tasks to create (can include nested children) | |
| projectId | No | Project ID to add tasks to | |
| projectName | No | Project name to add tasks to | |
| parentTaskId | No | Parent task ID for subtasks | |
| sync | No | Trigger an OmniFocus sync after the batch completes (default false). Skips on error. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description carries full burden. It mentions subtask hierarchy but omits details on error handling, atomicity, return values, or side effects (e.g., sync trigger). The sync parameter is not explained in the description.
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, front-loaded with key purpose, no extraneous content. Efficient and clear.
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 high schema coverage, the description lacks information on return values, error handling, and batch behavior (e.g., partial success). For a complex batch tool, this is insufficient for an agent to fully understand implications.
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 param descriptions are already complete. The description adds no new meaning to parameters; it only summarizes the tool's overall function. Baseline score of 3 is appropriate.
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 tool creates multiple tasks at once with subtask hierarchy support, and highlights efficiency versus single-task creation. It distinguishes itself from sibling tools like create_task.
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 when efficiency is desired over creating tasks individually, but does not specify when not to use (e.g., for small numbers), prerequisites, or alternatives like create_task. No explicit exclusion or guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete multiple tasks at once. More efficient than deleting one by one.
| Name | Required | Description | Default |
|---|---|---|---|
| taskIds | Yes | Array of task IDs to delete | |
| sync | No | Trigger an OmniFocus sync after the batch completes (default false). Skips on error. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; the description only mentions efficiency and omits critical behavioral details such as error handling, permissions, or whether deletion is permanent, leaving the agent uninformed.
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 brief, front-loaded sentences with no filler, clearly stating the purpose and efficiency benefit.
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?
Lacks explanation of return values, error behavior, or batch semantics; the 'sync' parameter behavior is only in schema, not in description, leaving gaps for a batch operation.
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% with descriptions for both parameters; the tool description adds no additional semantic value beyond what the schema already provides, meeting baseline.
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 tool deletes multiple tasks at once, distinguishing it from the single-delete sibling 'delete_task' by highlighting efficiency.
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 use when batch deletion is more efficient than individual deletions, but does not provide explicit guidance on when not to use or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a project as completed (done)
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The project ID to complete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits. It only says 'completed (done)' without mentioning side effects, reversibility, or permissions, leaving ambiguity.
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 extremely concise with no extraneous words, but it may be too brief for full clarity. Structure is front-loaded and efficient.
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 simplicity and lack of output schema, the description is insufficient. It does not explain how 'complete' differs from 'drop' or 'delete' among sibling tools, nor does it cover edge cases.
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 schema already documents the only parameter. The description adds no semantic value beyond the schema's 'The project ID to complete'.
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 ('Mark as completed') and resource ('project'), distinguishing it from siblings like complete_task and batch_complete_tasks by specifying 'project'.
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 guidance is provided on when to use this tool versus alternatives such as drop_project or delete_project. The description does not mention exclusions or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a task as completed
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The task ID to complete | |
| completionDate | No | Optional ISO 8601 completion date to backdate the completion (defaults to now) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description should disclose behavioral traits such as side effects (e.g., whether the task is irreversible, notifications triggered), but it only states the action without any such context.
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 concise sentence with no wasted words, but it is very brief and lacks front-loaded behavioral context; still appropriate for a simple 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 low complexity (2 parameters, no output schema), the description covers the basic purpose but omits context like default behavior of completionDate or what happens after completion, leaving minor gaps.
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 input schema already describes both parameters (id, completionDate) clearly, and the description adds no additional meaning beyond what the schema provides, earning the baseline score of 3.
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 (mark as completed) and the resource (task), effectively distinguishing it from sibling tools like uncomplete_task and batch_complete_tasks.
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 guidance is provided on when to use this tool versus alternatives (e.g., batch_complete_tasks for multiple tasks) or any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert an existing task into a new project, preserving subtasks
| Name | Required | Description | Default |
|---|---|---|---|
| taskId | Yes | The task ID to convert |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It mentions preserving subtasks but fails to explain what happens to the original task (e.g., is it deleted or transformed?), side effects, or permissions required. This leaves ambiguity for the agent.
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 with no wasted words. It front-loads the core action. However, it could benefit from slightly more structure to cover missing details.
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 no output schema and no annotations, the description is too minimal. It does not explain the return value, confirmation, or error states. For a conversion tool, more details on the operation's effect are needed.
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 description adds no value beyond the schema. The schema already describes 'taskId' as 'The task ID to convert'. No additional context is provided for the parameter.
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 (convert), the resource (task to project), and a key behavior (preserving subtasks). It effectively distinguishes this tool from siblings like create_project or update_task.
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 provides no guidance on when to use this tool versus alternatives, nor does it mention prerequisites or warning conditions. It simply states the function without context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new folder in OmniFocus
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Folder name | |
| parentFolderId | No | Parent folder ID for nesting | |
| parentFolderName | No | Parent folder name for nesting |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure, but it only states the obvious creation action without any details on side effects, permissions, or error conditions.
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, concise sentence with no wasted words, though it may be too brief to be fully informative.
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 3 parameters and no output schema or annotations, the description is insufficient to fully understand the tool's behavior, such as when to use each parent identifier or what the return value is.
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 baseline is 3. The description adds no value beyond the schema; it does not explain parameter semantics or clarify the difference between parentFolderId and parentFolderName.
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?
Description clearly states 'Create a new folder in OmniFocus', specifying a verb and resource, and it distinguishes from sibling tools like create_project, create_tag, and create_task.
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 guidance on when to use this tool vs alternatives, nor any explanation of how to choose between parentFolderId and parentFolderName parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new project in OmniFocus
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Project name | |
| note | No | Project note/description | |
| folderId | No | Parent folder ID | |
| folderName | No | Parent folder name | |
| sequential | No | Whether tasks must be completed in order | |
| singleActionList | No | Whether this is a single-action list | |
| completedByChildren | No | Auto-complete when all children are completed | |
| deferDate | No | Defer date (ISO 8601) | |
| dueDate | No | Due date (ISO 8601) | |
| plannedDate | No | Planned date (ISO 8601) | |
| flagged | No | Whether to flag the project | |
| tags | No | Tag names to apply | |
| reviewInterval | No | Review interval |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as required permissions, side effects, or constraints. The agent lacks critical context about mutation consequences.
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 very concise at one sentence with no wasted words. However, it could be slightly more informative without sacrificing brevity.
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 has 13 parameters, no output schema, and no annotations, the description is far too brief. It lacks essential behavioral context, return value information, and parameter details.
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 input schema has 100% coverage with descriptions for all parameters, so the description adds no additional meaning beyond what the schema already provides. Baseline score is appropriate.
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 verb 'Create' and resource 'a new project in OmniFocus', which is specific and distinguishes from sibling tools like create_folder or create_task.
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 provides no guidance on when to use this tool versus alternatives such as update_project, complete_project, or create_task. No exclusions or context for usage are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new tag in OmniFocus
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Tag name | |
| parentTagId | No | Parent tag ID for nested tags | |
| parentTagName | No | Parent tag name for nested tags | |
| allowsNextAction | No | Whether tasks with this tag can be next actions (default true) | |
| status | No | Tag status |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must convey behavioral traits. It does not mention uniqueness constraints, side effects, or requirements (e.g., tag name uniqueness). The schema covers parameters but not behavior.
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 extremely concise with no wasted words. However, it could be slightly more informative without losing conciseness.
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 5 parameters and no output schema or annotations, the description is insufficient. It lacks information about return values, error conditions, and prerequisites for a creation tool.
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 baseline is 3. The description adds no extra meaning over the schema; it simply states the action without clarifying parameter relationships or 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 is clear and specific: 'Create a new tag in OmniFocus' uses a precise verb and resource, making the action immediately understandable.
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 guidance is provided on when to use this tool versus alternatives like update_tag or list_tags. The sibling list exists but is not referenced.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new task in OmniFocus. By default creates in inbox; specify projectId or projectName to add to a project.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Task name | |
| note | No | Task note/description | |
| flagged | No | Whether to flag the task | |
| deferDate | No | Defer date (ISO 8601) | |
| dueDate | No | Due date (ISO 8601) | |
| plannedDate | No | Planned date (ISO 8601) | |
| estimatedMinutes | No | Estimated duration in minutes | |
| completedByChildren | No | Auto-complete when all children are completed | |
| projectId | No | Project ID to add task to | |
| projectName | No | Project name to add task to | |
| tags | No | Tag names to apply (created if they don't exist) | |
| repetitionRule | No | Repetition rule for recurring tasks |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions creation and default placement but does not disclose side effects, permissions, or limits. Adequate for a straightforward creation action but lacks depth.
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 concise sentence that is front-loaded with action and resource. No fluff, every word earns its place.
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 12 parameters (including a nested object) and no output schema, the description lacks return value information and deeper context about behavior (e.g., what happens after creation). Incomplete for a complex tool.
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 baseline is 3. Description adds meaning by explaining default inbox and project options, but does not elaborate on parameters beyond what schema already provides.
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 (create a task), the resource (OmniFocus), and the default behavior (creates in inbox) with an option to add to a project. It effectively distinguishes from sibling tools like create_project or batch_create_tasks.
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 provides clear context: use for single task creation, default inbox unless projectId or projectName is specified. However, it does not explicitly mention when not to use or alternatives like batch_create_tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a folder from OmniFocus
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The folder ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It mentions 'permanently delete' but does not explain irreversibility, cascading effects on child items, or permission requirements. Minimal disclosure for a destructive operation.
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?
Single sentence with no waste. However, it is slightly under-specified, bordering on insufficient for a destructive tool. Still concise but not fully earned.
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 simple delete with one param, the description is minimally functional but lacks crucial context like return value (or lack thereof), permanent nature, and potential side effects. More detail would be expected for completeness.
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% with one parameter described as 'The folder ID to delete'. The description adds no extra meaning beyond the schema, meeting baseline but not exceeding.
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 explicitly states the action (delete) and the resource (folder) with the scope (permanently, from OmniFocus). It clearly distinguishes from sibling tools like create_folder or update_folder.
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 guidance on when to use this tool vs alternatives like drop_project or delete_task. Lacks prerequisites (e.g., folder must be empty) or contextual hints about consequences.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a project from OmniFocus
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The project ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states 'permanently delete', which implies destruction but lacks details on side effects, required permissions, or whether the project must be empty. More behavioral context is needed for a destructive tool.
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, front-loaded sentence with no wasted words, efficiently conveying the tool's purpose.
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 simple tool with one parameter and no output schema, the description covers the basic purpose but lacks behavioral completeness for a destructive operation without annotations.
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 covers 100% of the single parameter 'id' with a description, and the tool description does not add additional meaning beyond 'The project ID to delete'. Baseline score of 3 is appropriate.
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 'Permanently delete a project from OmniFocus', specifying the verb, resource, and permanence, which distinguishes it from siblings like 'complete_project' and 'drop_project'.
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 usage guidelines are provided; the description does not indicate when to use this tool versus alternatives like 'drop_project' or 'complete_project', nor does it mention any prerequisites or precautions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a tag from OmniFocus
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The tag ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose side effects like what happens if the tag is attached to tasks. It only says 'permanently delete,' missing crucial behavioral context.
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?
Single sentence, front-loaded with action, no unnecessary words. Highly concise and structured.
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 simple deletion tool with one parameter and no output schema, the description is minimally adequate but lacks details on error cases or consequences.
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% and the single parameter 'id' is described in the schema. The description adds no extra meaning beyond the schema, meeting baseline.
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 verb 'delete' and the resource 'tag' in OmniFocus, distinguishing it from siblings like create_tag or get_tag.
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 guidance on when to use this tool versus alternatives, nor any prerequisites or exclusion criteria provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a task from OmniFocus
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The task ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals that deletion is permanent, which is a key behavioral trait. However, with no annotations, it lacks details on side effects, permissions, or state requirements.
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, focused sentence with no unnecessary words, effectively conveying the core action.
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 simple delete operation with one parameter, the description is mostly sufficient. It could note that it only deletes a single task, distinguishing from batch operations.
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 100% coverage for the single parameter 'id' with a description. The tool description adds no additional meaning beyond that.
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 it permanently deletes a task from OmniFocus, using a specific verb and resource. It distinguishes itself from siblings like batch_delete_tasks by focusing on single task deletion.
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 guidance on when to use this tool versus alternatives like batch_delete_tasks. The description does not mention prerequisites or scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a project as dropped (cancelled)
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The project ID to drop |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description carries the full burden. It does not disclose any behavioral traits such as irreversibility, side effects on tasks, or access requirements. The description only states the basic action without additional context.
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 extremely concise (one short sentence) and to the point. However, it lacks structure or any elaboration that would enhance clarity; but given its brevity, it is not wasteful.
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?
The tool is simple with one parameter and no output schema. While the description minimally covers what the tool does, it misses usage guidance and behavioral context, making it barely adequate for complete understanding.
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% for the single 'id' parameter, which already has a description. The tool description adds no additional meaning beyond the schema, so baseline 3 is appropriate.
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 ('Mark') and the resource ('project') and the intended state ('dropped (cancelled)'). It distinguishes from siblings like 'delete_project' and 'complete_project' by implying a different status, but does not explicitly contrast them.
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 guidance on when to use this tool versus alternatives like 'complete_project' or 'delete_project'. There is no context about prerequisites or scenarios where dropping vs completing vs deleting is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a task as dropped (cancelled)
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The task ID to drop |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates a state change ('dropped/cancelled') but lacks details on whether it's reversible, permissions required, or effects on related tasks. With no annotations, the description fails to disclose behavioral traits sufficiently.
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?
A single, clear sentence with no filler. Every word contributes to understanding.
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 simple tool with one parameter and no output schema, the description is adequate but could include more context like error conditions or examples. Sibling tools suggest this is a standard mutation, but completeness is minimal.
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 covers the single required parameter 'id' with a description. The tool description does not add further context (e.g., format, constraints), so it adds minimal value beyond the schema.
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 uses clear verb 'Mark' and resource 'task', specifying 'dropped (cancelled)' which distinguishes it from siblings like 'delete_task' (permanent removal) and 'complete_task' (finished).
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?
Description implies the tool is for cancellation, but does not explicitly contrast with alternatives or state when not to use it (e.g., vs. delete or complete). No prerequisites or exclusion conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dump the entire OmniFocus database including inbox, projects, folders, tags, and perspectives in a single call. Essential for getting full context.
| Name | Required | Description | Default |
|---|---|---|---|
| includeCompleted | No | Include completed/dropped items (default false) | |
| maxDepth | No | Max depth for subtask hierarchy (0 = unlimited, default 0) | |
| hideRecurringDuplicates | No | Hide future instances of recurring tasks (default false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It does not clarify whether the operation is read-only or destructive, nor does it mention potential performance impacts or authorization requirements.
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 two sentences, front-loaded with the core action, and no extraneous information. Every sentence adds value without redundancy.
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?
The description lacks details about return format (no output schema) and potential side effects or limits. For a tool dumping an entire database, more context on output structure or performance considerations would improve completeness.
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%, with each parameter having a clear description in the schema. The tool description adds no extra meaning beyond these schema definitions, so baseline score of 3 is appropriate.
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 tool dumps the entire OmniFocus database, listing covered entities (inbox, projects, folders, tags, perspectives). It distinguishes from sibling tools like list_tasks or get_project by emphasizing full context retrieval.
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 mentions it's 'essential for getting full context,' implying use when comprehensive data is needed. However, it lacks explicit guidance on when not to use it (e.g., for targeted queries) or alternatives like the more specific get/list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Duplicate one or more tasks, optionally into a different project
| Name | Required | Description | Default |
|---|---|---|---|
| taskIds | Yes | Task IDs to duplicate | |
| projectId | No | Destination project ID | |
| projectName | No | Destination project name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must fully disclose behavior. It only states 'duplicate', but does not explain side effects (e.g., preserving subtasks, dependencies) or whether original tasks remain unchanged.
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?
Single sentence, front-loaded with action. Every word is meaningful, no redundancy.
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 no output schema and no annotations, the description is adequate for a simple duplicate action but lacks details on behavior when destination project doesn't exist or on handling of nested structures.
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. Description adds minor context ('one or more', 'optionally into a different project') but does not significantly enrich beyond schema.
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 verb (duplicate), resource (tasks), and optional scope (into a different project). It differentiates from siblings like move_tasks or batch_create_tasks.
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?
Usage is implied but no explicit guidance on when to use this vs. alternatives like move_tasks or batch_create_tasks. No exclusions or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a summary of the OmniFocus database including counts of inbox items, projects, tags, folders, available/due-soon/overdue/flagged tasks
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It indicates a read-only operation without destructive effects. It could mention that no modifications occur, but the description is sufficient for safe inference.
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, concise sentence that immediately conveys the tool's purpose and scope. Every word adds value, and there is no redundancy.
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 simple, zero-parameter tool with no output schema, the description is complete. It lists all entities summarized, giving the agent full understanding of the return content.
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?
There are no parameters, so the description cannot add meaning beyond the schema. The baseline score of 4 is appropriate as the description is clear about what the tool does despite zero parameters.
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 tool retrieves a summary of the OmniFocus database, specifying exactly which counts are included (inbox items, projects, tags, etc.). This distinguishes it from sibling tools that get individual entities or task lists.
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 for obtaining an overview rather than detailed data. While not explicitly stating when not to use it, the sibling tools (e.g., get_inbox_tasks, get_flagged_tasks) provide alternatives for specific details, making the context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all available flagged tasks
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a read operation but provides no additional behavioral details. With no annotations, it fails to disclose potential side effects, rate limits, or data limitations, such as whether pagination or sorting is supported.
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 concise at one sentence, but its brevity sacrifices clarity. It is appropriately sized for a simple tool but could benefit from more context.
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 lack of annotations, output schema, and parameter details, the description is incomplete. It does not explain what constitutes a 'flagged' task, how results are ordered, or if there are any limits on the number of tasks returned.
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 zero parameters and 100% coverage, so the description does not need to explain parameters. However, it adds minimal semantic value beyond the tool name by stating 'all available' flagged tasks.
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 tool retrieves 'flagged tasks', which is distinct from sibling tools like 'list_tasks' or 'get_inbox_tasks'. However, it does not specify what 'flagged' means or if there are any filtering criteria.
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 guidance is provided on when to use this tool versus alternatives. The description does not mention use cases, prerequisites, or situations where another tool would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a folder including its child folders and projects
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The folder ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It clearly indicates a read operation, but does not disclose potential limitations like access requirements or whether child items are retrieved recursively. Adequate for a simple get, but could be more explicit.
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?
Single sentence, front-loaded with verb and resource, no extraneous words. Efficient and clear.
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 simple read tool with one parameter and no output schema, the description adequately explains purpose and return scope. Could mention if children are one level deep or recursive, but overall sufficient.
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 covers the single 'id' parameter with 100% coverage. Description adds semantic value by stating the output includes child folders and projects, which goes beyond the schema and aids agent understanding of return content.
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?
Clear verb (Get) and resource (folder) with specific inclusion of child folders and projects, distinguishing it from siblings like create_folder, delete_folder, update_folder, list_folders.
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?
Description implies use when detailed folder info is needed, but does not explicitly state when to use versus alternatives like list_folders or get_project. No exclusions or when-not guidance provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all tasks currently in the OmniFocus inbox (not yet assigned to a project)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It clearly states read-only behavior (Get) and scope (inbox, unassigned). No hidden side effects. However, it does not disclose pagination or volume limits, but for a simple 0-param tool this is adequate.
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?
Single, well-structured sentence with no extraneous words. Front-loads the action and resource.
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 simple 0-parameter tool with no output schema, the description fully explains what the tool returns. No missing critical information given the low complexity.
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?
No parameters exist (schema coverage 100%). Description adds meaning by explaining what 'inbox tasks' are, which is beyond the empty schema. Baseline of 4 for 0-parameter tools applies.
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 uses specific verb 'Get' and resource 'tasks in the OmniFocus inbox' with a clarifying parenthetical 'not yet assigned to a project'. It clearly distinguishes from sibling tools like get_task, list_tasks, and get_flagged_tasks.
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 use when needing inbox tasks but provides no explicit guidance on when not to use or alternatives among many related sibling tools (e.g., list_tasks, get_flagged_tasks). Scored at minimum viable due to lack of exclusion context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get tasks shown in a specific custom perspective. Built-in perspectives (Inbox, Forecast, etc.) are not supported — use dedicated tools instead.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The perspective name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states 'get tasks' which implies a read operation, but does not disclose any behavioral traits such as whether results are filtered, sorted, or limited, nor any authorization requirements. The description adds little beyond the name.
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 no fluff. The first sentence states the primary function, the second provides crucial usage guidance. Every word earns its place.
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 simplicity (1 required parameter, no output schema, no nested objects), the description is adequate but not complete. It does not explain what 'tasks shown' means (e.g., all tasks visible in that perspective) nor what the output format is. For a straightforward tool, this is acceptable but could be expanded.
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% for the single parameter 'name', which is described as 'The perspective name'. The description does not add any extra meaning, e.g., case sensitivity, format, or how to find names. Baseline of 3 is appropriate for complete schema coverage with no additional detail.
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 tool retrieves tasks from a custom perspective. It explicitly distinguishes from built-in perspectives by naming them (Inbox, Forecast) and directing to dedicated tools, which differentiates it from siblings like get_inbox_tasks.
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 explicitly tells when to use this tool (custom perspectives) and when not to (built-in perspectives), even naming alternative tools. This is precise and helpful for agent decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific project by ID or name
| Name | Required | Description | Default |
|---|---|---|---|
| idOrName | Yes | The project ID or exact name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Describes return of detailed information but does not disclose read-only nature, auth needs, or side effects. Minimum behavioral context.
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?
Single sentence, efficient and informative. No wasted words. Could be slightly improved by front-loading the key action, but already clear.
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 a single parameter and no output schema, description sufficiently explains what the tool does and how to identify the project. Missing details on output format but adequate for a simple getter.
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% with one parameter described as 'The project ID or exact name'. Description adds no new meaning beyond the schema, merely restating 'by ID or name'. Baseline 3 applies.
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?
Description clearly states 'Get detailed information about a specific project by ID or name', specifying verb, resource, and identification method. Distinguished from siblings like 'list_projects' and 'get_project_tasks'.
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?
Description implies use when needing detailed info on one project, but no explicit guidance on when to use alternatives or when not to use it. Does not mention exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all tasks belonging to a specific project
| Name | Required | Description | Default |
|---|---|---|---|
| projectId | Yes | The project ID | |
| includeCompleted | No | Include completed/dropped tasks (default false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for disclosing behavioral traits. However, it only states the purpose and does not mention that this is a read-only operation, authentication requirements, pagination, error behavior, or any side effects. The description is insufficient for safe autonomous use.
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 concise sentence that front-loads the main purpose. It avoids unnecessary words, but could potentially include a brief note about the optional parameter without losing conciseness.
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 simple retrieval tool with 2 parameters, the description covers the basic need but lacks details such as whether results are paginated, sorted, or if authentication is required. Given the absence of output schema and annotations, the description is adequate but not complete.
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 input schema already provides full coverage (100%) with descriptions for both parameters. The description adds no additional meaning beyond the schema. Baseline score of 3 is appropriate as the description does not need to compensate further.
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 'Get all tasks belonging to a specific project' clearly states a specific action (get) and resource (tasks of a project). It distinguishes itself from sibling tools like 'list_tasks' which likely have broader scope. The purpose is immediately understandable.
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 provides no guidance on when to use this tool versus alternatives like 'list_tasks' or 'get_task'. There are no exclusions, prerequisites, or context about when it might be inappropriate to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get projects that are due for review
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. The description only states the purpose without revealing any behavioral traits (e.g., read-only nature, potential side effects, authorization needs). For a simple retrieval tool, more context would be helpful.
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, concise sentence that immediately conveys the tool's purpose. It is front-loaded and contains no extraneous information.
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 has no parameters and no output schema, the description is minimally adequate. However, it does not explain what 'due for review' means or what the output contains. It could be improved by clarifying the output format or linking to related tools like 'mark_reviewed'.
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 input schema has no parameters, and schema coverage is 100% (implicitly). Since baseline for 0 parameters is 4, the description does not need to add parameter information. The description is adequate for the parameterless context.
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 tool retrieves a specific subset of projects ('due for review'). It uses a specific verb ('Get') and resource ('projects due for review'), distinguishing it from sibling tools like 'list_projects' or 'get_project'.
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 usage guidance is provided. The description does not indicate when to use this tool versus alternatives, such as 'list_projects' for all projects or 'mark_reviewed' after review. The context is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a tag including its child tags
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The tag ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must explain behavior. It only states what it does (get details) without specifying what those details include (e.g., name, color, metadata), whether it is read-only, or any side effects.
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 sentence that conveys the core purpose efficiently with no superfluous words.
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 simple tool with one parameter and no output schema, the minimal description is adequate but could be enhanced with examples or return value hints. It meets basic needs without being comprehensive.
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% with a single 'id' parameter described as 'The tag ID'. The description adds no extra meaning beyond the schema, so baseline 3 is appropriate.
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 verb 'get' and resource 'tag' are clear. Including 'child tags' provides differentiation from basic tag retrieval. However, it doesn't explicitly distinguish from sibling tools like list_tags or get_task.
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 guidance on when to use this tool vs alternatives such as list_tags for a list of tags or get_project for project details. The agent is left to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific task by its ID, optionally including subtask hierarchy
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The task ID | |
| includeChildren | No | Include subtask tree (default false) | |
| maxDepth | No | Max subtask depth (0 = unlimited) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral burden. It mentions the option to include subtask hierarchy but does not specify what 'detailed information' entails (e.g., fields returned). The description is adequate but lacks specifics expected given no annotations.
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, front-loaded sentence that efficiently conveys the tool's purpose and optional behavior. No unnecessary words.
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?
With no output schema, the description omits any information about the return value structure. The tool has 3 parameters, and the description covers them via schema, but the output is completely unspecified, leaving a significant gap in completeness.
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 input schema has 100% description coverage, so the description adds no new meaning beyond the schema. The baseline is 3 as per rules; no extra value is contributed.
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 tool retrieves detailed information about a specific task by ID, with optional subtask hierarchy inclusion. It uses a specific verb and resource, and implicitly distinguishes from sibling tools like list_tasks or get_task_count that retrieve multiple tasks or summaries.
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 when detailed info on a single task is needed, but provides no explicit context on when to prefer this over similar tools like get_task_count, list_tasks, or get_project_tasks. No guidance on when to include children or not is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get count of tasks matching filters without fetching full data. Faster than list_tasks when you only need the count.
| Name | Required | Description | Default |
|---|---|---|---|
| completed | No | Filter by completion status | |
| flagged | No | Filter by flagged status | |
| available | No | Only count available (actionable) tasks | |
| inInbox | No | Only count inbox tasks | |
| projectId | No | Filter by project ID | |
| projectName | No | Filter by project name | |
| tagNames | No | Filter by tag names (all must match) | |
| dueAfter | No | Filter tasks due after this ISO date | |
| dueBefore | No | Filter tasks due before this ISO date | |
| deferAfter | No | Filter tasks deferred after this ISO date | |
| deferBefore | No | Filter tasks deferred before this ISO date | |
| plannedAfter | No | Filter tasks planned after this ISO date | |
| plannedBefore | No | Filter tasks planned before this ISO date | |
| search | No | Full-text search in task name and note | |
| taskStatus | No | Filter by task status |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the key behavioral trait: it returns a count without fetching full data, implying a lightweight, read-only operation. However, it does not specify the exact return format (e.g., integer) or mention potential edge cases like empty results.
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 two sentences, highly efficient, and front-loaded with the core action. Every word serves a purpose: stating the action, contrasting with an alternative, and providing a performance benefit.
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 the clear purpose and parameter coverage, the description lacks specification of the return value. Since there is no output schema, the agent is left guessing whether the count is a number, string, or object. For a tool with many parameters and a simple output, this omission harms completeness.
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 all 15 parameters already have descriptions. The tool description adds no further semantic details about parameters. It meets the baseline but does not exceed it.
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 tool's function: 'Get count of tasks matching filters without fetching full data.' It uses a specific verb ('get count') and resource ('tasks'), and distinguishes from the sibling tool 'list_tasks' by noting it's for when only the count is needed.
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 explicitly advises when to use this tool: 'Faster than list_tasks when you only need the count.' This provides clear guidance and implicitly warns against using it when full task data is required. No explicit exclusions, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all tasks completed today
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 only states what the tool does, not any side effects, permissions needed, or invariants. For a read operation, it is safe, but the lack of detail (e.g., 'read-only', 'no side effects') limits transparency.
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 appropriately concise for a simple tool, though it could be slightly more informative (e.g., defining 'completed today'). Still, it earns a high score for brevity.
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 simplicity (no parameters, no output schema), the minimal description is adequate but not complete. It fails to define 'completed today' (e.g., tasks with a completion date equal to today's date). Among many sibling tools, more context would help the agent decide when to use this tool.
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 input schema is empty, meaning no parameters. Since there are no parameters, the description does not need to elaborate. According to guidelines, a tool with 0 parameters has a baseline score of 4. The description does not contradict or miss any parameter details.
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 'Get all tasks completed today' clearly states the tool retrieves tasks completed today. It matches the tool name closely and is unambiguous. However, it does not differentiate from sibling tools like 'get_inbox_tasks' or 'list_tasks', which lowers the score from 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 guidance is provided on when to use this tool versus alternatives such as 'complete_task' or 'get_flagged_tasks'. The description lacks any contextual or preferential information, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all folders in OmniFocus
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only states 'List all folders' without indicating performance, ordering, or any side effects. This is insufficient.
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 sentence, very concise. It is front-loaded and contains no waste, though it could add more context without becoming verbose.
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 that there are no parameters, no output schema, and the operation is simple, the description is minimally adequate. However, it lacks details like what a 'folder' object contains or return format, so completeness is mediocre.
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?
There are zero parameters, so the description carries no burden for parameter information. The baseline for 0 params is 4, and the description meets that.
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 'List all folders in OmniFocus' clearly states what the tool does: listing folders. However, it does not differentiate from sibling tools like 'list_projects' or 'list_tags', which have similar patterns.
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 provides no guidance on when to use this tool versus alternatives (e.g., 'get_folder' for a single folder) or any prerequisites. The agent receives no usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List custom perspectives in OmniFocus. Built-in perspectives (Inbox, Projects, Tags, Forecast, Flagged, Review, Nearby) are not enumerable via the API — use dedicated tools instead (get_inbox_tasks, get_flagged_tasks, get_review_queue, list_projects, list_tags, or list_tasks with date filters for Forecast).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It discloses that built-in perspectives are not enumerable, but doesn't detail return format or side effects. Still, it adds valuable behavioral context beyond the schema.
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 compact sentences. First sentence states purpose; second provides exclusions and alternatives. No filler, every word earns its place.
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 tool with no parameters and no output schema, the description fully covers what the tool does, what it excludes, and how to access excluded items. No gaps.
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?
No parameters exist, so the description needs no parameter info. With 100% schema coverage, baseline is 3, but zero parameters raise the bar; description provides no param details, which is fine.
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 specifies the verb 'List' and the resource 'custom perspectives in OmniFocus'. It directly distinguishes from built-in perspectives by naming them and referencing dedicated sibling tools.
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?
Explicitly states when to use this tool (for custom perspectives) and when not to (for built-in perspectives). It names exact alternative tools, providing clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List projects from OmniFocus with optional filters for status, folder, and text search
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Filter by project status | |
| folderId | No | Filter by containing folder ID | |
| folderName | No | Filter by containing folder name | |
| search | No | Full-text search in project name and note | |
| limit | No | Maximum results (default 100) | |
| offset | No | Skip this many results |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description should disclose behavioral traits like read-only, pagination, or ordering. It only states it lists projects with filters, omitting any side-effect or performance details.
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, well-structured sentence that front-loads the verb and resource. It is appropriately concise for a simple list tool, though it could include minimal guidance.
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?
With 6 parameters and no output schema, the description covers the basic purpose but does not explain the return format, default limit, or how folder filters work (ID vs name). It is partially complete.
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 summarizes filters ('status, folder, and text search') but adds no extra meaning beyond what the schema already provides for each parameter.
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 verb 'list', the resource 'projects', the source 'OmniFocus', and optional filters. It distinguishes itself from sibling tools like 'get_project' (single project) and 'list_folders' (different entity).
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 lacks guidance on when to use this tool versus alternatives. It does not mention when not to use it (e.g., for a single project) or suggest sibling tools like 'get_project' for specific lookups.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all tags in OmniFocus
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and description lacks behavioral details such as return format, ordering, or pagination. It only states the basic operation.
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?
Single sentence is concise and front-loaded, but extremely minimal.
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 simple list-all operation with no parameters, the description covers the essential purpose. However, lacks return value details since no output schema exists.
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?
No parameters exist, so schema coverage is 100%. Per rubric, baseline is 4 for zero-parameter tools.
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?
Description clearly states the verb 'List' and resource 'tags', and is distinguishable from siblings like 'get_tag' which retrieves a single tag.
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?
Implies usage for listing all tags, but no explicit guidance on when to use over alternatives like 'get_tag' or 'search' tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all notifications/reminders on a task
| Name | Required | Description | Default |
|---|---|---|---|
| taskId | Yes | The task ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states the operation without disclosing behavioral traits like read-only nature, side effects, or authorization 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?
The description is a single, clear sentence that is front-loaded and efficient with no wasted words.
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 simple list operation with one parameter and no output schema, the description is minimally adequate but lacks usage guidance and behavioral details.
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% with one parameter, and the description adds no additional meaning beyond what the schema provides. Baseline score of 3 is appropriate.
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 tool lists all notifications/reminders on a task, using a specific verb and resource. It distinguishes from sibling tools like add_task_notification and remove_task_notification.
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 provides no guidance on when to use this tool versus alternatives, such as add_task_notification or remove_task_notification. No when-to-use or when-not-to-use context is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tasks from OmniFocus with optional filters for status, flags, tags, projects, date ranges, and text search
| Name | Required | Description | Default |
|---|---|---|---|
| completed | No | Filter by completion status | |
| flagged | No | Filter by flagged status | |
| available | No | Only show available (actionable) tasks | |
| inInbox | No | Only show inbox tasks | |
| projectId | No | Filter by project ID | |
| projectName | No | Filter by project name | |
| tagNames | No | Filter by tag names (all must match) | |
| dueAfter | No | Filter tasks due after this ISO date | |
| dueBefore | No | Filter tasks due before this ISO date | |
| deferAfter | No | Filter tasks deferred after this ISO date | |
| deferBefore | No | Filter tasks deferred before this ISO date | |
| plannedAfter | No | Filter tasks planned after this ISO date | |
| plannedBefore | No | Filter tasks planned before this ISO date | |
| search | No | Full-text search in task name and note | |
| taskStatus | No | Filter by task status | |
| limit | No | Maximum results (default 100) | |
| offset | No | Skip this many results |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states it lists tasks (a read operation) but does not disclose behavioral traits like pagination behavior (beyond limit/offset in schema), how filters combine (AND/OR), or any side effects. The description is partially transparent but lacks explicit detail.
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 sentence of 16 words, efficiently front-loading the core action and essential details. No extraneous or redundant information.
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 has 17 parameters and no output schema or annotations, the description is too sparse. It does not explain the return structure, default sorting, or how multiple filters interact. For a complex listing tool, this leaves significant gaps for an AI agent.
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 input schema has 100% description coverage, so each parameter is already documented. The description only loosely summarizes the filters ('status, flags, tags, projects, date ranges, and text search') without adding new semantic meaning or clarifying combination logic. With high schema coverage, a baseline of 3 is appropriate.
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 verb 'list', the resource 'tasks', and the source 'OmniFocus'. It lists the available filters, making the purpose unmistakable. This distinguishes it from sibling tools like get_task (single task) or create_task (mutation).
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 it is for general listing with filters, but it does not explicitly guide when to use this vs. more specific sibling tools like get_project_tasks, get_inbox_tasks, or get_flagged_tasks. There is no mention of when not to use or what alternatives exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a project as reviewed, advancing its next review date
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The project ID to mark as reviewed |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry full burden. It mentions advancing review date but lacks details on side effects, permissions, or reversibility.
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?
Single sentence, front-loaded, no wasted words.
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?
Lacks context about review cycle, idempotency, or outcomes; no output schema; potential confusion with 'complete_project' not addressed.
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 covers 100% of parameters with clear description of 'id'. Description adds no extra meaning beyond what schema provides.
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?
Description clearly states the action (mark as reviewed) and the effect (advancing next review date), distinguishing it from siblings like 'complete_project'.
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 explicit when-to-use or when-not-to-use; usage is implied but no guidance on alternatives or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move a project to a different folder
| Name | Required | Description | Default |
|---|---|---|---|
| projectId | Yes | The project ID to move | |
| folderId | Yes | The destination folder ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only states the action, omitting side effects (e.g., moving tasks within the project, timestamp updates), permissions, or return value. This is insufficient for a mutation tool.
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 very short and to the point, using minimal words. However, for a mutation tool, it could include more detail without being verbose.
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 lack of annotations and output schema, the description should provide more context about the operation's effects and expected outcomes. It is too minimal to fully inform an AI agent.
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% and already describes both parameters. The description adds no extra meaning beyond what the schema provides, so it meets the baseline of 3.
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 'Move' and the resource 'project' with destination 'to a different folder'. It effectively distinguishes from sibling tools like create_project (creates new) or update_project (modifies settings).
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 when a project's folder needs changing, but it does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives like move_tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move one or more tasks to a different project or parent task. Omit destination to move to inbox.
| Name | Required | Description | Default |
|---|---|---|---|
| taskIds | Yes | Task IDs to move | |
| projectId | No | Destination project ID | |
| projectName | No | Destination project name | |
| parentTaskId | No | Destination parent task ID (for subtasks) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so description must disclose behavioral traits. It indicates location change but lacks details on atomicity, subtask handling, or required permissions. Adequate but could be more explicit.
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 sentences perfectly front-load the primary action and a key usage variant. No wasted words.
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?
With 4 parameters and no output schema, description covers core function but omits return value info. It is adequate for a straightforward move operation but could mention response type.
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 covers all parameters with descriptions. Description adds insight: omitting destination moves to inbox, which is not inferable from schema alone. High schema coverage (100%) maintains baseline, but the added inbox behavior justifies a higher score.
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?
Description clearly states the action (move), resource (tasks), and distinguishes between moving to a project/parent vs. inbox. It stands out from sibling tools like 'move_project' and batch operations.
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?
Explicitly mentions when to use (move to different project or parent task) and when to omit destination (move to inbox). However, it does not specify exclusions or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a specific notification from a task
| Name | Required | Description | Default |
|---|---|---|---|
| taskId | Yes | The task ID | |
| notificationId | Yes | The notification ID to remove |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as permanence, side effects, or authorization requirements. The minimal description lacks necessary transparency.
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 concise sentence, 5 words, with no superfluous information. It is efficient but might be overly terse for a tool with no annotations.
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 simplicity (2 parameters, no output schema), the description provides the essential purpose. However, it lacks details on return values, error conditions, or post-removal state, leaving some gaps.
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 input schema provides full descriptions for both parameters (taskId, notificationId), achieving 100% coverage. However, the description adds no extra context about how to obtain the notification ID or format constraints.
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 (remove) and the resource (notification from a task), distinguishing it from sibling tools like add_task_notification and list_task_notifications.
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 guidance on when to use this tool versus alternatives such as add_task_notification or list_task_notifications. No prerequisites or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Explicitly save the OmniFocus database to disk
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states the basic purpose. It does not disclose behavioral details like whether it is required before closing, what happens on failure, or if it is idempotent.
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 unnecessary words, providing immediate understanding of the tool's purpose.
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?
While the tool is simple, the description lacks context such as prerequisites (e.g., database must be open) or confirmation of what 'save' entails (e.g., writes all pending changes). For a minimal tool, it is adequate but not complete.
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 tool has zero parameters, so the baseline is 4. No parameter description is needed, and the description adds no additional parameter semantics beyond the empty schema.
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 (explicitly save) and the resource (OmniFocus database), distinguishing it from sibling tools like sync_database and dump_database.
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 guidance is provided on when to use this tool versus alternatives such as sync_database or how it fits into a workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search across all OmniFocus items (tasks, projects, folders, tags) by name or note content
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query string | |
| limit | No | Maximum number of results (default 50) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description does not disclose return format, pagination, search behavior (e.g., fuzzy matching, case sensitivity), or any limitations. Fails to carry the full burden of behavioral disclosure.
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?
Single sentence that is front-loaded with the action and resource. No unnecessary words; every part is information-dense.
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?
Lacks details on return structure, which is critical since no output schema exists. Also missing search behavior details (e.g., exact match vs full-text, boolean operators). Incomplete for a general search tool in a rich ecosystem.
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% with clear descriptions for both parameters. The description adds value by specifying the search scope ('by name or note content') for the query parameter, which is not in the schema. The limit parameter is adequately described in the schema, so the description contributes moderately.
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 verb 'Search' and the resource 'all OmniFocus items' (tasks, projects, folders, tags) and includes the search scope 'by name or note content'. It distinguishes this general search from specific sibling tools like get_task or get_project.
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 guidance on when to use this tool versus alternatives like get_task, get_project, or get_flagged_tasks. Lacks context on preferred scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set, add, or remove tags on a task
| Name | Required | Description | Default |
|---|---|---|---|
| taskId | Yes | The task ID | |
| tagNames | Yes | Tag names to set/add/remove | |
| mode | Yes | How to modify tags: replace all, add to existing, or remove specific tags |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry full behavioral burden. It only says 'set, add, or remove' which mirrors the schema's mode enum. It does not disclose any side effects, permissions, atomicity, or failure behaviors. The description adds minimal value beyond the schema.
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, concise sentence that is front-loaded with the essential information. No wasted words. It is appropriately sized for the tool's simplicity.
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 has 3 required parameters and no output schema or annotations, the description is too minimal. It does not explain return behavior, error handling, or prerequisites. A more complete description would include typical use cases or constraints.
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 parameters are well-documented in the schema. The description ('tags on a task') adds no extra meaning beyond what the parameter descriptions already provide. Baseline 3 is appropriate.
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 verb and resource: 'Set, add, or remove tags on a task'. It distinguishes from sibling tools like create_tag (which creates a new tag entity) and update_task (which updates task fields). The action is specific and 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?
No guidance on when to use this tool vs alternatives like update_task or append_task_note. There is no mention of prerequisites, context, or scenarios. The description is purely operational.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Trigger an OmniFocus sync to push local changes to OmniSync and pull updates from other devices. CALL THIS ONCE at the end of any session that mutated data — especially after batch_create_tasks, batch_complete_tasks, batch_delete_tasks, or any sequence of multiple create/update/delete/move operations. Do NOT call after every individual mutation; sync once at the end of the chain. Returns immediately while sync runs in the background.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses background execution and immediate return, and implies it is safe to call once per session. Lacks potential details like concurrency behavior, but adequate.
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?
Three sentences, front-loaded with purpose and usage, no wasted words. Every sentence adds value.
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 zero-param tool with no output schema, the description fully covers what, when, how, and return behavior. References sibling tools for proper usage context.
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?
No parameters in schema (0 params, coverage 100%), so baseline is 4. Description does not add param info, but none needed.
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 tool triggers an OmniFocus sync to push/pull changes, and specifically distinguishes it from sibling mutation tools by emphasizing it is a synchronization action, not a data mutation.
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?
Explicitly says 'CALL THIS ONCE at the end of any session that mutated data' and provides examples of when (after batch operations) and when not (after individual mutations). Also explains it returns immediately while sync runs in background.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a completed task as incomplete (re-open it)
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The task ID to uncomplete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It correctly indicates a mutation (re-opens), but fails to disclose any side effects, permissions needed, or constraints like the task must already be completed.
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 concise sentence with no unnecessary words or repetition, efficiently conveying the core action.
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 simple tool with one parameter and no output schema, the description is sufficient. It explains the action clearly, though it could mention that the task must be in a completed state. Overall, it provides enough context for an agent to invoke the tool 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?
The only parameter 'id' is fully described in the schema (100% coverage). The description adds no additional meaning beyond what the schema already provides, meeting the baseline.
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 verb 'Mark' and the resource 'completed task' with the result 'as incomplete (re-open it)', making the purpose unambiguous. It also implicitly distinguishes from the sibling tool 'complete_task'.
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 provides no explicit guidance on when to use this tool vs alternatives. It implies usage for reopening completed tasks but does not mention prerequisites (e.g., task must be completed) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a folder's properties
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The folder ID | |
| name | No | New folder name | |
| status | No | New folder status |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states 'update' without disclosing behavioral traits like immediate effect, required permissions, reversibility, or side effects of changing status to 'dropped'.
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 concise sentence with clear verb and resource. It is appropriately sized for a simple tool, though it could benefit from minimal context.
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 no output schema, the description is incomplete. It does not explain return values, side effects (e.g., dropping a folder), or implications of status changes. More context is needed for safe and 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?
Schema coverage is 100% with descriptions for id, name, and status. The description adds no additional meaning beyond the schema, so baseline 3 is appropriate.
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 'Update a folder's properties' clearly specifies the action (update) and the resource (folder), distinguishing it from sibling tools like create_folder, delete_folder, get_folder, and list_folders.
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 provides no guidance on when to use this tool versus alternatives, such as when to use update_project or batch operations. No usage context or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update properties of an existing project
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The project ID | |
| name | No | New project name | |
| note | No | New project note | |
| status | No | New project status | |
| sequential | No | Whether tasks must be completed in order | |
| singleActionList | No | Whether this is a single-action list | |
| completedByChildren | No | Auto-complete when all children are completed | |
| deferDate | No | New defer date (ISO 8601) or null to clear | |
| dueDate | No | New due date (ISO 8601) or null to clear | |
| plannedDate | No | New planned date (ISO 8601) or null to clear | |
| flagged | No | New flagged status | |
| reviewInterval | No | New review interval |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey behavioral traits. It only states 'update properties' without disclosing idempotency, error handling (e.g., if project not found), or whether it's a partial or full update. No mention of permissions or side effects.
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 short sentence, making it concise. However, it could be improved by front-loading key info like partial update or required fields. Still efficient with no wasted words.
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 12 parameters and no output schema, the description is too sparse. It fails to mention that only 'id' is required, that others are optional, or that updates are partial. It also doesn't specify return value or error behavior. Incomplete for a mutation tool.
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% with detailed descriptions for each parameter. The description adds no extra meaning beyond what the schema provides, so baseline 3 is appropriate. No clarification on optionality beyond schema required field.
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 tool updates properties of an existing project, using a specific verb ('update') and resource ('project'). This distinguishes it from siblings like create_project, delete_project, complete_project, drop_project, and move_project.
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 for modifying project properties but provides no explicit guidance on when to use this tool versus alternatives like complete_project (for finishing) or drop_project (for canceling). There is no when-not-to-use or context for partial updates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a tag's properties
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The tag ID | |
| name | No | New tag name | |
| allowsNextAction | No | Whether tasks with this tag can be next actions | |
| status | No | New tag status |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits like authentication needs, effects of updates, or error responses, but it only states the action without elaboration.
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, front-loaded sentence with no unnecessary words, making it extremely concise.
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?
The description lacks details on return values, side effects, or behavior in edge cases (e.g., invalid ID), leaving gaps for a mutation tool.
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?
Since schema coverage is 100%, the description adds no extra meaning beyond the schema, meeting the baseline but not exceeding it.
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 'Update a tag's properties' clearly states the action (update) and the resource (tag properties), distinguishing it from sibling tools like create_tag and delete_tag.
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 guidance is provided on when to use this tool vs alternatives, such as create_tag or delete_tag, nor any conditions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update properties of an existing task
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The task ID to update | |
| name | No | New task name | |
| note | No | New task note | |
| flagged | No | New flagged status | |
| deferDate | No | New defer date (ISO 8601) or null to clear | |
| dueDate | No | New due date (ISO 8601) or null to clear | |
| plannedDate | No | New planned date (ISO 8601) or null to clear | |
| estimatedMinutes | No | New estimated minutes or null to clear | |
| sequential | No | Whether subtasks must be completed in order | |
| completedByChildren | No | Auto-complete when all children are completed | |
| repetitionRule | No | Repetition rule or null to clear |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral details such as whether updates are partial, what happens on failure, or any side effects. The word 'update' implies mutation, but nothing more.
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 sentence, which is concise and front-loaded. However, it could be expanded slightly to include more context without becoming verbose.
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 complexity (11 parameters, no output schema, multiple date/null fields), the description is too minimal. It fails to mention partial update behavior, return values, or prerequisites.
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 input schema has 100% coverage descriptions for all 11 parameters, so the description adds no additional semantic value. Baseline 3 is appropriate.
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 verb 'update' and the resource 'existing task', making the tool's purpose unambiguous and distinct from sibling tools like complete_task or delete_task.
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 provides no guidance on when to use this tool versus alternatives (e.g., batch update, complete_task). It lacks context for when an update is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.2.0add_task_notificationappend_task_notebatch_complete_tasksbatch_create_tasksbatch_delete_taskscomplete_projectcomplete_taskconvert_task_to_projectcreate_foldercreate_projectcreate_tagcreate_taskdelete_folderdelete_projectdelete_tagdelete_taskdrop_projectdrop_taskdump_databaseduplicate_tasksget_database_summaryget_flagged_tasksget_folderget_inbox_tasksget_perspective_tasksget_projectget_project_tasksget_review_queueget_tagget_taskget_task_countget_today_completed_taskslist_folderslist_perspectiveslist_projectslist_tagslist_task_notificationslist_tasksmark_reviewedmove_projectmove_tasksremove_task_notificationsave_databasesearchset_task_tagssync_databaseuncomplete_taskupdate_folderupdate_projectupdate_tagupdate_taskScored across 51 tools
Each tool targets a specific action on a specific entity (task, project, folder, tag, notification) with clear descriptions. Even related tools like 'complete_task' and 'batch_complete_tasks' are easily distinguished by scope and intent.
All tool names follow a consistent verb_noun pattern (e.g., create_task, delete_folder, sync_database) with no mixing of styles. The naming is predictable and clear.
With 51 tools, the set is extremely large. While the domain (OmniFocus) is complex, many tools are batch variants or duplicate operations (e.g., complete_task and batch_complete_tasks). This exceeds typical well-scoped tool sets and may overwhelm agents.
The tool set covers all major CRUD operations for tasks, projects, folders, and tags, plus batch operations, notifications, tags, search, sync, and review. There are no obvious gaps for managing an OmniFocus database.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Official Todoist MCP server for AI assistants to manage tasks, projects, and workflows.
Hosted MCP server connecting AI assistants to 9,000+ apps and 40,000+ actions via Zapier.
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
