Update list_commits Filtering Descriptions (#634)

LuluBeatson · web-flow · commit 39d7fec500a6 · 2025-07-07T12:59:49.000+01:00
* update sha arg description for list_commits, get_file_contents

* update perPage description for pagination to inform of default 30

* toolsnaps, docs

* revert perPage description
diff --git a/README.md b/README.md
@@ -902,7 +902,7 @@ export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description
   - `path`: Path to file/directory (directories must end with a slash '/') (string, required)
   - `ref`: Accepts optional git refs such as `refs/tags/{tag}`, `refs/heads/{branch}` or `refs/pull/{pr_number}/head` (string, optional)
   - `repo`: Repository name (string, required)
-  - `sha`: Accepts optional git sha, if sha is specified it will be used instead of ref (string, optional)
+  - `sha`: Accepts optional commit SHA. If specified, it will be used instead of ref (string, optional)
 
 - **get_tag** - Get tag details
   - `owner`: Repository owner (string, required)
@@ -916,12 +916,12 @@ export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description
   - `repo`: Repository name (string, required)
 
 - **list_commits** - List commits
-  - `author`: Author username or email address (string, optional)
+  - `author`: Author username or email address to filter commits by (string, optional)
   - `owner`: Repository owner (string, required)
   - `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`: The commit SHA, branch name, or tag name to list commits from. If not specified, defaults to the repository's default branch. (string, optional)
+  - `sha`: Commit SHA, branch or tag name to list commits of. If not provided, uses the default branch of the repository. If a commit SHA is provided, will list commits up to that SHA. (string, optional)
 
 - **list_tags** - List tags
   - `owner`: Repository owner (string, required)
diff --git a/pkg/github/__toolsnaps__/get_file_contents.snap b/pkg/github/__toolsnaps__/get_file_contents.snap
@@ -23,7 +23,7 @@
         "type": "string"
       },
       "sha": {
-        "description": "Accepts optional git sha, if sha is specified it will be used instead of ref",
+        "description": "Accepts optional commit SHA. If specified, it will be used instead of ref",
         "type": "string"
       }
     },
diff --git a/pkg/github/__toolsnaps__/list_commits.snap b/pkg/github/__toolsnaps__/list_commits.snap
@@ -7,7 +7,7 @@
   "inputSchema": {
     "properties": {
       "author": {
-        "description": "Author username or email address",
+        "description": "Author username or email address to filter commits by",
         "type": "string"
       },
       "owner": {
@@ -30,7 +30,7 @@
         "type": "string"
       },
       "sha": {
-        "description": "The commit SHA, branch name, or tag name to list commits from. If not specified, defaults to the repository's default branch.",
+        "description": "Commit SHA, branch or tag name to list commits of. If not provided, uses the default branch of the repository. If a commit SHA is provided, will list commits up to that SHA.",
         "type": "string"
       }
     },
diff --git a/pkg/github/repositories.go b/pkg/github/repositories.go
@@ -111,10 +111,10 @@ func ListCommits(getClient GetClientFn, t translations.TranslationHelperFunc) (t
 				mcp.Description("Repository name"),
 			),
 			mcp.WithString("sha",
-				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.Description("Commit SHA, branch or tag name to list commits of. If not provided, uses the default branch of the repository. If a commit SHA is provided, will list commits up to that SHA."),
 			),
 			mcp.WithString("author",
-				mcp.Description("Author username or email address"),
+				mcp.Description("Author username or email address to filter commits by"),
 			),
 			WithPagination(),
 		),
@@ -470,7 +470,7 @@ func GetFileContents(getClient GetClientFn, getRawClient raw.GetRawClientFn, t t
 				mcp.Description("Accepts optional git refs such as `refs/tags/{tag}`, `refs/heads/{branch}` or `refs/pull/{pr_number}/head`"),
 			),
 			mcp.WithString("sha",
-				mcp.Description("Accepts optional git sha, if sha is specified it will be used instead of ref"),
+				mcp.Description("Accepts optional commit SHA. If specified, it will be used instead of ref"),
 			),
 		),
 		func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
diff --git a/pkg/github/server.go b/pkg/github/server.go
@@ -175,7 +175,9 @@ func OptionalStringArrayParam(r mcp.CallToolRequest, p string) ([]string, error)
 }
 
 // WithPagination returns a ToolOption that adds "page" and "perPage" parameters to the tool.
-// The "page" parameter is optional, min 1. The "perPage" parameter is optional, min 1, max 100.
+// The "page" parameter is optional, min 1.
+// The "perPage" parameter is optional, min 1, max 100. If unset, defaults to 30.
+// https://docs.github.com/en/rest/using-the-rest-api/using-pagination-in-the-rest-api
 func WithPagination() mcp.ToolOption {
 	return func(tool *mcp.Tool) {
 		mcp.WithNumber("page",

Original file line number	Diff line number	Diff line change
`@@ -23,7 +23,7 @@`
`23`	`23`	`"type": "string"`
`24`	`24`	`},`
`25`	`25`	`"sha": {`
`26`		`- "description": "Accepts optional git sha, if sha is specified it will be used instead of ref",`
	`26`	`+ "description": "Accepts optional commit SHA. If specified, it will be used instead of ref",`
`27`	`27`	`"type": "string"`
`28`	`28`	`}`
`29`	`29`	`},`