Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations correctly indicate a non-read-only, non-destructive write operation, and the description aligns with that. The description adds valuable context beyond annotations by noting the list is 'shared global', which implies that adding affects a common resource visible to others. Minor gap: no mention of what happens on success or failure (e.g., return value), but this is relatively minor for a non-destructive add 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?

Two compact sentences with zero filler. The core action is front-loaded, and the key usage distinction follows immediately. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 6 parameters and full schema coverage, the description covers the major decision point (which list to use). The only notable gap is that the description doesn't mention the return value (e.g., created item, ID, confirmation), which could matter since there is no output schema. Overall, it's still complete enough for an agent to select and invoke correctly.

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 baseline is 3. The description goes beyond the schema by giving each list meaningful purpose ('park' versus 'near-term actionable'), which is semantic guidance the schema doesn't provide. This additional distinction justifies a 4.

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 a specific action ('Add a new item') on a specific resource ('the shared global TODO list'). It clearly distinguishes this from siblings like todo_edit and todo_delete, and it even clarifies the semantics of the two lists, leaving no ambiguity about what the tool does.

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?

Provides exemplary routing guidance: explicitly states when to use list='backlog' (deferred findings, low-priority follow-ups) versus list='todo' (near-term actionable items). This directly helps an agent decide which list to use, going beyond what the schema's default value alone would convey.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds meaningful behavioral context beyond annotations by stating that the claim is advisory, not a lock, and by specifying the actions that should follow. Combined with readOnlyHint=false and destructiveHint=false, the agent understands this is a non-destructive state-change operation. It does not detail edge cases like claiming an already-claimed item, but the advisory framing mitigates that gap.

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 compact, front-loaded with the core purpose, and every sentence adds value. It fits the essential guidance into two sentences without repetition or filler.

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 one-parameter mutation tool, the description covers the action, the advisory nature, the pre-check workflow, and the follow-up calls. There is no output schema, so the description could theoretically mention the return value, but that is not essential for correct 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?

Schema coverage is 100%, and the id parameter is adequately described as 'The todo id, e.g. 3'. The description does not add extra parameter semantics, but none are needed because the schema already handles the documentation burden.

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 uses a specific verb-resource pair: 'Mark an item as actively being worked on by you' clearly identifies what the tool does and which resource it affects. It further distinguishes itself from related operations by calling out todo_release and todo_complete, and by emphasizing that claiming is advisory rather than a lock.

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 operational context: check todo_list with inProgress:true before starting new work to avoid duplicating someone else's active item, and call todo_release or todo_complete when stopping. It does not enumerate all alternatives or explicitly state when not to use the tool, but the workflow guidance is strong.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate the operation is neither read-only nor destructive; the description adds that the todo transitions to a 'done' state. It does not disclose whether completing is idempotent, reversible via todo_release, or what happens if the id is missing or invalid.

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 action-first sentence with no filler. It delivers the core operation and the required identifier without wasting tokens.

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 one-parameter mutation with annotations covering safety, the description is mostly sufficient, but it does not clarify the todo lifecycle relationship to release/claim or the result of successful completion. Given the sibling set, a short lifecycle note would make it 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 single parameter 'id' already has a complete schema description including an example, and the tool description only repeats the concept of 'by id'. With schema coverage at 100%, the baseline of 3 applies without needing additional explanation.

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 names a specific action ('mark'), the resource ('a todo'), and the target state ('done'), and identifies the selection key ('by id'). This clearly sets it apart from siblings like todo_delete, todo_edit, and todo_claim.

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 given about when to use todo_complete versus alternatives. With eight siblings including todo_release and todo_claim, the description does not state conditions or exclusions, such as not for re-opening or not for editing details.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds the nuance of permanence, but it does not disclose side effects like whether related history or version records are affected, or whether any preconditions apply. This is acceptable given the annotation coverage, but not richly informative.

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 one short sentence with no filler. The core action and object are front-loaded, and every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter destructive operation with annotations already flagging the destructive nature, the description is nearly complete. It clearly states the input requirement and behavior. The only minor gap is not mentioning what the operation returns or whether it is reversible beyond 'permanently,' but this does not block correct 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?

