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., "@omniplan-mcp create a milestone 'Launch' under the Deployment group"
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.
Drive OmniPlan 4 on macOS from Claude (or any MCP-compatible LLM agent) using natural language.
Tell an agent "create a milestone called Beta Launch under the Deployment group, link it after the QA-complete task, and assign it to Alice." It does. The Gantt redraws.
20 tools across tasks, dependencies, resources, assignments, and project metadata. MIT-licensed. macOS only.
Lineage: this build is inspired by
xiahan4956/omniplan-mcp(MIT) — the originaljxa.pybridge is reused under MIT. The rest of the codebase was rebuilt from scratch (~86% of current LOC). It's distributed under a distinct PyPI name (mcp-omniplan-jtr) so as not to take the original author's namespace. SeeCHANGELOG.mdfor what changed.
You say | The agent calls | OmniPlan reflects |
"Show me incomplete tasks due this week" |
| filters the outline |
"Create a 4-hour task 'Refactor login' under Auth" |
| new row in the Gantt |
"Link 'Refactor login' before 'Run E2E'" |
| dependency arrow drawn |
"Assign Alice at 50%" |
| assignment chip on the bar |
"Mark Beta Launch as a milestone, color green" |
| diamond marker, green |
"Save the document" |
| written to disk |
Related MCP server: OmniFocus MCP Server
macOS (any recent version)
OmniPlan 4 — installed and running with a document open. See "Supported OmniPlan versions" below for the matrix
Python 3.11+
Automation permission granted to your terminal / MCP host app (System Settings → Privacy & Security → Automation → enable OmniPlan)
This MCP is verified against the following builds. "Verified" = full pytest integration suite passes against that build inside a Tart macOS VM with OmniPlan running.
OmniPlan version | Build | All tools? | Verified | Notes |
4.10.3 test | v232.5.9 ( | ✅ All 22 tools | 2026-05-07 | Test build from https://omnistaging.omnigroup.com/omniplan/. Adds |
4.10.2 | 232.5.0 | ✅ Except | 2026-05-01 | Public release. The two move tools raise a clear "requires 4.10.3+" error; everything else works including all reads, writes, dependencies, resource assignments, and |
4.10.0–4.10.1 | (older 4.10.x patch builds) | Likely yes for non-move tools | Inferred (untested) | Should work — same omniJS surface as 4.10.2 for the tools we use, but not empirically verified |
4.9.x and older | — | Unknown | Untested | Not part of the supported matrix |
Reporting a version compatibility issue: if you find a build where a tool fails that the matrix says should work, please file an issue with the build number (visible in OmniPlan → About OmniPlan) and the tool name.
Pick whichever you prefer:
# 1. Homebrew tap (Python deps bundled in an isolated venv; only python@3.13 comes from brew)
brew tap johntrandall/tap
brew install mcp-omniplan-jtr# 2. uv tool (recommended for the MCP ecosystem; installs from PyPI)
uv tool install mcp-omniplan-jtr# 3. pip (if you don't have uv)
pip install mcp-omniplan-jtrAll three install the mcp-omniplan-jtr command. Register it as an MCP server with whichever client you use:
claude mcp add -s user omniplan-local mcp-omniplan-jtrThen restart Claude Code.
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"omniplan-local": {
"command": "mcp-omniplan-jtr"
}
}
}Then restart Claude Desktop.
The first time the agent calls a tool, macOS may prompt for Automation access. Approve OmniPlan automation for your terminal or the app running the MCP server. If the prompt was missed, grant it manually:
System Settings → Privacy & Security → Automation — enable OmniPlan for your terminal or MCP host.
If denied, every tool returns a clear error: "macOS blocked Automation access to OmniPlan. Grant permission in System Settings > Privacy & Security > Automation."
Tool | What it does |
| List all currently open OmniPlan documents |
| Search and filter tasks by keyword, type, completion, color, or date range |
| Look up tasks by title; substring by default, exact opt-in |
| Get full details of a task by ID |
| Create a new task under a parent task or project root |
| Bulk-create many tasks in a single round-trip; supports intra-batch parent references |
| Update title, note, dates, completion, color, effort, three-point estimates, constraint dates |
| Reparent a task while preserving its uniqueID (so dependencies and assignments survive). Requires OmniPlan 4.10.3+ |
| Delete a task by ID |
| Link two tasks (FS / SS / FF / SF, optional lead time) |
| Remove the dependency between two tasks |
| List dependencies in the document (or filtered to one task) |
| Save the front document to disk |
| Project metadata: name, path, dates, scenarios |
| Update project-level fields (currently start date) |
| List all resources |
| Create a resource (staff / equipment / material / group) |
| Reparent a resource (across the resource group hierarchy) while preserving its uniqueID. Requires OmniPlan 4.10.3+ |
| Delete a resource by ID |
| Assign a resource to a task with optional units fraction |
| Remove a resource assignment from a task |
| List a task's resource assignments |
All tools accept an optional document_name parameter. If omitted, the frontmost open document is used.
"Show me all incomplete tasks due this week in my project."
"Create a milestone called 'Beta Launch' under the Deployment group, dependent on 'QA-complete', and assign it to Alice at 50%."
"Mark task 42 as complete and set its bar color to green."
"What tasks are assigned the red color?"
"List every resource and how much they're allocated across the project."
A few small omniJS edges. Per-version availability is in the supported-versions matrix above; this section names what's currently outside the omniJS surface entirely.
Resource working hours are not editable through this MCP — actual.rootResource.schedule is opaque on the omniJS surface.
Project currency (actual.currency) is not writable — writes via omniJS don't persist across calls. Cost values themselves work; just not the currency unit.
OmniPlan must be running with a document open. The MCP doesn't launch OmniPlan or open documents for you.
For per-release detail and verification status, see CHANGELOG.md.
For the full catalogue (and the mitigations), see dev-docs/omnijs-persistence-gaps.md.
If you want to extend, hack on, or contribute to this MCP:
Architecture & internals: dev-docs/README-DEV.md
Roadmap & feature tiers: dev-docs/ROADMAP.md
Testing policy: dev-docs/testing-policy.md
VM provisioning for the pre-release test runner: dev-docs/vm-provisioning.md
Sibling OmniPlan tooling in the same workflow:
oplx-tools — Python toolkit for OmniPlan .oplx documents: generate, lint, parse. Useful when you want to build a Gantt from a database or CI pipeline rather than the GUI.
oplx-format — Community-maintained file-format specification for .oplx documents (verified against OmniPlan 4.10.2). Reference doc that informed both oplx-tools and the e2e XML cross-checks in this MCP's test suite.
MIT. See LICENSE.
Add a dependency from predecessor to successor.
Args: predecessor_id: uniqueID of the prerequisite task. successor_id: uniqueID of the dependent task. kind: One of "FS" (finish-to-start, default), "SS", "FF", "SF". lead_time_seconds: Lead time before the successor can start, in work-seconds. Defaults to 0. Negative values are not supported here; if you need lag in the other direction, model it as a different dependency kind.
Returns:
JSON {predecessor_id, successor_id, kind, lead_time_seconds}.
lead_time_seconds is read back via
dep.leadTimeDuration.workSeconds after the write — a true
round-trip, not an echo. When no Duration is set on the
dependency (e.g. lead_time_seconds=0), the field is reported as
0 rather than null.
| Name | Required | Description | Default |
|---|---|---|---|
| predecessor_id | Yes | ||
| successor_id | Yes | ||
| kind | No | FS | |
| lead_time_seconds | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavior: it adds a dependency, returns JSON with round-trip values, explains the `lead_time_seconds` read-back via `dep.leadTimeDuration.workSeconds`, and notes edge case when `lead_time_seconds=0`. No contradictions.
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?
Well-structured with clear 'Args' and 'Returns' sections. The first sentence is concise. Slightly lengthy due to detailed parameter descriptions, but justified given the schema lacks descriptions. No superfluous content.
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?
Covers parameters, return format, and important nuances like round-trip and default behavior. Lacks discussion of error conditions (e.g., duplicate dependencies), but overall complete for typical usage. Output schema exists but description adds useful 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 description coverage is 0%, so the description adds full meaning. It explains each parameter's role, default values, allowed enum values for 'kind', and constraints on 'lead_time_seconds'. Substantially adds value beyond the bare 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 action: 'Add a dependency from predecessor to successor.' It uses specific verb+resource and distinguishes from sibling 'remove_dependency'.
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 alternatives like 'remove_dependency' or 'list_dependencies'. Usage is implied by the tool name but not elaborated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Assign a resource to a task.
Args:
task_id: uniqueID of the task.
resource_id: uniqueID of the resource.
units: Optional fractional allocation (1.0 = 100% of a staff
resource's working hours). Maps to the documented
assignment.unitsAssigned accessor (Number, read/write).
Round-trips cleanly across JXA call boundaries.
Returns:
JSON {task_id, resource_id, units}. units is read back from
assignment.unitsAssigned after the write — a true round-trip.
When units is omitted on input, the returned value reflects
whatever default OmniPlan applied (typically 1.0).
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | ||
| resource_id | Yes | ||
| units | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses the round-trip behavior for units, the default value when omitted (1.0), and that mapping is to an internal accessor. This exceeds minimal expectations.
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 well-structured with 'Args' and 'Returns' sections, front-loaded with the purpose. Every sentence adds unique value, and the length is appropriate for the tool's complexity.
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 parameters, return format, and side effects (round-trip, defaults). It lacks error handling or prerequisite info, but the presence of an output schema reduces the burden. Nearly 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 0%, but the description adds detailed semantics for all three parameters: task_id and resource_id are explained as 'uniqueID', and units gets a full explanation including type, default, round-trip behavior, and boundary handling.
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 opens with 'Assign a resource to a task' which is a specific verb+resource pairing. It clearly distinguishes from siblings like 'unassign_resource' (reverse operation) and 'list_assignments' (read-only).
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 alternatives (e.g., when to assign vs. unassign, or prerequisites like existing resource/task). The description focuses on mechanics, not usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new resource at the document's resource root.
Args:
name: Resource name.
type: One of "staff" (default), "equipment", "material", "group".
email: Optional email address (relevant mainly for staff).
cost_per_use: Optional cost in the document's currency. Stored
as a Decimal — writes go through Decimal.fromString(...)
so float inputs round-trip without Number precision issues.
Returns:
JSON {id, name, type, email, cost_per_use} for the new resource.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| type | No | staff | |
| No | |||
| cost_per_use | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description explains key behaviors: writes go through Decimal.fromString (avoiding float precision issues), returns a JSON with id, name, type, email, cost_per_use. It does not mention auth requirements or prerequisites like an existing document, but covers the most important behavioral 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 concise and well-structured with Args and Returns sections. Every sentence provides value; no redundancy. It is appropriately sized for the tool's complexity.
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 creation, parameters, and return. Missing high-level context such as the need for an existing document or error states, but given the output schema exists and parameters are well-documented, it is mostly 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 0%, so the description fully compensates: name is described as 'Resource name', type lists all possible values and default, email clarifies relevance for staff, cost_per_use explains Decimal storage. This adds crucial meaning 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 clearly states 'Create a new resource at the document's resource root.' It specifies the verb (create) and resource (resource), and distinguishes from sibling tools like create_task by focusing on resources. No 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 implies use when a new resource is needed, but does not explicitly state when to use this tool versus alternatives (e.g., create_task) or when not to use it. No exclusion criteria or context for choosing this over other creation tools.
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 an OmniPlan document.
Args: title: Task title. parent_id: uniqueID of the parent task. If omitted, adds to root. task_type: One of: task, group, milestone, hammock. Defaults to task. note: Optional task description. manual_start_date: ISO date string for manual start. manual_end_date: ISO date string for manual end. effort_seconds: Total effort in person-seconds (e.g. 14400 for 4h). min_effort_seconds: Three-point estimation minimum (person-seconds). expected_effort_seconds: Three-point estimation expected value. max_effort_seconds: Three-point estimation maximum.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | ||
| parent_id | No | ||
| task_type | No | ||
| note | No | ||
| manual_start_date | No | ||
| manual_end_date | No | ||
| effort_seconds | No | ||
| min_effort_seconds | No | ||
| expected_effort_seconds | No | ||
| max_effort_seconds | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description bears full burden. It only says 'Create a new task' without disclosing behavioral traits such as idempotency, permissions, side effects, or constraints on document state. The description lacks transparency beyond the basic action.
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 uses a clear docstring format with an introductory line and an Args section. It is well-structured and readable, though the parameter list repeats information present in the schema, making it slightly longer than necessary. However, it remains concise overall.
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 10 parameters, 1 required, and an output schema presumably documenting return values, the description covers all input semantics thoroughly. It does not explain return values, which is acceptable given the output schema. Some behavioral context is missing, but overall it is sufficiently complete for parameter 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 0% (no descriptions in schema), but the description provides detailed explanations for all 10 parameters, including examples like 'effort_seconds: Total effort in person-seconds (e.g. 14400 for 4h)'. This adds significant meaning beyond the schema's type information.
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 new task' and the resource 'OmniPlan document', with specific verb and resource. It distinguishes from sibling tools like 'update_task' and 'delete_task', and the singular 'task' differentiates from 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?
No explicit guidance on when to use this tool vs alternatives. Since there is a sibling 'create_tasks' for batch creation, the description should mention when to use the singular version. The description omits any usage context or when-not-to-use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create multiple tasks in a single JXA call.
Performance: each evaluateJavascript round-trip is ~1-3s of
osascript startup. Building 50 tasks via 50 calls to create_task
is ~50-150s. This tool does the whole batch in one round-trip.
Args:
tasks: list of task specs. Each spec is a dict with the same
fields create_task accepts:
title (required), parent_id, task_type, note,
manual_start_date, manual_end_date, effort_seconds,
min_effort_seconds, expected_effort_seconds,
max_effort_seconds.
Plus one extra:
parent_index — int, optional. References another task in
the same batch by zero-based position. Must be less than
the task's own index. At most one of parent_id and
parent_index may be set; if neither is set, the task
is added under the document root.
Returns:
JSON array of created-task shapes — same fields as create_task
returns, in the order the inputs were given.
Raises ValueError on invalid parent_index references or unknown parent_id, before any task is created.
| Name | Required | Description | Default |
|---|---|---|---|
| tasks | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden. It discloses performance characteristics (1-3s per round-trip), atomic validation (raises ValueError before any creation), and batching behavior. However, it does not explicitly state whether the operation is fully transactional or mention required permissions.
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 well-structured with clear sections (Performance, Args, Returns, Raises). Every sentence adds value—no fluff. It is appropriately sized for the tool's complexity.
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 output schema exists, the description still adds useful return details. It covers error handling, parameter constraints, and performance context. All relevant aspects are addressed 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?
Schema coverage is 0%, but the description provides exhaustive semantics for the `tasks` parameter: lists accepted fields (title, parent_id, etc.), explains the extra `parent_index` field, and clarifies constraints (at most one of parent_id/parent_index). This fully compensates for the schema's lack of 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 opens with a specific verb and resource: 'Create multiple tasks in a single JXA call.' It clearly distinguishes from the sibling `create_task` by highlighting the batch nature.
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 this tool over `create_task` by quantifying the performance cost of multiple individual calls (50-150s) versus one batch call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a resource by uniqueID.
Args: resource_id: uniqueID of the resource to delete.
Returns:
JSON {deleted: bool, id, name}. deleted is true when a
matching resource was found and removed, false if not found.
Removing a resource that is currently assigned to tasks
succeeds — OmniPlan strips the assignments.
| Name | Required | Description | Default |
|---|---|---|---|
| resource_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses that deleting a resource assigned to tasks succeeds and strips assignments. It also details the return value format. This adds important behavioral context beyond a simple 'delete'.
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, front-loaded with the purpose, and uses clear structure (Args, Returns, additional note). 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?
The description covers purpose, parameter meaning, return value, and a notable side effect. However, it lacks usage guidelines and does not mention error cases beyond the return value. Still fairly complete for a simple delete 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 schema has 0% description coverage, but the description explains 'resource_id: uniqueID of the resource to delete,' providing essential meaning that the schema alone does not.
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 'Delete a resource by uniqueID,' specifying the action, resource, and identifier. It distinguishes from siblings like create_resource or list_resources.
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, nor any prerequisites or conditions for use. This is a notable gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a task by its unique ID.
Args: task_id: The uniqueID of the task to delete.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It only states 'delete,' implying destruction but lacks details on irreversibility, cascade effects, permissions, or error handling.
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?
Short and front-loaded with purpose. The docstring format is efficient, though slightly verbose for a single parameter.
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 deletion tool, the description is incomplete. It lacks behavioral context (irreversibility, effects on dependencies) and error conditions, despite an output schema existing.
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 0%, so description must compensate. It mentions task_id and its purpose but adds no format, source, or validation beyond what the 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?
The description clearly states 'Delete a task by its unique ID,' specifying the verb (delete), resource (task), and parameter (unique ID). It distinguishes from sibling tools like create_task and 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?
No guidance on when to use this tool versus alternatives (e.g., move_task, update_task). No prerequisites, conditions, or restrictions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up tasks by title, returning lightweight identifiers.
Removes the "list everything → grep → use ID" pattern when an agent knows the title but not the uniqueID.
Args:
name: Title to match. Case-insensitive substring match by default.
exact: When True, only return tasks whose title equals name
exactly (case-sensitive). When False, returns every descendant
whose title contains name (case-insensitive).
Returns:
JSON array of {"id", "title", "outline_id"}. Empty array if
nothing matches. Order matches outline traversal (depth-first,
children in document order).
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| exact | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavior: it is a read operation, returns lightweight identifiers, default case-insensitive substring matching, exact option, empty array on no match, and depth-first order. This covers all essential behavioral aspects.
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 well-structured with a clear one-sentence purpose, a context paragraph, and formatted Args/Returns sections. Every sentence adds value with 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 the tool's low complexity (2 parameters, no annotations, an output schema mentioned), the description provides complete information: what it does, when to use, parameter semantics, return format, and ordering. Nothing essential is missing.
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 0%, so the description must compensate. It does so effectively by explaining that 'name' is matched case-insensitively by default, and 'exact' changes to exact case-sensitive match. It also describes the return format, adding meaning 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 clearly states the verb 'look up' and the resource 'tasks by title', with a specific goal: returning lightweight identifiers. It explicitly contrasts with the 'list everything → grep → use ID' pattern, distinguishing it from more extensive listing tools like query_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: 'when an agent knows the title but not the uniqueID.' It also explains the two matching modes (default case-insensitive substring, exact case-sensitive). However, it does not explicitly mention alternatives like get_task for when the ID is known, leaving a minor gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return project-level info for the front document.
Returns:
JSON {name, path, start_date, end_date, scenarios}. path comes
from the JXA SDEF surface (omniJS doesn't expose it). start_date
and end_date are the actual scenario's computed bounds (ISO
YYYY-MM-DD). scenarios is ["Actual", ...proj.baselineNames]
— the active scenario followed by every baseline scenario name
defined on the project. The order matches OmniPlan's own
baseline list; "Actual" is the conventional name for the active
scenario (proj.actual).
omniJS surface gaps surfaced during implementation (probed 2026-05-01 against OmniPlan 4.10.2):
proj.startDate is undefined; date lives on actual.startDate.
actual.currency accepts a write inline but does NOT persist
across JXA calls (same trap as constraint dates) — omitted from
the response shape rather than returning a stale value.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully bears the burden of transparency. It details the return format, data sources (JXA SDEF surface vs omniJS), and known implementation quirks like date and currency persistence issues, offering deep behavioral insight.
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 front-loaded with the main purpose but includes extensive implementation details and surface gap notes. While each sentence adds value, the length could be reduced for quick consumption.
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 no output schema provided in the input, the description fully specifies the return shape (JSON fields and their meanings) including edge cases and known bugs, making the tool's behavior completely understandable.
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, and schema coverage is 100%. Baseline for zero-parameter tools is 4; the description adds no redundant parameter info, which 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 'Return project-level info for the front document,' specifying the verb (return), resource (project-level info), and scope (front document). This distinguishes it from siblings like get_task or list_documents.
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 project-level details but does not explicitly contrast with alternatives or advise when not to use it. No exclusions or sibling references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full details of a single task by its unique ID.
Args: task_id: The uniqueID of the task.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It indicates a read operation ('get'), which is inherently non-destructive, but does not mention permissions, error handling (e.g., if task not found), or any side effects. Adequate for a simple retrieval 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?
Description is two sentences with a clear 'Args' section. No fluff or redundancy. Front-loaded with purpose. Efficient and well-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?
Given the tool has an output schema (not shown), explanation of return values is unnecessary. The description covers the single required parameter and the action. It could mention that the response contains full details, but it's already implied. Lacks nothing critical 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?
The schema has 1 parameter (task_id) with 0% description coverage. The tool description adds 'The uniqueID of the task,' which essentially repeats the schema field title and type without additional detail (e.g., format, examples, constraints). This 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?
Description clearly states 'Get full details of a single task by its unique ID.' This uses a specific verb (get) and resource (task), and the phrase 'by its unique ID' distinguishes it from sibling tools like query_tasks or find_task which may use filters.
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 usage for retrieving details of a single task. However, it does not provide explicit guidance on when to use this over alternatives like query_tasks or when not to use it (e.g., for batch retrieval). Still, the purpose is clear and appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the resource assignments on a task.
Args: task_id: uniqueID of the task.
Returns:
JSON array of {resource_id, resource_name, units_assigned}
for each assignment on the task. Empty array if the task has
no assignments. Reads assignment.unitsAssigned directly per
the documented Assignment class.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 the tool reads `assignment.unitsAssigned` directly, returns an empty array for no assignments, and is clearly a read-only operation. It could mention if there are any prerequisites, but overall it is 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 succinct, using a clear structure with Args and Returns sections. Every sentence adds value, and there is no unnecessary 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 listing tool with one parameter and a documented return format, the description is complete. It explains the output structure, empty array behavior, and even mentions the internal field read. The output schema exists to provide further details, but the description suffices on its own.
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 0% description coverage, so the description must add meaning. It describes the task_id parameter as 'uniqueID of the task', which provides clarity beyond the schema that only defines it as a string. This compensates well for the schema gap.
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 it lists resource assignments on a task, using a specific verb and resource. It clearly distinguishes from sibling tools like assign_resource and unassign_resource by focusing on read-only listing.
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 tool is for viewing assignments on a given task. Although it does not explicitly mention when not to use it, the context from sibling tools and the task_id parameter make the usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List dependencies in the document.
Args: task_id: Optional uniqueID. If provided, only dependencies where the task is the predecessor or successor are returned. If omitted, every dependency in the document is returned.
Returns:
JSON array of {"predecessor_id", "successor_id", "kind", "lead_time_seconds"}. lead_time_seconds is read from
dep.leadTimeDuration.workSeconds; it is null only when no
lead-time Duration is set on the dependency.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It thoroughly explains the return format, including fields and the special handling of lead_time_seconds when null.
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 and well-structured: a brief intro line followed by Args and Returns sections. 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?
Given the single optional parameter and the presence of an output schema, the description fully covers behavior and return details, making it complete for a simple list 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?
With 0% schema coverage, the description compensates by explaining the task_id parameter's effect: optional, filters when provided, otherwise returns all. It adds meaning beyond the schema's type definition.
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 'List dependencies in the document,' specifying the verb (list) and resource (dependencies). This distinguishes it from siblings like add_dependency and remove_dependency.
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 explains the optional filtering by task_id and the default behavior of listing all dependencies. It provides clear context but does not explicitly state when not to use it or list alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all currently open OmniPlan documents. Note: task tools now always operate on the current front document.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It indicates the tool lists 'currently open' documents, implying a read-only operation with no destructive side effects. However, it does not explicitly state that it is non-modifying, but the verb 'list' and the context of OmniPlan suggest safety.
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: two sentences with no wasted words. The core purpose is front-loaded, and the note provides additional context 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?
For a simple no-parameter list tool, the description covers the essential behavior (listing open documents) and the note about task tools adds valuable context. The existence of an output schema handles return values, so no further details 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?
The tool has no parameters, so the input schema fully covers them. The description adds no parameter information because none is needed, meeting the baseline for 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 'List all currently open OmniPlan documents,' which is a specific verb ('list') and resource ('documents'), and distinguishes this tool from sibling tools like list_assignments or list_resources by focusing on documents.
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 context that listing documents is about open documents, and the note about task tools operating on the current front document hints at when this tool might be used (e.g., to check which document is active), but it does not explicitly state when to use this versus other list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all resources in the document.
Returns:
JSON array of {id, name, type, email, cost_per_use}. Walks
the rootResource tree depth-first; group resources are flattened
out (their leaf members appear individually).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses depth-first traversal and flattening of group resources, which adds behavioral context beyond the simple listing. It also specifies the return format.
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 with two clear paragraphs. The first sentence states the purpose, and the second explains the return format and behavior. 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?
Despite having an output schema externally, the description provides the return format and traversal behavior. It is complete for a simple list tool with no parameters, covering purpose, behavior, and output.
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, and schema coverage is 100% (no params). According to the rubric, baseline is 4. The description adds no parameter info, which is unnecessary.
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 'List all resources in the document' with a specific verb and resource. It distinguishes from sibling tools like create_resource, delete_resource, etc., by focusing on listing.
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 listing resources but provides no explicit guidance on when to use this tool over alternatives like list_assignments or list_dependencies. No when-not or context cues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reparent a resource without changing its uniqueID.
Wraps the omniJS resource.move(newParent, index) method introduced
in OmniPlan 4.10.3 (build v232.5.9, 2026-05-06). Both omniJS args
are required at the API level; this tool fills in index with
newParent.members.length (append at end) when omitted.
Because uniqueID is preserved across the move, assignments that reference the moved resource stay intact — no clone-and-rebuild.
Args:
resource_id: uniqueID of the resource to move.
new_parent_id: uniqueID of the destination group resource. If
omitted, the resource is moved under the document's
rootResource.
index: 0-based position in new_parent.members. If omitted,
appended at the end.
Returns:
JSON {moved: true, id, new_parent_id, index} where id is
the unchanged uniqueID and new_parent_id is the resolved
parent's uniqueID.
| Name | Required | Description | Default |
|---|---|---|---|
| resource_id | Yes | ||
| new_parent_id | No | ||
| index | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that uniqueID is preserved, describes the underlying omniJS method, explains automatic index filling, and specifies the return format. However, it omits error conditions or permission requirements, which 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?
The description is well-structured with clear sections (purpose, method details, args, returns). It is front-loaded with the main action. However, the omniJS version and build details add unnecessary length for an AI agent; trimming would improve 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 the tool complexity (3 parameters, output schema), the description covers core behaviors: reparenting without ID change, default index behavior, and return format. It is sufficient for typical usage but lacks details on error handling or constraints (e.g., cycles).
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 0%, so description must explain parameters. It provides detailed semantics for each: resource_id (required), new_parent_id (defaults to root), and index (defaults to append). Adds context beyond schema, such as automatic index handling, which is critical for correct usage.
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: 'Reparent a resource without changing its uniqueID.' It uses a specific verb (move) and resource (resource), and distinguishes itself from siblings like 'move_task' and 'create_resource' by focusing on moving within the hierarchy.
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 explains behavior (preserves uniqueID, fills index if omitted) but lacks explicit guidance on when to use this tool over alternatives like delete-and-recreate. It implies usage for re-parenting but does not state exclusions or contexts where other tools 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.
Reparent a task without changing its uniqueID.
Wraps the omniJS task.move(newParent, index) method introduced in
OmniPlan 4.10.3 (build v232.5.9, 2026-05-06). Both omniJS args are
required at the API level; this tool fills in index with
newParent.subtasks.length (append at end) when the caller omits it.
Because uniqueID is preserved across the move, dependencies and resource assignments that reference the moved task stay intact — no clone-and-rebuild required.
Args:
task_id: uniqueID of the task to move.
new_parent_id: uniqueID of the destination parent. If omitted,
the task is moved to the document root.
index: 0-based position in new_parent.subtasks after the move.
If omitted, the task is appended at the end.
Returns:
JSON {moved: true, id, new_parent_id, index} where id is the
unchanged uniqueID, new_parent_id is the resolved parent's
uniqueID (root's -1 if moved to root), and index is the
final position used.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | ||
| new_parent_id | No | ||
| index | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavioral traits: preserves uniqueID, maintains dependencies/resource assignments, fills in index when omitted, and specifies the underlying omniJS method and version. No contradictions.
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 well-structured with clear sections (main purpose, context, Args, Returns). While slightly lengthy, every sentence serves a purpose. Front-loaded with 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?
Given the complexity of reparenting and the existence of sibling tools like move_resource, the description covers inputs, behavior, output format, edge cases (omitted params), and version requirements. It is fully self-contained.
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 0%, but the description's Args section explains all three parameters: task_id (required), new_parent_id (defaults to root), index (defaults to append at end). This adds complete meaning beyond the schema's type and required fields.
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 'Reparent a task without changing its uniqueID.' It uses specific verbs ('reparent') and distinguishes from alternative approaches (clone-and-rebuild) by emphasizing preservation of uniqueID, dependencies, and assignments.
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 implicitly guides usage by highlighting when to use (to preserve uniqueID and dependencies) but does not explicitly mention when not to use or enumerate alternatives like delete_task+create_task. The context is clear but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query tasks in an OmniPlan document with optional filters.
Args: keyword: Filter by title or note containing this text (case-insensitive). task_type: One of: task, group, milestone, hammock. completed: True = completed only, False = incomplete only, None = all. due_before: ISO date string (e.g. 2025-12-31). Tasks ending before this date. due_after: ISO date string (e.g. 2025-01-01). Tasks ending after this date. limit: Maximum number of tasks to return. Returns all tasks if omitted. detail: 'summary' (default) returns core fields only; 'full' returns all fields.
| Name | Required | Description | Default |
|---|---|---|---|
| keyword | No | ||
| task_type | No | ||
| completed | No | ||
| due_before | No | ||
| due_after | No | ||
| limit | No | ||
| detail | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description details filter behavior (case-insensitive keyword, date filtering, detail levels) but does not explicitly state read-only nature or potential performance implications.
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 and well-structured, with a summary line followed by a clear list of parameters, each earning 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 output schema exists, the description covers input parameters thoroughly. It lacks mention of error handling or edge cases, but is otherwise complete for a query 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?
With 0% schema coverage, the description provides complete explanations for all 7 parameters, including types, defaults, and behavior, adding significant 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 clearly states it queries tasks with optional filters, distinguishing it from sibling tools like create_task 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?
The description explains each filter but does not provide explicit guidance on when to use this tool versus alternatives like get_task or list_assignments.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove the dependency between two tasks.
Args: predecessor_id: uniqueID of the prerequisite task. successor_id: uniqueID of the dependent task.
Returns:
JSON {"removed": true} if a matching dependency was found and
removed, {"removed": false} if no such dependency existed.
| Name | Required | Description | Default |
|---|---|---|---|
| predecessor_id | Yes | ||
| successor_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool returns a JSON indicating success or failure, but it does not mention idempotency, permissions, or side effects. 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?
The description is concise and well-structured, with a clear one-line purpose followed by bullet-pointed arguments and return value. 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?
Given the simplicity of the tool (2 parameters, clear return type), the description fully explains inputs and outputs. The output schema is described in the return section, making the description complete for the 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 description coverage is 0%, so the description must compensate. It provides clear, human-readable explanations for both parameters (predecessor_id and successor_id) beyond the schema's type-only information.
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 'Remove the dependency between two tasks,' using a specific verb and resource. It distinguishes from siblings like add_dependency and list_dependencies by focusing on 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 does not explicitly state when to use this tool vs alternatives, but the sibling list provides implicit context. No when-not-to-use or precondition information is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save the front OmniPlan document to disk.
OmniPlan does NOT autosave the front document on idle — verified
empirically against OmniPlan 4.10.2 by editing a task via MCP and
polling document.modified over a 10-second window: the flag
stayed true throughout. Explicit save is therefore the only way to
persist changes to disk between explicit File > Save commands in
the UI (or quit-time prompts).
Returns:
JSON {"saved": true, "name": "<doc>", "modified_after": false}
on success. The modified_after field reads back the document's
dirty flag after the save call to confirm the save took effect.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: saves to disk, verifies dirty flag after save, and provides empirical evidence about lack of autosave. Return format is detailed.
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?
Reasonably concise, front-loaded with purpose and context, though the empirical verification section is slightly verbose. Still well-structured and every sentence contributes 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 simple tool with no parameters, the description covers purpose, necessity, and return format completely. 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; schema coverage is trivially 100%. The description adds rich meaning about what the tool does and its return value, far 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?
Clearly states 'Save the front OmniPlan document to disk', a specific verb and resource. No sibling tool performs save, so it is well distinguished.
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 notes that OmniPlan does not autosave and that explicit save is the only way to persist changes, providing clear when-to-use guidance and context for necessity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a resource assignment from a task.
Args: task_id: uniqueID of the task. resource_id: uniqueID of the resource.
Returns:
JSON {removed: bool}. True when a matching assignment was
found and removed, false otherwise.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | ||
| resource_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 the tool returns a boolean indicating success, and notes behavior when no matching assignment is found (returns false). However, it does not mention potential side effects, permissions needed, or error conditions (e.g., invalid task_id).
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 introductory sentence, then a clear Args list and Returns statement. Every sentence adds value, and the action is 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?
Given the simplicity of the operation (two string parameters, a boolean return) and the existence of an output schema (implied by the return description), the description is sufficiently complete. It covers the core function, parameters, and return format. Minor missing details (e.g., error handling) are not critical for a straightforward 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 description coverage is 0%, so the description must compensate. It explains that task_id is the 'uniqueID of the task' and resource_id is the 'uniqueID of the resource', adding clear semantics beyond the schema's type and title. This is adequate for clarity.
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 a resource assignment from a task.' It uses a specific verb (remove) and resource (assignment from task), and distinguishes from siblings like assign_resource (which adds) and list_assignments (which 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?
No usage guidelines are provided. The description does not indicate when to use this tool instead of alternatives, such as when an assignment exists versus when it doesn't, or prerequisites like the task and resource must exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update project-level fields on the front document.
Args:
start_date: ISO date for the project's actual start. Maps to
document.project.actual.startDate. Verified persistent
across JXA calls. Empty string is rejected — clearing the
project start date isn't supported.
Returns:
Post-write get_project_info shape.
Note: currency and working_hours are NOT supported by this
tool. omniJS accepts the writes but they don't persist across calls
(probed live 2026-05-01); shipping them would be a footgun. The
fields would need a parallel SDEF AppleScript bridge.
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the behavioral transparency burden. It discloses persistence across calls, rejection of empty string for start_date, and explicitly warns that currency and working_hours writes are non-persistent, providing live probing 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 well-structured with Args, Returns, and Note sections, each sentence adding value. It is front-loaded with the main action and contains no fluff, making it concise yet comprehensive.
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 single parameter and existence of an output schema (returning get_project_info shape), the description covers all necessary aspects: parameter mapping, constraints, unsupported fields, and return shape. It is fully sufficient for an agent to use 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?
Schema description coverage is 0%, so the description must compensate. It does so by explaining start_date as an ISO date mapping to document.project.actual.startDate, and notes that empty string is rejected, adding significant meaning beyond the schema's type and default.
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 'Update project-level fields on the front document,' with a specific verb and resource. It further elaborates on the start_date parameter, distinguishing it from sibling tools like update_task by focusing on project-level updates.
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 updating start_date and provides a note that currency and working_hours are not supported, offering negative guidance. However, it lacks explicit instructions on when to use this tool versus alternatives like add_dependency or get_project_info.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing task. Only provided fields are changed.
Args:
task_id: The uniqueID of the task.
title: New title.
note: New note text.
completed: True to mark complete, False to mark incomplete.
manual_start_date: ISO date string, or empty string to clear.
manual_end_date: ISO date string, or empty string to clear.
effort_seconds: Total effort in person-seconds. Pass 0 to set to zero;
None (omit) to leave unchanged.
min_effort_seconds: Three-point estimation minimum (person-seconds).
expected_effort_seconds: Three-point estimation expected value.
max_effort_seconds: Three-point estimation maximum.
start_no_earlier_than: ISO date string, or empty string to clear.
Maps to task.startNoEarlierThanDate.
start_no_later_than: ISO date string, or empty string to clear.
Maps to task.startNoLaterThanDate.
end_no_earlier_than: ISO date string, or empty string to clear.
Maps to task.endNoEarlierThanDate.
end_no_later_than: ISO date string, or empty string to clear.
Maps to task.endNoLaterThanDate.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | ||
| title | No | ||
| note | No | ||
| completed | No | ||
| manual_start_date | No | ||
| manual_end_date | No | ||
| effort_seconds | No | ||
| min_effort_seconds | No | ||
| expected_effort_seconds | No | ||
| max_effort_seconds | No | ||
| start_no_earlier_than | No | ||
| start_no_later_than | No | ||
| end_no_earlier_than | No | ||
| end_no_later_than | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses key behavioral traits: it confirms mutation ('Update'), explains partial update semantics ('Only provided fields are changed'), and details parameter-specific behaviors like clearing dates with empty strings and leaving fields unchanged with null omission. However, it does not mention error handling or idempotency.
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 efficiently front-loaded with the core purpose, then lists parameters in a clear, readable format. While it is lengthy due to 14 parameters, every line adds value without redundancy. A slightly more structured list format could improve scannability.
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 (14 parameters), the description covers all input semantics thoroughly. The presence of an output schema absolves the need to describe return values. The description could be improved by mentioning behavior for non-existent task_id or other error scenarios.
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?
With 0% schema coverage, the description fully compensates by detailing each parameter's purpose, format (ISO dates), units (person-seconds), and special values (0 to set, None to omit). It also clarifies internal field mappings for date constraints. This goes well beyond the schema's minimal type info.
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 'Update an existing task' with a specific verb and resource, and adds the important qualifier 'Only provided fields are changed' to distinguish from full replacement. This is distinct from sibling tools like create_task and 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?
Description implies use for updating existing tasks but provides no explicit guidance on when to use this tool vs alternatives (e.g., move_task, assign_resource). No preconditions or when-not-to-use advice is given.
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. Dates show when Glama detected each change.
v0.4.5add_dependencyassign_resourcecreate_resourcecreate_taskcreate_tasksdelete_resourcedelete_taskfind_taskget_project_infoget_tasklist_assignmentslist_dependencieslist_documentslist_resourcesmove_resourcemove_taskquery_tasksremove_dependencysave_documentunassign_resourceupdate_projectupdate_taskEach tool targets a distinct operation on tasks, resources, assignments, dependencies, project info, or documents. No two tools have overlapping purposes; e.g., create_task and create_tasks differ in batch vs. single, and query_tasks vs. find_task serve different query patterns.
All 22 tools follow a consistent verb_noun snake_case pattern (e.g., add_dependency, assign_resource, create_task). There are no deviations or mixed conventions, making the naming predictable and intuitive.
With 22 tools, the server is slightly above the typical well-scoped range (3-15) but still reasonable for a project management domain. The count is justified by the need to cover tasks, resources, assignments, dependencies, project settings, and document operations.
The tool surface covers full CRUD for tasks and resources, plus assignments, dependencies, project info, and document management. Batched creation and query/find variants are included. There are no obvious gaps for core project scheduling workflows.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Manage Superlist tasks and lists in plain language from any MCP-compatible AI agent.
Task management your AI agents can actually run. One line becomes a context-ready task over MCP.
Project management MCP for AI agents with safe task reads and writes.
Local-first task manager: create, edit, and complete tasks, projects, and checklists via MCP.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/johntrandall/omniplan-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
