Provides tools for interacting with the OmniFocus application on macOS, enabling project and task management, folder organization, tag handling, and UI navigation via AppleScript.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@OmniFocus MCP Server add a task to review the project proposal due tomorrow at 5pm"
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.
A comprehensive, fast, reliable, and agent-friendly MCP server for OmniFocus on macOS.
21 tools covering projects, tasks, folders, tags, perspectives, and focus. Full CRUD with unified batch operations (Pydantic model inputs), 20+ filter types on task and project queries, and date management including recurrence (RRULE read/write).
Sub-second reads on filtered queries, even with hundreds of tasks in the database.
Operation | Time | Items | Database |
Get flagged tasks | 0.66s | 14 | 202 tasks |
Get overdue tasks | 0.69s | 8 | 202 tasks |
Get next tasks | 0.66s | 27 | 202 tasks |
Get inbox tasks | 0.64s | 10 | 202 tasks |
Search tasks by keyword | 1.07s | 37 | 202 tasks |
Get all tasks (unfiltered) | 2.20s | 202 | 202 tasks |
Get all projects | 0.57s | 35 | 35 projects |
Create or update a task | 0.9s | — | — |
Full profiling data: PERFORMANCE_PROFILING.md
93% code coverage from 1027 unit tests. 192 integration and E2E tests run against real OmniFocus, plus 5 protocol-level smoke tests verifying the full MCP JSON-RPC transport. Tests cover task, project, and tag lifecycles, filtering, hierarchy, dates, recurrence, and review workflows.
73-scenario blind eval suite with frontier models scoring 100% and popular open-weight models scoring 90-94% (full results). Agents that have never seen OmniFocus can correctly use every tool from descriptions alone. Scenarios cover tool selection, parameter usage, multi-step workflows, date semantics, recurrence, tag behavior, task movement, text search, and safety-critical operations (drop vs delete, destructive action guardrails). Server instructions teach GTD concepts (task states, project types, sequential dependencies, review cycles) so agents make informed decisions, not just API calls.
Related MCP server: OmniFocus MCP Server
get_projects — filter by ID, query, status; includes dates, review info, task health, stalled detection
create_project — with folder placement, dates, review interval, project type
update_project — all properties: name, note, status, dates, folder, review settings
update_projects — batch update (status, dates, folder, review settings)
delete_projects — single or batch
reorder_project — position relative to siblings within a folder (before/after)
get_tasks — 14 filter types: by ID, project, parent, tags, status, dates, flags, text search, inbox
create_task — with dates, tags, flags, estimated time, parent task, sequential
update_task — all properties including recurrence (RRULE), tags (replace/add/remove), hierarchy
update_tasks — batch update (dates, flags, tags, status, project)
delete_tasks — single or batch
reorder_task — position relative to siblings (before/after)
get_folders — hierarchy with paths
create_folder — with optional parent
update_folder — rename or move to different parent
get_tags — with status and mutual exclusivity info
create_tag — with parent nesting and exclusivity
update_tag — name, status, exclusivity
delete_tags — single or batch
get_perspectives — list with type info
switch_perspective — navigate to perspective
set_focus — focus on projects/folders or clear
get_focus — current focus state
macOS with OmniFocus installed
Python 3.10+
uv package manager
git clone https://github.com/s-morgan-jeffries/omnifocus-mcp.git
cd omnifocus-mcp
git checkout v0.13.2 # Latest stable release
# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Install dependencies
uv sync --devAdd to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"omnifocus": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/omnifocus-mcp",
"run",
"omnifocus-mcp"
]
}
}
}python -m omnifocus_mcp.server_fastmcpCommunicates via stdin/stdout using the MCP protocol.
macOS will prompt for:
Accessibility access (to control OmniFocus via AppleScript)
Automation permissions for OmniFocus
Bug reports and feature requests are welcome via GitHub Issues.
MIT
Create one or more folders.
Parameters (per item):
name: str (required)
parent_path: str -- e.g. "Work > Clients"
| Name | Required | Description | Default |
|---|---|---|---|
| folders | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose behavior beyond the creation action. No annotations are provided, so it should cover aspects like handling of duplicate names, invalid parent_path, or side effects. None are mentioned.
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 short paragraphs with no unnecessary words. It front-loads the purpose and parameter details efficiently.
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 presence of an output schema, the description is not required to explain return values. However, the tool has nested objects and could benefit from more context on error conditions or permissions. It is adequate but not thorough.
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 description lists the per-item parameters and provides an example for parent_path, adding value over the bare schema. However, it does not explain the format fully (e.g., delimiter), null handling, or optionality. Schema coverage is 0%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates one or more folders, and lists the key parameters. This distinguishes it from siblings like create_projects or create_tags, which are for different 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 on when to use this tool vs alternatives (e.g., create_projects). No mention of prerequisites, error handling, 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.
Create one or more projects.
Parameters (per item):
name: str (required)
note, folder_path: str
project_type: str -- "parallel" (default), "sequential", "single_actions"
sequential: bool (deprecated, use project_type)
review_interval_value: int + review_interval_unit: str ("day"/"week"/"month"/"year"); review_interval_weeks: int (deprecated)
completed_by_children: bool
due_date, defer_date, planned_date: str -- ISO 8601
| Name | Required | Description | Default |
|---|---|---|---|
| projects | 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 must cover behavioral traits. It lists parameters and deprecation notes but omits details like authentication requirements, idempotency, error behavior, or what happens on duplicate names.
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, starting with a purpose sentence followed by a bulleted parameter list. It avoids fluff but could be slightly more structured (e.g., grouping fields).
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 all parameters, notes deprecations, and provides format hints (ISO 8601 for dates). With an output schema present, return values are covered elsewhere. Missing sibling comparisons or usage conditions, but sufficient for invocation.
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 description coverage, the description compensates by detailing each parameter, including types, defaults, and deprecation warnings (e.g., sequential is deprecated, use project_type). It explains the pairing of review_interval_value and review_interval_unit. However, some fields like completed_by_children lack explanation.
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 'Create one or more projects,' clearly stating the action and resource. This distinguishes it from sibling tools like create_tasks, create_folders, etc.
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 versus alternatives like update_projects or delete_projects. It only describes parameters, leaving usage context implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create one or more tags.
Parameters (per item):
name: str (required)
parent_tag: str -- parent by name
children_are_mutually_exclusive: bool
| Name | Required | Description | Default |
|---|---|---|---|
| tags | 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 must carry the full burden. It only states 'Create one or more tags' without mentioning idempotency, conflicts, permissions, or side effects. The parameter list adds some context but lacks behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one sentence plus parameter list. No unnecessary information. However, it could be slightly more structured with bullet points for readability.
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 purpose and parameters but omits return behavior, error states, and constraints. Since an output schema exists (not shown), the description isn't required to explain return values, but more context on use cases would be beneficial.
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 description adds minimal meaning beyond the input schema: it lists parameters with types and a brief comment for parent_tag ('parent by name'). However, it does not explain children_are_mutually_exclusive. Schema description coverage is 0%, so the description compensates partially but not fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and resource 'tags', and explicitly mentions it can create one or more tags. It is distinct from siblings like create_folders, create_projects, etc.
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. It does not specify prerequisites, use cases, 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.
Create one or more tasks.
Parameters (per item):
task_name: str (required)
project_id: str -- mutually exclusive with parent_task_id
parent_task_id: str -- creates subtask
note: str (plain text only)
due_date, defer_date, planned_date: str -- ISO 8601
flagged: bool
tags: list[str] -- must already exist
estimated_minutes: int
sequential: bool -- subtasks completed in order
completed_by_children: bool
| 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 provided, so the description carries full burden. It discloses key behaviors (mutual exclusion, subtask creation, tag prerequisite, date format) but does not mention idempotency, permission requirements, success/failure behavior, or side effects beyond creation.
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 core action and then uses a clear bullet list for parameters. While mostly efficient, the list could be slightly more concise (e.g., grouping related fields) but overall well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists (context signal), the description need not explain return values. It covers creation behavior, parameter constraints, and basic semantics. It omits error handling, batch size limits, and what happens on duplicate task names, but for a creation tool it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does so thoroughly: it explains constraints (mutual exclusion, required fields, date format, tag existence), default values are implied through description, and boolean roles are clarified (sequential, completed_by_children).
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 one or more tasks.' and the sibling tools list includes other create operations for different resources (folders, projects, tags), so the tool is well-differentiated.
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 constraints (mutual exclusivity of project_id and parent_task_id, tags must already exist, date format) that guide correct usage. It does not, however, discuss when to use this tool versus other task-related tools (e.g., update_tasks) or state 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.
Permanently delete projects and all their tasks. Cannot be undone.
project_ids: str | list[str] (required)
| Name | Required | Description | Default |
|---|---|---|---|
| project_ids | 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 destructive behavior ('permanently delete', 'cannot be undone') and cascading deletion of tasks. This adds significant behavioral context beyond the schema, though it omits details like 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?
Extremely concise: two sentences and a param note, with no wasted words. Key information is front-loaded, including the permanent and cascading effects.
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 (one param, destructive action), the description covers the main purpose, consequence, and parameter. It could mention the output schema (exists but not described) and potential errors, but it is reasonably complete for a deletion 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 description coverage, the description adds useful clarification: it specifies 'project_ids' as a string or list of strings and marks it required, which supplements the anyOf schema definition. However, it does not explain the meaning or constraints further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'permanently delete' and the resource 'projects and all their tasks', including the irreversible nature. It effectively distinguishes itself from sibling tools like delete_tags and delete_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 does not provide guidance on when to use this tool versus alternatives (e.g., archive vs delete, or other deletion tools). No explicit when-to-use or when-not-to-use conditions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete tags. Tasks lose tag association but are not deleted.
tag_ids: str | list[str] (required)
| Name | Required | Description | Default |
|---|---|---|---|
| tag_ids | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes that deleting tags does not delete associated tasks, which is a key behavioral trait. However, with no annotations, more details (e.g., permanence, required permissions) are needed for full 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?
Very short and front-loaded, but the parameter line is redundant with the schema. Every sentence serves a purpose, but could be more concise by omitting the schema repetition.
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 delete tool with no annotations and an output schema not shown, the description lacks details on return values, confirmation, or error handling, leaving the agent underinformed.
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 description merely repeats the schema type and required status without adding meaning, format examples, or constraints. Schema coverage is 0%, so the description fails to compensate.
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?
Tool name 'delete_tags' and description 'Delete tags' clearly state the action and resource. The additional sentence clarifies that tasks are preserved, distinguishing it from possibly destructive sibling tools like 'delete_projects' or 'delete_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 like removing individual tag associations through other means. No prerequisites or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete tasks. Cannot be undone.
task_ids: str | list[str] (required)
| Name | Required | Description | Default |
|---|---|---|---|
| task_ids | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Only mentions irreversibility; lacks details on batch behavior, error handling, or effects on related data.
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?
Very concise; two sentences plus parameter line. No waste, but could be slightly more structured (e.g., using bullet points). Still efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a deletion tool with one parameter and output schema present, description is minimal. Lacks detail on behavior for multiple IDs, invalid IDs, or return value indications.
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?
Repeats schema info (type, required) but adds no new meaning. With 0% schema parameter coverage, description should compensate with format, constraints, or examples, which it 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?
Clearly states 'Permanently delete tasks' with verb and resource, distinguishing it from siblings like delete_projects and delete_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?
No guidance on when to use this tool vs alternatives (e.g., update_tasks to mark as completed) or when not to use it. Only warns of irreversibility.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get currently focused items.
| 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 provided, and description only states it gets items without disclosing whether it returns a list or single item, side effects, or meaning of 'focused items'.
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 (4 words), but lacks detail that could be helpful without being overly long.
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 parameters and an output schema, description still fails to explain what 'focused items' are or the nature of the return value, leaving the agent underinformed.
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, schema coverage 100%, so description does not need to add parameter info. Baseline of 4 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 it retrieves currently focused items, distinguishing it from sibling tool set_focus which sets focus.
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 set_focus or other retrieval tools. Does not mention that it is useful for checking current state before modifications.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all folders with hierarchy.
Returns: id, name, path (e.g. "Work > Clients"), status ("active"/"dropped").
| 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 carries the full burden. It states it returns folders but does not disclose any behavioral details such as performance, error handling, or whether it is a safe read operation (though 'get' implies read-only).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences, front-loading the purpose and listing return fields. 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 that an output schema exists (not shown but indicated), the description's mention of return fields is sufficient. It covers the essentials for a simple list tool, though missing details on potential edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so schema coverage is 100%. The description adds no parameter information because none is needed, meeting the baseline of 4.
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 all folders with hierarchy, and enumerates returned fields. It does not explicitly differentiate from sibling tools like get_projects or get_tags, but the resource 'folders' is distinct enough.
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. There is no mention of prerequisites, limitations, or a comparison to other 'get' tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all perspectives.
Returns: name, type (built-in/custom), id
| 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, and the description only states it returns data without disclosing any behavioral traits like read-only nature, permissions, or side effects. For a simple get operation, minimal disclosure is given.
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 with no extraneous information, front-loaded with the core purpose, and efficiently includes return field details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and the presence of an output schema, the description sufficiently states what the tool returns. It could potentially mention ordering or scope, but for a list-all tool it is adequate.
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, baseline is 4. The description adds value by specifying what is returned (name, type, id), which the input schema does not cover.
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 all perspectives' with a specific verb and resource, and lists the return fields (name, type, id). This distinguishes it from sibling tools like get_tasks or get_projects.
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. With many sibling get_* tools, the description lacks context for when to choose get_perspectives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve projects with optional filtering.
Parameters:
project_id: str -- filter to specific project
query: str -- search name/note/folder (case-insensitive)
flagged_only, on_hold_only, completed_only: bool
stalled_only: bool -- active projects with no available next actions
include_dropped, include_completed: bool -- include hidden states
include_full_notes: bool
include_task_health: bool -- adds remainingCount, availableCount, overdueCount, deferredCount, stalled, health
include_last_activity: bool -- adds lastActivityDate
has_overdue_tasks: bool -- implies include_task_health
tag_filter: list[str] -- projects with ALL specified tags
due_after, due_before, due_on: str -- ISO date filters for due date
defer_after, defer_before, defer_on: str -- ISO date filters for defer date
planned_after, planned_before, planned_on: str
completion_after, completion_before, completion_on: str
dropped_after, dropped_before, dropped_on: str
created_after, created_before, created_on: str
modified_after, modified_before, modified_on: str
min_task_count: int
has_no_due_dates: bool
sort_by: str -- "name", "due_date", "defer_date", "planned_date", "creation_date", "modification_date", "completion_date", "dropped_date"; sort_order: str -- "asc"/"desc"
Returns: id, name, folderPath, status, projectType, sequential (deprecated), completedByChildren, flagged, creationDate, modificationDate, completionDate, droppedDate, dueDate, deferDate, plannedDate, tags, note, lastReviewDate, nextReviewDate, reviewIntervalValue, reviewIntervalUnit. Optional health/activity fields when requested.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | No | ||
| include_full_notes | No | ||
| on_hold_only | No | ||
| query | No | ||
| include_task_health | No | ||
| include_last_activity | No | ||
| stalled_only | No | ||
| flagged_only | No | ||
| include_dropped | No | ||
| include_completed | No | ||
| completed_only | No | ||
| tag_filter | No | ||
| planned_after | No | ||
| planned_before | No | ||
| planned_on | No | ||
| due_after | No | ||
| due_before | No | ||
| due_on | No | ||
| defer_after | No | ||
| defer_before | No | ||
| defer_on | No | ||
| completion_after | No | ||
| completion_before | No | ||
| completion_on | No | ||
| dropped_after | No | ||
| dropped_before | No | ||
| dropped_on | No | ||
| created_after | No | ||
| created_before | No | ||
| created_on | No | ||
| modified_on | No | ||
| has_overdue_tasks | No | ||
| sort_by | No | ||
| sort_order | No | asc | |
| modified_after | No | ||
| modified_before | No | ||
| min_task_count | No | ||
| has_no_due_dates | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description carries the burden. It explains parameter behaviors (e.g., stalled_only, has_overdue_tasks) but does not mention rate limits, pagination, or result size limits. The read-only nature is implied but not explicitly stated.
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 thorough but verbose, spanning many lines. It is well-structured with parameter documentation and return field listing, but could be more concise by grouping similar date filters.
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 high parameter count and existence of an output schema, the description covers nearly all aspects of the tool, including all parameters and return fields. It lacks pagination info and error handling, but is otherwise 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?
With 0% schema description coverage, the description fully compensates by providing clear explanations for all 38 parameters, including types, defaults, and semantics (e.g., 'stalled_only: bool -- active projects with no available next actions').
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 projects with optional filtering, using the verb 'Retrieve' and resource 'projects'. It distinguishes itself from sibling tools like create_projects, delete_projects, and update_projects by focusing on read-only retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like get_tasks or get_focus. The description lacks context about prerequisites, exclusivity, or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve all tags.
Returns: id, name, status ("active"/"on hold"/"dropped"), parentTagId (empty if top-level; create/update accept parent by NAME not ID), childrenAreMutuallyExclusive (assigning one child silently removes siblings).
| 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 effectively discloses return fields and important behaviors, such as parentTagId being empty for top-level tags and the mutual exclusivity behavior for children.
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 sentences, front-loading the core purpose and efficiently detailing key field semantics and behavioral notes without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers essential field details and a notable behavior (mutual exclusivity) beyond the output schema, making it sufficiently complete for a simple list tool with no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist in the schema, so the description had no need to add parameter information. The baseline of 4 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 'Retrieve all tags' with a specific verb and resource, distinguishing it from sibling tools like create_tags, update_tags, and delete_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 lacks explicit guidance on when to use this tool versus alternatives. While context implies it's for listing all tags, no when-not-to-use or sibling differentiation is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get tasks with optional filtering.
Parameters:
task_id, parent_task_id, project_id: str
query: str -- search name/note
flagged_only, available_only, overdue, dropped_only, blocked_only, next_only, inbox_only: bool
include_completed: bool
include_full_notes: bool
tag_filter: list[str]; tag_filter_mode: str -- "and" (default), "or", "not"
due_after, due_before, due_on: str -- ISO date filters for due date
defer_after, defer_before, defer_on: str -- ISO date filters for defer date
planned_after, planned_before, planned_on: str
completion_after, completion_before, completion_on: str -- requires include_completed
dropped_after, dropped_before, dropped_on: str -- requires dropped_only or include_completed
modified_after, modified_before, modified_on, created_after, created_before, created_on: str
max_estimated_minutes: int -- quick wins filter
has_estimate: bool
recurring_only: bool
sort_by: str -- "name", "due_date", "defer_date", "planned_date", "creation_date", "modification_date", "completion_date", "dropped_date"; sort_order: str
Returns: id, name, projectName, completed, dropped, blocked, available, next, flagged, dueDate, deferDate, plannedDate, estimatedMinutes, tags, note, parentTaskId, subtaskCount, sequential, isRecurring, recurrence, repetitionMethod, repeatSummary, nextDueDate, nextDeferDate, nextPlannedDate, catchUpAutomatically, creationDate, modificationDate, completionDate, droppedDate.
Key fields:
available -- true when actionable (accounts for inherited status from containers)
repeatSummary -- human-readable recurrence; always use this for display, don't parse RRULE
repetitionMethod -- "fixed" (original schedule), "start_after_completion" (defer shifts), "due_after_completion" (due shifts)
catchUpAutomatically -- recurring only; true = one catch-up occurrence, false = each missed interval spawns its own
Date fields are effective (include inherited from project). Next-occurrence fields populated only for recurring tasks.
Tasks inherit tags from their parent project. A task showing a tag it wasn't explicitly assigned has inherited it -- this is expected, not a bug.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | No | ||
| parent_task_id | No | ||
| include_full_notes | No | ||
| project_id | No | ||
| flagged_only | No | ||
| include_completed | No | ||
| available_only | No | ||
| overdue | No | ||
| dropped_only | No | ||
| blocked_only | No | ||
| next_only | No | ||
| tag_filter | No | ||
| query | No | ||
| inbox_only | No | ||
| sort_by | No | ||
| sort_order | No | asc | |
| modified_after | No | ||
| modified_before | No | ||
| created_after | No | ||
| created_before | No | ||
| max_estimated_minutes | No | ||
| has_estimate | No | ||
| recurring_only | No | ||
| tag_filter_mode | No | and | |
| planned_after | No | ||
| planned_before | No | ||
| planned_on | No | ||
| due_after | No | ||
| due_before | No | ||
| due_on | No | ||
| defer_after | No | ||
| defer_before | No | ||
| defer_on | No | ||
| completion_after | No | ||
| completion_before | No | ||
| completion_on | No | ||
| dropped_after | No | ||
| dropped_before | No | ||
| dropped_on | No | ||
| created_on | No | ||
| modified_on | 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 carries the full burden. It discloses key behaviors: date fields are effective (inherit from project), tags may be inherited, and specific recurrence behaviors (e.g., repeatSummary should be used for display, not RRULE). This adds significant context beyond the schema, though it could mention pagination or default limits.
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 lengthy but well-structured: a one-line summary, parameter list, return fields, and key field explanations. It front-loads the purpose. However, it could be more concise by omitting parameter names already in schema.
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 (41 parameters, rich return fields), the description covers most important aspects: inherited dates/tags, recurrence details, and field meanings. It is largely complete, though it omits potential behavior like pagination or result limits.
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 must add meaning. It lists all 41 parameters with types and minimal descriptions, plus crucial notes like 'requires include_completed' for completion filters. This adds value over the bare schema, though some parameters (e.g., sort_order) lack explanation of values.
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 with optional filtering,' identifying the verb (get), resource (tasks), and capability (filtering). This distinguishes it from sibling tools like create_tasks or delete_tasks, which have different purposes.
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 by listing parameters for various filtering scenarios, but it does not explicitly guide when to use this tool over others (e.g., for simple listing vs. complex queries). It lacks exclusion criteria or alternatives, making it adequate but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move a project before or after another project within the same folder.
project_id: str (required)
before_project_id: str
after_project_id: str
Exactly one of before/after required.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| before_project_id | No | ||
| after_project_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 must disclose behavioral traits. It indicates a mutation operation ('move') but does not detail side effects, permissions, or error conditions. The output schema exists, but the description does not reference it, leaving some behavioral aspects implicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus a bullet list, with no redundant information. The first sentence states the purpose clearly, and the list explains parameters and constraints efficiently.
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 main functionality and parameter constraints. It implicitly assumes the 'same folder' context (stated) but does not clarify ordering semantics or error handling. Given the simple nature and existence of an output schema, 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?
The schema has 0% description coverage, so the description fully compensates. It lists all three parameters and explains the constraint that exactly one of 'before_project_id' or 'after_project_id' is required, adding crucial meaning beyond the schema names and types.
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 a project relative to another project within the same folder. It uses specific verbs ('move') and resource ('project'), and distinguishes from the sibling tool 'reorder_task' which operates on 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 specifies that exactly one of 'before_project_id' or 'after_project_id' is required, but does not provide guidance on when to use this tool versus other project management tools like 'update_projects' or 'delete_projects'. It implies the context of reordering but lacks explicit alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move a task before or after another task within the same project/level.
task_id: str (required)
before_task_id: str -- place before this task
after_task_id: str -- place after this task
Exactly one of before/after required. In sequential projects, order = dependencies.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | ||
| before_task_id | No | ||
| after_task_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions reordering within same project/level and dependency effects, but lacks details on side effects, idempotency, or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: five lines front-loaded with main action, each 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 presence of output schema, description reasonably covers core functionality and constraints. Lacks error details or prerequisites, but adequate for 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 has 0% description coverage, but the description explains all three parameters and the constraint of exactly one before/after. Compensates well for schema deficiency.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action (Move/reorder), resource (task), and scope (within same project/level). It effectively distinguishes from sibling tool reorder_project.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly specifies that exactly one of before/after is required, and notes dependency implications in sequential projects. Could further clarify when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Focus on projects/folders, or clear focus. Does not support tasks or tags.
item_ids: str | list[str] -- omit or empty to clear
item_types: str | list[str] -- "project" or "folder"
| Name | Required | Description | Default |
|---|---|---|---|
| item_ids | No | ||
| item_types | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears the full burden. It discloses the clear-focus behavior via empty item_ids and the limitation on item_types, but does not explain idempotency, side effects (e.g., overwrites previous focus), or authentication needs. It adds some value beyond the schema but lacks comprehensive 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 (two sentences plus bullet list) and front-loaded with the core behavior and limitations. Every sentence adds value. The structure is clean, though the parameter list could be more integrated into the 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?
Given the tool's simplicity (2 optional params, output schema exists), the description covers the essential usage pattern and limitations. It does not explain error cases or the exact meaning of 'focus' in the system, but for a low-complexity tool this is 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%, so the description must compensate. It explains that item_ids can be omitted/empty to clear focus and that item_types must be 'project' or 'folder', adding crucial semantic meaning. However, it does not clarify whether both parameters must match or if they can be used together for filtering.
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 focuses on projects/folders or clears focus, and it explicitly says it does not support tasks or tags, distinguishing it from sibling tools like create_tasks. However, it does not mention the specific verb 'set' vs 'get' to contrast with get_focus, slightly reducing clarity.
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 setting focus on projects/folders, and notes what it does not support (tasks/tags), but it does not provide explicit when-to-use or when-not-to-use guidance compared to alternatives like get_focus or update_folders. The omission/empty pattern to clear focus is useful but not a full guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Switch front window to a perspective.
perspective_name: str (required)
| Name | Required | Description | Default |
|---|---|---|---|
| perspective_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description must fully disclose behavioral traits. It only says 'switch front window' without noting any side effects, required permissions, or whether changes are reversible. Minimal insight beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences), but the second sentence simply restates the parameter. It is under-specified rather than appropriately concise. Every part should add value; the parameter line does not.
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 (not shown), the description does not mention return values or error conditions. With sibling tools like 'get_perspectives' and 'set_focus', no guidance is given on when to use this tool. Incomplete for effective agent use.
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 merely repeats the parameter name and type ('perspective_name: str (required)'), adding no meaning beyond the schema. Does not explain what a perspective is, how to obtain valid values, or the parameter's role.
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 states 'Switch front window to a perspective,' which is a specific verb ('switch') and resource ('perspective'). It distinguishes from siblings like 'get_perspectives' which lists perspectives. However, it does not elaborate on what 'front window' means, leaving slight 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. There is no mention of prerequisites, context, or exclusions. The agent is left to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update one or more folders. Each item has id (required) plus fields to change.
Parameters (per item):
id: str (required)
name: str
status: str -- "active" or "dropped"
| Name | Required | Description | Default |
|---|---|---|---|
| folders | 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 must disclose behavior. It only states 'Update' and lists fields, but does not mention whether updates are partial or full, idempotency, error handling, or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with two brief paragraphs. The first sentence states the purpose, and the second lists parameters in a clear format. Every sentence is essential.
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 purpose and parameters, but lacks information on error scenarios, prerequisites (e.g., folder must exist), or whether updates are atomic. An output schema exists but its content is unknown.
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 significant value: it clarifies the 'status' field as only 'active' or 'dropped' and lists parameters with types. This compensates for the empty 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?
The description clearly states 'Update one or more folders', with a specific verb and resource. It lists the updatable fields (name, status), distinguishing it from sibling tools like create_folders or update_projects.
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., create_folders or delete). The context of updating existing folders is implied but not contrasted with other operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update one or more projects. Each item has id (required) plus fields to change.
Parameters (per item):
id: str (required)
project_name, note, folder_path: str -- note: replaces rich text
project_type: str; sequential: bool (deprecated)
status: str -- "active", "on_hold", "done", "dropped"
review_interval_value: int + review_interval_unit: str ("day"/"week"/"month"/"year"); review_interval_weeks: int (deprecated)
last_reviewed: str -- ISO or "now" (recalculates next_review_date from review interval)
next_review_date: str -- set AFTER last_reviewed to override the calculated date
completed_by_children: bool
due_date, defer_date, planned_date: str -- ISO or "" to clear
flagged: bool
estimated_minutes: int
tags: list[str] -- full replacement (conflicts with add_tags/remove_tags)
add_tags, remove_tags: list[str]
recurrence: str -- RRULE or "" to clear; repetition_method: str -- "fixed", "start_after_completion", "due_after_completion"
| Name | Required | Description | Default |
|---|---|---|---|
| projects | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description adds valuable behavioral context: note replacement of rich text, tag replacement vs. add/remove, deprecated fields, and date calculation interactions (e.g., last_reviewed recalculates next_review_date). However, it does not cover authorization or side effects of mutating multiple projects.
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 efficient and well-structured with a leading sentence and bullet points. It front-loads the purpose and groups related parameters. However, it is somewhat lengthy due to the high number of parameters, which is justified.
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 (22+ parameters, array input) and lack of annotations, the description covers all parameters and their interactions. It also explains deprecated fields. The output schema is not referenced but is present in the tool definition. Minor omission: no mention of error handling or success feedback.
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 carries full burden. It explains each parameter with type hints and special behaviors (e.g., 'ISO or "" to clear', 'full replacement', 'deprecated'). This adds substantial meaning 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 'Update one or more projects' with a required 'id' per item, distinguishing this tool from related tools like 'create_projects' and 'delete_projects'.
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 for updating existing projects, but does not explicitly state when to use instead of alternatives like 'create_projects' or 'update_tasks'. No when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update one or more tags. Each item has id (required) plus fields to change.
Parameters (per item):
id: str (required)
name, status: str -- status: "active", "on_hold", "dropped"
children_are_mutually_exclusive: bool
parent_tag: str -- move to parent by name, "" for top level
| Name | Required | Description | Default |
|---|---|---|---|
| tags | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavioral traits. It only lists parameters and does not mention what happens if an id is missing, whether updates are partial/full, return behavior, idempotency, or side effects. This is insufficient for an agent to understand the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and readable, mixing a prose sentence with a parameter list. It is not overly verbose. Slight improvement could be better formatting, but it efficiently conveys the parameter structure.
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 has moderate complexity with nested parameters and an output schema. The description omits important context: return values, error handling, whether updates are atomic, and effects on tag relationships. It is incomplete for safe and effective use.
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, so the description must add meaning. It explains id is required, lists allowed status values, and notes parent_tag usage. However, it does not explain the effect of children_are_mutually_exclusive or how fields interact. The description adds moderate 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 'Update one or more tags', which is a specific verb-resource pair. It distinguishes itself from sibling tools like create_tags, delete_tags, and get_tags, so the agent knows exactly what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for modifying existing tags but does not explicitly state when to use update_tags versus create_tags or delete_tags. There is no guidance on prerequisites or exclusions, leaving room for misinterpretation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update one or more tasks. Each item has id (required) plus fields to change.
Parameters (per item):
id: str (required)
task_name, project_id, parent_task_id, note: str
due_date, defer_date, planned_date: str -- ISO or "" to clear
flagged, completed: bool -- completed=True on recurring task creates next occurrence
status: str -- "dropped" (prefer completed: bool for completion)
tags: list[str] -- full replacement (conflicts with add_tags/remove_tags)
add_tags, remove_tags: list[str]
estimated_minutes: int
recurrence: str -- RRULE or "" to clear; repetition_method: str
sequential: bool; completed_by_children: bool
| Name | Required | Description | Default |
|---|---|---|---|
| tasks | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description discloses important behaviors such as recurrence creation on completed=true, tag replacement vs add/remove conflict, and date clearing with empty string. However, it omits mentioning that omitted fields remain unchanged (null default).
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 main sentence followed by a parameter list, though slightly verbose with 'Parameters (per item):' and some redundancy. Generally efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all input fields and key behaviors, but lacks mention of batch limits or error handling. Output schema exists so return values are not needed. Good for complexity level.
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 compensates by explaining each parameter's semantics, including date format, tag conflict, and completed behavior on recurring tasks, 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 'Update one or more tasks' with a verb and resource, and distinguishes from sibling tools like create_tasks and delete_tasks by specifying the update action.
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 clear context for use (updating tasks) and includes guidance on tag conflicts and status preference, but does not explicitly state when not to use this tool vs alternatives like create_tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scored across 21 tools
Each tool targets a distinct entity or action (folders, projects, tags, tasks, focus, perspectives) with clear CRUD separation. No two tools have overlapping purposes.
All tools follow a consistent verb_noun pattern, using plural for collections (create_folders, get_projects) and singular for singular concepts (get_focus, switch_perspective). No mixing of conventions.
21 tools is slightly above the typical range but well-justified by the domain's complexity, covering multiple entities and operations like reordering and focus management. Still feels well-scoped without redundancy.
CRUD operations for all main entities exist, plus focus and perspective management. Minor gaps like perspective CRUD or advanced note handling are absent but core task management workflows are fully covered.
Manage tasks, Focus Zone, notes, projects, and task history from compatible AI assistants.
Manage projects, tasks, time tracking, and team collaboration through natural language.
ADHD-friendly tasks, notes & projects for LucidNest - 18 tools, scoped tokens, Streamable HTTP.
AI-native task management: list, create, update and archive tasks with rich context for AI agents
