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
+28
View File
@@ -0,0 +1,28 @@
namespace ClaudeDo.Worker.External;
/// <summary>
/// Boilerplate clauses shared by several external MCP tool descriptions. Every tool description is
/// still emitted in full to the client — these constants only stop the wording from drifting apart
/// across ~50 attributes.
///
/// Description style (keep new tools in line with it):
/// 1. First sentence says what the tool does AND when to reach for it — MCP clients rank tools by
/// this text, so the trigger must not be buried behind return-shape prose.
/// 2. Then only non-obvious preconditions and refusals.
/// 3. Document parameters with [Description] on the parameter, not in the tool description.
/// 4. Describe result fields only where the caller must branch on them (isEmpty, truncated,
/// conflicts, …). Everything else is visible in the first actual response.
/// 5. No design rationale or "since this feature was introduced" history.
/// Budget: ~400 chars for a simple tool, ~800 for the merge/review family.
/// </summary>
internal static class McpToolDocs
{
/// <summary>Warns that the payload is the lean reference, not the task's description/result.</summary>
public const string LeanTaskRef = " Returns a lean task reference, not the task's description.";
/// <summary>Batch-size cap shared by every BatchMcpTools entry point.</summary>
public const string MaxBatch = " Max 100 per call.";
/// <summary>Mutations that refuse to touch a task while its agent is running.</summary>
public const string NotWhileRunning = " Refused while the task is Running — cancel it first.";
}