Skip to main content
Glama

Plan task steps

taskhold_plan
Destructive

Add ordered steps (subtasks) to a task so the person sees a checklist; the progress bar fills as steps finish. taskhold_begin already does this for new work. For an existing task: taskhold_start it, then taskhold_plan. Steps don't nest. Returns the task's whole step list with ids. Fails on an unknown task_id, on a step (plan its parent) or past 200 steps per task. Planning a done task adds todo steps but leaves it done; taskhold_start it to reopen.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "task_id": "<task_id>",
      "steps": "<steps>"
    },
    "name": "taskhold_plan"
  }
}

Input Schema

NameRequiredDescriptionDefault
stepsYesSteps in order, e.g. ["Write the migration", "Update the API", "Add tests"]
replaceNoReplace steps that haven't started yet (done and in-progress steps stay). Default false: append.
task_idYesThe ID of the task to plan

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • removedInput schema / properties / task_id / pattern
      Removed value: -"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  2. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only say destructiveHint=true and readOnlyHint=false; the description goes well beyond by disclosing that steps don't nest, that the call returns the full step list with ids, and the precise failure modes (unknown task_id, step-targeted task_id, >200 steps per task). It also clarifies the non-obvious behavior that planning a done task appends todo steps without reopening it, which is exactly the kind of context annotations cannot carry.

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

Conciseness4/5

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

The purpose and the primary alternative are front-loaded, and every clause carries information (limits, failure modes, done-task edge case). It is dense and slightly run-on, but there is essentially no filler.

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

Completeness5/5

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

There is no output schema, yet the description states what is returned ('task's whole step list with ids'), and it covers failure conditions, limits, and interactions with sibling tools. For a three-parameter mutation tool, nothing an agent needs to call it correctly is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline would be 3; the description still adds meaning by explaining that steps are ordered and non-nesting and by implying append-vs-replace behavior. It does not detail the string-vs-object step forms or the 50-item cap, which remain schema-only.

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

Purpose5/5

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

The description states a specific verb and resource ('Add ordered steps (subtasks) to a task') plus the user-visible effect (checklist, progress bar). It explicitly distinguishes itself from taskhold_begin and taskhold_start, so an agent can route correctly without opening any schema.

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

Usage Guidelines5/5

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

It names the alternatives and the exact conditions that select them: use taskhold_begin for new work, and for an existing task 'taskhold_start it, then taskhold_plan'. It also covers the edge case of planning an already-done task and how to reopen it.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources