From 3c242ef12eac52c988bbff8be929c1272bbe23bc Mon Sep 17 00:00:00 2001 From: Owen Wang Date: Sat, 7 Mar 2026 22:52:52 -0800 Subject: [PATCH] docs: improve tool descriptions for better AI agent selection Add scenario triggers ("Use when...") and disambiguation guidance to tool descriptions in git and memory servers. AI agents select tools based on description text. Current descriptions are minimal (e.g., "Shows the working tree status") and give agents no guidance on when to use each tool vs similar alternatives. Changes: - git: Add "Use when" guidance and disambiguation between diff tools - memory: Add "Use when" guidance and clarify entity vs relation vs observation operations No code changes -- only description strings updated. Tested with TeeShield (https://github.com/teehooai/teeshield): - git: description score 2.9 -> 8.7 (+5.8) - memory: description score 3.4 -> 9.6 (+6.2) --- src/git/src/mcp_server_git/server.py | 26 ++++++++++++-------------- src/memory/index.ts | 18 +++++++++--------- 2 files changed, 21 insertions(+), 23 deletions(-) diff --git a/src/git/src/mcp_server_git/server.py b/src/git/src/mcp_server_git/server.py index 1d0298b465..dcb6fe1742 100644 --- a/src/git/src/mcp_server_git/server.py +++ b/src/git/src/mcp_server_git/server.py @@ -287,65 +287,63 @@ async def list_tools() -> list[Tool]: return [ Tool( name=GitTools.STATUS, - description="Shows the working tree status", + description="Show the working tree status including modified, staged, and untracked files. Use when the user wants to see the current state of the repository before committing or staging changes.", inputSchema=GitStatus.model_json_schema(), ), Tool( name=GitTools.DIFF_UNSTAGED, - description="Shows changes in the working directory that are not yet staged", + description="Show changes in working directory files that are not yet staged. Use when the user wants to review modifications before running git_add. Unlike git_diff_staged, this shows only unstaged changes.", inputSchema=GitDiffUnstaged.model_json_schema(), ), Tool( name=GitTools.DIFF_STAGED, - description="Shows changes that are staged for commit", + description="Show changes that are staged for the next commit. Use when the user wants to review exactly what will be committed. Unlike git_diff_unstaged, this shows only staged changes.", inputSchema=GitDiffStaged.model_json_schema(), ), Tool( name=GitTools.DIFF, - description="Shows differences between branches or commits", + description="Show differences between two branches, commits, or tags. Use when the user wants to compare code across branches or review changes between specific commits.", inputSchema=GitDiff.model_json_schema(), ), Tool( name=GitTools.COMMIT, - description="Records changes to the repository", + description="Record staged changes to the repository with a message. Use when the user wants to save their staged changes as a new commit. Requires files to be staged first with git_add.", inputSchema=GitCommit.model_json_schema(), ), Tool( name=GitTools.ADD, - description="Adds file contents to the staging area", + description="Stage file changes for the next commit. Use when the user wants to prepare specific files for committing. Use git_status first to see which files have changes.", inputSchema=GitAdd.model_json_schema(), ), Tool( name=GitTools.RESET, - description="Unstages all staged changes", + description="Unstage all staged changes, moving them back to the working directory. Use when the user wants to undo git_add without losing the actual file changes.", inputSchema=GitReset.model_json_schema(), ), Tool( name=GitTools.LOG, - description="Shows the commit logs", + description="Show the commit history log. Use when the user wants to review past commits, find a specific change, or see who changed what and when.", inputSchema=GitLog.model_json_schema(), ), Tool( name=GitTools.CREATE_BRANCH, - description="Creates a new branch from an optional base branch", + description="Create a new branch from an optional base branch. Use when the user wants to start working on a new feature or fix without affecting the current branch.", inputSchema=GitCreateBranch.model_json_schema(), ), Tool( name=GitTools.CHECKOUT, - description="Switches branches", + description="Switch to a different branch. Use when the user wants to change their working context to an existing branch. Use git_create_branch first if the branch does not exist.", inputSchema=GitCheckout.model_json_schema(), ), Tool( name=GitTools.SHOW, - description="Shows the contents of a commit", + description="Show the contents and metadata of a specific commit. Use when the user wants to inspect what changed in a particular commit, including the diff and commit message.", inputSchema=GitShow.model_json_schema(), ), - Tool( name=GitTools.BRANCH, - description="List Git branches", + description="List all local and remote branches. Use when the user wants to see available branches before switching or to check if a branch exists.", inputSchema=GitBranch.model_json_schema(), - ) ] diff --git a/src/memory/index.ts b/src/memory/index.ts index b560bf1e53..3bdaca886b 100644 --- a/src/memory/index.ts +++ b/src/memory/index.ts @@ -263,7 +263,7 @@ server.registerTool( "create_entities", { title: "Create Entities", - description: "Create multiple new entities in the knowledge graph", + description: "Create multiple new entities in the knowledge graph. Use when the user wants to add new concepts, people, or objects. Each entity needs a name, type, and optional observations.", inputSchema: { entities: z.array(EntitySchema) }, @@ -285,7 +285,7 @@ server.registerTool( "create_relations", { title: "Create Relations", - description: "Create multiple new relations between entities in the knowledge graph. Relations should be in active voice", + description: "Create multiple new relations between entities in the knowledge graph. Relations must use active voice (e.g., 'works_at' not 'is_employed_by'). Use when the user wants to connect existing entities.", inputSchema: { relations: z.array(RelationSchema) }, @@ -307,7 +307,7 @@ server.registerTool( "add_observations", { title: "Add Observations", - description: "Add new observations to existing entities in the knowledge graph", + description: "Add new observations to existing entities in the knowledge graph. Use when the user wants to record new facts about an entity without creating duplicates. Unlike create_entities, this updates existing entries.", inputSchema: { observations: z.array(z.object({ entityName: z.string().describe("The name of the entity to add the observations to"), @@ -335,7 +335,7 @@ server.registerTool( "delete_entities", { title: "Delete Entities", - description: "Delete multiple entities and their associated relations from the knowledge graph", + description: "Delete multiple entities and all their associated relations from the knowledge graph. Use when the user wants to permanently remove concepts. This also removes all relations involving the deleted entities.", inputSchema: { entityNames: z.array(z.string()).describe("An array of entity names to delete") }, @@ -358,7 +358,7 @@ server.registerTool( "delete_observations", { title: "Delete Observations", - description: "Delete specific observations from entities in the knowledge graph", + description: "Delete specific observations from entities in the knowledge graph. Use when the user wants to remove outdated or incorrect facts from an entity without deleting the entity itself.", inputSchema: { deletions: z.array(z.object({ entityName: z.string().describe("The name of the entity containing the observations"), @@ -384,7 +384,7 @@ server.registerTool( "delete_relations", { title: "Delete Relations", - description: "Delete multiple relations from the knowledge graph", + description: "Delete multiple relations from the knowledge graph. Use when the user wants to remove connections between entities without deleting the entities themselves.", inputSchema: { relations: z.array(RelationSchema).describe("An array of relations to delete") }, @@ -407,7 +407,7 @@ server.registerTool( "read_graph", { title: "Read Graph", - description: "Read the entire knowledge graph", + description: "Read the entire knowledge graph including all entities and relations. Use when the user wants a complete overview. For large graphs, prefer search_nodes to find specific items.", inputSchema: {}, outputSchema: { entities: z.array(EntitySchema), @@ -428,7 +428,7 @@ server.registerTool( "search_nodes", { title: "Search Nodes", - description: "Search for nodes in the knowledge graph based on a query", + description: "Search for nodes in the knowledge graph by matching against entity names, types, and observations. Use when the user wants to find specific entities without loading the entire graph.", inputSchema: { query: z.string().describe("The search query to match against entity names, types, and observation content") }, @@ -451,7 +451,7 @@ server.registerTool( "open_nodes", { title: "Open Nodes", - description: "Open specific nodes in the knowledge graph by their names", + description: "Retrieve specific nodes from the knowledge graph by their exact names. Use when the user wants to look up known entities directly. Unlike search_nodes, this requires exact name matches.", inputSchema: { names: z.array(z.string()).describe("An array of entity names to retrieve") },