Taskhold

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

No annotations are provided, so the description carries the full burden. It does disclose one genuine behavioral trait — the note is written for human consumption — but says nothing about immutability, whether notes can later be edited or removed, permissions, or failure modes when the task_id is 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?

Two short sentences, verb and resource front-loaded, with the audience note second. Nothing is wasted and nothing is buried.

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 two-parameter append operation with a fully documented schema and no output schema, this covers what an agent needs to call it. Only the mutation/immutability semantics are missing, which is a minor gap at this complexity.

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%: both parameters have descriptions and task_id carries format/pattern constraints and note carries length bounds. The description adds no syntax or formatting guidance beyond the schema, so the baseline 3 applies.

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?

States a specific verb (add) and resource (note to a task), plus the kinds of content it carries: progress, findings, decisions. That distinguishes it from taskhold_update and taskhold_progress by implication, though it never names those siblings explicitly.

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 human reads these' hints that the tool is for human-facing commentary rather than state changes, but there is no explicit when-to-use/when-not guidance and no pointer to a sibling such as taskhold_update when the intent is to change fields rather than annotate.

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?

With no annotations, the description carries the full burden and does well: it discloses the side effect (the question surfaces on the board under 'Needs you'), that the reply comes back as a note, and the required follow-up read. It doesn't cover error cases (unknown task_id), whether blocking is reversible in-place, or whether the call returns anything, which keeps it from a 5.

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?

Actionable content is front-loaded and every sentence contributes (purpose, reason format, board behavior, follow-up tool, retry strategy). It is longer than typical but not padded; a small trim of the example or the 'meanwhile' clause would tighten it further.

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 two-parameter tool with no annotations, no output schema and no nested objects, it covers the workflow end to end: what it does, how the human responds, and how the agent should read the reply. The one gap is that with no output schema, the description never says what the call itself returns or what identifier to use as the cursor.

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%, so baseline is 3, but the description adds real guidance on the 'reason' parameter's content and phrasing ('one question the person can answer from the board in a line', with a worked example) that the schema's shorter hint only partially conveys. task_id is left to the 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?

