refactor(mcp): rewrite external MCP tool descriptions for trigger clarity

Every tool description now leads with what the tool does AND when to reach for
it, since MCP clients rank tools by that text. Per-parameter prose moved onto
the parameters as [Description], exhaustive result-shape enumerations and
design/history rationale dropped, and the repeated boilerplate clauses
(lean-task-ref, batch cap, refused-while-Running) pulled into McpToolDocs,
which also documents the style for future tools.

Tool-level description text: 20494 -> 13605 chars (-34%); combined with the new
parameter descriptions 18517 (-10%).

Closes gaps that caused wrong calls rather than just verbose ones:
- list_task_attachments returns metadata only, no file content
- run_task_now shares continue_task's single override slot and throws when busy
- list_runs is ordered oldest-first and feeds get_run
- workingDir on create_list/update_list is an existing local git repo path,
  unvalidated until the first task run
- get_task_worktree's behind=0 also means the main ref was unreachable

Removes get_task_status_values: a whole tool entry for static reference text.
GetTask's description is now the canonical place for status meanings.
This commit is contained in:
mika kuns
2026-08-07 09:25:45 +02:00
parent 6e9a7cea87
commit c792765ed3
16 changed files with 295 additions and 282 deletions
+17 -12
View File
@@ -29,19 +29,24 @@ public sealed class TaskWaitMcpTools
}
[McpServerTool, Description(
"Blocks until at least one of the given tasks leaves Queued/Running, or until timeoutSeconds elapses " +
"(clamped server-side to 900s). Returns immediately if any task is already outside Queued/Running " +
"when called (an unknown id is reported as status \"NotFound\" and counts as changed). Use this instead " +
"of polling get_task in a loop. Pitfall: a planning parent with children goes Running -> " +
"WaitingForChildren while its children are still working, and by default that counts as \"changed\" -- " +
"so waiting on a parent returns immediately even though the work isn't done. Set " +
"treatWaitingForChildrenAsBusy=true to keep waiting through WaitingForChildren; the call then only " +
"returns once the parent reaches WaitingForReview or a terminal status (default: false, unchanged " +
"legacy behavior). Requires the calling claude process to run with MCP_TOOL_TIMEOUT >= 930000 (ms) for " +
"a long wait to actually be held open -- ClaudeDo's own launchers already set this. " +
"Result: { changed: [{ taskId, status }], timedOut }.")]
"Blocks until at least one of the given tasks leaves Queued/Running -- use this instead of " +
"polling get_task in a loop. Returns immediately if a task is already outside Queued/Running " +
"(an unknown id reports status \"NotFound\" and counts as changed). Pitfall: a planning parent " +
"goes Running -> WaitingForChildren while its children are still working, so by default " +
"waiting on a parent returns early; see treatWaitingForChildrenAsBusy. Requires the calling " +
"claude process to run with MCP_TOOL_TIMEOUT >= 930000 (ms) for a long wait to actually be " +
"held open -- ClaudeDo's own launchers already set this.")]
public async Task<WaitForTaskChangeResult> WaitForTaskChange(
string[] taskIds, int timeoutSeconds = 60, bool treatWaitingForChildrenAsBusy = false,
string[] taskIds,
[Description(
"How long to wait, in seconds, before giving up. Clamped server-side to 900s (15 min) " +
"regardless of what's passed.")]
int timeoutSeconds = 60,
[Description(
"When true, WaitingForChildren still counts as busy, so waiting on a planning parent " +
"continues until it reaches WaitingForReview or a terminal status instead of returning " +
"as soon as it leaves Running.")]
bool treatWaitingForChildrenAsBusy = false,
CancellationToken cancellationToken = default)
{
if (taskIds.Length == 0)