Skip to content

Commit b43600a

Browse files
RossTarrantCopilot
RossTarrant
and
Copilot
committed
Improve discussion comment tool descriptions
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent 1b5402b commit b43600a

4 files changed

Lines changed: 57 additions & 48 deletions

File tree

‎pkg/github/__toolsnaps__/discussion_comment_write.snap‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
"destructiveHint": true,
44
"title": "Manage discussion comments"
55
},
6-
"description": "Write operations for discussion comments.\nSupports adding top-level comments, replying to existing comments, updating comment content, deleting comments, and marking or unmarking comments as the answer.",
6+
"description": "Write-only operations for discussion comments.\nUse only when the user explicitly asks to add a comment, reply, update, delete, mark as answer, or unmark as answer.\nDo not use this to read, list, get, summarize, count, search, or inspect discussion comments; use get_discussion_comments for read-only comment requests.",
77
"inputSchema": {
88
"properties": {
99
"body": {
@@ -15,7 +15,7 @@
1515
"type": "string"
1616
},
1717
"discussionNumber": {
18-
"description": "Discussion number (required for 'add' and 'reply' methods)",
18+
"description": "Discussion number from the URL path after /discussions/ (required for 'add' and 'reply' methods). This is not a node ID.",
1919
"type": "number"
2020
},
2121
"method": {
@@ -31,11 +31,11 @@
3131
"type": "string"
3232
},
3333
"owner": {
34-
"description": "Repository owner (required for 'add' and 'reply' methods)",
34+
"description": "Repository owner or organization login (required for 'add' and 'reply' methods). For org-level discussion URLs like https://github.com/orgs/ORG/discussions/NUMBER, use ORG.",
3535
"type": "string"
3636
},
3737
"repo": {
38-
"description": "Repository name (required for 'add' and 'reply' methods)",
38+
"description": "Repository name (required for 'add' and 'reply' methods). For org-level discussion URLs like https://github.com/orgs/ORG/discussions/NUMBER, use .github.",
3939
"type": "string"
4040
}
4141
},

‎pkg/github/__toolsnaps__/get_discussion.snap‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,19 +3,19 @@
33
"readOnlyHint": true,
44
"title": "Get discussion"
55
},
6-
"description": "Get a specific discussion by ID. Does not return comments.",
6+
"description": "Get a specific discussion by owner, repository, and discussion number.\nReturns discussion metadata such as title, body, URL, status, category, and timestamps.\nDoes not return comments, replies, or comment counts. Do not use this for requests to read, list, summarize, count, or inspect discussion comments; use get_discussion_comments instead.",
77
"inputSchema": {
88
"properties": {
99
"discussionNumber": {
10-
"description": "Discussion Number",
10+
"description": "Discussion number from the URL path after /discussions/. This is not a node ID.",
1111
"type": "number"
1212
},
1313
"owner": {
14-
"description": "Repository owner",
14+
"description": "Repository owner or organization login. For org-level discussion URLs like https://github.com/orgs/ORG/discussions/NUMBER, use ORG.",
1515
"type": "string"
1616
},
1717
"repo": {
18-
"description": "Repository name",
18+
"description": "Repository name. For org-level discussion URLs like https://github.com/orgs/ORG/discussions/NUMBER, use .github.",
1919
"type": "string"
2020
}
2121
},

‎pkg/github/__toolsnaps__/get_discussion_comments.snap‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,33 +3,33 @@
33
"readOnlyHint": true,
44
"title": "Get discussion comments"
55
},
6-
"description": "Get comments from a discussion",
6+
"description": "Get/list comments for a specific discussion by owner, repository, and discussion number.\nUse this when the user asks to read, list, summarize, count, inspect, filter, or find what someone said in discussion comments.\nReturns top-level comments, pagination information, and totalCount. Can include replies only when includeReplies is explicitly requested.\nDo not call get_discussion first for comment-related requests; this tool is sufficient.",
77
"inputSchema": {
88
"properties": {
99
"after": {
1010
"description": "Cursor for pagination. Use the endCursor from the previous page's PageInfo for GraphQL APIs.",
1111
"type": "string"
1212
},
1313
"discussionNumber": {
14-
"description": "Discussion Number",
14+
"description": "Discussion number from the URL path after /discussions/. This is not a node ID.",
1515
"type": "number"
1616
},
1717
"includeReplies": {
18-
"description": "When true, each top-level comment will include its replies nested within it (up to 100 replies per comment, which is the GitHub API maximum). Defaults to false.",
18+
"description": "Optional. Set true only when the user explicitly asks to include replies. Set false when the user explicitly asks to exclude replies. Omit when replies are not mentioned.",
1919
"type": "boolean"
2020
},
2121
"owner": {
22-
"description": "Repository owner",
22+
"description": "Repository owner or organization login. For org-level discussion URLs like https://github.com/orgs/ORG/discussions/NUMBER, use ORG.",
2323
"type": "string"
2424
},
2525
"perPage": {
26-
"description": "Results per page for pagination (min 1, max 100)",
26+
"description": "Optional page size. Do not provide unless the user explicitly asks for a page size, limit, first N comments, or pagination.",
2727
"maximum": 100,
2828
"minimum": 1,
2929
"type": "number"
3030
},
3131
"repo": {
32-
"description": "Repository name",
32+
"description": "Repository name. For org-level discussion URLs like https://github.com/orgs/ORG/discussions/NUMBER, use .github.",
3333
"type": "string"
3434
}
3535
},

‎pkg/github/discussions.go‎

Lines changed: 43 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -281,8 +281,10 @@ func GetDiscussion(t translations.TranslationHelperFunc) inventory.ServerTool {
281281
return NewTool(
282282
ToolsetMetadataDiscussions,
283283
mcp.Tool{
284-
Name: "get_discussion",
285-
Description: t("TOOL_GET_DISCUSSION_DESCRIPTION", "Get a specific discussion by ID. Does not return comments."),
284+
Name: "get_discussion",
285+
Description: t("TOOL_GET_DISCUSSION_DESCRIPTION", `Get a specific discussion by owner, repository, and discussion number.
286+
Returns discussion metadata such as title, body, URL, status, category, and timestamps.
287+
Does not return comments, replies, or comment counts. Do not use this for requests to read, list, summarize, count, or inspect discussion comments; use get_discussion_comments instead.`),
286288
Annotations: &mcp.ToolAnnotations{
287289
Title: t("TOOL_GET_DISCUSSION_USER_TITLE", "Get discussion"),
288290
ReadOnlyHint: true,
@@ -292,15 +294,15 @@ func GetDiscussion(t translations.TranslationHelperFunc) inventory.ServerTool {
292294
Properties: map[string]*jsonschema.Schema{
293295
"owner": {
294296
Type: "string",
295-
Description: "Repository owner",
297+
Description: "Repository owner or organization login. For org-level discussion URLs like https://github.com/orgs/ORG/discussions/NUMBER, use ORG.",
296298
},
297299
"repo": {
298300
Type: "string",
299-
Description: "Repository name",
301+
Description: "Repository name. For org-level discussion URLs like https://github.com/orgs/ORG/discussions/NUMBER, use .github.",
300302
},
301303
"discussionNumber": {
302304
Type: "number",
303-
Description: "Discussion Number",
305+
Description: "Discussion number from the URL path after /discussions/. This is not a node ID.",
304306
},
305307
},
306308
Required: []string{"owner", "repo", "discussionNumber"},
@@ -382,37 +384,43 @@ func GetDiscussion(t translations.TranslationHelperFunc) inventory.ServerTool {
382384
}
383385

384386
func GetDiscussionComments(t translations.TranslationHelperFunc) inventory.ServerTool {
387+
schema := WithCursorPagination(&jsonschema.Schema{
388+
Type: "object",
389+
Properties: map[string]*jsonschema.Schema{
390+
"owner": {
391+
Type: "string",
392+
Description: "Repository owner or organization login. For org-level discussion URLs like https://github.com/orgs/ORG/discussions/NUMBER, use ORG.",
393+
},
394+
"repo": {
395+
Type: "string",
396+
Description: "Repository name. For org-level discussion URLs like https://github.com/orgs/ORG/discussions/NUMBER, use .github.",
397+
},
398+
"discussionNumber": {
399+
Type: "number",
400+
Description: "Discussion number from the URL path after /discussions/. This is not a node ID.",
401+
},
402+
"includeReplies": {
403+
Type: "boolean",
404+
Description: "Optional. Set true only when the user explicitly asks to include replies. Set false when the user explicitly asks to exclude replies. Omit when replies are not mentioned.",
405+
},
406+
},
407+
Required: []string{"owner", "repo", "discussionNumber"},
408+
})
409+
schema.Properties["perPage"].Description = "Optional page size. Do not provide unless the user explicitly asks for a page size, limit, first N comments, or pagination."
410+
385411
return NewTool(
386412
ToolsetMetadataDiscussions,
387413
mcp.Tool{
388-
Name: "get_discussion_comments",
389-
Description: t("TOOL_GET_DISCUSSION_COMMENTS_DESCRIPTION", "Get comments from a discussion"),
414+
Name: "get_discussion_comments",
415+
Description: t("TOOL_GET_DISCUSSION_COMMENTS_DESCRIPTION", `Get/list comments for a specific discussion by owner, repository, and discussion number.
416+
Use this when the user asks to read, list, summarize, count, inspect, filter, or find what someone said in discussion comments.
417+
Returns top-level comments, pagination information, and totalCount. Can include replies only when includeReplies is explicitly requested.
418+
Do not call get_discussion first for comment-related requests; this tool is sufficient.`),
390419
Annotations: &mcp.ToolAnnotations{
391420
Title: t("TOOL_GET_DISCUSSION_COMMENTS_USER_TITLE", "Get discussion comments"),
392421
ReadOnlyHint: true,
393422
},
394-
InputSchema: WithCursorPagination(&jsonschema.Schema{
395-
Type: "object",
396-
Properties: map[string]*jsonschema.Schema{
397-
"owner": {
398-
Type: "string",
399-
Description: "Repository owner",
400-
},
401-
"repo": {
402-
Type: "string",
403-
Description: "Repository name",
404-
},
405-
"discussionNumber": {
406-
Type: "number",
407-
Description: "Discussion Number",
408-
},
409-
"includeReplies": {
410-
Type: "boolean",
411-
Description: "When true, each top-level comment will include its replies nested within it (up to 100 replies per comment, which is the GitHub API maximum). Defaults to false.",
412-
},
413-
},
414-
Required: []string{"owner", "repo", "discussionNumber"},
415-
}),
423+
InputSchema: schema,
416424
},
417425
[]scopes.Scope{scopes.Repo},
418426
func(ctx context.Context, deps ToolDependencies, _ *mcp.CallToolRequest, args map[string]any) (*mcp.CallToolResult, any, error) {
@@ -590,8 +598,9 @@ func DiscussionCommentWrite(t translations.TranslationHelperFunc) inventory.Serv
590598
ToolsetMetadataDiscussions,
591599
mcp.Tool{
592600
Name: "discussion_comment_write",
593-
Description: t("TOOL_DISCUSSION_COMMENT_WRITE_DESCRIPTION", `Write operations for discussion comments.
594-
Supports adding top-level comments, replying to existing comments, updating comment content, deleting comments, and marking or unmarking comments as the answer.`),
601+
Description: t("TOOL_DISCUSSION_COMMENT_WRITE_DESCRIPTION", `Write-only operations for discussion comments.
602+
Use only when the user explicitly asks to add a comment, reply, update, delete, mark as answer, or unmark as answer.
603+
Do not use this to read, list, get, summarize, count, search, or inspect discussion comments; use get_discussion_comments for read-only comment requests.`),
595604
Annotations: &mcp.ToolAnnotations{
596605
Title: t("TOOL_DISCUSSION_COMMENT_WRITE_USER_TITLE", "Manage discussion comments"),
597606
ReadOnlyHint: false,
@@ -615,15 +624,15 @@ Options are:
615624
},
616625
"owner": {
617626
Type: "string",
618-
Description: "Repository owner (required for 'add' and 'reply' methods)",
627+
Description: "Repository owner or organization login (required for 'add' and 'reply' methods). For org-level discussion URLs like https://github.com/orgs/ORG/discussions/NUMBER, use ORG.",
619628
},
620629
"repo": {
621630
Type: "string",
622-
Description: "Repository name (required for 'add' and 'reply' methods)",
631+
Description: "Repository name (required for 'add' and 'reply' methods). For org-level discussion URLs like https://github.com/orgs/ORG/discussions/NUMBER, use .github.",
623632
},
624633
"discussionNumber": {
625634
Type: "number",
626-
Description: "Discussion number (required for 'add' and 'reply' methods)",
635+
Description: "Discussion number from the URL path after /discussions/ (required for 'add' and 'reply' methods). This is not a node ID.",
627636
},
628637
"body": {
629638
Type: "string",

0 commit comments

Comments
 (0)