Retrieve complete details of a todo item, including its body, blockers, dependencies, and optional comments.
Read one todo in full: body, blockers, what it blocks, and optionally comments.
| Name | Required | Description | Default |
|---|---|---|---|
| todo_id | Yes | ||
| project_id | No | Different project override. Use ONLY when the user explicitly asks for another project by name; otherwise stay in the current scope, even when results are empty. | |
| include_comments | No |
Changes observed during successful MCP inspections.
v1.0.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that this is a read operation ('Read') indicating no side effects. However, it does not mention behavior on missing IDs, error handling, or any authorization requirements. For a simple read tool, this is minimally adequate but missing important edge cases.
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, front-loaded sentence that immediately states the action and scope. It contains no filler and every word adds value. This is an exemplar of concise tool descriptions.
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?
No output schema exists, so the description must convey what is returned. It does so by listing body, blockers, what it blocks, and optional comments. While it lacks details on error responses or the effect of project_id (though the schema describes that), the core information needed to call the tool correctly is present. Minor gaps prevent a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33% (only project_id has a description). The tool description adds meaning to include_comments by saying 'optionally comments', but does not clarify todo_id beyond its obvious role. Given the low coverage, the description partially compensates but not fully. The parameters are simple and self-explanatory enough that a 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads a single todo in full, specifying exactly what is returned (body, blockers, what it blocks, optionally comments). This distinguishes it from sibling tools like todo_list (which lists todos) and todo_create/update (which modify). The verb 'Read' plus the resource 'one todo' makes 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: use this when you need a single todo's complete details, as opposed to todo_list for multiple. However, it does not explicitly mention alternatives or state when not to use it. The guidance is inferred from the tool name and description rather than explicitly provided, so it falls at 'implied usage'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.