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.
English | 한국어
MCP server for Things 3 on macOS. It adds, reads, and updates to-dos through the Things URL scheme and JXA, and npm run sync copies the Today list into a Notion database.
The server talks to the client over stdio on your Mac.
macOS
Node.js 18 or newer
Things URLs turned on: Things > Settings > General > Enable Things URLs
Automation permission for whichever app starts the server (Terminal, Claude, Cursor, or Codex). osascript has to be allowed to control Things.
Related MCP server: Things Cloud MCP
git clone https://github.com/lucas-flatwhite/things-app-mcp.git
cd things-app-mcp
npm install
npm run buildYou can also skip the clone and let the client run npx -y things-app-mcp@latest. The configs below do that.
Adding and reading to-dos works without a token. Changing an existing item, or applying a reschedule, needs the Things auth token.
In Things: Settings > General > Enable Things URLs > Manage.
Set THINGS_AUTH_TOKEN in the client config. If you pass authToken on each call, that token lands in the client log. Replies strip the token, notes, and JSON data. The URL given to open still has the token for a moment. Things expects it there.
~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"things": {
"command": "npx",
"args": ["-y", "things-app-mcp@latest"],
"env": {
"THINGS_AUTH_TOKEN": "your-token-here"
}
}
}
}.cursor/mcp.json
{
"mcpServers": {
"things": {
"command": "npx",
"args": ["-y", "things-app-mcp@latest"],
"env": {
"THINGS_AUTH_TOKEN": "your-token-here"
}
}
}
}~/.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"export THINGS_AUTH_TOKEN="your-token-here"
gemini mcp add things npx -y things-app-mcp@latestFor a local build, use node and the absolute path to dist/index.js instead of npx.
Tool | Description |
| New to-do: title, notes, when, deadline, tags, checklist, project, or area. |
| New project. Put to-do titles in |
| Change a to-do by id, including completing or canceling it. Needs the token. |
| Change a project by id. Needs the token. |
| Open a list, project, area, tag, or to-do in Things. |
| Open Things search. |
| Nested projects, headings, to-dos, and checklist items. Updates need the token. |
When a write succeeds, macOS has opened the URL. Read the item again if you need to see that Things saved it. add-todo does not return the new id.
Tool | Description |
| To-dos from one list, project, area, or tag. |
| One to-do by id. |
| Every project. |
| One project by id. |
| Every area. |
| Every tag. |
| To-dos whose title or notes contain the query. |
| To-dos changed in the last N days. Default is 7. |
Call get-todos with one of list, project, area, or tag. If you leave them all out, you get Today.
Lists: Inbox, Today, Anytime, Upcoming, Someday, Logbook.
Results include titles and notes.
reschedule-distant-todos looks through Today for open items whose deadline is still far off, and moves the start date to a few days before that deadline.
No arguments means preview only, and only when a token is set. To apply:
{
"daysThreshold": 7,
"bufferDays": 3,
"dryRun": false,
"confirm": true
}daysThreshold (default 7): a closer deadline stays in Today.
bufferDays (default 3): new start date, this many days before the deadline.
An item you put on today yourself (activationDate is today) stays where it is.
dryRun: false without confirm: true returns an error and leaves Today unread.
confirm is a tool argument. A client that reads destructiveHint may ask again before it runs.
The update is one JSON batch.
update-todo, update-project, and updates through add-json do not take confirm. With the token set, those calls can edit or complete items.
Add a to-do:
{
"title": "Buy groceries",
"when": "today",
"tags": "Errand"
}Create a project and its to-dos:
{
"title": "Launch Website",
"area": "Work",
"todos": "Design mockups\nBuild frontend\nDeploy"
}Read Today:
{ "list": "Today" }Read one project:
{ "project": "Launch Website" }Complete a to-do once you have its id:
{
"id": "the-todo-id",
"completed": true
}Preview a reschedule, then apply it:
{ "dryRun": true }{ "dryRun": false, "confirm": true }Write tools follow the Things URL scheme.
Format | Example |
Named |
|
Date |
|
Date and time |
|
Natural language |
|
show list idsinbox, today, anytime, upcoming, someday, logbook, tomorrow, deadlines, repeating, all-projects, logged-projects
add-json typesType | What it is |
| A task: title, notes, when, deadline, tags, checklist items. |
| A project: title, notes, nested items. |
| A section in a project. |
| One line in a to-do. |
To update, set "operation": "update" and "id". That needs the auth token.
src/index.ts MCP tools
src/things-url.ts things:/// URLs, and stripping secrets from replies
src/applescript.ts JXA reads
src/reschedule-mode.ts preview versus apply
src/notion-sync.ts `npm run sync`, separate from the MCP server
src/notion-sync/ plan, Notion client, Things read and writeWrites build a things:/// URL and hand it to open. Reads run JXA through osascript.
npm install
npm run build
npm run dev # tsc --watch
npm start # node dist/index.jsSee TESTING.md.
# No Things required.
node scripts/test-unit.js
# Sync plan, hashes, and the Notion client. No network and no Things.
npm run test:sync
# macOS and Things 3. Writes stay off.
npm run test:tools
THINGS_MCP_TEST_ALLOW_WRITES=1 npm run test:toolsOne case in the unit script reads Today when Things is installed. Skip it with:
THINGS_UNIT_SKIP_LIVE=1 node scripts/test-unit.jsnpm run sync copies the Things Today list into Notion database 9ac2752989a646918bfa93ab900dfb8c. That list is whatever Things is showing under Today: items for today, this evening, and overdue items still sitting there. Inbox, Upcoming, Anytime, and Someday are left as they are.
You start each run yourself.
Put the Notion token in the macOS keychain. Every run reads it from there.
security add-generic-password -s things-notion-sync -a "$USER" -wSet THINGS_AUTH_TOKEN when the plan changes a Things to-do. A run that only creates or edits Notion rows can go without it.
If a column is missing, the dry-run exits 2 and prints a database patch. This command adds the missing columns and then writes the plan:
npm run sync -- --apply --ensure-schema시작일 is the calendar formula. A missing column, or a column of some other type, prints a warning and the sync continues. Paste this into Notion:
if(test(prop("언제"), "^\d{4}-\d{2}-\d{2}"), parseDate(slice(prop("언제"), 0, 10)), parseDate(""))npm run build
npm run sync # print the plan
npm run sync -- --apply # write itThe table columns are action, things_id, title, fields, and detail. With nothing to do, the command prints 변경 없음. The same text is appended to ~/Library/Logs/things-notion-sync.log, with ids, actions, and field names. Tokens and note text are stripped first.
Column | What the sync does |
제목, 메모, 마감일, 태그 | Copied both ways while the to-do is in Today. |
언제 | Copied both ways for |
상태 |
|
시작일 | Shown on a calendar. The sync skips this column. |
프로젝트, 프로젝트 id, 영역, 영역 id | Filled from the Things to-do. |
things_id | Things id for the row. The next run finds the row with this. |
동기화 해시 | Field hashes from the last write. The next run compares against this. Edit the hash and a later |
마지막 동기화 | When that write happened. |
A tag name Things has never seen is dropped. Checklists, headings, and repeat rules stay in Things. A repeat that is in Today is copied like any other to-do. If Things ignores a when or deadline change, that Things value is written back to the row.
On the Notion page, set 상태 to 완료. Leave things_id and 동기화 해시 alone. Then run npm run sync -- --apply while the to-do is still in Today, and Things completes it. The same works the next day if it is still in Today when you run the command. 취소 cancels the to-do. 열림 opens it again.
After Things completes it, the to-do leaves Today and the row stays 완료. The next run fills any other differing fields from Things. From then on, edits to that row stay in Notion.
A new Notion row with an empty 언제, or with 오늘 or 오늘 저녁, is added to Today when you apply.
Rows are matched by things_id. Delete an 열림 row while its to-do is still in Today, and the next run creates the row again. The to-do stays open.
Finished rows can stay in the database. A completed to-do has left Today, so that row is left alone. A row can also be deleted after its to-do moves to Inbox, Anytime, Upcoming, or Someday. It comes back if the to-do returns to Today.
MIT
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…
