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 "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@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 include 'openWorldHint: true', indicating the tool can create new resources, which aligns with the description's 'Create a new project'. The description adds value by specifying supported fields and mentioning 'initial to-dos', but does not disclose behavioral traits like permissions needed, rate limits, or side effects (e.g., how areaId/area precedence works). 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, efficient sentence that front-loads the core action ('Create a new project') and enumerates supported fields without redundancy. It avoids unnecessary words, though it could be slightly more structured (e.g., separating core vs. optional features) for optimal clarity.
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 with full schema coverage and no output schema, the description adequately covers the tool's purpose and key inputs. However, it lacks context on usage guidelines, behavioral details (e.g., error handling), and output expectations, making it incomplete for a mutation tool with many options. Annotations provide some support but not full transparency.
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 each parameter well-documented in the schema (e.g., 'when' includes format examples). The description lists key parameters (title, notes, when/deadline, tags, area, to-dos) but does not add significant meaning beyond the schema, such as explaining interactions (e.g., areaId vs. area) 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 specific action ('Create a new project') and resource ('in Things'), distinguishing it from sibling tools like 'add-todo' or 'update-project'. It explicitly lists the supported fields (title, notes, dates, tags, area, to-dos), making the purpose unambiguous and 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 no guidance on when to use this tool versus alternatives like 'add-todo' for individual tasks or 'update-project' for modifications. It lacks context about prerequisites (e.g., whether an area must exist) or exclusions (e.g., not for bulk operations), offering only a functional statement without usage boundaries.
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 provide openWorldHint=true, indicating flexible input handling. The description adds valuable context beyond this: it discloses the tool 'Uses the Things URL scheme' (implementation detail affecting behavior) and lists specific supported fields, giving practical insight into what can be set. 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 front-loaded with the core purpose ('Create a new to-do in Things'), followed by a concise list of supported fields and a key implementation note. It avoids redundancy, though the list of fields is somewhat lengthy but necessary for clarity.
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 (17 parameters, no output schema) and rich schema coverage, the description is reasonably complete. It covers purpose, supported fields, and a behavioral note. However, it lacks details on error handling, response format, or interactions with sibling tools, leaving minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter well-documented in the schema (e.g., format for 'when', max lengths). The description adds no additional parameter semantics beyond listing field names, 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 explicitly states 'Create a new to-do in Things' with a specific verb ('Create') and resource ('to-do'), clearly distinguishing it from sibling tools like 'update-todo' (modifies existing) or 'get-todos' (reads). It lists supported fields (title, notes, dates, tags, etc.) to further clarify scope.
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 but doesn't explicitly state when to use this vs. alternatives like 'add-json' (for batch creation) or 'update-todo' (for modifications). No guidance on prerequisites (e.g., needing Things app) or exclusions is provided.
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 already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds value by disclosing the implementation detail 'Uses AppleScript (macOS only)', which is useful context beyond annotations, but doesn't cover other behavioral aspects like 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 two sentences with zero waste: the first states the core purpose, and the second adds critical implementation context. It's appropriately sized and front-loaded, making it efficient for an agent 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 operation) and lack of output schema, the description is adequate but minimal. It covers the purpose and platform constraint, but doesn't explain what 'Get' entails (e.g., returns project details) or error cases, leaving some gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the parameter 'id' fully documented in the schema. The description doesn't add any parameter-specific details beyond what the schema provides, so it meets the baseline for high coverage without extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('a specific project by its ID'), making the purpose unambiguous. However, it doesn't differentiate from sibling tools like 'get-projects' or 'get-todo-by-id' beyond mentioning the resource type, which keeps 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 implies usage context by specifying 'Uses AppleScript (macOS only)', which provides platform constraints. However, it doesn't explicitly state when to use this tool versus alternatives like 'get-projects' or 'search', leaving some ambiguity for the agent.
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 declare readOnlyHint=true, which the description aligns with by using 'Get' (implying read-only). The description adds context about platform dependency ('macOS only') and implementation detail ('Uses AppleScript'), which are useful beyond annotations. However, it doesn't disclose behavioral traits like rate limits, error handling, or return format, keeping it at a baseline level.
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 short sentences with zero waste: the first states the purpose, and the second adds essential technical constraints. It's front-loaded with the core functionality and appropriately sized for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, read-only, no output schema), the description covers the basic purpose and platform constraints adequately. However, it lacks details on output format (e.g., what 'projects' includes) and doesn't leverage sibling context for differentiation, making it minimally viable but with gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and schema description coverage is 100% (though empty). With no parameters to document, the description doesn't need to compensate, and the baseline for 0 parameters is 4. The description appropriately doesn't discuss parameters, which is correct for this case.
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 'projects from Things', making the purpose specific and understandable. However, it doesn't distinguish this tool from sibling tools like 'get-project-by-id' or 'get-areas', which would require explicit differentiation to earn a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'get-project-by-id' or 'search'. It mentions 'Uses AppleScript (macOS only)', which is a technical constraint but not usage guidance. Without explicit when/when-not instructions or named alternatives, this scores low.
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 already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds useful context about platform dependency ('macOS only') and implementation method ('Uses AppleScript'), which aren't covered by annotations. However, it doesn't describe error handling, return format, or performance characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (two short sentences) with zero wasted words. The first sentence states the core purpose, and the second adds essential implementation context. Every element earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with good annotations (readOnlyHint) and full schema coverage, the description provides adequate context about platform constraints and implementation. The main gap is the lack of output schema, but the description doesn't need to explain return values since it's a straightforward get-by-id operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with the single parameter 'id' fully documented as 'The ID of the to-do to retrieve'. The description doesn't add any additional parameter semantics beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Get a specific to-do') and resource ('by its ID'), distinguishing it from sibling tools like 'get-todos' (list) and 'get-recent-todos' (filtered list). The phrase 'Uses AppleScript (macOS only)' further clarifies implementation constraints.
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 specifying 'by its ID' and 'macOS only', which helps differentiate from tools like 'search-todos' or 'get-recent-todos'. However, it doesn't explicitly state when to use this versus alternatives like 'get-todo-by-id' versus 'get-todos' for bulk retrieval.
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?
Annotations provide readOnlyHint=true, and the description doesn't contradict this. It adds valuable context beyond annotations: the 'Uses AppleScript (macOS only)' disclosure about implementation and platform dependency, which isn't captured in annotations. However, it lacks details on rate limits, auth needs, or return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, followed by critical constraints. Every word earns its place: no fluff, clear and efficient 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?
Given the tool's moderate complexity (4 parameters, no output schema), the description is fairly complete. It covers purpose, usage rules, and platform constraints. However, without output schema, it doesn't describe return values or pagination, leaving a minor gap for a retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter well-documented in the schema (e.g., 'list' includes enum-like values). The description adds minimal semantics by mentioning the source types but doesn't provide extra syntax or format details beyond the schema. 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 verb ('Get') and resource ('to-dos from Things'), specifies the filtering options ('by list, project, area, or tag'), and distinguishes from siblings like 'get-recent-todos' or 'search-todos' by emphasizing exact source specification. It's specific and 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 explicitly states 'Specify exactly one source', providing clear usage rules. It implies when not to use alternatives by focusing on filtered retrieval rather than search or recent items, and the platform constraint ('macOS only') adds context for exclusion.
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 already indicate readOnlyHint=true and openWorldHint=true, so the agent knows this is a safe, exploratory operation. The description adds that it 'opens the search screen', suggesting a UI interaction rather than a direct data return, which provides useful behavioral context beyond the 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 directly states the tool's purpose without any unnecessary words. It's appropriately sized for a simple tool and front-loads the core functionality.
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 good annotations and full schema coverage, the description is adequate but minimal. It lacks output information (no output schema provided) and doesn't clarify the relationship with the 'search-todos' sibling tool, leaving some contextual gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the single parameter 'query' fully documented in the schema. The description mentions it's 'optional search query text', which aligns with but doesn't add meaningful semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Open the search screen') and target ('in Things'), specifying the resource as the search interface. However, it doesn't explicitly differentiate from the sibling 'search-todos' tool, which appears to perform a more specific search operation.
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 minimal guidance, mentioning an optional query parameter but offering no context on when to use this tool versus alternatives like 'search-todos'. There's no mention of prerequisites, typical use cases, or exclusion criteria.
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?
The description adds minimal behavioral context beyond the openWorldHint annotation. It mentions authentication requirements ('your Things auth-token'), which is useful since annotations don't cover authentication. However, it doesn't describe what 'Update' entails behaviorally - whether it's a partial or complete update, how conflicts are handled, or what happens to unspecified fields. With annotations providing only openWorldHint, the description could do more to explain 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 appropriately concise with just two sentences that get straight to the point. The first sentence states the purpose, and the second provides the key requirements. There's no unnecessary verbiage, though it could be slightly more informative without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex update tool with 18 parameters and no output schema, the description is somewhat minimal. While the schema provides excellent parameter documentation, the description doesn't explain what constitutes a successful update, what gets returned, or how to interpret the various update options. The openWorldHint annotation suggests flexibility, but the description doesn't elaborate on this behavioral aspect.
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 18 parameters thoroughly. The description doesn't add any meaningful parameter semantics beyond what's in the schema - it only mentions the two required parameters (authToken and id) without explaining their purpose or relationship. This meets the baseline for high schema coverage but doesn't provide additional value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and resource 'existing project in Things', making the purpose immediately understandable. However, it doesn't differentiate this tool from its sibling 'update-todo' tool, which appears to serve a similar update function for a different 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 mentions that it 'Requires the project ID and your Things auth-token', which provides some basic prerequisites but doesn't offer guidance on when to use this tool versus alternatives like 'update-todo' or other project-related tools. No explicit when/when-not scenarios or sibling tool comparisons are provided.
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?
Annotations provide openWorldHint: true, indicating flexibility in parameter usage. The description adds value by listing the specific fields that can be updated (title, notes, dates, tags, etc.), which goes beyond the annotations. However, it does not disclose behavioral traits like rate limits, error handling, or what happens when only some fields are provided, leaving room for improvement.
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 requirements, followed by a concise list of updatable fields. It avoids redundancy and uses efficient phrasing, though the list of fields could be slightly more structured (e.g., grouped by category) for optimal 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?
Given the complexity of 23 parameters and no output schema, the description adequately covers the tool's purpose and scope. It lists the updatable fields, which helps contextualize the many parameters. However, it lacks details on return values or error cases, which would be beneficial for a mutation tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 23 parameters thoroughly. The description adds minimal value by summarizing the updatable fields but does not provide additional syntax, format details, or usage nuances beyond what the schema specifies. This meets the baseline for 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 verb 'update' and resource 'existing to-do in Things', distinguishing it from sibling tools like 'add-todo' (creation) and 'update-project' (different resource). It specifies the exact operation with the required parameters, 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 explicitly states 'Requires the to-do ID and your Things auth-token', providing clear prerequisites. However, it does not specify when to use this tool versus alternatives like 'update-project' or 'add-todo', nor does it mention any exclusions or specific scenarios where this tool is preferred over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.0.0add-jsonadd-projectadd-todoget-areasget-project-by-idget-projectsget-recent-todosget-tagsget-todo-by-idget-todossearchsearch-todosshowupdate-projectupdate-todoMost 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.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
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…
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/lucas-flatwhite/things-app-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
