Update list commits tool description (#629)

JoannaaKL · web-flow · commit f88456f9897f · 2025-07-02T20:07:59.000+02:00
diff --git a/README.md b/README.md
@@ -903,7 +903,7 @@ export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description
   - `page`: Page number for pagination (min 1) (number, optional)
   - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
   - `repo`: Repository name (string, required)
-  - `sha`: SHA or Branch name (string, optional)
+  - `sha`: The commit SHA, branch name, or tag name to list commits from. If not specified, defaults to the repository's default branch. (string, optional)
 
 - **list_tags** - List tags
   - `owner`: Repository owner (string, required)
diff --git a/pkg/github/__toolsnaps__/list_commits.snap b/pkg/github/__toolsnaps__/list_commits.snap
@@ -3,7 +3,7 @@
     "title": "List commits",
     "readOnlyHint": true
   },
-  "description": "Get list of commits of a branch in a GitHub repository",
+  "description": "Get list of commits of a branch in a GitHub repository. Returns at least 30 results per page by default, but can return more if specified using the perPage parameter (up to 100).",
   "inputSchema": {
     "properties": {
       "author": {
@@ -30,7 +30,7 @@
         "type": "string"
       },
       "sha": {
-        "description": "SHA or Branch name",
+        "description": "The commit SHA, branch name, or tag name to list commits from. If not specified, defaults to the repository's default branch.",
         "type": "string"
       }
     },
diff --git a/pkg/github/repositories.go b/pkg/github/repositories.go
@@ -97,7 +97,7 @@ func GetCommit(getClient GetClientFn, t translations.TranslationHelperFunc) (too
 // ListCommits creates a tool to get commits of a branch in a repository.
 func ListCommits(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
 	return mcp.NewTool("list_commits",
-			mcp.WithDescription(t("TOOL_LIST_COMMITS_DESCRIPTION", "Get list of commits of a branch in a GitHub repository")),
+			mcp.WithDescription(t("TOOL_LIST_COMMITS_DESCRIPTION", "Get list of commits of a branch in a GitHub repository. Returns at least 30 results per page by default, but can return more if specified using the perPage parameter (up to 100).")),
 			mcp.WithToolAnnotation(mcp.ToolAnnotation{
 				Title:        t("TOOL_LIST_COMMITS_USER_TITLE", "List commits"),
 				ReadOnlyHint: ToBoolPtr(true),
@@ -111,7 +111,7 @@ func ListCommits(getClient GetClientFn, t translations.TranslationHelperFunc) (t
 				mcp.Description("Repository name"),
 			),
 			mcp.WithString("sha",
-				mcp.Description("SHA or Branch name"),
+				mcp.Description("The commit SHA, branch name, or tag name to list commits from. If not specified, defaults to the repository's default branch."),
 			),
 			mcp.WithString("author",
 				mcp.Description("Author username or email address"),
@@ -139,13 +139,17 @@ func ListCommits(getClient GetClientFn, t translations.TranslationHelperFunc) (t
 			if err != nil {
 				return mcp.NewToolResultError(err.Error()), nil
 			}
-
+			// Set default perPage to 30 if not provided
+			perPage := pagination.perPage
+			if perPage == 0 {
+				perPage = 30
+			}
 			opts := &github.CommitsListOptions{
 				SHA:    sha,
 				Author: author,
 				ListOptions: github.ListOptions{
 					Page:    pagination.page,
-					PerPage: pagination.perPage,
+					PerPage: perPage,
 				},
 			}
 
