From 6d562eae87a429292dec67a86edee4f646fd4058 Mon Sep 17 00:00:00 2001 From: Amolith Date: Sat, 6 Sep 2025 16:40:25 -0600 Subject: [PATCH] chore: refine tool/parameter descriptions --- internal/mcp/server.go | 30 +++++++++++++----------------- 1 file changed, 13 insertions(+), 17 deletions(-) diff --git a/internal/mcp/server.go b/internal/mcp/server.go index 1d724a9e36b8de8bc0931d634bb2beadcd8c614d..c55a42bf95f0baabecae062b84e67480b1967a96 100644 --- a/internal/mcp/server.go +++ b/internal/mcp/server.go @@ -62,39 +62,37 @@ func New(cfg *config.Config, logger *slog.Logger, planner *planning.Manager) (*S func (s *Server) registerTools(mcpServer *server.MCPServer) { // Register set_goal tool setGoalTool := mcp.NewTool("set_goal", - mcp.WithDescription("Set the initial project goal. Returns error if already set and encourages calling change_goal"), + mcp.WithDescription("Set the session goal. If this is a new conversation, use me first. Otherwise, use change_goal and include a reason."), mcp.WithString("title", mcp.Required(), - mcp.Description("The goal title"), + mcp.Description("Short, imperative, sentence-case phrase concisely describing the session's overarching goal"), ), mcp.WithString("description", mcp.Required(), - mcp.Description("The goal description"), + mcp.Description("More comprehensive, paragraph-style description capturing additional nuance and detail"), ), ) mcpServer.AddTool(setGoalTool, s.handleSetGoal) // Register change_goal tool changeGoalTool := mcp.NewTool("change_goal", - mcp.WithDescription("Change an existing project goal. Only use if the operator explicitly requests clearing the board/list/goal and doing something else"), + mcp.WithDescription("Alter the existing session goal. Only use if the operator explicitly requests clearing the board/list/goal and doing something else"), mcp.WithString("title", mcp.Required(), - mcp.Description("The new goal title"), ), mcp.WithString("description", mcp.Required(), - mcp.Description("The new goal description"), ), mcp.WithString("reason", mcp.Required(), - mcp.Description("The reason for changing the goal"), + mcp.Description("_Must_ include adequate justification; doesn't have to be long, just complete. If you find the goal requires adjusting, do not just change it on your own. Suggest the change to the user and only call me with their consent. Examples: 'User requested doing x, y, and z' or 'We assumed X was true, but I discovered Y. User consented to the change.'"), ), ) mcpServer.AddTool(changeGoalTool, s.handleChangeGoal) // Register add_tasks tool addTasksTool := mcp.NewTool("add_tasks", - mcp.WithDescription("Add one or more tasks to work on. Break tasks down into the smallest units of work possible. If there are more than one, use me to keep track of where you are in fulfilling the user's request. Call get_tasks often to stay on track."), + mcp.WithDescription("Add one or more tasks to work on. Break them down into the smallest, complete units of work possible. If there are more than one, use me to keep track of where you are in fulfilling the user's request."), mcp.WithArray("tasks", mcp.Required(), mcp.Description("Array of tasks to add"), @@ -103,11 +101,11 @@ func (s *Server) registerTools(mcpServer *server.MCPServer) { "properties": map[string]any{ "title": map[string]any{ "type": "string", - "description": "Task title", + "description": "Imperative, sentence-case phrase completely describing the task", }, "description": map[string]any{ "type": "string", - "description": "Task description (optional)", + "description": "If the title isn't enough, use this field to capture additional nuance in a single paragraph. If title is enough, leave this field empty.", }, }, "required": []string{"title"}, @@ -118,7 +116,7 @@ func (s *Server) registerTools(mcpServer *server.MCPServer) { // Register get_tasks tool getTasksTool := mcp.NewTool("get_tasks", - mcp.WithDescription("Get task list with status indicators. Call this frequently to stay organized and track your progress. Prefer to call with 'all' or 'pending', only 'completed' if unsure, only 'cancelled' or 'failed' if the operator explicitly asks."), + mcp.WithDescription("Get the goal and list of tasks. Prefer to call with 'all' or 'pending', only 'completed' if unsure, only 'cancelled' or 'failed' if the operator explicitly asks. The update tool prints the revised list, so calling me isn't always necessary."), mcp.WithString("status", mcp.Description("Filter tasks by status: all, pending, in_progress, completed, cancelled, or failed (default: all)"), ), @@ -135,12 +133,10 @@ func (s *Server) registerTools(mcpServer *server.MCPServer) { "type": "object", "properties": map[string]any{ "task_id": map[string]any{ - "type": "string", - "description": "The task ID to update", + "type": "string", }, "status": map[string]any{ - "type": "string", - "description": "New status: pending, in_progress, completed, cancelled, or failed", + "type": "string", }, }, "required": []string{"task_id", "status"}, @@ -151,10 +147,10 @@ func (s *Server) registerTools(mcpServer *server.MCPServer) { // Register delete_tasks tool deleteTasksTool := mcp.NewTool("delete_tasks", - mcp.WithDescription("Delete one or more tasks by their IDs. Only use if the operator explicitly requests clearing the board/list/goal and doing something else. Otherwise, update statuses to 'cancelled', 'failed', etc. as appropriate. After deletion, respond with the resulting task list."), + mcp.WithDescription("Delete one or more tasks by their IDs. Only use if the operator _explicitly_ requests clearing the board/list/goal and doing something else. Otherwise, update statuses to 'cancelled', 'failed', etc. as appropriate."), mcp.WithArray("task_ids", mcp.Required(), - mcp.Description("Array of task IDs to delete"), + mcp.Description("Array of task IDs to delete, can be one or many"), mcp.Items(map[string]any{ "type": "string", }),