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:
+11
-13
@@ -46,7 +46,7 @@ public sealed class ConfigMcpTools
|
||||
_dbFactory = dbFactory;
|
||||
}
|
||||
|
||||
[McpServerTool, Description("Get a list's default config (model, system prompt, agent path). Returns { found: false, config: null } if no config is set.")]
|
||||
[McpServerTool, Description("Read a list's default run config — the fallback used by tasks in this list that don't set their own overrides. Returns { found: false, config: null } if none is set.")]
|
||||
public async Task<TaskConfigResult> GetListConfig(string listId, CancellationToken cancellationToken)
|
||||
{
|
||||
var cfg = await _lists.GetConfigAsync(listId, cancellationToken);
|
||||
@@ -56,9 +56,8 @@ public sealed class ConfigMcpTools
|
||||
}
|
||||
|
||||
[McpServerTool, Description(
|
||||
"Set a list's default model/system prompt/agent path/max turns. Passing all four as null clears the list " +
|
||||
"config. Returns { ok, listId, config } — config is null when the config was cleared, otherwise it echoes " +
|
||||
"the fields that were set (a field is null there if it was individually left unset/cleared).")]
|
||||
"Set a list's default model/system prompt/agent path/max turns — the fallback for tasks in this list " +
|
||||
"that don't override them. Passing all four as null clears the list config instead of setting one.")]
|
||||
public async Task<SetListConfigResult> SetListConfig(
|
||||
string listId, string? model = null, string? systemPrompt = null, string? agentPath = null,
|
||||
int? maxTurns = null, CancellationToken cancellationToken = default)
|
||||
@@ -90,9 +89,8 @@ public sealed class ConfigMcpTools
|
||||
}
|
||||
|
||||
[McpServerTool, Description(
|
||||
"Set per-task config overrides (model/system prompt/agent path/max turns). Pass null for any field to " +
|
||||
"clear that override. Returns { ok, taskId, config } — config echoes the resulting overrides (a field is " +
|
||||
"null there if it was cleared or never set).")]
|
||||
"Set per-task overrides for model/system prompt/agent path/max turns; these take precedence over the " +
|
||||
"list's default config for this one task. Pass null for any field to clear that override.")]
|
||||
public async Task<SetTaskConfigResult> SetTaskConfig(
|
||||
string taskId, string? model = null, string? systemPrompt = null, string? agentPath = null,
|
||||
int? maxTurns = null, CancellationToken cancellationToken = default)
|
||||
@@ -109,7 +107,7 @@ public sealed class ConfigMcpTools
|
||||
return new SetTaskConfigResult(true, taskId, new TaskConfigDto(m, sp, ap, maxTurns));
|
||||
}
|
||||
|
||||
[McpServerTool, Description("Get per-task config overrides (model/system prompt/agent path/max turns). Returns { found: false, config: null } if no override is set on this task.")]
|
||||
[McpServerTool, Description("Read this task's per-task overrides (model/system prompt/agent path/max turns), which take precedence over the list's default config. Returns { found: false, config: null } if none is set.")]
|
||||
public async Task<TaskConfigResult> GetTaskConfig(string taskId, CancellationToken cancellationToken)
|
||||
{
|
||||
var task = await _tasks.GetByIdAsync(taskId, cancellationToken)
|
||||
@@ -120,11 +118,11 @@ public sealed class ConfigMcpTools
|
||||
}
|
||||
|
||||
[McpServerTool, Description(
|
||||
"Get the config a task will ACTUALLY run with — model, max turns, effort, permission mode, agent path, " +
|
||||
"whether a system prompt is set, and skill names — with each field's source (task/list/preset/global). " +
|
||||
"Uses the exact same resolution TaskRunner runs with, so this never drifts from get_app_settings/" +
|
||||
"get_task_config's raw, possibly-unused values. maxTurns also reports the raw requested value and " +
|
||||
"whether it was clamped to the global ceiling. Read-only, no side effects.")]
|
||||
"Report the config a task will ACTUALLY run with — model, max turns, effort, permission mode, agent " +
|
||||
"path, whether a system prompt is set, and skill names — each tagged with its source " +
|
||||
"(task/list/preset/global). Use this over get_task_config/get_app_settings when you need resolved " +
|
||||
"values, not raw overrides. maxTurns also reports the raw requested value and whether it was clamped " +
|
||||
"to the global ceiling.")]
|
||||
public async Task<EffectiveRunConfigDto> GetEffectiveRunConfig(string taskId, CancellationToken cancellationToken)
|
||||
{
|
||||
var task = await _tasks.GetByIdAsync(taskId, cancellationToken)
|
||||
|
||||
Reference in New Issue
Block a user