The Things MCP server enables AI assistants to fully manage Tasks and Projects in Things 3 on macOS, supporting creation, reading, updating, and automation.
Write Operations
add-todo — Create to-dos with title, notes, scheduled date, deadline, tags, checklist items, and project/area assignment (supports multiple at once)
add-project — Create projects with initial to-dos, notes, dates, tags, and area assignment
update-todo — Modify a to-do's title, notes, dates, tags, checklist, status (complete/canceled), or list assignment (requires auth token)
update-project — Update a project's title, notes, dates, tags, area, or status (requires auth token)
add-json — Create complex nested structures (projects with headings, to-dos, checklist items) using Things' JSON command format
Read Operations
get-todos — Retrieve to-dos by built-in list (Inbox, Today, Upcoming, Someday, etc.), project, area, or tag
get-todo-by-id / get-project-by-id — Fetch a specific to-do or project by ID
get-projects / get-areas / get-tags — List all projects, areas, or tags
search-todos — Search to-dos by title or notes content
get-recent-todos — Get recently modified to-dos within a configurable number of days
Navigation & Search
show — Open Things to a specific list, project, area, tag, or individual to-do
search — Open the Things search screen with an optional query
Automation
reschedule-distant-todos — Automatically move far-future tasks out of the Today list, with configurable threshold/buffer days and a dryRun preview mode (requires auth token)
Requirements: macOS, Things 3 (with URL Scheme enabled), Node.js >= 18. Compatible with Claude Desktop, Cursor, Codex, and Gemini CLI.
Enables management of the Things 3 task manager on macOS, allowing for the creation, retrieval, and modification of to-dos, projects, areas, and tags through AppleScript and URL schemes.
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., "@Things MCP Add 'Review project proposal' to my Today list with a reminder at 4pm"
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.
An MCP (Model Context Protocol) server for Things 3 on macOS. Enables AI assistants like Claude to create, read, update, and manage your tasks directly in Things.
Tool | Description |
| Create a new to-do with title, notes, dates, tags, checklist, project/area assignment |
| Create a new project with to-dos, notes, dates, tags, area assignment |
| Update an existing to-do (requires auth-token) |
| Update an existing project (requires auth-token) |
| Navigate to a list, project, area, tag, or specific to-do |
| Open the Things search screen |
| Create complex structures via the Things JSON command |
Tool | Description |
| Get to-dos from a list (Inbox, Today, etc.), project, area, or by tag |
| Get a specific to-do by its ID |
| Get all projects |
| Get a specific project by its ID |
| Get all areas |
| Get all tags |
| Search to-dos by title/notes content |
| Get recently modified to-dos |
Tool | Description |
| Move distant-deadline to-dos out of Today. Finds items whose deadline is far away and reschedules their start date to a few days before the deadline, keeping your Today list focused on what matters now. Requires auth-token. |
Key behaviors of reschedule-distant-todos:
Items explicitly scheduled for today (activationDate = today) are always preserved
Uses a single JSON batch update for atomic, reliable rescheduling
daysThreshold (default: 7) controls how many days away a deadline must be to qualify
bufferDays (default: 3) controls how many days before the deadline to set the new start date
Supports dryRun mode to preview changes without applying them
Annotated with destructiveHint: true so MCP clients can prompt for user confirmation
Related MCP server: Things Cloud MCP
macOS (required for AppleScript/JXA and open command)
Things 3 installed
Node.js >= 18
Things URL Scheme enabled (Things > Settings > General > Enable Things URLs)
# Clone and build
git clone <repository-url>
cd things-app-mcp
npm install
npm run buildOr install globally:
npm install -g things-app-mcpAdd to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"things": {
"command": "npx",
"args": ["-y", "things-app-mcp@latest"]
}
}
}Add to your Cursor MCP settings (.cursor/mcp.json):
{
"mcpServers": {
"things": {
"command": "npx",
"args": ["-y", "things-app-mcp@latest"]
}
}
}Add to ~/.codex/config.toml:
[mcp_servers.things]
command = "npx"
args = ["-y", "things-app-mcp@latest"]
startup_timeout_sec = 20
tool_timeout_sec = 120Run the following command to register the MCP server:
gemini mcp add things npx -y things-app-mcp@latestTo use update-todo, update-project, and reschedule-distant-todos, you need your Things auth-token.
Option 1: Environment Variable (Recommended)
Set the THINGS_AUTH_TOKEN environment variable in your MCP client configuration. This avoids needing to pass the token with every request.
Claude Desktop:
{
"mcpServers": {
"things": {
"command": "npx",
"args": ["-y", "things-app-mcp@latest"],
"env": {
"THINGS_AUTH_TOKEN": "your-token-here"
}
}
}
}Codex (~/.codex/config.toml):
[mcp_servers.things]
command = "npx"
args = ["-y", "things-app-mcp@latest"]
startup_timeout_sec = 20
tool_timeout_sec = 120
[mcp_servers.things.env]
THINGS_AUTH_TOKEN = "your-token-here"Gemini CLI: Set the environment variable in your shell configuration or pass it when running:
export THINGS_AUTH_TOKEN="your-token-here"Option 2: Parameter
If the environment variable is not set, you must pass the token as the authToken parameter when calling update tools:
Open Things on Mac
Go to Things > Settings > General > Enable Things URLs > Manage
Copy your authorization token
Pass it as the authToken parameter when calling update tools
"Add a to-do called 'Buy groceries' scheduled for today with tags 'Errand'"The AI will call add-todo with:
{
"title": "Buy groceries",
"when": "today",
"tags": "Errand"
}"Create a project called 'Launch Website' in the Work area with to-dos: Design mockups, Build frontend, Deploy"The AI will call add-project with:
{
"title": "Launch Website",
"area": "Work",
"todos": "Design mockups\nBuild frontend\nDeploy"
}"Create a vacation planning project with headings for Travel, Accommodation, and Activities"The AI will call add-json with structured JSON data containing nested headings and to-dos.
"What's on my Today list?"The AI will call get-todos with { "list": "Today" } and return the structured data.
"Mark the 'Buy groceries' todo as complete"The AI will first search/get the to-do to find its ID, then call update-todo with the auth-token.
"My Today list is too cluttered. Move everything that isn't due soon to later."The AI will call reschedule-distant-todos with { "dryRun": true } first to preview, then apply:
{
"daysThreshold": 7,
"bufferDays": 3,
"dryRun": false
}Items with deadlines 7+ days away will be rescheduled to 3 days before their deadline. Items you explicitly set to today are always preserved.
"Show me which todos would be moved out of Today without actually changing anything"The AI will call reschedule-distant-todos with { "dryRun": true } and return a list of what would change.
This MCP server implements the full Things URL Scheme v2:
Format | Example | Description |
Named |
| Built-in schedule options |
Date |
| Specific date |
Date + Time |
| Date with reminder |
Natural language |
| English natural language (parsed by Things) |
show tool)inbox, today, anytime, upcoming, someday, logbook, tomorrow, deadlines, repeating, all-projects, logged-projects
Type | Description |
| A task with title, notes, when, deadline, tags, checklist-items |
| A project with title, notes, items (to-dos and headings) |
| A section heading within a project |
| A checklist item within a to-do |
things-app-mcp/
src/
index.ts # MCP server entry point with all tool registrations
things-url.ts # Things URL scheme builder (URL construction)
applescript.ts # AppleScript/JXA executor (read operations)
scripts/
test-client.js # Basic MCP server connectivity test
test-all-tools.js # Integration tests for all 16 tools
test-unit.js # Unit tests for logic, URL builders, and edge cases (122 tests)
dist/ # Compiled JavaScript output
package.json
tsconfig.jsonWrite operations construct things:/// URLs and open them via macOS open command. Things processes the URL and creates/updates items accordingly.
Read operations use JXA (JavaScript for Automation) scripts executed via osascript to query the Things database directly and return structured JSON data.
# Install dependencies
npm install
# Build
npm run build
# Watch mode
npm run dev
# Run directly
npm startSee TESTING.md for full details.
# Unit tests (date utilities, URL builders, reschedule logic, edge cases)
# Runs anywhere - no macOS or Things 3 required
node scripts/test-unit.js
# Integration tests (all 16 tools via MCP protocol)
# Requires macOS + Things 3 for full coverage
npm run test:tools
# With write operations enabled
THINGS_MCP_TEST_ALLOW_WRITES=1 npm run test:tools
# Full suite with auth token
THINGS_AUTH_TOKEN=your-token \
THINGS_MCP_TEST_TODO_ID=some-id \
THINGS_MCP_TEST_PROJECT_ID=some-id \
npm run test:toolsMIT
Create complex projects and to-dos using the Things JSON command. Supports nested projects with headings, checklist items, and to-dos. The data should be an array of objects with "type" (to-do, project, heading, checklist-item) and "attributes" fields. For updates, include "operation": "update" and "id" fields, and provide auth-token.
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | JSON string containing an array of Things objects. Each object has 'type' (to-do/project/heading/checklist-item), optional 'operation' (create/update), optional 'id' (for updates), and 'attributes' (title, notes, when, deadline, tags, items, etc.) | |
| authToken | No | Things auth-token (required when data contains update operations) | |
| reveal | No | Navigate to the first created item |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include 'openWorldHint: true', which suggests flexibility, but the description adds useful behavioral context: it discloses that the tool supports both creation and updates, requires an auth-token for updates, and handles nested structures. However, it doesn't mention potential side effects, error handling, or rate limits, leaving some behavioral aspects unclear.
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 appropriately sized and front-loaded, starting with the core purpose. Sentences are efficient, but the last sentence could be more concise by combining update instructions. Overall, it avoids redundancy and each sentence adds value, though minor improvements in flow are possible.
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 (handling creation and updates of nested structures) and lack of output schema, the description is moderately complete. It covers key usage aspects but doesn't explain return values or error cases. With annotations providing some context and schema covering parameters, it meets basic needs but could benefit from more detail on outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents parameters. The description adds minimal semantics beyond the schema: it reiterates that 'data' should be an array with 'type' and 'attributes', and notes auth-token is required for updates. This provides slight clarification but doesn't significantly enhance understanding beyond the schema's detailed descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Create complex projects and to-dos using the Things JSON command. Supports nested projects with headings, checklist items, and to-dos.' It specifies the verb ('create'), resource ('projects and to-dos'), and distinguishes from siblings like 'add-project' or 'add-todo' by emphasizing JSON-based creation with complex nested structures.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for usage: 'For updates, include "operation": "update" and "id" fields, and provide auth-token.' This indicates when to use this tool for updates versus creation, though it doesn't explicitly name alternatives like 'update-project' or 'update-todo' for updates, nor does it specify when to use this over simpler sibling tools like 'add-project' for basic operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new project in Things. Supports setting title, notes, when/deadline dates, tags, area assignment, and initial to-dos.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Title of the project | |
| notes | No | Notes for the project (max 10,000 chars) | |
| when | No | When to schedule: today, tomorrow, evening, anytime, someday, YYYY-MM-DD, or YYYY-MM-DD@HH:MM | |
| deadline | No | Deadline date: YYYY-MM-DD or natural language | |
| tags | No | Comma-separated tag names | |
| areaId | No | ID of an area to add to (takes precedence over area) | |
| area | No | Title of an area to add to | |
| todos | No | To-do titles separated by newlines to create inside the project | |
| completed | No | Set to true to mark as completed | |
| canceled | No | Set to true to mark as canceled | |
| reveal | No | Navigate into the newly created project | |
| creationDate | No | Creation date in ISO8601 format | |
| completionDate | No | Completion date in ISO8601 format |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide openWorldHint=true, indicating flexibility, but the description adds context about supported fields and the ability to create initial to-dos. However, it doesn't disclose behavioral traits like whether the tool requires authentication, rate limits, or what happens on conflicts (e.g., duplicate titles). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose and enumerates supported features. It avoids redundancy but could be slightly more structured, such as separating core vs. optional parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 13 parameters, no output schema, and minimal annotations, the description adequately covers the tool's purpose and key inputs. However, it lacks details on return values, error conditions, or advanced usage (e.g., handling of dates like 'someday'), leaving gaps for an agent to infer behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all 13 parameters. The description lists key parameters (title, notes, when/deadline dates, tags, area assignment, initial to-dos) but doesn't add meaning beyond what's in the schema, such as explaining interactions (e.g., areaId vs. area precedence) or constraints. Baseline 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a new project') and the resource ('in Things'), with specific details about supported fields (title, notes, dates, tags, area assignment, to-dos). It distinguishes from siblings like 'add-todo' (creates tasks) and 'update-project' (modifies existing 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 usage for creating new projects but doesn't explicitly state when to use this vs. alternatives like 'update-project' for modifications or 'add-todo' for standalone tasks. No guidance on prerequisites, such as whether areas must exist first, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new to-do in Things. Supports setting title, notes, when/deadline dates, tags, checklist items, and assigning to projects/areas. Uses the Things URL scheme.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Title of the to-do | |
| titles | No | Multiple to-do titles separated by newlines (takes priority over title) | |
| notes | No | Notes for the to-do (max 10,000 chars) | |
| when | No | When to schedule: today, tomorrow, evening, anytime, someday, YYYY-MM-DD, or YYYY-MM-DD@HH:MM for a reminder | |
| deadline | No | Deadline date: YYYY-MM-DD or natural language like 'next friday' | |
| tags | No | Comma-separated tag names (must already exist in Things) | |
| checklistItems | No | Checklist items separated by newlines (max 100) | |
| listId | No | ID of a project or area to add to (takes precedence over list) | |
| list | No | Title of a project or area to add to | |
| headingId | No | ID of a heading within a project | |
| heading | No | Title of a heading within a project | |
| completed | No | Set to true to mark as completed | |
| canceled | No | Set to true to mark as canceled (takes priority over completed) | |
| showQuickEntry | No | Show the quick entry dialog instead of adding directly | |
| reveal | No | Navigate to and show the newly created to-do | |
| creationDate | No | Creation date in ISO8601 format | |
| completionDate | No | Completion date in ISO8601 format |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include openWorldHint=true, indicating flexibility, but the description adds context about the 'Things URL scheme' and supports setting multiple attributes. However, it does not disclose behavioral traits like error handling, rate limits, or authentication needs beyond what annotations provide.
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 purpose and efficiently lists key attributes in a single sentence, followed by a brief note on the URL scheme. It avoids redundancy but could be slightly more structured for clarity with 17 parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 17 parameters and no output schema, the description adequately covers the tool's purpose and supported fields. However, it lacks details on return values or error cases, which would enhance completeness for a creation tool with many options.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all 17 parameters. The description lists the supported attributes (e.g., title, notes, dates) but does not add significant meaning beyond the schema, such as explaining interactions between parameters like 'titles' taking priority over 'title'.
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 specific action ('Create a new to-do in Things') and lists the key attributes that can be set (title, notes, dates, tags, etc.), distinguishing it from sibling tools like 'add-project' or 'update-todo' by focusing on to-do creation with comprehensive field support.
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 creating to-dos with various attributes but does not explicitly state when to use this tool versus alternatives like 'add-json' or 'update-todo'. It mentions the 'Things URL scheme' as context but lacks guidance on prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all areas from Things. Uses AppleScript (macOS only).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, indicating a safe read operation. The description adds value by specifying the implementation method ('Uses AppleScript') and platform constraint ('macOS only'), which aren't covered by annotations. However, it lacks details on return format, error handling, or other behavioral traits, so it only partially compensates for the absence of richer annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences: one stating the purpose and one adding implementation context. Every word earns its place, and it's front-loaded with the core functionality, making it 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's simplicity (0 parameters, read-only operation) and lack of output schema, the description is adequate but could be more complete. It covers purpose and platform constraints but doesn't explain what 'areas' are in the Things context or what the return data looks like, leaving some gaps for an AI agent to infer.
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 parameters and 100% schema description coverage, the schema fully documents the input (none required). The description doesn't need to add parameter details, so it meets the baseline for this scenario. No additional semantic information is provided or needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get all areas') and resource ('from Things'), providing a specific verb+resource combination. However, it doesn't distinguish this tool from sibling tools like 'get-projects' or 'get-todos' beyond specifying the resource type, which is why it doesn't reach a perfect score.
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 context with 'Uses AppleScript (macOS only)', suggesting platform restrictions, but doesn't explicitly state when to use this tool versus alternatives like 'get-projects' or 'get-todos'. No guidance on prerequisites or exclusions is provided, leaving usage somewhat ambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a specific project by its ID. Uses AppleScript (macOS only).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the project to retrieve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true, indicating a safe read operation. The description adds value by specifying the implementation uses AppleScript and is macOS-only, which are important behavioral constraints not covered by annotations. However, it lacks details on error handling, response format, or other operational traits.
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 that directly convey the tool's purpose and key constraints (AppleScript, macOS-only). Every word serves a clear purpose, and it is front-loaded with the core functionality, making it efficient and easy to parse.
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 (single parameter, read-only) and lack of output schema, the description covers the basic purpose and platform constraints adequately. However, it does not explain what the tool returns (e.g., project details) or potential limitations, leaving some gaps in context for effective use by an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the 'id' parameter fully documented. The description does not add any additional meaning or context beyond what the schema provides, such as ID format or examples, so it meets the baseline for high schema coverage without compensating 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 action ('Get') and resource ('a specific project by its ID'), making the purpose evident. However, it does not explicitly differentiate from sibling tools like 'get-projects' or 'get-todo-by-id', which would require mentioning it retrieves a single project rather than a list or other entity types.
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 you need a specific project by ID, but does not provide explicit guidance on when to use this tool versus alternatives like 'get-projects' for listing or 'search' for broader queries. No exclusions or prerequisites are mentioned, leaving usage context somewhat vague.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all projects from Things. Uses AppleScript (macOS only).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds useful context about the implementation method ('Uses AppleScript') and platform limitation ('macOS only'), which aren't covered by annotations. However, it doesn't describe behavioral aspects like return format, pagination, 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?
The description is perfectly concise with two sentences that each add distinct value: the first states the core functionality, the second provides important implementation context. There's zero wasted language, and information is front-loaded appropriately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with readOnlyHint annotation and no parameters, the description covers the basic purpose and platform constraints adequately. However, without an output schema, it doesn't describe what 'projects' data is returned (e.g., fields, structure), leaving the agent uncertain about the response format. The macOS limitation is important but doesn't fully compensate for the missing output information.
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 parameters and 100% schema description coverage, the schema fully documents the absence of inputs. The description doesn't need to add parameter information, so it appropriately focuses on other aspects. A baseline of 4 is appropriate for zero-parameter tools when the schema coverage is complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get all projects') and resource ('from Things'), making the purpose immediately understandable. It distinguishes from siblings like 'get-project-by-id' by specifying 'all projects' rather than a single one. However, it doesn't explicitly differentiate from other list tools like 'get-areas' or 'get-todos' beyond the resource name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to choose 'get-projects' over 'get-project-by-id' for specific projects, or 'get-areas' for different resource types. The macOS-only note is a platform constraint, not usage guidance relative to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get recently modified to-dos. Uses AppleScript (macOS only).
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Number of days to look back (default: 7) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond annotations by disclosing platform dependency ('macOS only') and implementation details ('Uses AppleScript'), which aren't covered by the readOnlyHint annotation. However, it lacks information on behavioral traits such as rate limits, error handling, or what 'recently modified' entails (e.g., modification vs. creation). No contradiction with annotations is present.
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 and front-loaded, consisting of just two sentences that efficiently convey the core functionality and key constraints. Every word earns its place, with no wasted information, making it easy to parse quickly.
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 (one optional parameter) and the presence of annotations (readOnlyHint), the description is minimally adequate. However, without an output schema, it doesn't explain return values (e.g., format of to-dos), and it lacks details on scope (e.g., all to-dos or filtered). For a read-only tool, it meets basic needs but could be more 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 description doesn't add any parameter-specific information beyond what's in the input schema, which has 100% coverage for the single parameter 'days'. Since the schema fully describes the parameter, the baseline score of 3 is appropriate, as the description doesn't compensate but also doesn't detract.
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 with a specific verb ('Get') and resource ('recently modified to-dos'), making it easy to understand what it does. However, it doesn't explicitly differentiate from sibling tools like 'get-todos' or 'search-todos', which likely have overlapping functionality, so it falls short of a perfect score.
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 some usage context by mentioning 'macOS only' and 'recently modified', which implies when to use it (for recent items on macOS). However, it doesn't offer explicit guidance on when to choose this tool over alternatives like 'get-todos' or 'search-todos', nor does it specify exclusions or prerequisites beyond the OS requirement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all tags from Things. Uses AppleScript (macOS only).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, which the description aligns with by using 'Get' (a read operation). The description adds value by specifying the implementation method ('Uses AppleScript') and platform constraint ('macOS only'), which aren't covered by annotations. However, it doesn't detail behavioral aspects like performance, error handling, or output 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 extremely concise with two short sentences that front-load the core purpose ('Get all tags from Things') and follow with implementation details. Every word earns its place, with no wasted text or unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with 0 parameters and annotations covering safety, the description is adequate but minimal. It lacks output details (no schema provided) and doesn't explain the scope of 'all tags' (e.g., if filtered or paginated). The macOS constraint is helpful, but more context on behavior would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, maintaining focus on the tool's purpose and constraints without redundancy.
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 ('Get all tags') and resource ('from Things'), making the purpose understandable. It distinguishes from some siblings like 'add-todo' or 'update-project' by focusing on retrieval, but doesn't explicitly differentiate from other get operations like 'get-areas' or 'get-projects' beyond the resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It mentions 'macOS only' as a platform constraint, but doesn't explain when to choose this over other tag-related operations (none exist in siblings) or other retrieval tools like 'get-areas' or 'get-projects' for different data types.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a specific to-do by its ID. Uses AppleScript (macOS only).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the to-do to retrieve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, indicating a safe read operation. The description adds valuable context beyond annotations: it specifies the implementation uses AppleScript and is macOS-only, which are critical behavioral traits not covered by annotations. It does not mention rate limits or error handling, but with annotations covering safety, this is sufficient for a high score.
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 with zero waste: the first states the core purpose, and the second adds essential platform and implementation details. It is front-loaded and appropriately sized, with every sentence 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 tool's low complexity (single parameter, read-only), no output schema, and rich annotations, the description is mostly complete. It covers purpose, platform constraints, and implementation method. However, it lacks details on return values (e.g., what data is included) or error cases, which would be helpful despite the absence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the 'id' parameter fully documented. The description does not add any meaning beyond the schema (e.g., format examples or constraints), so it meets the baseline of 3 where the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('a specific to-do by its ID'), making the purpose explicit. It distinguishes from siblings like 'get-todos' (list) and 'get-recent-todos' (filtered list) by specifying retrieval of a single item via ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it's for retrieving a specific to-do when you have its ID, implying it should not be used for listing or searching. However, it does not explicitly state when to use alternatives like 'get-todos' for listing or 'search-todos' for searching, nor does it mention prerequisites (e.g., ID must exist).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get to-dos from Things by list, project, area, or tag. Specify exactly one source. Uses AppleScript (macOS only).
| Name | Required | Description | Default |
|---|---|---|---|
| list | No | Built-in list name: Inbox, Today, Anytime, Upcoming, Someday, Logbook | |
| project | No | Project name to get to-dos from | |
| area | No | Area name to get to-dos from | |
| tag | No | Tag name to filter to-dos by |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond annotations: 'Uses AppleScript (macOS only).' This discloses platform limitations not covered by the readOnlyHint annotation. The annotations already indicate it's a read-only operation, so the description appropriately focuses on additional constraints rather than repeating safety information.
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 perfectly concise and front-loaded: two sentences that efficiently cover purpose, constraints, and platform limitations. Every word earns its place with no redundancy or unnecessary elaboration.
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 read-only retrieval tool with good annotations and full parameter documentation, the description is reasonably complete. It covers the core purpose, usage constraint, and platform limitation. The main gap is the lack of output schema, but the description doesn't need to explain return values since that's the schema's role when available.
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 100% schema description coverage, the input schema already fully documents all four parameters. The description adds marginal value by emphasizing 'Specify exactly one source,' which clarifies the mutual exclusivity of parameters. However, it doesn't provide additional semantic context beyond what's in the 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 the tool's purpose: 'Get to-dos from Things by list, project, area, or tag.' It specifies the verb ('Get') and resource ('to-dos'), and mentions the source options. However, it doesn't explicitly differentiate from sibling tools like 'get-recent-todos' or 'search-todos', which reduces it from a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: 'Specify exactly one source.' This gives explicit guidance on how to use the parameters. It also implies when to use this tool (for filtered retrieval) vs. alternatives like 'get-recent-todos' (for recent items) or 'search-todos' (for keyword searches), though it doesn't explicitly name these alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open the search screen in Things with an optional search query.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Search query text |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true and openWorldHint=true, indicating a safe, exploratory operation. The description adds that it 'opens the search screen,' which suggests a UI interaction rather than a direct data return, but does not detail what this screen entails, any limitations, or how it integrates with the system. No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that efficiently conveys the core action and parameter. It is front-loaded with the main purpose and avoids unnecessary details, making it highly concise 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's simplicity (one optional parameter, no output schema) and annotations covering safety and openness, the description is adequate but minimal. It lacks details on what the 'search screen' is, how results are presented, or interaction with sibling tools like 'search-todos,' leaving gaps in contextual understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for the single optional parameter 'query,' documented as 'Search query text.' The description mentions 'optional search query,' adding minimal context beyond the schema. With high schema coverage, the baseline score of 3 is appropriate as the description does not significantly enhance parameter understanding.
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: 'Open the search screen in Things with an optional search query.' It specifies the verb ('Open') and resource ('search screen in Things'), but does not explicitly distinguish it from the sibling 'search-todos' tool, which appears to be a more targeted search function.
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 mentioning it opens the search screen, but provides no explicit guidance on when to use this tool versus alternatives like 'search-todos' or other querying tools. It lacks clear when/when-not instructions or prerequisites for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for to-dos by title or notes content. Uses AppleScript (macOS only).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query to match against to-do titles and notes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint: true, indicating this is a safe read operation. The description adds value by disclosing the implementation method ('Uses AppleScript') and platform constraint ('macOS only'), which are behavioral traits not covered by annotations. However, it doesn't detail aspects like performance, error handling, or result format, keeping the score moderate.
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 and front-loaded, consisting of just two sentences that efficiently convey the core functionality and key constraints. Every word earns its place without redundancy, making it easy for an AI agent to parse quickly.
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 search tool with one parameter and read-only annotations, the description covers basic purpose and platform limits. However, without an output schema, it doesn't explain return values (e.g., result format or pagination), and it lacks details on search behavior (e.g., case sensitivity, partial matches). Given the simplicity, it's adequate but has clear gaps in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the 'query' parameter fully documented. The description adds minimal semantics by mentioning that the search matches against 'titles and notes,' but this is largely redundant with the schema's description. Given the high schema coverage, a baseline score of 3 is appropriate as the description doesn't significantly enhance parameter understanding.
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: 'Search for to-dos by title or notes content.' It specifies the verb (search) and resource (to-dos), and mentions the search scope (title or notes). However, it doesn't explicitly distinguish this tool from sibling tools like 'search' or 'get-todos', which might offer similar functionality, so it doesn't reach the highest score.
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 some usage context by stating 'Uses AppleScript (macOS only),' which implies platform restrictions. However, it doesn't offer explicit guidance on when to use this tool versus alternatives like 'search' or 'get-todos' from the sibling list, nor does it specify prerequisites or exclusions beyond the macOS note. This leaves room for ambiguity in tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Navigate to and show a list, project, area, tag, or to-do in Things. Built-in list IDs: inbox, today, anytime, upcoming, someday, logbook, tomorrow, deadlines, repeating, all-projects, logged-projects.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | ID of item to show, or a built-in list ID (inbox, today, anytime, upcoming, someday, logbook, tomorrow, deadlines, repeating, all-projects, logged-projects) | |
| query | No | Name of an area, project, tag, or built-in list to show (ignored if id is set) | |
| filter | No | Comma-separated tag names to filter the list by |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true and openWorldHint=true, indicating safe, read-only operations with flexible inputs. The description adds context by specifying the navigation aspect (implying UI interaction) and listing built-in list IDs, but does not disclose further behavioral traits like rate limits, authentication needs, or what 'show' entails beyond navigation. With annotations covering safety, a 3 is appropriate as the description adds some value but not rich 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 appropriately sized with two sentences: the first states the purpose and scope, and the second lists built-in list IDs for clarity. Every sentence earns its place by providing essential information without redundancy, making it front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (navigation with three parameters), rich annotations (readOnlyHint, openWorldHint), and 100% schema coverage, the description is mostly complete. It covers what the tool does and provides examples, but lacks details on output (no output schema) or explicit usage boundaries. For a read-only navigation tool, this is sufficient but not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for 'id', 'query', and 'filter' parameters. The description adds minimal value by listing built-in list IDs (which are already in the schema for 'id'), but does not explain parameter interactions (e.g., 'id' overrides 'query') or provide additional semantics beyond the schema. Baseline 3 is correct when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Navigate to and show') and the resources involved ('a list, project, area, tag, or to-do in Things'), distinguishing it from siblings like 'get-areas' or 'search' which retrieve data rather than navigate. It also lists built-in list IDs, providing concrete examples of what can be shown.
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 specifying what items can be shown (lists, projects, areas, tags, to-dos) and listing built-in list IDs, giving clear context for when to use it. However, it does not explicitly state when not to use it or name alternatives (e.g., 'get-todos' for retrieving data without navigation), which prevents a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing project in Things. Requires the project ID and your Things auth-token.
| Name | Required | Description | Default |
|---|---|---|---|
| authToken | Yes | Things URL scheme authorization token | |
| id | Yes | ID of the project to update | |
| title | No | New title | |
| notes | No | Replace notes | |
| prependNotes | No | Text to prepend to existing notes | |
| appendNotes | No | Text to append to existing notes | |
| when | No | When to schedule | |
| deadline | No | Deadline date | |
| tags | No | Replace all tags | |
| addTags | No | Add tags | |
| areaId | No | ID of area to move to | |
| area | No | Title of area to move to | |
| completed | No | Set completion status | |
| canceled | No | Set canceled status | |
| reveal | No | Navigate to the project | |
| duplicate | No | Duplicate before updating | |
| creationDate | No | Creation date in ISO8601 | |
| completionDate | No | Completion date in ISO8601 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide openWorldHint=true, indicating the tool can handle unknown parameters, but the description adds minimal behavioral context beyond stating authentication requirements. It doesn't disclose mutation effects, rate limits, or other behavioral traits. However, it doesn't contradict annotations, so it earns a baseline score for adding some value without rich 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?
The description is a single, efficient sentence that front-loads the core purpose and key requirements. It avoids unnecessary words, though it could be slightly more structured by separating purpose from prerequisites. Overall, it's appropriately sized with zero waste.
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 (18 parameters, mutation operation) and lack of output schema, the description is minimally adequate. It covers authentication and ID requirements but doesn't explain update behaviors, side effects, or return values. With annotations providing only openWorldHint, more context on mutation impact would improve completeness for this non-trivial 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 100% schema description coverage, the input schema fully documents all 18 parameters. The description adds no parameter-specific information beyond mentioning 'project ID' and 'auth-token' in general terms. This meets the baseline of 3 since the schema does the heavy lifting, but the description doesn't enhance understanding of parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update an existing project') and resource ('in Things'), which provides a specific verb+resource combination. However, it doesn't distinguish this tool from its sibling 'update-todo' or explain what differentiates project updates from todo updates, missing full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions that the tool 'Requires the project ID and your Things auth-token,' which provides basic prerequisites but no guidance on when to use this tool versus alternatives like 'update-todo' or other project-related tools. There's no explicit when/when-not usage context or named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing to-do in Things. Requires the to-do ID and your Things auth-token. Supports changing title, notes, dates, tags, checklist, list assignment, and status.
| Name | Required | Description | Default |
|---|---|---|---|
| authToken | Yes | Things URL scheme authorization token (find in Things Settings > General > Things URLs) | |
| id | Yes | ID of the to-do to update | |
| title | No | New title | |
| notes | No | Replace notes (pass empty string to clear) | |
| prependNotes | No | Text to prepend to existing notes | |
| appendNotes | No | Text to append to existing notes | |
| when | No | When to schedule: today, tomorrow, evening, someday, YYYY-MM-DD, or YYYY-MM-DD@HH:MM | |
| deadline | No | Deadline date (pass empty string to clear) | |
| tags | No | Comma-separated tags to replace all current tags | |
| addTags | No | Comma-separated tags to add to existing tags | |
| checklistItems | No | Newline-separated checklist items to replace all existing | |
| prependChecklistItems | No | Newline-separated checklist items to prepend | |
| appendChecklistItems | No | Newline-separated checklist items to append | |
| listId | No | ID of project or area to move to | |
| list | No | Title of project or area to move to | |
| headingId | No | ID of heading within project | |
| heading | No | Title of heading within project | |
| completed | No | Set completion status | |
| canceled | No | Set canceled status | |
| reveal | No | Navigate to the updated to-do | |
| duplicate | No | Duplicate the to-do before updating | |
| creationDate | No | Creation date in ISO8601 format | |
| completionDate | No | Completion date in ISO8601 format |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond the annotations. While annotations only provide 'openWorldHint: true', the description discloses that the tool requires authentication ('Requires the to-do ID and your Things auth-token'), which is crucial operational information not captured in annotations. It also clarifies the scope of updates ('Supports changing title, notes, dates...'), helping the agent understand what modifications are possible.
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 perfectly concise and front-loaded. The first sentence establishes the core purpose and requirements, while the second efficiently enumerates the supported update fields. Every word earns its place with zero redundancy or unnecessary elaboration, making it easy for an agent to quickly understand the tool's capabilities.
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 complex mutation tool with 23 parameters and no output schema, the description provides good contextual coverage. It clearly states authentication requirements, identifies the resource being modified, and outlines the scope of possible updates. The main gap is the lack of information about return values or error conditions, which would be helpful given the absence of an output schema. However, the description adequately covers the essential operational 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?
With 100% schema description coverage, the input schema already documents all 23 parameters thoroughly. The description adds minimal parameter semantics by listing categories of updatable fields ('title, notes, dates, tags, checklist, list assignment, and status'), but this mostly restates what's already evident from the schema. The baseline score of 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Update an existing to-do in Things') and resource ('to-do'), distinguishing it from sibling tools like 'add-todo' (creation) and 'update-project' (different resource). It specifies the exact scope of what can be updated (title, notes, dates, tags, etc.), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by stating it's for updating existing to-dos and listing the supported fields, but doesn't explicitly state when to use this versus alternatives like 'add-todo' or 'update-project'. It mentions the required parameters (to-do ID and auth-token) which provides some usage prerequisites, but lacks explicit guidance on tool selection scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0add-jsonadd-projectadd-todoget-areasget-project-by-idget-projectsget-recent-todosget-tagsget-todo-by-idget-todossearchsearch-todosshowupdate-projectupdate-todoScored across 15 tools
Most tools are clearly distinct by resource and action, such as add-project vs. update-project. However, some potential confusion exists: 'search' opens the search screen, while 'search-todos' performs a specific search; 'get-todos' retrieves by source, and 'get-recent-todos' gets recent ones, which might overlap in use cases. Descriptions help clarify, but minor ambiguity remains.
Tool names follow a consistent verb_noun pattern throughout, with clear actions like 'add', 'get', 'update', and 'search' paired with specific nouns like 'project', 'todo', or 'areas'. All names use snake_case uniformly, making them predictable and easy to parse.
With 15 tools, this server is well-scoped for managing tasks and projects in Things. It covers core CRUD operations for projects and to-dos, plus additional utilities like listing areas and tags, which fits the domain appropriately without being overwhelming or insufficient.
The tool set provides strong coverage for the task management domain, including creation, retrieval, and updates for projects and to-dos, plus listing areas and tags. Minor gaps exist: there's no explicit delete tool for projects or to-dos, and 'add-json' might overlap with other add tools, but agents can likely work around these with updates or existing methods.
Official Todoist MCP server for AI assistants to manage tasks, projects, and workflows.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
