From a33975f46bd3f70fb985a301a6d7b61e82b607a2 Mon Sep 17 00:00:00 2001
From: sujugithub <rnacharya39@gmail.com>
Date: Mon, 13 Jul 2026 13:20:25 +1000
Subject: [PATCH] git: clarify when NOT to call status/diff/log in tool
 descriptions

Measured with an agent harness (12 scenarios x 5 runs each, live server):
tool selection was already perfect (100% hit rate) but agents padded runs
with ritual git_status/git_diff_staged/git_log verification calls. With only
these description changes: strict success (right tool + right args + no
extra calls) 75.0% -> 96.7%. No behavior changes.
---
 src/git/src/mcp_server_git/server.py | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/src/git/src/mcp_server_git/server.py b/src/git/src/mcp_server_git/server.py
index 84188d8fd7..6744e37804 100644
--- a/src/git/src/mcp_server_git/server.py
+++ b/src/git/src/mcp_server_git/server.py
@@ -323,7 +323,7 @@ async def list_tools() -> list[Tool]:
         return [
             Tool(
                 name=GitTools.STATUS,
-                description="Shows the working tree status",
+                description="Shows the current working tree and staged changes status. Use this only when the user explicitly asks for the repository status; do not use to verify the results of git_add, git_reset, or git_checkout.",
                 inputSchema=GitStatus.model_json_schema(),
                 annotations=ToolAnnotations(
                     readOnlyHint=True,
@@ -345,7 +345,7 @@ async def list_tools() -> list[Tool]:
             ),
             Tool(
                 name=GitTools.DIFF_STAGED,
-                description="Shows changes that are staged for commit",
+                description="Shows the diff of changes currently staged for commit. Use this only when the user explicitly asks to see staged differences; do not use after git_add to verify that files were staged.",
                 inputSchema=GitDiffStaged.model_json_schema(),
                 annotations=ToolAnnotations(
                     readOnlyHint=True,
@@ -378,7 +378,7 @@ async def list_tools() -> list[Tool]:
             ),
             Tool(
                 name=GitTools.ADD,
-                description="Adds file contents to the staging area",
+                description="Stages the specified files for the next commit. Use this when the user asks to stage files; the operation is complete and does not require calling git_status or git_diff_staged to verify.",
                 inputSchema=GitAdd.model_json_schema(),
                 annotations=ToolAnnotations(
                     readOnlyHint=False,
@@ -389,7 +389,7 @@ async def list_tools() -> list[Tool]:
             ),
             Tool(
                 name=GitTools.RESET,
-                description="Unstages all staged changes",
+                description="Unstages all staged changes, returning them to the working directory. Use this when the user asks to unstage everything; the operation is complete and does not require calling git_status to verify.",
                 inputSchema=GitReset.model_json_schema(),
                 annotations=ToolAnnotations(
                     readOnlyHint=False,
@@ -400,7 +400,7 @@ async def list_tools() -> list[Tool]:
             ),
             Tool(
                 name=GitTools.LOG,
-                description="Shows the commit logs",
+                description="Lists the commit history with author, date, and message. Use this when the user wants a list of commits; use git_show instead when asked to inspect the contents or changes of the most recent or a specific commit.",
                 inputSchema=GitLog.model_json_schema(),
                 annotations=ToolAnnotations(
                     readOnlyHint=True,
@@ -422,7 +422,7 @@ async def list_tools() -> list[Tool]:
             ),
             Tool(
                 name=GitTools.CHECKOUT,
-                description="Switches branches",
+                description="Switches the working tree to the specified branch_name. Use this directly when the user asks to switch branches; do not stage or commit pending changes first unless the user explicitly requests it.",
                 inputSchema=GitCheckout.model_json_schema(),
                 annotations=ToolAnnotations(
                     readOnlyHint=False,
@@ -433,7 +433,7 @@ async def list_tools() -> list[Tool]:
             ),
             Tool(
                 name=GitTools.SHOW,
-                description="Shows the contents of a commit",
+                description="Shows the contents and file changes of a commit. Pass revision=\"HEAD\" to view the most recent commit. Use this directly when asked what the latest commit changed; do not call git_log first to obtain a hash.",
                 inputSchema=GitShow.model_json_schema(),
                 annotations=ToolAnnotations(
                     readOnlyHint=True,