Click on "Install 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., "@codex-omnifocus-mcp Add a task to review design doc due Friday"
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.
Local Codex-focused MCP server for OmniFocus on macOS.
This project starts from omnifocus-mcp-enhanced and adds Codex-oriented server instructions, MCP resources, compact query tools, tag tools, clean shutdown, logging, and write audit logging.
This repository is the source code for a local MCP server. It is not a hosted web service and it does not run a central cloud server.
Each user installs this repo on their own Mac. Codex starts the MCP server locally with Node.js, talks to it over stdio, and the server reads or updates the user's local OmniFocus database through AppleScript/JXA.
In short:
Codex -> local MCP stdio -> node dist/server.js -> AppleScript/JXA -> OmniFocusThe GitHub repo's role is distribution: source code, docs, install scripts, tests, and release history.
Related MCP server: OmniFocus MCP Server
git clone https://github.com/phd-peter/codex-omnifocus-mcp.git ~/.local/share/codex-omnifocus-mcp
cd ~/.local/share/codex-omnifocus-mcp
scripts/install-codex.shTo clone from a script-driven install after downloading this script separately:
CODEX_OMNIFOCUS_REPO_URL=https://github.com/phd-peter/codex-omnifocus-mcp.git scripts/install-codex.shThe installer runs npm ci, builds the TypeScript output, and registers the MCP server with Codex:
codex mcp add codex-omnifocus -- node /path/to/codex-omnifocus-mcp/dist/server.jsIf Codex does not show the new tools immediately, restart Codex or open a new Codex session.
npm install
npm run build
codex mcp add codex-omnifocus -- node "$PWD/dist/server.js"The server is intended for local use. package.json remains marked private as an npm publishing guard; the GitHub repository can still be public.
Useful commands:
npm test
npm run build
npm run preflight
npm run register:codexThis repo provides the shared MCP server and the default Codex tool-use guidance in skills/codex-omnifocus/SKILL.md. Your personal agent behavior should live in a separate AGENTS.md so each user can define their own OmniFocus system without changing the server.
Start from the template:
cp AGENTS.example.md AGENTS.mdThen edit AGENTS.md for your own workflow:
default capture destination
tags and custom perspectives
due/defer date habits
daily planning and weekly review style
when the agent may write directly and when it should ask first
Personal AGENTS.md files are ignored by default because they can include sensitive project names, routines, or decision rules.
Write tools append JSONL entries to:
~/.codex/codex-omnifocus-mcp/audit/YYYY-MM-DD.jsonlOverride the directory with:
export CODEX_OMNIFOCUS_AUDIT_DIR=/path/to/auditAudited tools:
add_omnifocus_task
add_project
edit_item
move_task
remove_item
batch_add_items
batch_remove_items
create_tag
npm test
npm run build
npm audit --omit=devOmniFocus integration tests should be run manually with OmniFocus open on macOS.
See PRIVACY.md. Audit logs and OmniFocus exports can contain private task, project, tag, date, and note data. Do not commit backups/, exports/, .env*, audit/, or *.jsonl.
See docs/architecture.md for the local runtime model and trust boundary.
See docs/distribution.md for the public GitHub, local-first release strategy.
See docs/marketing.md for launch positioning, channels, content ideas, and the first 30 days of public distribution work.
See NOTICE.md for upstream attribution.
Create a NEW task in OmniFocus. Search first when a matching task may already exist; move/edit existing tasks instead of duplicating them.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name of the task | |
| note | No | Additional notes for the task | |
| dueDate | No | The due date of the task in ISO format (YYYY-MM-DD or full ISO date) | |
| deferDate | No | The defer date of the task in ISO format (YYYY-MM-DD or full ISO date) | |
| plannedDate | No | The planned date of the task in ISO format (YYYY-MM-DD or full ISO date) | |
| flagged | No | Whether the task is flagged or not | |
| estimatedMinutes | No | Estimated time to complete the task, in minutes | |
| tags | No | Tags to assign to the task | |
| projectName | No | The name of the project to add the task to (will add to inbox if not specified) | |
| parentTaskId | No | The ID of the parent task to create this task as a subtask | |
| parentTaskName | No | The name of the parent task to create this task as a subtask (alternative to parentTaskId) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It only says 'create' but lacks details on side effects, auth requirements, error handling, or idempotency. Minimal disclosure 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?
Two sentences, no waste, front-loaded with the core purpose. Every sentence 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 11 parameters and no output schema, description lacks return value details and behavior for optional fields. Adequate but not complete; e.g., unclear what happens if projectName is invalid.
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 does not add meaning beyond schema; it merely restates parameter purposes implicitly.
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 task in OmniFocus' with a specific verb and resource. It distinguishes from sibling tools like edit_item and move_task by emphasizing creation over duplication.
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 advises to search first and edit existing tasks instead of duplicating, providing clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a new project to OmniFocus
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name of the project | |
| note | No | Additional notes for the project | |
| dueDate | No | The due date of the project in ISO format (YYYY-MM-DD or full ISO date) | |
| deferDate | No | The defer date of the project in ISO format (YYYY-MM-DD or full ISO date) | |
| plannedDate | No | The planned date of the project in ISO format (YYYY-MM-DD or full ISO date) | |
| flagged | No | Whether the project is flagged or not | |
| estimatedMinutes | No | Estimated time to complete the project, in minutes | |
| tags | No | Tags to assign to the project | |
| folderName | No | The name of the folder to add the project to (will add to root if not specified) | |
| sequential | No | Whether tasks in the project should be sequential (default: false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must fully disclose behavior. It only states 'Add a new project' without explaining side effects (e.g., whether it creates immediately, if there are duplicate checks, required permissions, or what is returned). This is a critical gap 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 a single sentence, which is concise, but it is under-specified for the complexity of the tool. It lacks necessary detail and structure, such as front-loading key usage instructions or listing required parameters.
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 10 parameters, no output schema, and no annotations, the description is insufficient. It does not explain what happens upon success/failure, return values, or how the project is added relative to the OmniFocus hierarchy. The agent lacks crucial context 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?
Input schema covers all 10 parameters with descriptions (100% coverage). The description does not add any extra semantic meaning beyond the schema. Baseline 3 is appropriate as the schema does the heavy lifting.
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 'Add a new project to OmniFocus' with a specific verb and resource. It is distinguishable from sibling tools like add_omnifocus_task which deals with tasks, not projects. However, it doesn't explicitly differentiate from potential similar project tools if any, but given the sibling list, the name suffices.
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. For example, it doesn't mention that this adds a project at the root or into a folder, nor does it compare to batch_add_items or create_tag. An agent has no context to decide between add_project and other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add multiple tasks or projects to OmniFocus in a single operation
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | Array of items (tasks or projects) to add |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only states the action without disclosing behavioral traits such as atomicity, error handling, authentication requirements, or performance implications. As a write operation, more transparency is needed.
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?
Extremely concise single sentence that front-loads the action and scope. Every word is meaningful with zero 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?
Description covers basic purpose but lacks details on return value, error behavior, or practical constraints. Given the complexity of the items parameter and no output schema, additional context 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 description coverage is 100% (all parameters have descriptions). The tool description adds no additional parameter meaning beyond the schema, meeting the baseline for full coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add multiple tasks or projects') and the target system ('OmniFocus') with scope ('in a single operation'). It effectively distinguishes from sibling tools like add_omnifocus_task and add_project which handle single items.
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?
Implicitly suggests batch use via 'single operation', but no explicit when-to-use or when-not-to-use instructions. Does not mention alternatives like add_omnifocus_task for individual additions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove multiple tasks or projects from OmniFocus in a single operation. Prefer IDs for destructive batch operations.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | Array of items (tasks or projects) to remove |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It notes the operation is 'destructive' and 'batch', which are key traits. However, it lacks details on error handling, partial success, or reversibility, which are useful for a destructive batch 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?
The description is a single sentence that is concise and front-loaded with the core action. Every part serves a purpose, 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?
The description covers the basic batch removal functionality. For a batch operation with no output schema, lack of details on atomicity, error reporting, or post-removal state leaves some gaps. It is adequate but not fully 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%, so baseline is 3. The description adds value by recommending ID preference over name, which enhances parameter usage understanding beyond the schema's basic field descriptions.
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 removes multiple tasks or projects in a single operation, using specific verbs ('Remove') and resources ('tasks or projects'). It distinguishes from the sibling 'remove_item' by indicating batch scope, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a usage preference ('Prefer IDs for destructive batch operations'), guiding the agent to use IDs over names for safety. However, it does not explicitly state when to avoid using this tool or compare alternatives beyond the implicit single-removal tool.
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, optionally nested under an existing parent tag.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the tag to create | |
| parentTagName | No | Name of an existing tag to nest the new tag under. Ignored if parentTagID is provided. | |
| parentTagID | No | ID of an existing tag to nest the new tag under. Takes precedence over parentTagName. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations. Description only states action and optional nesting. Does not disclose behavior on duplicate names, error handling, or authentication needs. For a write operation, more detail expected.
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 and key optionality. 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?
Adequate for a simple create operation, but missing return value info and behavior on conflicts. With no output schema, description could clarify what is 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?
Schema coverage 100%, so baseline 3. Description adds the 'optionally nested' context, which aligns with optional parameters but does not significantly extend beyond schema descriptions.
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-resource pair: 'create a tag'. Specifies domain (OmniFocus) and optional nested under parent, distinguishing from sibling tools like list_tags or get_tasks_by_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 explicit when-to-use or alternatives. Implicit from context of creating tags, but lacks guidance on when not to use (e.g., when tag exists) or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Gets the current state of your OmniFocus database. Prefer query_omnifocus or filter_tasks for targeted lookups.
| Name | Required | Description | Default |
|---|---|---|---|
| hideCompleted | No | Set to false to show completed and dropped tasks (default: true) | |
| hideRecurringDuplicates | No | Set to true to hide duplicate instances of recurring tasks (default: true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Describes as read operation ('gets') but offers no additional behavioral details such as data volume, performance impact, or side effects. Minimal 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?
Two sentences: one states purpose, the other provides usage guidance. No redundant or wasted words. Front-loaded with key 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?
No output schema, but tool is simple (2 optional booleans). Description lacks details about output format or size. Adequate but minimal for a 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 two boolean parameters. Description adds no extra meaning beyond the schema descriptions, 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?
Description clearly states verb 'gets' and resource 'current state of your OmniFocus database'. It distinguishes from sibling tools query_omnifocus and filter_tasks by recommending them for targeted lookups.
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 advises preferring query_omnifocus or filter_tasks for targeted lookups, implying this tool is for broad dumps. No explicit exclusions or prerequisites, but clear recommendation provides usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit an existing task or project in OmniFocus. Also supports moving tasks via project, parent task, or inbox move fields.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | The ID of the task or project to edit | |
| name | No | The name of the task or project to edit (as fallback if ID not provided) | |
| itemType | Yes | Type of item to edit ('task' or 'project') | |
| newName | No | New name for the item | |
| newNote | No | New note for the item | |
| newDueDate | No | New due date in ISO format (YYYY-MM-DD or full ISO date); set to empty string to clear | |
| newDeferDate | No | New defer date in ISO format (YYYY-MM-DD or full ISO date); set to empty string to clear | |
| newPlannedDate | No | New planned date in ISO format (YYYY-MM-DD or full ISO date); set to empty string to clear | |
| newFlagged | No | Set flagged status (set to false for no flag, true for flag) | |
| newEstimatedMinutes | No | New estimated minutes | |
| newStatus | No | New status for tasks (incomplete, completed, dropped) | |
| addTags | No | Tags to add to the task | |
| removeTags | No | Tags to remove from the task | |
| replaceTags | No | Tags to replace all existing tags with | |
| newProjectId | No | For tasks: move task to this project ID | |
| newProjectName | No | For tasks: move task to this project name (errors on duplicate names) | |
| newParentTaskId | No | For tasks: move task under this parent task ID | |
| newParentTaskName | No | For tasks: move task under this parent task name (errors on duplicate names) | |
| moveToInbox | No | For tasks: move task to inbox | |
| newSequential | No | Whether the project should be sequential | |
| newFolderName | No | New folder to move the project to | |
| newProjectStatus | No | New status for projects |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose side effects, reversibility, or authorization needs. It only states editing and moving capabilities, omitting any behavioral traits like whether changes are permanent or trigger notifications.
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 efficiently convey core purpose and an additional capability. No wasted words, though a slightly more structured presentation could improve scannability. Still highly 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?
Given 22 parameters and no output schema or annotations, the description is far too brief. It fails to explain return behavior, error conditions, or the fallback identification logic (id vs name) hinted in the schema. More detail is needed for a tool of this 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?
Schema coverage is 100%, so the description adds no extra meaning beyond the param descriptions. The mention of moving tasks via certain fields is already covered in the schema, so it adds no new semantic value.
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 tool edits existing tasks or projects in OmniFocus and explicitly mentions it also supports moving tasks. This distinguishes it from siblings like 'add_omnifocus_task' (adds new) and 'remove_item' (deletes), though there is overlap with 'move_task'. The purpose is well-defined.
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 'move_task' for moving tasks, or 'add_omnifocus_task' for creation. There is no mention of prerequisites, typical scenarios, 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.
Advanced task filtering with unlimited perspective combinations - status, dates, projects, tags, search, and more
| Name | Required | Description | Default |
|---|---|---|---|
| taskStatus | No | Filter by task status. Can specify multiple statuses | |
| perspective | No | Limit search to specific perspective: inbox, flagged, all tasks | |
| projectFilter | No | Filter by project name (partial match) | |
| tagFilter | No | Filter by tag name(s). Can be single tag or array of tags | |
| exactTagMatch | No | Set to true for exact tag name match, false for partial (default: false) | |
| dueBefore | No | Show tasks due before this date (ISO format: YYYY-MM-DD) | |
| dueAfter | No | Show tasks due after this date (ISO format: YYYY-MM-DD) | |
| dueToday | No | Show tasks due today | |
| dueThisWeek | No | Show tasks due this week | |
| dueThisMonth | No | Show tasks due this month | |
| overdue | No | Show overdue tasks only | |
| deferBefore | No | Show tasks with defer date before this date (ISO format: YYYY-MM-DD) | |
| deferAfter | No | Show tasks with defer date after this date (ISO format: YYYY-MM-DD) | |
| deferToday | No | Show tasks deferred to today | |
| deferThisWeek | No | Show tasks deferred to this week | |
| deferAvailable | No | Show tasks whose defer date has passed (now available) | |
| plannedBefore | No | Show tasks planned before this date (ISO format: YYYY-MM-DD) | |
| plannedAfter | No | Show tasks planned after this date (ISO format: YYYY-MM-DD) | |
| plannedToday | No | Show tasks planned for today | |
| plannedThisWeek | No | Show tasks planned for this week | |
| plannedThisMonth | No | Show tasks planned for this month | |
| completedBefore | No | Show tasks completed before this date (ISO format: YYYY-MM-DD) | |
| completedAfter | No | Show tasks completed after this date (ISO format: YYYY-MM-DD) | |
| completedToday | No | Show tasks completed today | |
| completedThisWeek | No | Show tasks completed this week | |
| completedThisMonth | No | Show tasks completed this month | |
| flagged | No | Filter by flagged status | |
| searchText | No | Search in task names and notes | |
| hasEstimate | No | Filter tasks that have time estimates | |
| estimateMin | No | Minimum estimated minutes | |
| estimateMax | No | Maximum estimated minutes | |
| hasNote | No | Filter tasks that have notes | |
| inInbox | No | Filter tasks in inbox | |
| limit | No | Maximum number of tasks to return (default: 100) | |
| sortBy | No | Sort results by field | |
| sortOrder | No | Sort order (default: asc) |
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. However, it only mentions filtering capabilities and omits details about performance implications, sorting behavior, or that the tool returns tasks. This is insufficient for a complex 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 sentence, which is concise and to the point. However, it could be structured to list key features more clearly.
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 36 parameters and no output schema, the description is too brief. It fails to explain what the tool returns (list of tasks), how pagination works via the limit parameter, or any side effects. The tool's complexity demands more 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?
Schema coverage is 100%, so the schema already documents all parameters. The description provides no additional 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 clearly states it is for advanced task filtering with unlimited perspective combinations, listing specific filters like status, dates, projects, tags, and search. This distinctly differentiates it from simpler sibling tools like get_inbox_tasks or 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 complex filtering is needed, but does not explicitly state when not to use it or compare with alternatives. Sibling tools exist for specific perspectives, but no guidance is provided on selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get tasks from a specific OmniFocus custom perspective by name. Use when the user refers to a custom view, not a tag.
| Name | Required | Description | Default |
|---|---|---|---|
| perspectiveName | Yes | Exact name of the OmniFocus custom perspective (e.g., '今日工作安排', '今日复盘', '本周项目'). This is NOT a tag name. | |
| hideCompleted | No | Whether to hide completed tasks. Set to false to show all tasks including completed ones (default: true) | |
| limit | No | Maximum number of tasks to return in flat view mode (default: 1000, ignored in hierarchy mode) | |
| displayMode | No | Display mode for perspective tasks: project_tree (group by project + task hierarchy), task_tree (global task hierarchy), or flat (simple list). Default: project_tree | |
| showHierarchy | No | Display tasks in hierarchical tree structure showing parent-child relationships. Use this when user wants '层级显示' or 'tree view' (default: false) | |
| groupByProject | No | Legacy parameter. Group tasks by project when displayMode is not provided. Default: true |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must carry full behavioral disclosure. It only states the read action ('Get tasks') but omits details like error handling, permission needs, or effects. The schema parameters cover inputs but not behaviors.
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 concise sentences with no redundancy. Front-loaded with the core action and usage context. Every word 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?
With 6 parameters, no output schema, and no annotations, the description lacks completeness. It does not explain the return format, error cases, or behavior for missing perspectives. More detail is needed given the tool's 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?
Schema description coverage is 100%: all 6 parameters have detailed schema descriptions. The tool description adds no additional parameter context beyond what is already in the schema, so baseline score of 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?
Clearly states 'Get tasks from a specific OmniFocus custom perspective by name' and distinguishes from tag-based tools with 'Use when the user refers to a custom view, not a tag.' This provides a specific verb and resource, and explicitly contrasts with sibling tools like get_tasks_by_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?
Provides explicit guidance on when to use: 'when the user refers to a custom view, not a tag.' This clearly differentiates from tag-related tools but does not offer alternative tools for other scenarios or exclude misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get flagged tasks from OmniFocus with optional project filtering
| Name | Required | Description | Default |
|---|---|---|---|
| hideCompleted | No | Set to false to show completed flagged tasks (default: true) | |
| projectFilter | No | Filter flagged tasks by project name (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description only states basic read operation; lacks details on pagination, sorting, or whether all flagged tasks across projects are returned. Adequate but incomplete for a read 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?
Single sentence, front-loaded, no wasted words. Perfectly 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?
Simple tool but with 21 siblings, more differentiation would help. No output schema. Missing details on behavior (e.g., does it return all flagged tasks from all projects?). Minimum viable.
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 descriptions. Description adds 'optional project filtering' but adds no new meaning beyond schema. Baseline 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?
Description clearly states verb 'Get', resource 'flagged tasks', and scope with optional project filtering. Distinguishes from siblings like 'get_inbox_tasks' and 'get_forecast_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 on when to use this tool vs alternatives. No mention of prerequisites, when not to use, or workflow context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get tasks from OmniFocus forecast perspective (due/deferred tasks in date range)
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Number of days to look ahead for forecast (default: 7) | |
| hideCompleted | No | Set to false to show completed tasks in forecast (default: true) | |
| includeDeferredOnly | No | Set to true to show only deferred tasks becoming available (default: false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. It mentions due/deferred tasks and date range but omits read-only nature, permissions, or result formatting. The name 'get' implies safe operation, but more detail would improve 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?
Single, clear sentence that conveys the essential purpose without wasted words. Information is front-loaded.
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 3 parameters and no output schema, the description covers basic purpose but lacks details on return format, ordering, or pagination. Adequate but not 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 has 100% description coverage for all three parameters, so baseline is 3. The description adds no extra meaning beyond schema, e.g., does not explain parameter interactions or defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves tasks from OmniFocus forecast perspective, specifying it includes due/deferred tasks in a date range. This distinguishes it from sibling tools like get_flagged_tasks or get_today_completed_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 explicit guidance on when to use this tool versus siblings. With many similar get tasks, the description should indicate scenarios for forecast perspective or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get tasks from OmniFocus inbox perspective
| Name | Required | Description | Default |
|---|---|---|---|
| hideCompleted | No | Set to false to show completed tasks in inbox (default: true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It only states the basic function and does not disclose behavioral traits like sorting, pagination, or scope of returned tasks. 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 sentence, but it is too minimal. While concise, it could include more useful details without being verbose, striking a balance between brevity and informativeness.
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 parameter, no output schema), the description is adequate but lacks elaboration on what the inbox perspective entails, which is useful for understanding its scope. Not fully 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 coverage is 100% for the single parameter, which already describes its purpose and default value. The description adds no additional semantics, meeting 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 tool gets tasks from the OmniFocus inbox perspective, which identifies the resource and action. However, it does not differentiate from siblings like get_flagged_tasks or get_forecast_tasks, 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?
No guidance is provided on when to use this tool versus alternatives, such as get_tasks_by_tag or get_custom_perspective_tasks. The agent receives no context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get information about a specific task by ID or name, including attachment metadata when available.
| Name | Required | Description | Default |
|---|---|---|---|
| taskId | No | The ID of the task to retrieve | |
| taskName | No | The name of the task to retrieve (alternative to taskId) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry full behavioral disclosure. It mentions 'including attachment metadata when available' but does not clarify if the tool is read-only, if it mutates state, or behavior when both parameters are provided. This leaves gaps for an 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 sentence of 18 words, containing all essential information without waste. It is front-loaded with the main 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 retrieval tool with two parameters and no output schema, the description covers the core functionality. However, it could elaborate on parameter mutual exclusivity and the return format (e.g., always returns a single task). Still, it is largely 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 coverage is 100%, so the schema already documents both parameters. The description adds that the parameters are alternatives ('by ID or name'), which is also implied in the taskName schema description. Thus, minimal added value 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 tool's purpose: 'Get information about a specific task by ID or name, including attachment metadata when available.' It specifies the verb (Get), resource (specific task), and method (by ID or name), distinguishing it from sibling tools that filter 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 usage when a task ID or name is known, but does not explicitly state when to use this tool versus alternatives like filter_tasks or get_tasks_by_tag. No guidance on parameter selection (ID vs name) or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get tasks filtered by OmniFocus tags. Use this for tag names, not custom perspective names.
| Name | Required | Description | Default |
|---|---|---|---|
| tagName | Yes | Name of the tag to filter tasks by | |
| hideCompleted | No | Set to false to show completed tasks with this tag (default: true) | |
| exactMatch | No | Set to true for exact tag name match, false for partial (default: false) |
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 basic function without disclosing behavioral traits like read-only, pagination, or result format. This is insufficient for a tool that likely returns a list.
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 plus a clarification note, concise and front-loaded. However, it could be slightly more structured to include output or usage hints.
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 3 parameters, the description is too minimal. It lacks explanation of what the response looks like, whether it lists all tasks or paginates, and any side effects. More context is needed for complete agent 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 has 100% description coverage for all three parameters (tagName, hideCompleted, exactMatch). The description does not add 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 'Get tasks filtered by OmniFocus tags', specifying the action (get tasks) and resource (tags). It further distinguishes from custom perspective names, making it unique among siblings like get_custom_perspective_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?
Explicitly says 'Use this for tag names, not custom perspective names', providing clear guidance on when to use this tool vs alternatives. This is direct and helpful for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get tasks completed today - view today's accomplishments
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | 返回的最大任务数量 (默认: 20) |
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 only implies a read operation ('view') but omits details such as whether results are ordered, timezone handling, 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 concise sentence that front-loads the purpose. Every word earns its place, with no wasted text.
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 (1 optional param, no output schema), but the description lacks any mention of the return format or how results are structured. Given the absence of an output schema, the description should explain what the agent can expect from the response.
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, including a clear description for the 'limit' parameter (default 20). The tool description adds no additional semantic meaning beyond what the schema already provides, resulting in a 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 'Get tasks completed today - view today's accomplishments' clearly states the verb 'Get' and the specific resource 'tasks completed today', distinguishing this tool from sibling tools like get_flagged_tasks or get_forecast_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 no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions. The agent has no context for appropriate use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all custom perspectives defined in OmniFocus
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | Output format: simple (names only) or detailed (with identifiers) - default: simple |
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 the listing action but does not explicitly indicate that it is a read-only operation with no side effects, nor does it mention any performance or pagination characteristics.
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 9 words, starting with a verb. It is concise 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?
For a simple list tool with no output schema, the description is adequate but incomplete; it does not specify that the output is an array of perspective names or objects. The parameter hint at output format partially compensates.
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%; the schema already documents the 'format' parameter with enum values and a default. The tool description adds no extra parameter information, meeting the baseline expectation.
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 a specific verb 'List' and resource 'all custom perspectives' with context 'in OmniFocus', clearly distinguishing this tool from siblings like 'get_custom_perspective_tasks' (which retrieves tasks within a perspective) and 'list_tags' (which lists tags).
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 noting that 'get_custom_perspective_tasks' should be used to fetch tasks within a perspective. The usage context is implied but not explicitly compared to siblings.
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 with their hierarchy. Useful before creating or editing tagged tasks.
| Name | Required | Description | Default |
|---|---|---|---|
| includeDropped | No | Include dropped/inactive tags. Default: false |
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 the tool lists tags with hierarchy, implying read-only behavior. While it doesn't explicitly confirm non-destructiveness, 'list' sufficiently conveys safety, adding 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 consists of two concise sentences that immediately convey purpose and use case. Every word adds value, with no redundancy or wasted space.
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 listing tool with one parameter and no output schema, the description covers the main purpose (list all tags with hierarchy) and provides a usage hint. It could elaborate on the hierarchical representation, but it is largely 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 description coverage is 100% (the single parameter 'includeDropped' has a description in the schema). The tool description adds no extra parameter information, 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 it lists all tags in OmniFocus with their hierarchy, using a specific verb and resource. It distinguishes from sibling tools like create_tag or get_tasks_by_tag, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage context: 'Useful before creating or editing tagged tasks.' It does not explicitly mention alternatives or when not to use, but the context is helpful enough to guide use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move an existing task to a project, parent task, or inbox. Prefer task ID and destination IDs when available.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | The ID of the task to move | |
| name | No | The name of the task to move (fallback if ID not provided) | |
| targetProjectId | No | Destination project ID | |
| targetProjectName | No | Destination project name (errors on duplicate names) | |
| targetParentTaskId | No | Destination parent task ID | |
| targetParentTaskName | No | Destination parent task name (errors on duplicate names) | |
| targetInbox | No | Move task to inbox |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, and the description fails to disclose behavioral traits like side effects, error handling, or return value, relying too much on 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?
Single sentence, directly to the point 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?
Lacks details on destination selection (conflicting parameters), return value, and prerequisites, making it incomplete for a tool with 7 optional parameters and no output schema.
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 'prefer IDs' guidance but little else 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 tool moves an existing task to a destination (project, parent, or inbox) and is distinguishable from sibling tools like add_omnifocus_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?
Gives preference for using IDs when available, which helps parameter selection, but lacks explicit when-not or alternative tool guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Efficiently query OmniFocus database with filters, fields, sorting, limits, and summaries. Prefer this over dump_database for targeted lookups.
| Name | Required | Description | Default |
|---|---|---|---|
| entity | Yes | Type of entity to query. Choose 'tasks' for individual tasks, 'projects' for projects, or 'folders' for folder organization | |
| filters | No | Optional filters to narrow results. ALL filters combine with AND logic (must match all). Within array filters (tags, status) OR logic applies | |
| fields | No | Specific fields to return (reduces response size). TASK FIELDS: id, name, note, flagged, taskStatus, dueDate, deferDate, plannedDate, effectiveDueDate, effectiveDeferDate, effectivePlannedDate, completionDate, dropDate, effectiveDropDate, estimatedMinutes, tagNames, tags, projectName, projectId, parentId, childIds, hasChildren, sequential, completedByChildren, inInbox, isRepeating, repetitionRule, modificationDate (or modified), creationDate (or added). PROJECT FIELDS: id, name, status, note, folderName, folderID, sequential, dueDate, deferDate, effectiveDueDate, effectiveDeferDate, completionDate, dropDate, effectiveDropDate, completedByChildren, containsSingletonActions, taskCount, tasks, nextReviewDate, reviewInterval, modificationDate, creationDate. FOLDER FIELDS: id, name, path, parentFolderID, status, projectCount, projects, subfolders. NOTE: Date fields use 'added' and 'modified' in OmniFocus API | |
| limit | No | Maximum number of items to return. Useful for large result sets. Default: no limit | |
| sortBy | No | Field to sort by. OPTIONS: name (alphabetical), dueDate (earliest first, null last), deferDate (earliest first, null last), modificationDate (most recent first), creationDate (oldest first), estimatedMinutes (shortest first), taskStatus (groups by status) | |
| sortOrder | No | Sort order. 'asc' = ascending (A-Z, old-new, small-large), 'desc' = descending (Z-A, new-old, large-small). Default: 'asc' | |
| includeCompleted | No | Include completed and dropped items. Default: false (active items only) | |
| summary | No | Return only count of matches, not full details. Efficient for statistics. Default: false |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral aspects. It mentions efficiency but does not explicitly state it is read-only or disclose any side effects or rate limits. The comprehensive schema somewhat compensates, but the description adds minimal 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?
The description is extremely concise, using two sentences to convey the purpose and a usage hint. Every word 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?
Given the tool's complexity (8 parameters, nested objects) and the lack of an output schema, the description could have mentioned the return format or provided additional context about the output. The schema covers the input well, but the agent lacks guidance on what to expect as a result.
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 the schema itself provides very detailed parameter semantics including case sensitivity, AND/OR logic, and date formats. The description only summarizes parameters without adding significant new meaning.
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 queries an OmniFocus database with various features and explicitly distinguishes it from dump_database for targeted lookups. The verb 'query' and resource are well-defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear preference over dump_database for targeted lookups, but does not explicitly list when to avoid or mention other sibling tools like get_flagged_tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a task attachment reported by get_task_by_id. Images are returned as MCP image content when possible.
| Name | Required | Description | Default |
|---|---|---|---|
| taskId | No | The ID of the task that owns the attachment | |
| taskName | No | The name of the task that owns the attachment | |
| attachmentId | No | The attachment ID reported by get_task_by_id | |
| attachmentName | No | The attachment name reported by get_task_by_id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that images are returned as MCP content when possible, but does not explain behavior for non-image attachments, error conditions, or authorization requirements. This is partial but not comprehensive.
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 concise, front-loaded sentences: first states the core purpose, second adds a key behavioral detail about image handling. No filler or 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 read tool with 4 well-documented parameters and no output schema, the description is mostly complete. However, it could mention return format for non-images or error scenarios, but the overall simplicity keeps the score high.
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 all parameters have descriptions in the schema. The tool description does not add additional meaning beyond the schema; it only mentions the attachment ID/name references. 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 tool reads a task attachment, specifically one reported by get_task_by_id. It adds that images are returned as MCP content when possible. However, it could be more specific about what 'read' entails (e.g., download or view) and does not explicitly differentiate from sibling tools, though no sibling appears to do the same thing.
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 that the attachment should be obtained from get_task_by_id, but does not explicitly state 'use after get_task_by_id' or provide alternatives. There is no guidance on when not to use the tool or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a task or project from OmniFocus. Prefer ID over name for destructive operations.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | The ID of the task or project to remove | |
| name | No | The name of the task or project to remove (as fallback if ID not provided) | |
| itemType | Yes | Type of item to remove ('task' or 'project') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden. It states the tool is destructive but lacks details on side effects (e.g., cascading deletes, reversibility). For a simple removal, this is adequate but not comprehensive.
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, focused sentences. No redundant information; every word contributes to clarity and 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?
Given the tool's simplicity and full schema documentation, the description provides sufficient context for correct invocation. It could mention return behavior (e.g., success confirmation) but is otherwise 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 coverage is 100% with descriptions for all parameters. The description adds value by emphasizing the preference for 'id' over 'name' for reliability in destructive operations, which goes beyond the schema's indications.
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 ('a task or project from OmniFocus'), making it unambiguous. It distinguishes from sibling tools like 'batch_remove_items' by implying single-item removal.
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 explicit guidance: 'Prefer ID over name for destructive operations.' This helps the agent prioritize parameters correctly. It does not explicitly contrast with sibling tools, but the context is sufficient for proper use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools have distinct purposes, with clear descriptions that guide selection (e.g., get_custom_perspective_tasks vs get_tasks_by_tag). However, the large number of retrieval tools (filter_tasks, query_omnifocus, dump_database, multiple get_*) may cause occasional confusion despite differentiating texts.
Predominantly verb_noun snake_case pattern is used (e.g., add_project, filter_tasks, list_tags). Minor inconsistencies exist: 'add_omnifocus_task' vs 'add_project' (one includes product name), 'create_tag' vs 'add_project' (different verbs), and 'edit_item'/'move_task' are slightly vague but acceptable.
21 tools is well-scoped for an OmniFocus integration, covering creation, retrieval, modification, and deletion across tasks, projects, tags, and perspectives. Each tool serves a clear purpose without feeling excessive.
Tool surface covers most core workflows: CRUD for tasks/projects, batch operations, diverse retrieval, and attachment reading. However, tag management is incomplete – only create_tag and list_tags exist, lacking update or delete operations, which is a notable gap.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Let ChatGPT, Claude & Cursor use your Mac: email, calendar, iMessage, Teams, files. Local, free.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Manage tasks, Focus Zone, notes, projects, and task history from compatible AI assistants.
Secure AI access to OpenOak tasks, notes, and Kanban boards.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/phd-peter/codex-omnifocus-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
