Este servidor de Protocolo de Contexto de Modelo (MCP) te permite usar Claude Desktop para interactuar con tus datos de gestión de tareas en la app Things . Puedes pedirle a Claude que cree tareas, analice proyectos, te ayude a gestionar prioridades y mucho más.
Este servidor aprovecha la biblioteca Things.py y el esquema de URL de Things .
Acceso a todas las listas principales de cosas (Bandeja de entrada, Hoy, Próximos, etc.)
Gestión de proyectos y áreas
Operaciones de etiquetas
Capacidades de búsqueda avanzada
Seguimiento de artículos recientes
Información detallada del artículo, incluidas listas de verificación
Soporte para datos anidados (proyectos dentro de áreas, tareas pendientes dentro de proyectos)
Related MCP server: Things MCP
Prerrequisitos
Python 3.12+
Escritorio de Claude
Cosas 3 ("Habilitar URL de Cosas" debe estar activado en Configuración -> General)
Instale uv si aún no lo ha hecho:
curl -LsSf https://astral.sh/uv/install.sh | shLuego reinicie su terminal.
Clonar este repositorio:
git clone https://github.com/hald/things-mcpInstale los paquetes de Python necesarios:
cd things-mcp
uv venv
uv pip install -r pyproject.tomlEditar el archivo de configuración de Claude Desktop:
code ~/Library/Application\ Support/Claude/claude_desktop_config.jsonAgregue el servidor Things a la clave mcpServers al archivo de configuración (asegúrese de actualizar la ruta a la carpeta donde instaló estos archivos):
{
"mcpServers": {
"things": {
"command": "uv",
"args": [
"--directory",
"/ABSOLUTE/PATH/TO/PARENT/FOLDER/things-mcp",
"run",
"things_server.py"
]
}
}
}Reinicie la aplicación Claude Desktop.
"¿Qué hay en mi lista de tareas para hoy?"
"Crea una lista de cosas por hacer para preparar el equipaje para mis vacaciones en la playa la próxima semana. Incluye una lista de verificación para empacar".
"Evalúa mis tareas actuales utilizando la matriz de Eisenhower".
"Ayúdame a realizar una revisión semanal al estilo GTD usando Things".
Crea un proyecto en Claude con instrucciones personalizadas que expliquen cómo usar Things y organizar áreas, proyectos, etiquetas, etc. Dile a Claude qué información quieres que se incluya cuando cree una nueva tarea (por ejemplo, pedirle que incluya detalles relevantes en la descripción de la tarea podría ser útil).
Intenta agregar otro servidor MCP que le dé a Claude acceso a tu calendario. Esto te permitirá pedirle que bloquee tiempo en tu calendario para tareas específicas, cree tareas a partir de próximos eventos del calendario (por ejemplo, prepararse para una reunión), etc.
get-inbox - Obtener todos los archivos de la Bandeja de entrada
get-today - Obtener las tareas pendientes que vencen hoy
get-upcoming - Obtén tus próximas tareas pendientes
get-anytime - Obtener tareas pendientes de la lista Anytime
get-someday - Obtener tareas pendientes de la lista Someday
get-logbook - Obtener tareas completadas
get-trash - Obtener todos los archivos eliminados
get-todos - Obtener todos, opcionalmente filtrados por proyecto
get-projects - Obtener todos los proyectos
get-areas - Obtener todas las áreas
get-tags - Obtener todas las etiquetas
get-tagged-items - Obtener elementos con una etiqueta específica
search-todos - Búsqueda simple por título/notas
search-advanced - Búsqueda avanzada con múltiples filtros
get-recent - Obtener elementos creados recientemente
project_uuid (opcional) - Filtrar tareas por proyecto
include_items (opcional, valor predeterminado: verdadero): incluye elementos de la lista de verificación
include_items (opcional, predeterminado: falso): incluye elementos contenidos
status - Filtrar por estado (incompleto/completado/cancelado)
start_date - Filtrar por fecha de inicio (AAAA-MM-DD)
deadline - Filtrar por fecha límite (AAAA-MM-DD)
tag - Filtrar por etiqueta
area - Filtrar por UUID de área
type - Filtrar por tipo de elemento (tareas pendientes/proyecto/encabezado)
period - Período de tiempo (por ejemplo, '3d', '1s', '2m', '1y')
El servidor incluye gestión de errores para:
UUID no válidos
Faltan parámetros requeridos
Errores de acceso a la base de datos de Things
Errores de formato de datos
Todos los errores se registran y se devuelven con mensajes descriptivos. Para revisar los registros de MCP desde Claude Desktop, ejecute lo siguiente en la terminal:
# Follow logs in real-time
tail -n 20 -f ~/Library/Logs/Claude/mcp*.logCreate a new project in Things
Args: title: Title of the project notes: Notes for the project when: When to schedule the project deadline: Deadline for the project tags: Tags to apply to the project area_id: ID of area to add to area_title: Title of area to add to todos: Initial todos to create in the project
| Name | Required | Description | Default |
|---|---|---|---|
| area_id | No | ||
| area_title | No | ||
| deadline | No | ||
| notes | No | ||
| tags | No | ||
| title | Yes | ||
| todos | No | ||
| when | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states the basic creation action. It doesn't disclose behavioral traits like whether creation requires specific permissions, what happens on duplicate titles, if the project appears in specific views (e.g., Today/Upcoming), or error conditions. The description is minimal beyond the core function.
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 with the core purpose in the first sentence. The parameter list is organized but could be more concise (e.g., merging 'area_id' and 'area_title' explanations). Every sentence adds value, though the 'Args:' section is somewhat verbose.
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 8 parameters with 0% schema coverage and no annotations, the description provides basic parameter semantics but lacks behavioral context for a creation tool. The presence of an output schema reduces the need to explain return values, but gaps remain in usage guidelines and transparency (e.g., no mention of default behaviors or error handling).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It provides a clear list of all 8 parameters with brief explanations of each (e.g., 'Title of the project', 'ID of area to add to'), adding meaningful semantics beyond the schema's basic titles. However, it lacks format details (e.g., date formats for 'when'/'deadline', whether 'area_id' and 'area_title' are mutually exclusive).
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 'update_project' which modifies existing projects or 'get_projects' which retrieves them. The verb+resource combination is precise and 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 provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., whether an area must exist first), when to use 'add_todo' instead for single tasks, or how it differs from 'update_project' for modifying existing projects. Usage context is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new todo in Things
Args: title: Title of the todo notes: Notes for the todo when: When to schedule the todo (today, tomorrow, evening, anytime, someday, or YYYY-MM-DD) deadline: Deadline for the todo (YYYY-MM-DD) tags: Tags to apply to the todo checklist_items: Checklist items to add list_id: ID of project/area to add to list_title: Title of project/area to add to heading: Heading title to add under heading_id: Heading ID to add under (takes precedence over heading)
| Name | Required | Description | Default |
|---|---|---|---|
| checklist_items | No | ||
| deadline | No | ||
| heading | No | ||
| heading_id | No | ||
| list_id | No | ||
| list_title | No | ||
| notes | No | ||
| tags | No | ||
| title | Yes | ||
| when | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'Create' implies a write operation, it doesn't specify permissions needed, whether todos are immediately saved or require confirmation, what happens on duplicate titles, or error conditions. The description mentions parameter precedence ('heading_id takes precedence over heading') which adds some behavioral context, but overall leaves significant gaps for a mutation tool.
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 but not optimally structured. The initial sentence clearly states the purpose, but the parameter documentation could be better organized. While each parameter explanation is concise, the list format is functional but not particularly elegant. Every sentence earns its place, but the structure could be more front-loaded with critical information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (10 parameters, mutation operation) and the presence of an output schema (which handles return values), the description is moderately complete. It excels at parameter documentation but lacks behavioral context for a mutation tool with no annotations. The combination of good parameter semantics but missing behavioral guidance results in an incomplete picture for proper tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description provides excellent parameter semantics that fully compensate. It explains all 10 parameters with clear meanings, including special formats for 'when' (today, tomorrow, evening, anytime, someday, or YYYY-MM-DD) and 'deadline' (YYYY-MM-DD), plus important behavioral details like precedence rules for heading_id vs heading. This goes well beyond what the bare schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Create') and resource ('new todo in Things'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'add_project' or 'update_todo', which would require mentioning this is specifically for todos (not projects) and creates new items (not updates existing ones).
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 'add_todo' over 'add_project' for different item types, or when to use 'update_todo' instead for modifying existing todos. There's also no mention of prerequisites or contextual constraints for creating todos.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get todos from Anytime list
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure but only states the action ('Get todos') without details on permissions, rate limits, or what 'Anytime list' entails (e.g., is it a filtered view, does it include all todos?). It lacks critical behavioral context for a tool with output schema.
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 with no wasted words. It is appropriately sized and front-loaded, 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 complexity implied by multiple sibling tools (e.g., 'get_todos', 'get_today') and no annotations, the description is incomplete. It fails to explain what 'Anytime list' is or how it differs from other todo-fetching tools, leaving gaps in understanding despite the presence 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 tool has 0 parameters with 100% schema description coverage, so no parameter information is needed. The description does not add param semantics, but this is acceptable given the absence of parameters, aligning with the baseline for 0 params.
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 'Get todos from Anytime list' restates the tool name 'get_anytime' in slightly different wording (tautology), failing to clearly differentiate what 'Anytime list' means or how it differs from sibling tools like 'get_todos', 'get_today', or 'get_upcoming'. It provides minimal specificity beyond the 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?
No guidance is provided on when to use this tool versus alternatives such as 'get_todos', 'get_today', or 'get_upcoming'. The description lacks context, exclusions, or explicit comparisons, leaving the agent with no usage direction.
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
Args: include_items: Include projects and tasks within areas
| Name | Required | Description | Default |
|---|---|---|---|
| include_items | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states this is a 'Get' operation, implying read-only behavior, but doesn't disclose any behavioral traits like whether it requires authentication, has rate limits, returns paginated results, or what the output format is. The description is minimal and lacks essential context for safe invocation.
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: one stating the purpose and another explaining the parameter. It's front-loaded with the main purpose first. There's no wasted text, though the 'Args:' formatting is slightly redundant but not excessive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (which handles return values) and only one parameter with good semantic coverage in the description, the description is minimally adequate. However, for a retrieval tool with no annotations, it should ideally mention more about behavior (e.g., read-only, potential errors). The presence of an output schema raises the baseline, but gaps remain in behavioral 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?
The description adds meaningful semantics for the single parameter 'include_items' by explaining it controls whether to 'Include projects and tasks within areas'. With 0% schema description coverage (the schema only has a title 'Include Items'), this compensates well by clarifying what 'items' refers to in this context. For a tool with only one parameter, this is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get all areas from Things' which provides a clear verb ('Get') and resource ('areas'), but it doesn't distinguish this tool from sibling tools like 'get_projects', 'get_todos', or 'get_headings' that also retrieve specific Things resources. The purpose is understandable but lacks 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?
No guidance is provided on when to use this tool versus alternatives. With many sibling tools like 'get_projects', 'get_todos', 'get_inbox', etc., the description doesn't indicate what makes 'areas' distinct or when an agent should choose this over other retrieval tools. Usage is implied only by the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get headings from Things
Args: project_uuid: Optional UUID of a specific project to get headings from
| Name | Required | Description | Default |
|---|---|---|---|
| project_uuid | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states it 'gets' data, implying a read-only operation, but lacks details on permissions, rate limits, return format, or any side effects. This is inadequate for a tool with no annotation coverage.
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: one stating the purpose and another explaining the parameter. It's front-loaded with the main action, though the 'Args:' section could be integrated more smoothly, but overall it's efficient with minimal 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 has an output schema (which handles return values) and low complexity with one optional parameter, the description is somewhat complete but lacks behavioral context due to no annotations. It covers the basic purpose and parameter semantics but misses usage guidelines and transparency details, making it minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaning by explaining that 'project_uuid' is optional and specifies it's for 'a specific project to get headings from', clarifying the parameter's purpose beyond the schema's basic type. However, it doesn't detail format (e.g., UUID structure) or default behavior when omitted, leaving some gaps.
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 'headings from Things', which is specific and actionable. However, it doesn't differentiate from sibling tools like 'get_projects' or 'get_todos' that also retrieve data from the same system, missing explicit distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'get_projects' or 'search_items'. The description only mentions an optional parameter without context on appropriate use cases or exclusions, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get todos from Inbox
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states it 'gets' data, implying a read-only operation, but doesn't mention permissions, rate limits, pagination, or what happens on failure. It lacks critical context for safe and effective use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with just three words, making it easy to parse. However, it's arguably too brief, potentially under-specifying the tool's purpose. It front-loads the key action but could benefit from slightly more detail to improve 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 has 0 parameters, 100% schema coverage, and an output schema exists, the description is minimally adequate. However, it lacks context about the Inbox concept, how it differs from other todo-related tools, and behavioral traits, making it incomplete for optimal agent use without additional inference.
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%, so no parameter documentation is needed. The description doesn't add parameter details, but that's appropriate here. A baseline of 4 is given as it adequately handles the lack of parameters without introducing confusion.
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 'Get todos from Inbox' clearly states the action (get) and resource (todos from Inbox), but it's vague about scope and doesn't differentiate from siblings like 'get_todos' or 'get_today'. It specifies the source (Inbox) but lacks detail on what 'Inbox' means in this context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'get_todos' or 'get_today'. The description implies it's for retrieving todos from a specific location (Inbox), but it doesn't clarify if this is a filtered view, default location, or how it relates to other sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get completed todos from Logbook, defaults to last 7 days
Args: period: Time period to look back (e.g., '3d', '1w', '2m', '1y'). Defaults to '7d' limit: Maximum number of entries to return. Defaults to 50
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| period | No | 7d |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful context about default time periods and limits, which helps understand the tool's behavior beyond basic functionality. However, it doesn't cover aspects like authentication needs, rate limits, error handling, or what 'completed' entails (e.g., status criteria). The description compensates partially but leaves gaps for a read operation.
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, with the core purpose stated first ('Get completed todos from Logbook, defaults to last 7 days'), followed by a structured 'Args:' section. Every sentence adds value, and there's no redundant information. It could be slightly more concise by integrating the defaults into the initial sentence, but overall it's 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 low complexity (2 parameters, no annotations, but has an output schema), the description is reasonably complete. It explains the purpose, parameters, and defaults, which covers the essentials for a read operation. The presence of an output schema means the description doesn't need to explain return values, and the parameter documentation compensates for the 0% schema coverage. Minor gaps remain in behavioral details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must fully document parameters. It successfully adds meaning by explaining both parameters: 'period' as a time period with examples (e.g., '3d', '1w') and defaults, and 'limit' as maximum entries with defaults. This covers all 2 parameters adequately, though it could provide more detail on format constraints (e.g., valid period strings).
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 completed todos from Logbook'. It specifies the resource (completed todos) and the source (Logbook), making the verb+resource combination explicit. However, it doesn't explicitly differentiate from sibling tools like 'get_todos' or 'get_recent', which likely also retrieve todo-related data, leaving some ambiguity about uniqueness.
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 stating it 'defaults to last 7 days', suggesting it's for retrieving recent completed todos. However, it provides no explicit guidance on when to use this tool versus alternatives like 'get_todos' or 'get_recent', nor does it mention any exclusions or prerequisites. The context is clear but lacks sibling differentiation.
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
Args: include_items: Include tasks within projects
| Name | Required | Description | Default |
|---|---|---|---|
| include_items | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions 'Get all projects' but doesn't disclose behavioral traits like whether this is paginated, rate-limited, requires authentication, returns all projects at once, or what format the output takes. The description is minimal and lacks essential operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief but structured with a main statement and an 'Args:' section. However, the formatting is somewhat informal and could be more polished. It's concise but not optimally front-loaded or professionally 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 1 parameter with 0% schema coverage and an output schema exists, the description compensates somewhat for parameters but lacks behavioral context. For a simple retrieval tool, it's minimally adequate but doesn't provide enough guidance on usage or operational details to be fully helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and 1 parameter, the description adds meaningful context by explaining that 'include_items' controls whether tasks within projects are included. This clarifies the parameter's purpose beyond the schema's basic boolean type and title, though it doesn't detail default behavior or implications.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get all projects from Things' which provides a clear verb ('Get') and resource ('projects'), but it doesn't distinguish this from sibling tools like 'get_areas', 'get_tags', or 'get_todos' that also retrieve different Things resources. The purpose is clear but lacks 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?
No guidance is provided about when to use this tool versus alternatives like 'search_advanced', 'search_items', or 'search_todos' for filtered queries, or 'get_today'/'get_upcoming' for time-based retrieval. The description only states what the tool does, not when it's appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get recently created items
Args: period: Time period (e.g., '3d', '1w', '2m', '1y')
| Name | Required | Description | Default |
|---|---|---|---|
| period | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It states the tool retrieves items but doesn't specify what 'items' refers to (e.g., projects, todos, areas), whether it requires authentication, what the output format is, or if there are rate limits. The description is minimal and leaves critical behavioral aspects unspecified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the main purpose, followed by parameter details. Both sentences earn their place by stating what the tool does and explaining the parameter. There's no unnecessary verbiage, though it could be slightly more structured (e.g., separating purpose and args more clearly).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one parameter with no schema descriptions but an output schema exists, the description provides adequate basics but lacks context. It explains the parameter well but doesn't clarify what 'items' are or how 'recently created' is defined (e.g., relative to now?). The output schema will handle return values, but the description could better integrate with sibling tools and item types.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant value beyond the input schema, which has 0% description coverage. It explains that 'period' is a 'Time period' and provides examples of valid values ('3d', '1w', '2m', '1y'), clarifying the parameter's purpose and format. This compensates well for the schema's lack of documentation, though it doesn't cover all possible edge cases.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool's purpose as 'Get recently created items', which is a clear verb+resource combination. However, it doesn't distinguish this from sibling tools like 'get_today', 'get_upcoming', or 'get_anytime' that also retrieve items with different temporal filters. The purpose is understandable but lacks 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 provides no guidance on when to use this tool versus alternatives. With many sibling tools that retrieve items (e.g., 'get_today', 'get_upcoming', 'get_anytime', 'get_tagged_items'), there's no indication of when 'recently created' is appropriate versus other temporal or categorical filters. The user must infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get todos from Someday list
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states a read operation ('Get'), implying it's likely non-destructive, but doesn't disclose any behavioral traits such as permissions needed, rate limits, or what the output contains. This leaves significant gaps for an agent to understand how to interact with it effectively.
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 with no wasted words. It's front-loaded with the core action and resource, making it efficient and easy to parse for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 0 parameters, 100% schema coverage, and an output schema exists, the description is minimally adequate. However, with no annotations and multiple sibling tools, it lacks context on usage and behavioral aspects, making it incomplete for optimal agent selection in a crowded toolset.
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 with 100% schema coverage, so no parameter documentation is needed. The description doesn't add parameter details, which is appropriate, but it could hint at implicit filtering (e.g., by list type), though not required. Baseline is 4 for zero parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and resource ('todos from Someday list'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'get_today', 'get_upcoming', or 'get_todos' which likely retrieve similar items from different contexts, so it misses full sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. With siblings like 'get_today', 'get_upcoming', and 'get_todos', the description lacks context on what makes the 'Someday list' unique or when it's appropriate to use this specific retrieval method.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get items with a specific tag
Args: tag: Tag title to filter by
| Name | Required | Description | Default |
|---|---|---|---|
| tag | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states it 'Get items' but doesn't clarify if this is a read-only operation, what permissions are needed, how results are returned (e.g., pagination), or error handling. For a tool with no annotation coverage, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the main purpose, followed by a clear 'Args' section. It avoids unnecessary words, but the lack of additional context or examples slightly reduces its efficiency in fully informing the agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (which handles return values), the description doesn't need to explain outputs. However, with no annotations and low schema coverage, the description should compensate more by detailing behavioral aspects and usage context, which it only partially does. It's minimally adequate but leaves room for improvement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema provides no parameter descriptions. The description adds value by explaining that 'tag' is a 'Tag title to filter by', which clarifies its purpose beyond the schema's basic type. However, it doesn't detail format constraints or examples, leaving some ambiguity.
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 the resource 'items with a specific tag', making the purpose understandable. However, it doesn't explicitly differentiate from sibling tools like 'search_items' or 'search_todos' that might also filter by tags, so it's not fully distinguished from alternatives.
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 'search_items' or 'get_tags', nor does it mention prerequisites or exclusions. The agent must infer usage from the name and context alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all tags
Args: include_items: Include items tagged with each tag
| Name | Required | Description | Default |
|---|---|---|---|
| include_items | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. 'Get all tags' implies a read operation, but there's no information about permissions needed, rate limits, pagination, or what 'all' means in practice (complete list or limited). The description adds minimal behavioral context beyond the basic operation.
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 brief with two sentences that directly address the tool's purpose and its single parameter. The 'Args:' section is clearly separated, though the formatting could be more polished. There's no wasted verbiage, and information is front-loaded effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool with 1 parameter and an output schema (which handles return values), the description is minimally adequate. However, for a retrieval tool with no annotations, it should ideally mention whether this returns all tags at once or uses pagination, and clarify the relationship with 'get_tagged_items'. The presence of an output schema reduces but doesn't eliminate the need for more 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 0% schema description coverage and only 1 parameter, the description compensates well by explaining the 'include_items' parameter's purpose: 'Include items tagged with each tag.' This adds meaningful semantic context that the schema's boolean type alone doesn't provide, though it could specify what format these included items take.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get all tags' which clearly indicates the verb (get) and resource (tags). However, it doesn't distinguish this from sibling tools like 'get_tagged_items' or explain how this differs from other retrieval tools in the system. The purpose is clear but lacks 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?
No guidance is provided about when to use this tool versus alternatives. With sibling tools like 'get_tagged_items' and 'search_items' available, the description doesn't indicate whether this retrieves tag metadata versus tagged content, or when to prefer one approach over another. The single sentence offers no usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get todos due today
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. While 'Get' implies a read operation, it doesn't specify whether this returns all todos due today or only incomplete ones, how results are sorted, if there's pagination, or what authentication might be required. The description is too minimal for a tool with no annotation support.
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 at just three words, front-loading the essential information with zero wasted language. Every word earns its place by specifying the action, resource, and temporal filter in minimal form.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has zero parameters and an output schema exists, the description doesn't need to explain parameters or return values. However, for a read operation with no annotations, it should provide more behavioral context about what 'todos due today' means operationally. The description is complete enough for basic understanding but lacks depth about implementation details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters with 100% schema description coverage, so the schema already fully documents the parameter situation. The description doesn't need to compensate for any parameter gaps, and it correctly implies no input is required beyond the implicit 'today' filter. This meets the baseline expectation for zero-parameter tools.
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 ('todos due today'), making it immediately understandable. However, it doesn't explicitly distinguish this tool from similar siblings like 'get_todos' or 'get_upcoming', which might also retrieve todo items with different filters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With siblings like 'get_todos', 'get_upcoming', 'get_recent', and 'get_anytime', there's no indication of when this specific 'today' filter is appropriate or what distinguishes it from other date-based queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get todos from Things, optionally filtered by project
Args: project_uuid: Optional UUID of a specific project to get todos from include_items: Include checklist items
| Name | Required | Description | Default |
|---|---|---|---|
| include_items | No | ||
| project_uuid | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but offers minimal behavioral context. It mentions optional project filtering and checklist inclusion, but doesn't describe what 'Get todos' actually returns (list format, pagination, sorting), authentication requirements, rate limits, or whether this is a read-only operation (though implied by 'Get').
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise with zero wasted words. The purpose is stated in the first sentence, followed by clear parameter explanations. Every sentence earns its place, and the structure (purpose then args) is logical and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (which handles return values), 2 parameters with 0% schema coverage, and no annotations, the description is minimally adequate. It covers the basic purpose and parameters but lacks behavioral context and sibling differentiation that would be helpful given the many similar get_* tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It provides basic semantic meaning for both parameters ('Optional UUID of a specific project' and 'Include checklist items'), which adds value beyond the bare schema. However, it doesn't explain format details (what a valid UUID looks like) or the implications of including/excluding items.
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 'todos from Things', making the purpose immediately understandable. It distinguishes from some siblings like 'add_todo' or 'update_todo', but doesn't explicitly differentiate from other get_* tools like 'get_today' or 'get_inbox' that also retrieve todos with different filters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions optional filtering by project, but provides no guidance on when to use this tool versus the many sibling get_* tools (get_today, get_inbox, get_upcoming, etc.) that appear to retrieve todos with different scopes. No alternatives, prerequisites, or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get trashed todos
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. 'Get trashed todos' implies a read-only operation that retrieves deleted items, but it doesn't specify whether this requires special permissions, what format the output takes, whether there are pagination limits, or if the trash has retention policies. The description adds minimal behavioral context beyond the basic operation.
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 perfectly concise three-word phrase that communicates the essential action and target. Every word earns its place: 'Get' specifies the action, 'trashed' distinguishes the state, and 'todos' identifies the resource. There's zero waste or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, output schema exists), the description is adequate but minimal. The output schema will document return values, so the description doesn't need to explain those. However, for a tool that presumably accesses deleted/sensitive data, more context about permissions, scope, or limitations would be helpful despite the structured fields.
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 with 100% schema description coverage, so the schema already fully documents the lack of inputs. The description doesn't need to explain parameters, and it correctly doesn't mention any. The baseline for zero parameters with complete schema coverage is 4, as there's nothing to compensate for.
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 'trashed todos', making the purpose immediately understandable. It distinguishes this from sibling tools like get_todos, get_today, etc. by specifying the 'trashed' state. However, it doesn't explicitly contrast with other trash-related operations that might exist (though none are listed among siblings).
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 you might need trashed todos versus active ones (get_todos), or how this relates to other retrieval tools like get_inbox or get_tagged_items. There's no context about prerequisites, permissions, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get upcoming todos
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure but offers minimal information. It implies a read operation but doesn't specify whether it returns all upcoming todos, paginated results, or any filtering/sorting behavior. No details on permissions, rate limits, or error conditions are included.
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 just three words, front-loading the essential information ('Get upcoming todos') without any wasted text. It efficiently communicates the core purpose in a minimal format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 0 parameters, 100% schema coverage, and an output schema exists, the description is adequate as a basic read operation. However, it lacks context about what 'upcoming' entails (e.g., definition, scope) and behavioral details, making it minimally viable but with gaps in usage clarity.
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%, so no parameter documentation is needed. The description doesn't add parameter details, but this is appropriate given the lack of inputs, justifying a baseline score of 4 for clarity in a parameterless context.
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 ('upcoming todos'), making the purpose immediately understandable. It distinguishes this tool from siblings like 'get_today' or 'get_someday' by specifying 'upcoming' as the time frame, though it doesn't explicitly contrast with all similar tools like 'get_recent'.
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_today', 'get_someday', or 'get_recent'. It lacks context about what 'upcoming' means (e.g., time range, priority) or any prerequisites, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Advanced todo search with multiple filters
Args: status: Filter by todo status (incomplete, completed, canceled) start_date: Filter by start date (YYYY-MM-DD) deadline: Filter by deadline (YYYY-MM-DD) tag: Filter by tag area: Filter by area UUID type: Filter by item type (to-do, project, heading)
| Name | Required | Description | Default |
|---|---|---|---|
| area | No | ||
| deadline | No | ||
| start_date | No | ||
| status | No | ||
| tag | No | ||
| type | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states that it performs a search with filters, lacking information on permissions needed, rate limits, pagination, response format, or whether it's read-only. This is inadequate for a search tool with 6 parameters and no annotation coverage.
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, with the main purpose stated first followed by a structured list of parameters. Each sentence earns its place, though the parameter explanations could be slightly more concise (e.g., repeating 'Filter by' for each).
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 (6 parameters, no annotations, but with output schema), the description is partially complete. It covers parameter semantics well but lacks behavioral context and usage guidelines. The presence of an output schema means return values are documented elsewhere, reducing the burden on the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It provides clear semantics for all 6 parameters, explaining what each filters by (e.g., 'status: Filter by todo status', 'area: Filter by area UUID'), including specific values for 'status' and 'type'. This adds significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as 'Advanced todo search with multiple filters', specifying the verb ('search') and resource ('todo'). It distinguishes from basic search tools by emphasizing 'advanced' with multiple filters, though it doesn't explicitly differentiate from sibling tools like 'search_items' or 'search_todos'.
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 this advanced search is preferable over simpler sibling tools like 'get_todos', 'search_todos', or 'search_items', nor does it specify prerequisites or exclusions for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for items in Things
Args: query: Search query
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It only states the basic function without mentioning important behavioral aspects like whether this is a read-only operation, what kind of items are returned, how results are formatted/paginated, or any limitations/constraints. For a search tool with zero annotation coverage, this is insufficient.
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 just two sentences. The first states the purpose, the second documents the single parameter. There's no wasted text, though the structure with 'Args:' heading is slightly informal but clear.
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 there's an output schema (which handles return values), the description focuses on the search function and parameter. However, for a tool with 1 parameter but 0% schema description coverage and no annotations, the description should provide more context about what 'items' means in this system versus the many sibling tools, and how this search differs from other search 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?
The schema description coverage is 0%, so the description must compensate. It does provide the parameter name 'query' and indicates it's a search query, which adds basic semantic meaning beyond the schema's bare type information. However, it doesn't explain query syntax, supported operators, or examples - just the minimal parameter identification.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Search for items in Things' which clearly indicates the verb (search) and resource (items in Things). However, it doesn't differentiate from sibling tools like 'search_todos' or 'search_advanced' - it's unclear what 'items' encompasses versus 'todos' or what makes the advanced search different.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives like 'search_todos', 'search_advanced', or the various 'get_' tools. The description only states what the tool does, not when it's appropriate versus other search or retrieval options available.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search todos by title or notes
Args: query: Search term to look for in todo titles and notes
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It mentions what fields are searched (title/notes) but doesn't cover important aspects like search behavior (exact match, partial, case sensitivity), result format, pagination, or error conditions. This leaves significant gaps for a search operation.
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 brief with two sentences that directly address purpose and parameter meaning. The 'Args:' section is slightly redundant but adds clarity. No wasted words, though it could be more front-loaded by integrating the parameter explanation into the main sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (which handles return values), the description's main gaps are in behavioral transparency and usage guidelines. For a search tool with no annotations and multiple similar siblings, it should provide more context about search behavior and differentiation, making it minimally adequate but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful context for the single parameter: it explains that 'query' searches in 'todo titles and notes'. With 0% schema description coverage, this compensates somewhat, but doesn't provide details on query syntax, length limits, or special characters. The baseline is appropriate given the single parameter.
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 todos by title or notes' specifies the verb (search), resource (todos), and scope (title/notes). However, it doesn't explicitly distinguish this tool from sibling search tools like 'search_advanced' or 'search_items', which prevents 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 no guidance on when to use this tool versus alternatives. With multiple search-related siblings ('search_advanced', 'search_items'), there's no indication of what differentiates this tool or when it's preferred, leaving the agent to guess.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show a specific item or list in Things
Args: id: ID of item to show, or one of: inbox, today, upcoming, anytime, someday, logbook query: Optional query to filter by filter_tags: Optional tags to filter by
| Name | Required | Description | Default |
|---|---|---|---|
| filter_tags | No | ||
| id | Yes | ||
| query | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions showing items or lists but doesn't describe the output format, whether it's read-only, if it requires authentication, or any rate limits. For a tool with no annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded with the core purpose, followed by parameter explanations in a clear 'Args:' section. It avoids unnecessary words, though the structure could be slightly more polished by integrating the parameter details more seamlessly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema, the description doesn't need to explain return values, which helps. However, with no annotations, 3 parameters (one required), and many sibling tools, the description lacks context on behavior and usage guidelines, making it only minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful context beyond the input schema, which has 0% description coverage. It explains that 'id' can be an item ID or predefined list names (e.g., 'inbox', 'today'), and clarifies that 'query' and 'filter_tags' are optional filters. This compensates well for the schema's lack of 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 verb 'show' and resource 'specific item or list in Things', making the purpose understandable. However, it doesn't explicitly differentiate from sibling tools like 'get_inbox', 'get_today', etc., which appear to serve similar list-retrieval functions, 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 no guidance on when to use this tool versus alternatives. With many sibling tools like 'get_inbox', 'get_today', and 'search_items' that likely overlap in functionality, there's no indication of when this tool is preferred or what distinguishes it, leaving usage unclear.
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
Args: id: ID of the project to update title: New title notes: New notes when: New schedule deadline: New deadline tags: New tags completed: Mark as completed canceled: Mark as canceled
| Name | Required | Description | Default |
|---|---|---|---|
| canceled | No | ||
| completed | No | ||
| deadline | No | ||
| id | Yes | ||
| notes | No | ||
| tags | No | ||
| title | No | ||
| when | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'Update' implies a mutation operation, the description doesn't specify what happens to fields not mentioned (partial vs full updates), whether changes are reversible, what permissions are required, or what the response format looks like. It provides basic parameter mapping but minimal behavioral context.
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 reasonably concise with a clear purpose statement followed by parameter explanations. However, the parameter list format ('Args:') is somewhat redundant with the schema and could be more integrated. The structure is functional but not optimally front-loaded.
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 an update tool with 8 parameters, no annotations, but with an output schema, the description provides adequate parameter semantics but lacks behavioral context. The presence of an output schema reduces the need to describe return values, but the description should still address mutation behavior, partial updates, and usage context given the sibling tools 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 0% schema description coverage, the description provides essential semantic information for all 8 parameters, mapping each to specific project attributes. It clarifies that 'id' identifies which project to update, 'completed' marks as completed, 'canceled' marks as canceled, etc. This significantly compensates for the lack of 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 action ('Update') and resource ('an existing project in Things'), making the purpose immediately understandable. However, it doesn't explicitly differentiate this from sibling tools like 'update_todo' or 'add_project' beyond the 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 provides no guidance on when to use this tool versus alternatives like 'add_project' (for creating new projects) or 'update_todo' (for updating todos instead of projects). It also doesn't mention prerequisites or constraints for using this update operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing todo in Things
Args: id: ID of the todo to update title: New title notes: New notes when: New schedule deadline: New deadline tags: New tags completed: Mark as completed canceled: Mark as canceled list: The title of a project or area to move the to-do into list_id: The ID of a project or area to move the to-do into (takes precedence over list) heading: The heading title to move the to-do under heading_id: The heading ID to move the to-do under (takes precedence over heading)
| Name | Required | Description | Default |
|---|---|---|---|
| canceled | No | ||
| completed | No | ||
| deadline | No | ||
| heading | No | ||
| heading_id | No | ||
| id | Yes | ||
| list | No | ||
| list_id | No | ||
| notes | No | ||
| tags | No | ||
| title | No | ||
| when | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'update' implies mutation, it doesn't describe permission requirements, whether partial updates are supported, what happens when moving todos between lists/headings, or error conditions. The description only lists parameters without explaining 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 front-loaded with the purpose statement, but the parameter documentation is lengthy (12 items). While each parameter explanation is concise, the overall structure could be improved by grouping related parameters or providing more conceptual guidance before the detailed list.
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 mutation tool with 12 parameters, no annotations, and 0% schema description coverage, the description does well on parameter semantics but lacks behavioral context. The presence of an output schema reduces the need to describe return values, but important aspects like error handling, partial update behavior, and permission requirements remain undocumented.
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 provides clear semantic explanations for all 12 parameters beyond their titles in the schema (which has 0% description coverage). It clarifies precedence rules ('takes precedence over list/heading'), explains what each field controls, and distinguishes between title-based and ID-based parameters. This significantly compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing todo in Things' which specifies the verb (update), resource (todo), and system (Things). However, it doesn't differentiate from sibling 'update_project' or explain how this differs from other update operations in the system.
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 'update_project' or when to use it versus creating new todos with 'add_todo'. There's no mention of prerequisites, constraints, or typical use cases for updating versus other operations.
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_projectadd_todoget_anytimeget_areasget_headingsget_inboxget_logbookget_projectsget_recentget_somedayget_tagged_itemsget_tagsget_todayget_todosget_trashget_upcomingsearch_advancedsearch_itemssearch_todosshow_itemupdate_projectupdate_todoScored across 22 tools
Most tools have distinct purposes targeting specific resources like projects, todos, areas, or lists, with clear separation between creation, retrieval, and update operations. However, there is some overlap between search_items, search_todos, and search_advanced, which could cause confusion about which to use for different search scenarios.
Tool names follow a highly consistent verb_noun pattern throughout, with verbs like add, get, update, and search paired with specific nouns (e.g., add_project, get_areas, update_todo, search_items). All names use snake_case uniformly, making the set predictable and easy to navigate.
With 22 tools, the count is on the higher side for a task management server, bordering on heavy. While many tools serve distinct functions, the number might feel overwhelming compared to a more streamlined set, though it's not extreme given the domain's complexity.
The tool set provides comprehensive coverage for task management, including full CRUD operations for projects and todos, retrieval of various lists (e.g., inbox, today, upcoming), search capabilities, and management of related entities like areas, tags, and headings. No obvious gaps exist for core workflows.
Notes and actions in one app. Let Claude or ChatGPT read and update them.
Persistent context for Claude. Your AI always knows your projects and next actions across sessions.
Create projects, nodes, and tasks in UluP Spaces by conversation with Claude.
Manage tasks, Focus Zone, notes, projects, and task history from compatible AI assistants.