Schema description coverage is 100% and the sole parameter 'id' is already documented with an example. The description's phrase 'by id' adds no semantic information beyond the schema. Baseline of 3 is appropriate because the schema carries the parameter documentation burden.

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 a specific verb ('remove'), a resource ('todo'), and the exact scope ('by id'). The word 'permanently' clearly distinguishes this from state-changing siblings like todo_complete or todo_release, which alter status rather than delete.

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 given about when to choose this tool over alternatives, such as whether todo_complete or todo_release would be more appropriate for non-destructive status changes. The description implies only that this is for permanent removal, but it does not explicitly rule out or redirect to any sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only state readOnlyHint=false and destructiveHint=false, so they do not convey how the edit behaves. The description adds valuable non-obvious behavior: updates are partial rather than full replacements, and passing """ clears fields instead of setting invalid values. It does not cover invalid id or response behavior, but the key side effects are disclosed.

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?

Two sentences carry the entire definition: the first front-loads the core purpose and fields, the second captures the update and clearing semantics. There is no filler or redundant 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 7-parameter partial update with full schema coverage and annotations, the description plus schema is enough for an agent to select and invoke the tool correctly. It could additionally mention return value or error behavior for non-existent ids, but those are minor gaps for a simple edit operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and every parameter, including the empty-string clear behavior, is documented in the schema itself. The description provides a useful high-level summary but does not add per-parameter meaning beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb ('Edit'), a resource ('an existing item'), and the exact affected fields (title/description/category/priority/dueDate/list) by id. This sharply distinguishes it from sibling tools like todo_add (creation) and todo_delete (destruction) without ambiguity.

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?

It gives clear context for when to use this tool: editing existing todos by id. It also adds essential partial-update guidance ('Only fields you pass are changed') and explain how to clear fields with empty strings. It does not explicitly name when not to use it relative to siblings, so it stops short of 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable context beyond annotations by specifying exactly which change events are included and indicating the returned data (who made the change and when), which is useful given there is no 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, concise sentence that front-loads the main purpose and supplies the key details (change types, actor, timestamp) without any filler 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?

For a simple read-only tool with a single integer parameter, the description is complete: it explains what the tool shows, what events are included, and what information is returned. The lack of an output schema is compensated by the description's clarity about the return contents.

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%, and the parameter already has a clear description ('The todo id, e.g. 3'). The tool description adds no new parameter-level meaning beyond implying that the id refers to 'one item,' so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Show') and a clear resource ('change history for one item'), and it enumerates the change types (create/edit/claim/release/complete). This makes it easy to distinguish from sibling tools like todo_add or todo_edit, which perform mutations rather than display history.

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 phrase 'for one item' clearly signals that this tool is for per-item history, not for listing todos or viewing aggregate state. It does not explicitly name alternatives or exclusion criteria, but the context is clear enough for an agent to select it appropriately among the sibling mutation and list tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful context beyond that: the list is 'shared' and 'global', clarifying scope, and 'formatted as a checklist' gives the agent an idea of the return presentation despite no 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?

A single sentence that states the resource, the action, and the output format with no filler. Every element earns its place and the most important information is 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 a read-only list tool with no required parameters and a rich schema, the description covers the shared-global nature and checklist output. Without an output schema, more detail about returned fields could help, but this is adequate for correct invocation and interpretation of the core intent.

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 all six parameters are already documented with defaults and enum constraints. The description adds no additional parameter-level meaning, making the baseline 3 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 specifies a clear verb ('List') and resource ('items from the shared global TODO list'), and adds output formatting ('as a checklist'). It distinguishes this as the read-only listing tool among sibling mutation tools like todo_add and todo_edit, though it does not explicitly name a sibling it is not.

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 this is for viewing items on the shared TODO list, and the sibling names make it obvious this is the read path. However, it does not state when to prefer todo_list over todo_history or mention exclusions such as 'use todo_history for past versions'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description clearly states the behavioral effect: the claim is cleared and the item is not completed. This adds useful context beyond the annotations, and it does not contradict readOnlyHint=false or destructiveHint=false. It also helps the agent understand the tool is a state change but non-destructive.

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?

A single sentence delivers the core action, the crucial exclusion, and a concrete use case. There is no wasted text and the most important information is 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 a one-parameter tool with no output schema, this description is largely sufficient: it names the action, gives an example scenario, and prevents confusion with completion. It does not mention prerequisites like whether the item must already be claimed, but that is a minor gap for such a simple operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides 100% parameter description coverage for 'id', so the description does not need to add parameter-level detail. The description's use of 'item' instead of 'todo' is slightly loose but not confusing.

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 verb 'Clear' and resource 'in-progress claim on an item' make the action concrete. The qualifier 'without completing it' explicitly distinguishes it from the sibling todo_complete, so an agent can tell them apart at a glance.

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 parenthetical 'e.g. you're pausing this work' gives a practical scenario for when to use this tool. It implies this is for temporary pauses rather than finishing work, though it does not explicitly name sibling alternatives such as todo_claim or todo_complete as routing options.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already carry the safety profile (readOnlyHint=true, destructiveHint=false), so the description isn't burdened with that. It adds valuable behavioral context beyond annotations: the tool exposes version and start time precisely so the agent can detect stale code, and it explains how to interpret the result. It doesn't disclose the output format, but for a simple version/start-time report this is a minor gap.

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?

Two sentences, both earning their place: the first states the core function, the second states the usage scenario. The purpose is front-loaded and there is zero filler or repetition of schema/annotation content.

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 zero-parameter, read-only diagnostic tool with no output schema, the description is fully sufficient. It states what is returned (version and start time), when to call it (stale-code suspicion), and what to do with the result (reconnect if old). An agent has everything needed to invoke and act on this tool correctly.

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 and 100% schema coverage (empty schema), so there is nothing for the description to clarify about inputs. The baseline of 4 applies, and the description appropriately spends no space on parameters it doesn't have.

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 uses a specific verb and resource — 'Report this todo-mcp process's data format version and start time' — stating exactly what the tool outputs. It clearly differentiates from the sibling tools (todo_add, todo_claim, etc.), which all operate on todo items, whereas this is a diagnostic version-check tool.

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?

It explicitly names the trigger condition: 'if todo_list output looks wrong (missing/undefined fields), check this first.' It also prescribes the follow-up action ('reconnect if the process looks old'), giving the agent a complete decision procedure with no inference required.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.