States a specific verb and resource ('Mark a task (or step) blocked') plus the exact triggering condition ('when you can't continue without the human'). The parenthetical '(or step)' and the handoff to taskhold_updates clearly separate it from siblings like taskhold_unblock and taskhold_progress.

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?

Explicitly names when to use it (decision, missing info, access), the correct follow-up tool (taskhold_updates with your cursor), what to do while waiting (keep working on independent items), and the retry path (block again with a narrower question, don't guess). This is close to a complete routing rule.

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?

With no annotations, the description carries the full burden. It does disclose one genuine behavioral trait beyond the schema: completing a step returns information about the next step, which shapes the agent's follow-up action. However, it does not say whether completion is irreversible, what happens if the task is already complete or blocked, or what errors to expect.

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 short sentences with zero filler, front-loading the action before the follow-on effect. Every clause carries 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?

For a two-parameter mutation with no output schema, the description covers the core action and hints at the response. But "with a summary" implies summary is expected, while the schema marks only task_id as required — leaving ambiguity about whether summary is mandatory — and preconditions for completion go unstated.

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 both task_id and summary are already documented, establishing a baseline of 3. The description's "with a summary of what you did" merely echoes the schema's "What was done" and adds no format, length, or expected-content guidance beyond it.

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?

States a specific verb and resource: "Mark a task or step done." That distinguishes it from taskhold_start (begin work) and taskhold_add_note (annotate), though it doesn't explicitly address taskhold_progress or taskhold_update, which an agent might confuse with completion.

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?

Usage is implied by "Mark a task or step done" — call it when work is finished. But there is no guidance on what to use instead for partial progress (taskhold_progress), interruptions (taskhold_block), or logging without completing (taskhold_add_note), and no stated preconditions such as whether the task must be started first.

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?

There are no annotations, so the description carries the full burden. It does disclose a key behavioral trait – that passing parent_task_id nests the new item as a single step – but says nothing about permissions, duplicate handling, what the response returns, or what defaults get applied beyond the schema's own priority note.

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 tight sentences, front-loaded with the core action, with no filler. The alternative-tool guidance is appended where it is actually needed rather than buried.

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 six-parameter mutation tool with no annotations and no output schema, the description covers intent and one routing case but leaves the agent guessing about the return value (an ID for follow-up operations) and creation side effects. Adequate, not 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?

Schema coverage is 100%, so all six parameters are already documented, and the description touches only parent_task_id, restating its meaning with a 'single step' constraint. The other five parameters get no added meaning beyond the schema, so baseline 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?

Names a specific verb+resource ('Create a task') and adds semantic framing ('work you found that needs doing – a bug, a refactor, a follow-up') that grounds the abstract concept. It also distinguishes itself from the sibling taskhold_plan in the same breath.

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?

Explicitly states when to use parent_task_id and explicitly routes the multi-step case to taskhold_plan. It does not distinguish itself from taskhold_create_from_todo or taskhold_update, but the primary branching decision an agent faces is covered.

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?

No annotations are provided, so the description carries the full behavioral burden. It mentions creating a task and retaining file path/line number, but does not disclose whether it parses code, requires permissions, handles duplicate TODOs, or what side effects or return behavior to expect.

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 single sentence is front-loaded and efficient, with no redundant or filler content. It communicates the core action and distinguishing source in minimal space.

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 create-from-TODO operation with fully documented parameters and no output schema, the description covers the essential purpose. However, because there are no annotations and this is a mutation tool, the lack of behavioral context leaves it only minimally 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?

Schema description coverage is 100%, so the schema already documents all four parameters. The description reinforces that file_path and line_number are retained, but adds no syntax, format, or constraint details beyond the 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 states a specific verb and resource (create a task) plus a distinct source (from a TODO comment in code) and retention behavior (file path and line number). This clearly differentiates it from the generic taskhold_create sibling.

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 use when a TODO comment exists in code, but does not explicitly state when to use this instead of taskhold_create or taskhold_add_note. No exclusions or alternative routing guidance are provided.

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 readOnlyHint annotation already signals a safe read operation. The description adds useful behavioral context by listing exactly what is returned: full description, subtasks, progress, labels, and notes. It does not describe not-found or error behavior, but for a read-only getter this is solid transparency beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is a single front-loaded sentence with zero waste. The key information—get one task and what comes back—is immediately 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?

For a simple read-only getter with one fully documented parameter and no output schema, the description is largely complete because it enumerates the returned data. It omits edge-case behavior such as missing or invalid task IDs, keeping it from 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 description coverage is 100%, and the task_id parameter is fully documented in the schema. The description adds no parameter-specific details beyond the schema, so the baseline of 3 applies.

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: "Get one task," and enumerates the returned fields (description, steps, progress, labels, notes). It distinguishes singular retrieval from list/search by saying "one task," though it does not explicitly name sibling 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 gives no explicit when-to-use or when-not-to-use guidance, and it does not mention alternatives such as taskhold_get_current, taskhold_search, or taskhold_list. Usage is only implied by the required task_id parameter.

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?

readOnlyHint=true already establishes the safety profile, so the description only needs to add context. It adds the return shape (task + steps + next step), but omits what happens when nothing is in progress (empty result vs error) and says nothing about the output schema because none exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, both front-loaded: purpose first, then the call-to-action. Nothing is wasted or repeated.

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?

With no output schema, the description bears responsibility for describing return values, and it only partially does so — 'steps and the next one to do' is helpful but the empty/no-active-task case is unaddressed. For a zero-param read that gates session startup, that omission matters.

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 takes zero parameters, so there is nothing for the description to disambiguate; baseline applies. No false hints about inputs are given.

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?

States a specific verb ('Get') and resource ('the task currently in progress') plus what comes back (steps, next step to do). This distinguishes it from the id-based sibling taskhold_get, though it doesn't name that sibling to reinforce the contrast.

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?

Explicitly tells the agent when to call it: 'at the start of a session.' No exclusions or named alternatives are given, but the usage context is unambiguous and non-obvious enough to be valuable.

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?

readOnlyHint=true already establishes this as a safe read. The description adds the meaningful behavioral trait that results are aggregated counts grouped by status, priority and origin rather than task records, but says nothing about scope (all tasks? current project?) or the shape of the returned object.

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 front-loaded fragment with zero filler, sized appropriately for a no-argument aggregation tool. It is a noun phrase rather than a complete sentence, which slightly weakens the framing but wastes nothing.

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?

With no output schema and no parameters, the description carries the burden of explaining the return shape and scope, and it only partially does so: grouping dimensions are listed but not the container structure, total counts, or whether counts cover all tasks or only open ones. Adequate to select the tool, not fully adequate to predict its output.

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 takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The mention of status/priority/origin could be misread as filter inputs, but the surrounding wording ('counts by') frames them as output groupings.

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 the resource (tasks) and the exact aggregation dimensions (status, priority, origin human vs agent), so an agent can tell it apart from taskhold_list (full records) and taskhold_get (single task). It never uses an explicit verb like 'returns' but the meaning of 'Task counts by...' is 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?

There is no statement of when to choose this over taskhold_list, taskhold_get_current, or taskhold_progress, which are the obvious overlapping siblings for status overviews. No prerequisites, scope, or exclusions are given.

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 readOnlyHint annotation already covers the safety profile, so the description only needs to add context beyond it. "Grouped by status" is a genuine output-shape detail not found in annotations, but pagination behavior, default ordering, and the effect of combining multiple filters are left unstated (the default limit only appears in the 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?

Two short sentences with the resource and grouping stated up front, and no wasted clauses. It is efficient, though the second sentence is thin enough that it borders on 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 filtered-list tool with a fully described schema and a readOnly annotation, the essentials for invocation are present. What is missing is filter-combination behavior and any guidance on interpreting the status grouping, which matters mildly for a triage tool with no output schema.

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

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

Schema description coverage is 100%, so all four parameters (limit, status, priority, project_id) are already documented with defaults and enums. The description adds no further parameter semantics, which is acceptable given the schema does the work, keeping this at the baseline.

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 and resource ("List tasks") and adds that results are grouped by status, so the agent knows what it gets back. It does not distinguish the tool from siblings like taskhold_search or taskhold_get_summary, which a reader would have to infer.

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?

"Use this to see what to work on" implies a browsing/triage scenario but names no alternatives and states no exclusions. Nothing tells the agent when to prefer taskhold_search (text matching) or taskhold_get_current (single active task) instead.

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 readOnlyHint=true annotation already establishes this is a safe read; the description adds no behavioral context beyond that — no scope, no pagination, no ordering, no note on whether labels are global or per-project. It does not contradict the annotations, but it contributes nothing they don't already say.

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 words with zero waste, but this is under-specification rather than disciplined concision — the sentence is too short to convey the scope an agent needs. It is at least front-loaded with the verb.

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 tool with an explicit readOnlyHint, the description is minimally sufficient to attempt a call. However, with no output schema and no statement of what set of labels is returned, the agent cannot predict the result before invoking it.

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 takes zero parameters, so there is nothing to document and the baseline of 4 applies. The empty schema is self-explanatory and needs no elaboration from the description.

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?

"List labels." states a verb and a resource, so the basic intent is legible, but it never says whose labels (task, project, workspace) or what the result covers. It is also not distinguished from siblings such as taskhold_list and taskhold_list_projects, which an agent could easily confuse with it.

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?

There is no guidance on when to call this instead of taskhold_list, taskhold_list_projects, or taskhold_search. The agent must infer the use case entirely from the tool name.

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?

readOnlyHint=true already declares the safety profile, so the description carries only a light burden. Beyond that it adds nothing: no indication of whether archived/empty projects are included, whether results are ordered or paginated, or what a returned project entry contains.

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 short sentence with the verb-resource pair front-loaded and no filler. The parenthetical earns its place by defining the term, though it is close to the minimum viable size.

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 list tool with annotations covering safety, this is nearly sufficient. The gap is the absence of any signal about output shape or scope (all projects vs. active only), which matters slightly more here since there is no output schema.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; the baseline of 4 applies. The description correctly implies no filtering inputs are accepted.

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?

States a specific verb and resource ("List projects") and adds a definitional gloss ("groups of related tasks") that tells the agent what a project is in this domain. It is clear on its own but never distinguishes itself from the sibling taskhold_list or taskhold_list_labels.

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?

There is no guidance on when to call this rather than taskhold_list, taskhold_list_labels, or any search tool. The agent must infer the use case purely from the name.

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?

With no annotations, the description does disclose useful behavior: steps are ordered, they do not nest, and they surface as a human-visible checklist with a progress bar. It leaves gaps on failure modes — what happens with an unknown or completed task_id, or whether repeated calls merge versus replace (that detail lives only in the 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?

Three tight sentences, no filler: effect first, timing second, constraint third. Every sentence carries information an agent needs.

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 three-parameter mutation tool with no annotations and no output schema, the description covers timing, effect, ordering, and the non-nesting constraint, which is enough to invoke it correctly. It could say more about what is returned or how existing steps interact, but nothing critical is missing.

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%, so the schema already documents task_id, steps, and the replace/append default. The description adds the ordering guarantee and the no-nesting constraint, which is genuinely useful context, but it does not elaborate on parameter values beyond the schema baseline.

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 ('Break a task into ordered steps') and explains the observable outcome (checklist plus progress bar). It is clearly distinguishable from siblings like taskhold_progress or taskhold_update, which do not create ordered subtasks.

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 states explicitly when to call ('after taskhold_start on work with more than a couple of steps'), giving a concrete precondition and a size threshold. It doesn't say when not to use it or name an alternative for simple tasks, but the context is clear.

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?

With no annotations, the description carries the full behavioral burden. It discloses the live-progress-bar effect and a cadence limit, but does not mention permissions, persistence, error behavior, or whether the update is idempotent, leaving notable gaps for a state-changing call.

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?

Three short sentences, front-loaded with the core purpose, followed by input guidance and cadence in a logical order. Every sentence earns its place with no 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 low-complexity progress-reporting tool with complete schema descriptions and no output schema, the description covers purpose, input combination, expected effect, and call cadence. Nothing essential for correct invocation is missing.

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%, so the baseline is 3, but the description adds semantic value by explaining "Give percent, or current and total (e.g. 12 of 40 files), and a short message." This clarifies how to combine the optional progress parameters beyond their individual 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?

States a specific verb and resource: "Report progress on a task or step." The phrase "so the human's live progress bar moves" distinguishes this from sibling tools like taskhold_complete or taskhold_update by scope and effect.

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?

Gives clear usage context with "Call at milestones, every few minutes at most," which tells the agent when to invoke it and how often. It does not explicitly name alternatives or when-not-to-use cases, so it falls short of a 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds the meaningful detail that matching happens across title and description, but says nothing about matching semantics (substring vs. token), ordering, result limits, or the default status behavior — all relevant for a search tool with 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?

One front-loaded sentence with no filler; appropriately sized for a two-parameter read tool. It is efficient rather than padded, though it could carry one more clause (e.g., matching behavior) at no cost to brevity.

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 tool with two well-described parameters and a read-only annotation, the essentials are covered. Missing are the return-shape-adjacent details an agent would want — whether results are ranked or truncated, and whether status defaults to filtering anything out.

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%, so both parameters are self-documenting, but the description still adds real meaning by specifying which task fields the 'query' string is matched against — information the schema's 'Search text' label does not convey. The status enum is left to the schema, which is adequate.

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?

States a specific verb (search) and resource (tasks) plus the searched fields (title or description), which clearly separates it from enumeration tools like taskhold_list or single-retrieval taskhold_get. It does not name a sibling explicitly, but the scope is 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?

Usage is only implied: an agent can infer this is the tool for text lookup versus taskhold_list for browsing, but the description never says when to prefer one over the other or what to do if the text query yields nothing.

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?

No annotations are provided, so the description carries the full burden. It does not say whether the change is idempotent, whether it notifies assignees, whether it works on completed/blocked tasks, or what the response contains — significant gaps for a mutation tool with zero 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?

A single front-loaded sentence with no filler, and the operation is stated first. Its brevity is appropriate, though the terseness borders on under-specification given the missing behavioral details.

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 no annotations and no output schema, the definition leaves too much open: side effects, permission requirements, and the distinction from taskhold_update are all unstated. The schema alone cannot convey those traits.

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 both parameters are documented with a UUID pattern and a four-value enum, so the description needs to add little. It adds nothing beyond the schema, which is the correct baseline at full coverage.

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

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

States a specific verb (change) and resource attribute (a task's priority), so the operation is unambiguous on its own. It does not, however, distinguish itself from the sibling taskhold_update, which plausibly also touches priority.

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 on when to use this versus taskhold_update (the obvious overlapping sibling), and no prerequisites mentioned such as task existing, being open, or permission to reprioritize. The agent must infer everything about selection conditions.

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?

With no annotations, the description carries the full burden, and it does disclose one important non-obvious trait: starting a step cascades to start its parent task. However, it omits idempotency, what happens if the task is already in progress or blocked, and permission/error 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?

Three short sentences, front-loaded with the action and then the trigger condition, with zero 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 state-mutating tool with no annotations and no output schema, the description covers the state transition and cascade but leaves return value, failure modes, and repeated-call behavior unexplained.

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 both parameters are documented in the schema, establishing a baseline of 3. The phrase 'task or step' mildly clarifies that task_id may reference a step, but no format or selection guidance is added beyond the 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?

States a specific verb+resource ('Mark a task or step in progress') that is immediately distinguishable from siblings like taskhold_complete and taskhold_block. Sibling differentiation is implicit via the obvious state opposites rather than named explicitly.

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?

'Call this when you begin working on it' gives a clear triggering condition. It stops short of naming alternatives (e.g., use taskhold_block when stalled) or stating when not to call it.

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?

With no annotations, the description carries the full behavioral burden. It does disclose the destination state (todo), which is the most important behavior for a state-transition mutation, but says nothing about failure when the task isn't blocked, idempotency, or whether the blocker relation is cleared.

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?

One sentence, zero waste, with the state transition front-loaded and the precondition trailing naturally. Nothing is padded or repeated.

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 with no output schema, the description covers what changes and when to call it. Error semantics (task not blocked, unknown task_id) are the only meaningful omission.

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 single task_id parameter is fully documented in the schema (including UUID format and pattern), so the description adds nothing beyond it. Baseline 3 applies for a fully-covered single-parameter 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 names a specific verb ('Move') plus the resource ('a blocked task') and the resulting state ('back to todo'), so the state transition is unambiguous. It is distinguishable from taskhold_block by direction of transition, though it doesn't explicitly name that sibling.

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?

'once the blocker is resolved' supplies a clear precondition for invocation, which is the key usage context for an unblock operation. It does not state what happens if the task isn't actually blocked or name explicit alternatives, so it stops short of full routing guidance.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. Aside from implying that this is a mutation operation, it does not explain partial-update semantics, whether omitted fields remain unchanged, whether the operation is reversible or destructive, or what permissions are required.

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 focused sentence with no filler. The updatable fields are front-loaded and listed compactly, so every part 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 mutation tool with no annotations and no output schema, the description is too thin. It does not explain partial-update behavior, effects of omitted fields, permissions, or how it relates to sibling tools such as taskhold_set_priority, leaving an agent without enough context to call it confidently in ambiguous cases.

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

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

Schema description coverage is 100%, so the schema already documents all parameters, including the project_id null-removal behavior and priority enum. The description adds almost no parameter meaning beyond the schema, 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 uses a specific verb and resource: 'Update a task's title, description, priority or project.' It is clear what the tool does. However, it does not distinguish this general update tool from the sibling taskhold_set_priority, which also updates priority, so it falls short of the sibling-differentiation bar for a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives such as taskhold_set_priority for priority changes, taskhold_complete for completion, or taskhold_get for reads. The description only states what can be updated and gives no context, exclusions, or routing advice.

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?

readOnlyHint=true is consistent with a read-only delta feed, so the annotation already carries the safety profile, and the description usefully reinforces the polling contract ('pass the cursor from the previous call'). It does not disclose what happens with a stale/expired cursor, whether the response is capped, or how the next cursor is surfaced, which matter for a polled endpoint with 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?

Two sentences, both earning their place: the first states what is returned, the second states when and how to call it. The most load-bearing information (what changed) is front-loaded with zero preamble.

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?

With no output schema, the description does tell the agent which categories of change come back, which is the main thing needed to decide to call it. The gap is that it never says the response carries the next cursor, so an agent must infer where the value for the next `since` comes from.

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 both parameters are already fully documented, including the 'omit the first time (you get the latest 20)' default and the include_agent default. The description only restates the cursor handoff, which is helpful reinforcement but adds no semantics beyond the 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?

States a specific resource — the set of changes the human made since a cursor — and enumerates the change categories (new tasks, notes and replies, priority changes, unblocks). This clearly separates it from taskhold_list/taskhold_get, which return state rather than a delta. The verb is implicit ('what ... changed') rather than an explicit fetch verb, which keeps it just short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives three concrete invocation triggers: when you resume, between steps, and before asking the human something. That is unusually actionable guidance for a polling tool. It does not state when *not* to call it or name a sibling alternative, so it stops short of the top score.

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