diff --git a/README.md b/README.md
index dc08311a4..e1a6750b4 100644
--- a/README.md
+++ b/README.md
@@ -621,7 +621,7 @@ The following sets of tools are available:
   - `inputs`: Inputs the workflow accepts. Only used for 'run_workflow' method. (object, optional)
   - `method`: The method to execute (string, required)
   - `owner`: Repository owner (string, required)
-  - `ref`: The git reference for the workflow. The reference can be a branch or tag name. Required for 'run_workflow' method. (string, optional)
+  - `ref`: Branch or tag name to run the workflow on. Required for 'run_workflow' method. (string, optional)
   - `repo`: Repository name (string, required)
   - `run_id`: The ID of the workflow run. Required for all methods except 'run_workflow'. (number, optional)
   - `workflow_id`: The workflow ID (numeric) or workflow file name (e.g., main.yml, ci.yaml). Required for 'run_workflow' method. (string, optional)
@@ -655,7 +655,7 @@ The following sets of tools are available:
   - `owner`: The owner of the repository. (string, required)
   - `page`: Page number for pagination (min 1) (number, optional)
   - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
-  - `ref`: The Git reference for the results you want to list. (string, optional)
+  - `ref`: Git ref to filter by, e.g. refs/heads/main or refs/pull/123/merge. (string, optional)
   - `repo`: The name of the repository. (string, required)
   - `severity`: Filter code scanning alerts by severity (string, optional)
   - `state`: Filter code scanning alerts by state. Defaults to open (string, optional)
@@ -689,7 +689,7 @@ The following sets of tools are available:
 
 - **assign_copilot_to_issue** - Assign Copilot to issue
   - **Required OAuth Scopes**: `repo`
-  - `base_ref`: Git reference (e.g., branch) that the agent will start its work from. If not specified, defaults to the repository's default branch (string, optional)
+  - `base_ref`: Branch or ref the agent starts from; defaults to the repository default branch (string, optional)
   - `custom_instructions`: Optional custom instructions to guide the agent beyond the issue body. Use this to provide additional context, constraints, or guidance that is not captured in the issue description (string, optional)
   - `issue_number`: Issue number (number, required)
   - `owner`: Repository owner (string, required)
@@ -732,7 +732,7 @@ The following sets of tools are available:
 
 - **discussion_comment_write** - Manage discussion comments
   - **Required OAuth Scopes**: `repo`
-  - `body`: Comment content (required for 'add', 'reply', and 'update' methods) (string, optional)
+  - `body`: Comment content. Markdown supported. Required for 'add', 'reply', and 'update' methods. (string, optional)
   - `commentNodeID`: The Node ID of the discussion comment (required for 'reply', 'update', 'delete', 'mark_answer', and 'unmark_answer' methods). For 'reply', this is the top-level comment to reply to; GitHub Discussions only support one level of nesting. (string, optional)
   - `discussionNumber`: Discussion number (required for 'add' and 'reply' methods) (number, optional)
   - `method`: Write operation to perform on a discussion comment.
@@ -785,7 +785,7 @@ The following sets of tools are available:
 
 - **create_gist** - Create Gist
   - **Required OAuth Scopes**: `gist`
-  - `content`: Content for simple single-file gist creation (string, required)
+  - `content`: Raw content for the single gist file (string, required)
   - `description`: Description of the gist (string, optional)
   - `filename`: Filename for simple single-file gist creation (string, required)
   - `public`: Whether the gist is public (boolean, optional)
@@ -801,7 +801,7 @@ The following sets of tools are available:
 
 - **update_gist** - Update Gist
   - **Required OAuth Scopes**: `gist`
-  - `content`: Content for the file (string, required)
+  - `content`: Raw content for the gist file (string, required)
   - `description`: Updated description of the gist (string, optional)
   - `filename`: Filename to update or create (string, required)
   - `gist_id`: ID of the gist to update (string, required)
@@ -828,7 +828,7 @@ The following sets of tools are available:
 
 - **add_issue_comment** - Add comment to issue
   - **Required OAuth Scopes**: `repo`
-  - `body`: Comment content (string, required)
+  - `body`: Comment body; Markdown supported. (string, required)
   - `issue_number`: Issue number to comment on (number, required)
   - `owner`: Repository owner (string, required)
   - `repo`: Repository name (string, required)
@@ -857,7 +857,7 @@ The following sets of tools are available:
 - **issue_write** - Create or update issue
   - **Required OAuth Scopes**: `repo`
   - `assignees`: Usernames to assign to this issue (string[], optional)
-  - `body`: Issue body content (string, optional)
+  - `body`: Issue body; Markdown supported. (string, optional)
   - `duplicate_of`: Issue number that this issue is a duplicate of. Only used when state_reason is 'duplicate'. (number, optional)
   - `issue_number`: Issue number to update (number, optional)
   - `labels`: Labels to apply to this issue (string[], optional)
@@ -897,7 +897,7 @@ The following sets of tools are available:
   - `owner`: Optional repository owner. If provided with repo, only issues for this repository are listed. (string, optional)
   - `page`: Page number for pagination (min 1) (number, optional)
   - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
-  - `query`: Search query using GitHub issues search syntax (string, required)
+  - `query`: Search query using GitHub issues search syntax. The tool adds is:issue and, when owner/repo are provided, repo:owner/repo; examples: "crash label:bug", "author:octocat updated:>=2024-01-01". (string, required)
   - `repo`: Optional repository name. If provided with owner, only issues for this repository are listed. (string, optional)
   - `sort`: Sort field by number of matches of categories, defaults to best match (string, optional)
 
@@ -1062,7 +1062,7 @@ The following sets of tools are available:
 
 - **add_comment_to_pending_review** - Add review comment to the requester's latest pending pull request review
   - **Required OAuth Scopes**: `repo`
-  - `body`: The text of the review comment (string, required)
+  - `body`: Review comment body; Markdown supported (string, required)
   - `line`: The line of the blob in the pull request diff that the comment applies to. For multi-line comments, the last line of the range (number, optional)
   - `owner`: Repository owner (string, required)
   - `path`: The relative path to the file that necessitates a comment (string, required)
@@ -1075,7 +1075,7 @@ The following sets of tools are available:
 
 - **add_reply_to_pull_request_comment** - Add reply to pull request comment
   - **Required OAuth Scopes**: `repo`
-  - `body`: The text of the reply (string, required)
+  - `body`: Reply body; Markdown supported (string, required)
   - `commentId`: The ID of the comment to reply to (number, required)
   - `owner`: Repository owner (string, required)
   - `pullNumber`: Pull request number (number, required)
@@ -1083,10 +1083,10 @@ The following sets of tools are available:
 
 - **create_pull_request** - Open new pull request
   - **Required OAuth Scopes**: `repo`
-  - `base`: Branch to merge into (string, required)
-  - `body`: PR description (string, optional)
+  - `base`: Base branch name to merge into, e.g. main (string, required)
+  - `body`: PR description; Markdown supported (string, optional)
   - `draft`: Create as draft PR (boolean, optional)
-  - `head`: Branch containing changes (string, required)
+  - `head`: Branch containing changes, or owner:branch for a fork (string, required)
   - `maintainer_can_modify`: Allow maintainer edits (boolean, optional)
   - `owner`: Repository owner (string, required)
   - `repo`: Repository name (string, required)
@@ -1094,9 +1094,9 @@ The following sets of tools are available:
 
 - **list_pull_requests** - List pull requests
   - **Required OAuth Scopes**: `repo`
-  - `base`: Filter by base branch (string, optional)
+  - `base`: Filter by base branch name. (string, optional)
   - `direction`: Sort direction (string, optional)
-  - `head`: Filter by head user/org and branch (string, optional)
+  - `head`: Filter by head user/org and branch, in user:branch format. (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)
@@ -1150,13 +1150,13 @@ The following sets of tools are available:
   - `owner`: Optional repository owner. If provided with repo, only pull requests for this repository are listed. (string, optional)
   - `page`: Page number for pagination (min 1) (number, optional)
   - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
-  - `query`: Search query using GitHub pull request search syntax (string, required)
+  - `query`: Search query using GitHub pull request search syntax. Qualifiers such as is:pr and repo:owner/repo are applied automatically when appropriate; examples: "review-requested:@me", "author:octocat updated:>=2024-01-01". (string, required)
   - `repo`: Optional repository name. If provided with owner, only pull requests for this repository are listed. (string, optional)
   - `sort`: Sort field by number of matches of categories, defaults to best match (string, optional)
 
 - **update_pull_request** - Edit pull request
   - **Required OAuth Scopes**: `repo`
-  - `base`: New base branch name (string, optional)
+  - `base`: New base branch name, e.g. main. (string, optional)
   - `body`: New description (string, optional)
   - `draft`: Mark pull request as draft (true) or ready for review (false) (boolean, optional)
   - `maintainer_can_modify`: Allow maintainer edits (boolean, optional)
@@ -1182,18 +1182,18 @@ The following sets of tools are available:
 
 - **create_branch** - Create branch
   - **Required OAuth Scopes**: `repo`
-  - `branch`: Name for new branch (string, required)
-  - `from_branch`: Source branch (defaults to repo default) (string, optional)
+  - `branch`: New branch name, without refs/heads/ (string, required)
+  - `from_branch`: Source branch name; defaults to the repository default branch (string, optional)
   - `owner`: Repository owner (string, required)
   - `repo`: Repository name (string, required)
 
 - **create_or_update_file** - Create or update file
   - **Required OAuth Scopes**: `repo`
-  - `branch`: Branch to create/update the file in (string, required)
-  - `content`: Content of the file (string, required)
-  - `message`: Commit message (string, required)
+  - `branch`: Branch name to create/update the file in (string, required)
+  - `content`: Raw file content (string, required)
+  - `message`: Commit message for this change (string, required)
   - `owner`: Repository owner (username or organization) (string, required)
-  - `path`: Path where to create/update the file (string, required)
+  - `path`: Repository-relative file path to create or update (string, required)
   - `repo`: Repository name (string, required)
   - `sha`: The blob SHA of the file being replaced. Required if the file already exists. (string, optional)
 
@@ -1207,10 +1207,10 @@ The following sets of tools are available:
 
 - **delete_file** - Delete file
   - **Required OAuth Scopes**: `repo`
-  - `branch`: Branch to delete the file from (string, required)
-  - `message`: Commit message (string, required)
+  - `branch`: Branch name to delete the file from (string, required)
+  - `message`: Commit message for the delete commit (string, required)
   - `owner`: Repository owner (username or organization) (string, required)
-  - `path`: Path to the file to delete (string, required)
+  - `path`: Repository-relative path to the file to delete (string, required)
   - `repo`: Repository name (string, required)
 
 - **fork_repository** - Fork repository
@@ -1231,7 +1231,7 @@ The following sets of tools are available:
 - **get_file_contents** - Get file or directory contents
   - **Required OAuth Scopes**: `repo`
   - `owner`: Repository owner (username or organization) (string, required)
-  - `path`: Path to file/directory (string, optional)
+  - `path`: Repository-relative file or directory path (string, optional)
   - `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 commit SHA. If specified, it will be used instead of ref (string, optional)
@@ -1296,7 +1296,7 @@ The following sets of tools are available:
 
 - **push_files** - Push files to repository
   - **Required OAuth Scopes**: `repo`
-  - `branch`: Branch to push to (string, required)
+  - `branch`: Branch name to push the commit to (string, required)
   - `files`: Array of file objects to push, each object with path (string) and content (string) (object[], required)
   - `message`: Commit message (string, required)
   - `owner`: Repository owner (string, required)
@@ -1308,7 +1308,7 @@ The following sets of tools are available:
   - `page`: Page number for pagination (min 1) (number, optional)
   - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
   - `query`: Search query (GitHub code search REST). Implicit AND between terms; supports `OR`, `NOT`, and `"quoted phrase"` for exact match. Qualifiers: `repo:owner/repo`, `org:`, `user:`, `language:`, `path:dir` (prefix match), `filename:exact.ext`, `extension:`, `in:file`, `in:path`, `size:`, `is:archived`, `is:fork`. Max 256 chars. Examples: `WithContext language:go org:github`; `"package main" repo:o/r`; `func extension:go path:cmd repo:o/r`; `NOT TODO language:go repo:o/r`. (string, required)
-  - `sort`: Sort field ('indexed' only) (string, optional)
+  - `sort`: Sort field. Use 'indexed' to sort by recently indexed files. (string, optional)
 
 - **search_commits** - Search commits
   - **Required OAuth Scopes**: `repo`
diff --git a/docs/feature-flags.md b/docs/feature-flags.md
index 0b75a61ba..4e9af06e2 100644
--- a/docs/feature-flags.md
+++ b/docs/feature-flags.md
@@ -37,10 +37,10 @@ runtime behavior (such as output formatting) won't appear here.
 - **create_pull_request** - Open new pull request
   - **Required OAuth Scopes**: `repo`
   - **MCP App UI**: `ui://github-mcp-server/pr-write`
-  - `base`: Branch to merge into (string, required)
-  - `body`: PR description (string, optional)
+  - `base`: Base branch name to merge into, e.g. main (string, required)
+  - `body`: PR description; Markdown supported (string, optional)
   - `draft`: Create as draft PR (boolean, optional)
-  - `head`: Branch containing changes (string, required)
+  - `head`: Branch containing changes, or owner:branch for a fork (string, required)
   - `maintainer_can_modify`: Allow maintainer edits (boolean, optional)
   - `owner`: Repository owner (string, required)
   - `repo`: Repository name (string, required)
@@ -54,7 +54,7 @@ runtime behavior (such as output formatting) won't appear here.
   - **Required OAuth Scopes**: `repo`
   - **MCP App UI**: `ui://github-mcp-server/issue-write`
   - `assignees`: Usernames to assign to this issue (string[], optional)
-  - `body`: Issue body content (string, optional)
+  - `body`: Issue body; Markdown supported. (string, optional)
   - `duplicate_of`: Issue number that this issue is a duplicate of. Only used when state_reason is 'duplicate'. (number, optional)
   - `issue_number`: Issue number to update (number, optional)
   - `labels`: Labels to apply to this issue (string[], optional)
@@ -76,7 +76,7 @@ runtime behavior (such as output formatting) won't appear here.
 - **issue_write** - Create or update issue
   - **Required OAuth Scopes**: `repo`
   - `assignees`: Usernames to assign to this issue (string[], optional)
-  - `body`: Issue body content (string, optional)
+  - `body`: Issue body; Markdown supported. (string, optional)
   - `duplicate_of`: Issue number that this issue is a duplicate of. Only used when state_reason is 'duplicate'. (number, optional)
   - `issue_fields`: Issue field values to set or clear. Each item requires 'field_name' and exactly one of 'value', 'field_option_name', or 'delete: true'. (object[], optional)
   - `issue_number`: Issue number to update (number, optional)
@@ -125,7 +125,7 @@ runtime behavior (such as output formatting) won't appear here.
 
 - **create_issue** - Create Issue
   - **Required OAuth Scopes**: `repo`
-  - `body`: Issue body content (optional) (string, optional)
+  - `body`: Issue body (optional); Markdown supported. (string, optional)
   - `owner`: Repository owner (username or organization) (string, required)
   - `repo`: Repository name (string, required)
   - `title`: Issue title (string, required)
@@ -162,7 +162,7 @@ runtime behavior (such as output formatting) won't appear here.
 
 - **update_issue_body** - Update Issue Body
   - **Required OAuth Scopes**: `repo`
-  - `body`: The new body content for the issue (string, required)
+  - `body`: Issue body; Markdown supported. (string, required)
   - `issue_number`: The issue number to update (number, required)
   - `owner`: Repository owner (username or organization) (string, required)
   - `repo`: Repository name (string, required)
@@ -209,7 +209,7 @@ runtime behavior (such as output formatting) won't appear here.
 
 - **add_pull_request_review_comment** - Add Pull Request Review Comment
   - **Required OAuth Scopes**: `repo`
-  - `body`: The comment body (string, required)
+  - `body`: Review comment body; Markdown supported (string, required)
   - `line`: The line number in the diff to comment on (optional) (number, optional)
   - `owner`: Repository owner (username or organization) (string, required)
   - `path`: The relative path of the file to comment on (string, required)
@@ -222,7 +222,7 @@ runtime behavior (such as output formatting) won't appear here.
 
 - **create_pull_request_review** - Create Pull Request Review
   - **Required OAuth Scopes**: `repo`
-  - `body`: The review body text (optional) (string, optional)
+  - `body`: Review body (optional); Markdown supported (string, optional)
   - `commitID`: The SHA of the commit to review (optional, defaults to latest) (string, optional)
   - `event`: The review action to perform. If omitted, creates a pending review. (string, optional)
   - `owner`: Repository owner (username or organization) (string, required)
@@ -240,7 +240,7 @@ runtime behavior (such as output formatting) won't appear here.
   - `owner`: Repository owner (username or organization) (string, required)
   - `pullNumber`: The pull request number (number, required)
   - `repo`: Repository name (string, required)
-  - `reviewers`: GitHub usernames to request reviews from (string[], required)
+  - `reviewers`: GitHub usernames or ORG/team-slug team reviewers to request reviews from (string[], required)
 
 - **resolve_review_thread** - Resolve Review Thread
   - **Required OAuth Scopes**: `repo`
@@ -248,7 +248,7 @@ runtime behavior (such as output formatting) won't appear here.
 
 - **submit_pending_pull_request_review** - Submit Pending Pull Request Review
   - **Required OAuth Scopes**: `repo`
-  - `body`: The review body text (optional) (string, optional)
+  - `body`: Review body; Markdown supported (string, optional)
   - `event`: The review action to perform (string, required)
   - `owner`: Repository owner (username or organization) (string, required)
   - `pullNumber`: The pull request number (number, required)
diff --git a/docs/insiders-features.md b/docs/insiders-features.md
index 881030f02..a2503fe09 100644
--- a/docs/insiders-features.md
+++ b/docs/insiders-features.md
@@ -31,10 +31,10 @@ The list below is generated from the Go source. It covers tool **inventory and s
 - **create_pull_request** - Open new pull request
   - **Required OAuth Scopes**: `repo`
   - **MCP App UI**: `ui://github-mcp-server/pr-write`
-  - `base`: Branch to merge into (string, required)
-  - `body`: PR description (string, optional)
+  - `base`: Base branch name to merge into, e.g. main (string, required)
+  - `body`: PR description; Markdown supported (string, optional)
   - `draft`: Create as draft PR (boolean, optional)
-  - `head`: Branch containing changes (string, required)
+  - `head`: Branch containing changes, or owner:branch for a fork (string, required)
   - `maintainer_can_modify`: Allow maintainer edits (boolean, optional)
   - `owner`: Repository owner (string, required)
   - `repo`: Repository name (string, required)
@@ -48,7 +48,7 @@ The list below is generated from the Go source. It covers tool **inventory and s
   - **Required OAuth Scopes**: `repo`
   - **MCP App UI**: `ui://github-mcp-server/issue-write`
   - `assignees`: Usernames to assign to this issue (string[], optional)
-  - `body`: Issue body content (string, optional)
+  - `body`: Issue body; Markdown supported. (string, optional)
   - `duplicate_of`: Issue number that this issue is a duplicate of. Only used when state_reason is 'duplicate'. (number, optional)
   - `issue_number`: Issue number to update (number, optional)
   - `labels`: Labels to apply to this issue (string[], optional)
@@ -70,7 +70,7 @@ The list below is generated from the Go source. It covers tool **inventory and s
 - **issue_write** - Create or update issue
   - **Required OAuth Scopes**: `repo`
   - `assignees`: Usernames to assign to this issue (string[], optional)
-  - `body`: Issue body content (string, optional)
+  - `body`: Issue body; Markdown supported. (string, optional)
   - `duplicate_of`: Issue number that this issue is a duplicate of. Only used when state_reason is 'duplicate'. (number, optional)
   - `issue_fields`: Issue field values to set or clear. Each item requires 'field_name' and exactly one of 'value', 'field_option_name', or 'delete: true'. (object[], optional)
   - `issue_number`: Issue number to update (number, optional)
diff --git a/pkg/github/__toolsnaps__/actions_list.snap b/pkg/github/__toolsnaps__/actions_list.snap
index a7e9ec56b..23f31a594 100644
--- a/pkg/github/__toolsnaps__/actions_list.snap
+++ b/pkg/github/__toolsnaps__/actions_list.snap
@@ -61,7 +61,7 @@
             "type": "string"
           },
           "branch": {
-            "description": "Filter workflow runs to a specific Git branch. Use the name of the branch.",
+            "description": "Filter workflow runs by branch name, e.g. main; do not include refs/heads/.",
             "type": "string"
           },
           "event": {
diff --git a/pkg/github/__toolsnaps__/actions_run_trigger.snap b/pkg/github/__toolsnaps__/actions_run_trigger.snap
index 41a643992..7081fa9c1 100644
--- a/pkg/github/__toolsnaps__/actions_run_trigger.snap
+++ b/pkg/github/__toolsnaps__/actions_run_trigger.snap
@@ -27,7 +27,7 @@
         "type": "string"
       },
       "ref": {
-        "description": "The git reference for the workflow. The reference can be a branch or tag name. Required for 'run_workflow' method.",
+        "description": "Branch or tag name to run the workflow on. Required for 'run_workflow' method.",
         "type": "string"
       },
       "repo": {
diff --git a/pkg/github/__toolsnaps__/add_comment_to_pending_review.snap b/pkg/github/__toolsnaps__/add_comment_to_pending_review.snap
index af4c41f52..eb3d4d1b0 100644
--- a/pkg/github/__toolsnaps__/add_comment_to_pending_review.snap
+++ b/pkg/github/__toolsnaps__/add_comment_to_pending_review.snap
@@ -6,7 +6,7 @@
   "inputSchema": {
     "properties": {
       "body": {
-        "description": "The text of the review comment",
+        "description": "Review comment body; Markdown supported",
         "type": "string"
       },
       "line": {
diff --git a/pkg/github/__toolsnaps__/add_issue_comment.snap b/pkg/github/__toolsnaps__/add_issue_comment.snap
index d273a582d..ecfa74752 100644
--- a/pkg/github/__toolsnaps__/add_issue_comment.snap
+++ b/pkg/github/__toolsnaps__/add_issue_comment.snap
@@ -6,7 +6,7 @@
   "inputSchema": {
     "properties": {
       "body": {
-        "description": "Comment content",
+        "description": "Comment body; Markdown supported.",
         "type": "string"
       },
       "issue_number": {
diff --git a/pkg/github/__toolsnaps__/add_pull_request_review_comment.snap b/pkg/github/__toolsnaps__/add_pull_request_review_comment.snap
index 1e27c5645..99c036ce1 100644
--- a/pkg/github/__toolsnaps__/add_pull_request_review_comment.snap
+++ b/pkg/github/__toolsnaps__/add_pull_request_review_comment.snap
@@ -8,7 +8,7 @@
   "inputSchema": {
     "properties": {
       "body": {
-        "description": "The comment body",
+        "description": "Review comment body; Markdown supported",
         "type": "string"
       },
       "line": {
diff --git a/pkg/github/__toolsnaps__/add_reply_to_pull_request_comment.snap b/pkg/github/__toolsnaps__/add_reply_to_pull_request_comment.snap
index e2187478e..e89e922a0 100644
--- a/pkg/github/__toolsnaps__/add_reply_to_pull_request_comment.snap
+++ b/pkg/github/__toolsnaps__/add_reply_to_pull_request_comment.snap
@@ -6,7 +6,7 @@
   "inputSchema": {
     "properties": {
       "body": {
-        "description": "The text of the reply",
+        "description": "Reply body; Markdown supported",
         "type": "string"
       },
       "commentId": {
diff --git a/pkg/github/__toolsnaps__/assign_copilot_to_issue.snap b/pkg/github/__toolsnaps__/assign_copilot_to_issue.snap
index 9c105267b..5095a9dae 100644
--- a/pkg/github/__toolsnaps__/assign_copilot_to_issue.snap
+++ b/pkg/github/__toolsnaps__/assign_copilot_to_issue.snap
@@ -19,7 +19,7 @@
   "inputSchema": {
     "properties": {
       "base_ref": {
-        "description": "Git reference (e.g., branch) that the agent will start its work from. If not specified, defaults to the repository's default branch",
+        "description": "Branch or ref the agent starts from; defaults to the repository default branch",
         "type": "string"
       },
       "custom_instructions": {
diff --git a/pkg/github/__toolsnaps__/create_branch.snap b/pkg/github/__toolsnaps__/create_branch.snap
index a561247ef..5cdbd74e2 100644
--- a/pkg/github/__toolsnaps__/create_branch.snap
+++ b/pkg/github/__toolsnaps__/create_branch.snap
@@ -6,11 +6,11 @@
   "inputSchema": {
     "properties": {
       "branch": {
-        "description": "Name for new branch",
+        "description": "New branch name, without refs/heads/",
         "type": "string"
       },
       "from_branch": {
-        "description": "Source branch (defaults to repo default)",
+        "description": "Source branch name; defaults to the repository default branch",
         "type": "string"
       },
       "owner": {
diff --git a/pkg/github/__toolsnaps__/create_gist.snap b/pkg/github/__toolsnaps__/create_gist.snap
index 0ef05aa4a..7b6b154de 100644
--- a/pkg/github/__toolsnaps__/create_gist.snap
+++ b/pkg/github/__toolsnaps__/create_gist.snap
@@ -6,7 +6,7 @@
   "inputSchema": {
     "properties": {
       "content": {
-        "description": "Content for simple single-file gist creation",
+        "description": "Raw content for the single gist file",
         "type": "string"
       },
       "description": {
diff --git a/pkg/github/__toolsnaps__/create_issue.snap b/pkg/github/__toolsnaps__/create_issue.snap
index 51923c47c..e34e9616d 100644
--- a/pkg/github/__toolsnaps__/create_issue.snap
+++ b/pkg/github/__toolsnaps__/create_issue.snap
@@ -8,7 +8,7 @@
   "inputSchema": {
     "properties": {
       "body": {
-        "description": "Issue body content (optional)",
+        "description": "Issue body (optional); Markdown supported.",
         "type": "string"
       },
       "owner": {
diff --git a/pkg/github/__toolsnaps__/create_or_update_file.snap b/pkg/github/__toolsnaps__/create_or_update_file.snap
index e6900c905..b30deb354 100644
--- a/pkg/github/__toolsnaps__/create_or_update_file.snap
+++ b/pkg/github/__toolsnaps__/create_or_update_file.snap
@@ -6,15 +6,15 @@
   "inputSchema": {
     "properties": {
       "branch": {
-        "description": "Branch to create/update the file in",
+        "description": "Branch name to create/update the file in",
         "type": "string"
       },
       "content": {
-        "description": "Content of the file",
+        "description": "Raw file content",
         "type": "string"
       },
       "message": {
-        "description": "Commit message",
+        "description": "Commit message for this change",
         "type": "string"
       },
       "owner": {
@@ -22,7 +22,7 @@
         "type": "string"
       },
       "path": {
-        "description": "Path where to create/update the file",
+        "description": "Repository-relative file path to create or update",
         "type": "string"
       },
       "repo": {
diff --git a/pkg/github/__toolsnaps__/create_pull_request.snap b/pkg/github/__toolsnaps__/create_pull_request.snap
index a8a94ce69..378f5020e 100644
--- a/pkg/github/__toolsnaps__/create_pull_request.snap
+++ b/pkg/github/__toolsnaps__/create_pull_request.snap
@@ -15,11 +15,11 @@
   "inputSchema": {
     "properties": {
       "base": {
-        "description": "Branch to merge into",
+        "description": "Base branch name to merge into, e.g. main",
         "type": "string"
       },
       "body": {
-        "description": "PR description",
+        "description": "PR description; Markdown supported",
         "type": "string"
       },
       "draft": {
@@ -27,7 +27,7 @@
         "type": "boolean"
       },
       "head": {
-        "description": "Branch containing changes",
+        "description": "Branch containing changes, or owner:branch for a fork",
         "type": "string"
       },
       "maintainer_can_modify": {
diff --git a/pkg/github/__toolsnaps__/create_pull_request_review.snap b/pkg/github/__toolsnaps__/create_pull_request_review.snap
index 1986b2cff..c797d1b1d 100644
--- a/pkg/github/__toolsnaps__/create_pull_request_review.snap
+++ b/pkg/github/__toolsnaps__/create_pull_request_review.snap
@@ -8,7 +8,7 @@
   "inputSchema": {
     "properties": {
       "body": {
-        "description": "The review body text (optional)",
+        "description": "Review body (optional); Markdown supported",
         "type": "string"
       },
       "commitID": {
diff --git a/pkg/github/__toolsnaps__/delete_file.snap b/pkg/github/__toolsnaps__/delete_file.snap
index ff110ff78..50bf1b3e5 100644
--- a/pkg/github/__toolsnaps__/delete_file.snap
+++ b/pkg/github/__toolsnaps__/delete_file.snap
@@ -7,11 +7,11 @@
   "inputSchema": {
     "properties": {
       "branch": {
-        "description": "Branch to delete the file from",
+        "description": "Branch name to delete the file from",
         "type": "string"
       },
       "message": {
-        "description": "Commit message",
+        "description": "Commit message for the delete commit",
         "type": "string"
       },
       "owner": {
@@ -19,7 +19,7 @@
         "type": "string"
       },
       "path": {
-        "description": "Path to the file to delete",
+        "description": "Repository-relative path to the file to delete",
         "type": "string"
       },
       "repo": {
diff --git a/pkg/github/__toolsnaps__/discussion_comment_write.snap b/pkg/github/__toolsnaps__/discussion_comment_write.snap
index 5edadfaea..ceacf6fc1 100644
--- a/pkg/github/__toolsnaps__/discussion_comment_write.snap
+++ b/pkg/github/__toolsnaps__/discussion_comment_write.snap
@@ -7,7 +7,7 @@
   "inputSchema": {
     "properties": {
       "body": {
-        "description": "Comment content (required for 'add', 'reply', and 'update' methods)",
+        "description": "Comment content. Markdown supported. Required for 'add', 'reply', and 'update' methods.",
         "type": "string"
       },
       "commentNodeID": {
diff --git a/pkg/github/__toolsnaps__/get_file_contents.snap b/pkg/github/__toolsnaps__/get_file_contents.snap
index 94b7aeeda..1821092d0 100644
--- a/pkg/github/__toolsnaps__/get_file_contents.snap
+++ b/pkg/github/__toolsnaps__/get_file_contents.snap
@@ -12,7 +12,7 @@
       },
       "path": {
         "default": "/",
-        "description": "Path to file/directory",
+        "description": "Repository-relative file or directory path",
         "type": "string"
       },
       "ref": {
diff --git a/pkg/github/__toolsnaps__/issue_write.snap b/pkg/github/__toolsnaps__/issue_write.snap
index a125864f0..5980fd4bb 100644
--- a/pkg/github/__toolsnaps__/issue_write.snap
+++ b/pkg/github/__toolsnaps__/issue_write.snap
@@ -17,12 +17,13 @@
       "assignees": {
         "description": "Usernames to assign to this issue",
         "items": {
+          "description": "GitHub username",
           "type": "string"
         },
         "type": "array"
       },
       "body": {
-        "description": "Issue body content",
+        "description": "Issue body; Markdown supported.",
         "type": "string"
       },
       "duplicate_of": {
@@ -36,6 +37,7 @@
       "labels": {
         "description": "Labels to apply to this issue",
         "items": {
+          "description": "Existing label name",
           "type": "string"
         },
         "type": "array"
diff --git a/pkg/github/__toolsnaps__/issue_write_ff_remote_mcp_issue_fields.snap b/pkg/github/__toolsnaps__/issue_write_ff_remote_mcp_issue_fields.snap
index 6fb00d249..31ea05fa7 100644
--- a/pkg/github/__toolsnaps__/issue_write_ff_remote_mcp_issue_fields.snap
+++ b/pkg/github/__toolsnaps__/issue_write_ff_remote_mcp_issue_fields.snap
@@ -17,12 +17,13 @@
       "assignees": {
         "description": "Usernames to assign to this issue",
         "items": {
+          "description": "GitHub username",
           "type": "string"
         },
         "type": "array"
       },
       "body": {
-        "description": "Issue body content",
+        "description": "Issue body; Markdown supported.",
         "type": "string"
       },
       "duplicate_of": {
@@ -72,6 +73,7 @@
       "labels": {
         "description": "Labels to apply to this issue",
         "items": {
+          "description": "Existing label name",
           "type": "string"
         },
         "type": "array"
diff --git a/pkg/github/__toolsnaps__/list_code_scanning_alerts.snap b/pkg/github/__toolsnaps__/list_code_scanning_alerts.snap
index 9eddf045d..b90e47a54 100644
--- a/pkg/github/__toolsnaps__/list_code_scanning_alerts.snap
+++ b/pkg/github/__toolsnaps__/list_code_scanning_alerts.snap
@@ -22,7 +22,7 @@
         "type": "number"
       },
       "ref": {
-        "description": "The Git reference for the results you want to list.",
+        "description": "Git ref to filter by, e.g. refs/heads/main or refs/pull/123/merge.",
         "type": "string"
       },
       "repo": {
diff --git a/pkg/github/__toolsnaps__/list_issues_ff_remote_mcp_issue_fields.snap b/pkg/github/__toolsnaps__/list_issues_ff_remote_mcp_issue_fields.snap
index b1d1c7a21..bd8f03f89 100644
--- a/pkg/github/__toolsnaps__/list_issues_ff_remote_mcp_issue_fields.snap
+++ b/pkg/github/__toolsnaps__/list_issues_ff_remote_mcp_issue_fields.snap
@@ -42,6 +42,7 @@
       "labels": {
         "description": "Filter by labels",
         "items": {
+          "description": "Label name",
           "type": "string"
         },
         "type": "array"
diff --git a/pkg/github/__toolsnaps__/list_pull_requests.snap b/pkg/github/__toolsnaps__/list_pull_requests.snap
index 25f1268c6..051e956ab 100644
--- a/pkg/github/__toolsnaps__/list_pull_requests.snap
+++ b/pkg/github/__toolsnaps__/list_pull_requests.snap
@@ -7,7 +7,7 @@
   "inputSchema": {
     "properties": {
       "base": {
-        "description": "Filter by base branch",
+        "description": "Filter by base branch name.",
         "type": "string"
       },
       "direction": {
@@ -19,7 +19,7 @@
         "type": "string"
       },
       "head": {
-        "description": "Filter by head user/org and branch",
+        "description": "Filter by head user/org and branch, in user:branch format.",
         "type": "string"
       },
       "owner": {
diff --git a/pkg/github/__toolsnaps__/projects_get.snap b/pkg/github/__toolsnaps__/projects_get.snap
index 864f61d83..1a0363cd6 100644
--- a/pkg/github/__toolsnaps__/projects_get.snap
+++ b/pkg/github/__toolsnaps__/projects_get.snap
@@ -13,6 +13,7 @@
       "fields": {
         "description": "Specific list of field IDs to include in the response when getting a project item (e.g. [\"102589\", \"985201\", \"169875\"]). If not provided, only the title field is included. Only used for 'get_project_item' method.",
         "items": {
+          "description": "Project field ID to include in the project item response, e.g. \"102589\".",
           "type": "string"
         },
         "type": "array"
diff --git a/pkg/github/__toolsnaps__/projects_list.snap b/pkg/github/__toolsnaps__/projects_list.snap
index c2bb0d3f4..95d44e8c2 100644
--- a/pkg/github/__toolsnaps__/projects_list.snap
+++ b/pkg/github/__toolsnaps__/projects_list.snap
@@ -17,6 +17,7 @@
       "fields": {
         "description": "Field IDs to include when listing project items (e.g. [\"102589\", \"985201\"]). CRITICAL: Always provide to get field values. Without this, only titles returned. Only used for 'list_project_items' method.",
         "items": {
+          "description": "Project field ID to include in each item's field values, e.g. \"102589\".",
           "type": "string"
         },
         "type": "array"
diff --git a/pkg/github/__toolsnaps__/push_files.snap b/pkg/github/__toolsnaps__/push_files.snap
index df6c4d1e7..a2b72056c 100644
--- a/pkg/github/__toolsnaps__/push_files.snap
+++ b/pkg/github/__toolsnaps__/push_files.snap
@@ -6,7 +6,7 @@
   "inputSchema": {
     "properties": {
       "branch": {
-        "description": "Branch to push to",
+        "description": "Branch name to push the commit to",
         "type": "string"
       },
       "files": {
@@ -15,11 +15,11 @@
           "additionalProperties": false,
           "properties": {
             "content": {
-              "description": "file content",
+              "description": "Raw file content",
               "type": "string"
             },
             "path": {
-              "description": "path to the file",
+              "description": "Repository-relative file path",
               "type": "string"
             }
           },
diff --git a/pkg/github/__toolsnaps__/request_pull_request_reviewers.snap b/pkg/github/__toolsnaps__/request_pull_request_reviewers.snap
index 7e6d33a27..9361767db 100644
--- a/pkg/github/__toolsnaps__/request_pull_request_reviewers.snap
+++ b/pkg/github/__toolsnaps__/request_pull_request_reviewers.snap
@@ -23,6 +23,7 @@
       "reviewers": {
         "description": "GitHub usernames or ORG/team-slug team reviewers to request reviews from",
         "items": {
+          "description": "GitHub username or ORG/team-slug team",
           "type": "string"
         },
         "type": "array"
@@ -37,4 +38,4 @@
     "type": "object"
   },
   "name": "request_pull_request_reviewers"
-}
+}
\ No newline at end of file
diff --git a/pkg/github/__toolsnaps__/search_code.snap b/pkg/github/__toolsnaps__/search_code.snap
index 79cbbf04e..2a0e0222b 100644
--- a/pkg/github/__toolsnaps__/search_code.snap
+++ b/pkg/github/__toolsnaps__/search_code.snap
@@ -30,7 +30,10 @@
         "type": "string"
       },
       "sort": {
-        "description": "Sort field ('indexed' only)",
+        "description": "Sort field. Use 'indexed' to sort by recently indexed files.",
+        "enum": [
+          "indexed"
+        ],
         "type": "string"
       }
     },
diff --git a/pkg/github/__toolsnaps__/search_issues.snap b/pkg/github/__toolsnaps__/search_issues.snap
index beaa5b737..d69f2ac68 100644
--- a/pkg/github/__toolsnaps__/search_issues.snap
+++ b/pkg/github/__toolsnaps__/search_issues.snap
@@ -30,7 +30,7 @@
         "type": "number"
       },
       "query": {
-        "description": "Search query using GitHub issues search syntax",
+        "description": "Search query using GitHub issues search syntax. The tool adds is:issue and, when owner/repo are provided, repo:owner/repo; examples: \"crash label:bug\", \"author:octocat updated:\u003e=2024-01-01\".",
         "type": "string"
       },
       "repo": {
diff --git a/pkg/github/__toolsnaps__/search_pull_requests.snap b/pkg/github/__toolsnaps__/search_pull_requests.snap
index 05376c006..a916ae0c9 100644
--- a/pkg/github/__toolsnaps__/search_pull_requests.snap
+++ b/pkg/github/__toolsnaps__/search_pull_requests.snap
@@ -30,7 +30,7 @@
         "type": "number"
       },
       "query": {
-        "description": "Search query using GitHub pull request search syntax",
+        "description": "Search query using GitHub pull request search syntax. Qualifiers such as is:pr and repo:owner/repo are applied automatically when appropriate; examples: \"review-requested:@me\", \"author:octocat updated:\u003e=2024-01-01\".",
         "type": "string"
       },
       "repo": {
diff --git a/pkg/github/__toolsnaps__/sub_issue_write.snap b/pkg/github/__toolsnaps__/sub_issue_write.snap
index 1e4fcceab..ad22767ac 100644
--- a/pkg/github/__toolsnaps__/sub_issue_write.snap
+++ b/pkg/github/__toolsnaps__/sub_issue_write.snap
@@ -19,6 +19,11 @@
       },
       "method": {
         "description": "The action to perform on a single sub-issue\nOptions are:\n- 'add' - add a sub-issue to a parent issue in a GitHub repository.\n- 'remove' - remove a sub-issue from a parent issue in a GitHub repository.\n- 'reprioritize' - change the order of sub-issues within a parent issue in a GitHub repository. Use either 'after_id' or 'before_id' to specify the new position.\n\t\t\t\t",
+        "enum": [
+          "add",
+          "remove",
+          "reprioritize"
+        ],
         "type": "string"
       },
       "owner": {
diff --git a/pkg/github/__toolsnaps__/submit_pending_pull_request_review.snap b/pkg/github/__toolsnaps__/submit_pending_pull_request_review.snap
index 81223e2a9..7d0f6b8a2 100644
--- a/pkg/github/__toolsnaps__/submit_pending_pull_request_review.snap
+++ b/pkg/github/__toolsnaps__/submit_pending_pull_request_review.snap
@@ -8,7 +8,7 @@
   "inputSchema": {
     "properties": {
       "body": {
-        "description": "The review body text (optional)",
+        "description": "Review body; Markdown supported",
         "type": "string"
       },
       "event": {
diff --git a/pkg/github/__toolsnaps__/update_gist.snap b/pkg/github/__toolsnaps__/update_gist.snap
index 6d5ed100e..34b291509 100644
--- a/pkg/github/__toolsnaps__/update_gist.snap
+++ b/pkg/github/__toolsnaps__/update_gist.snap
@@ -6,7 +6,7 @@
   "inputSchema": {
     "properties": {
       "content": {
-        "description": "Content for the file",
+        "description": "Raw content for the gist file",
         "type": "string"
       },
       "description": {
diff --git a/pkg/github/__toolsnaps__/update_issue_body.snap b/pkg/github/__toolsnaps__/update_issue_body.snap
index c54d69172..e84c43cce 100644
--- a/pkg/github/__toolsnaps__/update_issue_body.snap
+++ b/pkg/github/__toolsnaps__/update_issue_body.snap
@@ -8,7 +8,7 @@
   "inputSchema": {
     "properties": {
       "body": {
-        "description": "The new body content for the issue",
+        "description": "Issue body; Markdown supported.",
         "type": "string"
       },
       "issue_number": {
diff --git a/pkg/github/__toolsnaps__/update_pull_request.snap b/pkg/github/__toolsnaps__/update_pull_request.snap
index 640df7970..99d7538ee 100644
--- a/pkg/github/__toolsnaps__/update_pull_request.snap
+++ b/pkg/github/__toolsnaps__/update_pull_request.snap
@@ -6,7 +6,7 @@
   "inputSchema": {
     "properties": {
       "base": {
-        "description": "New base branch name",
+        "description": "New base branch name, e.g. main.",
         "type": "string"
       },
       "body": {
@@ -36,6 +36,7 @@
       "reviewers": {
         "description": "GitHub usernames or ORG/team-slug team reviewers to request reviews from",
         "items": {
+          "description": "GitHub username or ORG/team-slug team",
           "type": "string"
         },
         "type": "array"
@@ -61,4 +62,4 @@
     "type": "object"
   },
   "name": "update_pull_request"
-}
+}
\ No newline at end of file
diff --git a/pkg/github/actions.go b/pkg/github/actions.go
index a7ce039d8..a83207f27 100644
--- a/pkg/github/actions.go
+++ b/pkg/github/actions.go
@@ -249,7 +249,7 @@ Use this tool to list workflows in a repository, or list workflow runs, jobs, an
 							},
 							"branch": {
 								Type:        "string",
-								Description: "Filter workflow runs to a specific Git branch. Use the name of the branch.",
+								Description: "Filter workflow runs by branch name, e.g. main; do not include refs/heads/.",
 							},
 							"event": {
 								Type:        "string",
@@ -539,7 +539,7 @@ func ActionsRunTrigger(t translations.TranslationHelperFunc) inventory.ServerToo
 					},
 					"ref": {
 						Type:        "string",
-						Description: "The git reference for the workflow. The reference can be a branch or tag name. Required for 'run_workflow' method.",
+						Description: "Branch or tag name to run the workflow on. Required for 'run_workflow' method.",
 					},
 					"inputs": {
 						Type:        "object",
diff --git a/pkg/github/code_scanning.go b/pkg/github/code_scanning.go
index 44307513b..5384f3f2a 100644
--- a/pkg/github/code_scanning.go
+++ b/pkg/github/code_scanning.go
@@ -113,7 +113,7 @@ func ListCodeScanningAlerts(t translations.TranslationHelperFunc) inventory.Serv
 			},
 			"ref": {
 				Type:        "string",
-				Description: "The Git reference for the results you want to list.",
+				Description: "Git ref to filter by, e.g. refs/heads/main or refs/pull/123/merge.",
 			},
 			"severity": {
 				Type:        "string",
diff --git a/pkg/github/copilot.go b/pkg/github/copilot.go
index 017bb98bc..90c18941c 100644
--- a/pkg/github/copilot.go
+++ b/pkg/github/copilot.go
@@ -190,7 +190,7 @@ func AssignCopilotToIssue(t translations.TranslationHelperFunc) inventory.Server
 					},
 					"base_ref": {
 						Type:        "string",
-						Description: "Git reference (e.g., branch) that the agent will start its work from. If not specified, defaults to the repository's default branch",
+						Description: "Branch or ref the agent starts from; defaults to the repository default branch",
 					},
 					"custom_instructions": {
 						Type:        "string",
diff --git a/pkg/github/discussions.go b/pkg/github/discussions.go
index 514a2d030..6b3c137ca 100644
--- a/pkg/github/discussions.go
+++ b/pkg/github/discussions.go
@@ -627,7 +627,7 @@ Options are:
 					},
 					"body": {
 						Type:        "string",
-						Description: "Comment content (required for 'add', 'reply', and 'update' methods)",
+						Description: "Comment content. Markdown supported. Required for 'add', 'reply', and 'update' methods.",
 					},
 					"commentNodeID": {
 						Type:        "string",
diff --git a/pkg/github/gists.go b/pkg/github/gists.go
index de577af04..b7590f23a 100644
--- a/pkg/github/gists.go
+++ b/pkg/github/gists.go
@@ -186,7 +186,7 @@ func CreateGist(t translations.TranslationHelperFunc) inventory.ServerTool {
 					},
 					"content": {
 						Type:        "string",
-						Description: "Content for simple single-file gist creation",
+						Description: "Raw content for the single gist file",
 					},
 					"public": {
 						Type:        "boolean",
@@ -293,7 +293,7 @@ func UpdateGist(t translations.TranslationHelperFunc) inventory.ServerTool {
 					},
 					"content": {
 						Type:        "string",
-						Description: "Content for the file",
+						Description: "Raw content for the gist file",
 					},
 				},
 				Required: []string{"gist_id", "filename", "content"},
diff --git a/pkg/github/issues.go b/pkg/github/issues.go
index 046978981..9b729b100 100644
--- a/pkg/github/issues.go
+++ b/pkg/github/issues.go
@@ -1164,7 +1164,7 @@ func AddIssueComment(t translations.TranslationHelperFunc) inventory.ServerTool
 					},
 					"body": {
 						Type:        "string",
-						Description: "Comment content",
+						Description: "Comment body; Markdown supported.",
 					},
 				},
 				Required: []string{"owner", "repo", "issue_number", "body"},
@@ -1247,6 +1247,11 @@ Options are:
 - 'remove' - remove a sub-issue from a parent issue in a GitHub repository.
 - 'reprioritize' - change the order of sub-issues within a parent issue in a GitHub repository. Use either 'after_id' or 'before_id' to specify the new position.
 				`,
+						Enum: []any{
+							"add",
+							"remove",
+							"reprioritize",
+						},
 					},
 					"owner": {
 						Type:        "string",
@@ -1461,7 +1466,7 @@ func SearchIssues(t translations.TranslationHelperFunc) inventory.ServerTool {
 		Properties: map[string]*jsonschema.Schema{
 			"query": {
 				Type:        "string",
-				Description: "Search query using GitHub issues search syntax",
+				Description: "Search query using GitHub issues search syntax. The tool adds is:issue and, when owner/repo are provided, repo:owner/repo; examples: \"crash label:bug\", \"author:octocat updated:>=2024-01-01\".",
 			},
 			"owner": {
 				Type:        "string",
@@ -1815,20 +1820,22 @@ Options are:
 					},
 					"body": {
 						Type:        "string",
-						Description: "Issue body content",
+						Description: "Issue body; Markdown supported.",
 					},
 					"assignees": {
 						Type:        "array",
 						Description: "Usernames to assign to this issue",
 						Items: &jsonschema.Schema{
-							Type: "string",
+							Type:        "string",
+							Description: "GitHub username",
 						},
 					},
 					"labels": {
 						Type:        "array",
 						Description: "Labels to apply to this issue",
 						Items: &jsonschema.Schema{
-							Type: "string",
+							Type:        "string",
+							Description: "Existing label name",
 						},
 					},
 					"milestone": {
@@ -2086,20 +2093,22 @@ Options are:
 					},
 					"body": {
 						Type:        "string",
-						Description: "Issue body content",
+						Description: "Issue body; Markdown supported.",
 					},
 					"assignees": {
 						Type:        "array",
 						Description: "Usernames to assign to this issue",
 						Items: &jsonschema.Schema{
-							Type: "string",
+							Type:        "string",
+							Description: "GitHub username",
 						},
 					},
 					"labels": {
 						Type:        "array",
 						Description: "Labels to apply to this issue",
 						Items: &jsonschema.Schema{
-							Type: "string",
+							Type:        "string",
+							Description: "Existing label name",
 						},
 					},
 					"milestone": {
@@ -2484,7 +2493,8 @@ func ListIssues(t translations.TranslationHelperFunc) inventory.ServerTool {
 				Type:        "array",
 				Description: "Filter by labels",
 				Items: &jsonschema.Schema{
-					Type: "string",
+					Type:        "string",
+					Description: "Label name",
 				},
 			},
 			"orderBy": {
diff --git a/pkg/github/issues_granular.go b/pkg/github/issues_granular.go
index 73fa75413..8905abb8d 100644
--- a/pkg/github/issues_granular.go
+++ b/pkg/github/issues_granular.go
@@ -137,7 +137,7 @@ func GranularCreateIssue(t translations.TranslationHelperFunc) inventory.ServerT
 					},
 					"body": {
 						Type:        "string",
-						Description: "Issue body content (optional)",
+						Description: "Issue body (optional); Markdown supported.",
 					},
 				},
 				Required: []string{"owner", "repo", "title"},
@@ -218,7 +218,7 @@ func GranularUpdateIssueBody(t translations.TranslationHelperFunc) inventory.Ser
 		"Update the body content of an existing issue.",
 		"Update Issue Body",
 		map[string]*jsonschema.Schema{
-			"body": {Type: "string", Description: "The new body content for the issue"},
+			"body": {Type: "string", Description: "Issue body; Markdown supported."},
 		},
 		[]string{"body"},
 		func(args map[string]any) (*github.IssueRequest, error) {
diff --git a/pkg/github/projects.go b/pkg/github/projects.go
index 53ce51051..58d23be61 100644
--- a/pkg/github/projects.go
+++ b/pkg/github/projects.go
@@ -186,7 +186,8 @@ Use this tool to list projects for a user or organization, or list project field
 						Type:        "array",
 						Description: "Field IDs to include when listing project items (e.g. [\"102589\", \"985201\"]). CRITICAL: Always provide to get field values. Without this, only titles returned. Only used for 'list_project_items' method.",
 						Items: &jsonschema.Schema{
-							Type: "string",
+							Type:        "string",
+							Description: "Project field ID to include in each item's field values, e.g. \"102589\".",
 						},
 					},
 					"per_page": {
@@ -314,7 +315,8 @@ Use this tool to get details about individual projects, project fields, and proj
 						Type:        "array",
 						Description: "Specific list of field IDs to include in the response when getting a project item (e.g. [\"102589\", \"985201\", \"169875\"]). If not provided, only the title field is included. Only used for 'get_project_item' method.",
 						Items: &jsonschema.Schema{
-							Type: "string",
+							Type:        "string",
+							Description: "Project field ID to include in the project item response, e.g. \"102589\".",
 						},
 					},
 					"status_update_id": {
diff --git a/pkg/github/pullrequests.go b/pkg/github/pullrequests.go
index 7f1751b97..dc52635c7 100644
--- a/pkg/github/pullrequests.go
+++ b/pkg/github/pullrequests.go
@@ -578,15 +578,15 @@ func CreatePullRequest(t translations.TranslationHelperFunc) inventory.ServerToo
 					},
 					"body": {
 						Type:        "string",
-						Description: "PR description",
+						Description: "PR description; Markdown supported",
 					},
 					"head": {
 						Type:        "string",
-						Description: "Branch containing changes",
+						Description: "Branch containing changes, or owner:branch for a fork",
 					},
 					"base": {
 						Type:        "string",
-						Description: "Branch to merge into",
+						Description: "Base branch name to merge into, e.g. main",
 					},
 					"draft": {
 						Type:        "boolean",
@@ -744,7 +744,7 @@ func UpdatePullRequest(t translations.TranslationHelperFunc) inventory.ServerToo
 			},
 			"base": {
 				Type:        "string",
-				Description: "New base branch name",
+				Description: "New base branch name, e.g. main.",
 			},
 			"maintainer_can_modify": {
 				Type:        "boolean",
@@ -754,7 +754,8 @@ func UpdatePullRequest(t translations.TranslationHelperFunc) inventory.ServerToo
 				Type:        "array",
 				Description: "GitHub usernames or ORG/team-slug team reviewers to request reviews from",
 				Items: &jsonschema.Schema{
-					Type: "string",
+					Type:        "string",
+					Description: "GitHub username or ORG/team-slug team",
 				},
 			},
 		},
@@ -1029,7 +1030,7 @@ func AddReplyToPullRequestComment(t translations.TranslationHelperFunc) inventor
 			},
 			"body": {
 				Type:        "string",
-				Description: "The text of the reply",
+				Description: "Reply body; Markdown supported",
 			},
 		},
 		Required: []string{"owner", "repo", "pullNumber", "commentId", "body"},
@@ -1117,11 +1118,11 @@ func ListPullRequests(t translations.TranslationHelperFunc) inventory.ServerTool
 			},
 			"head": {
 				Type:        "string",
-				Description: "Filter by head user/org and branch",
+				Description: "Filter by head user/org and branch, in user:branch format.",
 			},
 			"base": {
 				Type:        "string",
-				Description: "Filter by base branch",
+				Description: "Filter by base branch name.",
 			},
 			"sort": {
 				Type:        "string",
@@ -1363,7 +1364,7 @@ func SearchPullRequests(t translations.TranslationHelperFunc) inventory.ServerTo
 		Properties: map[string]*jsonschema.Schema{
 			"query": {
 				Type:        "string",
-				Description: "Search query using GitHub pull request search syntax",
+				Description: "Search query using GitHub pull request search syntax. Qualifiers such as is:pr and repo:owner/repo are applied automatically when appropriate; examples: \"review-requested:@me\", \"author:octocat updated:>=2024-01-01\".",
 			},
 			"owner": {
 				Type:        "string",
@@ -2041,7 +2042,7 @@ func AddCommentToPendingReview(t translations.TranslationHelperFunc) inventory.S
 			},
 			"body": {
 				Type:        "string",
-				Description: "The text of the review comment",
+				Description: "Review comment body; Markdown supported",
 			},
 			"subjectType": {
 				Type:        "string",
diff --git a/pkg/github/pullrequests_granular.go b/pkg/github/pullrequests_granular.go
index 6bc2b99f3..c1703d4f6 100644
--- a/pkg/github/pullrequests_granular.go
+++ b/pkg/github/pullrequests_granular.go
@@ -298,7 +298,7 @@ func GranularRequestPullRequestReviewers(t translations.TranslationHelperFunc) i
 					"reviewers": {
 						Type:        "array",
 						Description: "GitHub usernames or ORG/team-slug team reviewers to request reviews from",
-						Items:       &jsonschema.Schema{Type: "string"},
+						Items:       &jsonschema.Schema{Type: "string", Description: "GitHub username or ORG/team-slug team"},
 					},
 				},
 				Required: []string{"owner", "repo", "pullNumber", "reviewers"},
@@ -390,7 +390,7 @@ func GranularCreatePullRequestReview(t translations.TranslationHelperFunc) inven
 					"owner":      {Type: "string", Description: "Repository owner (username or organization)"},
 					"repo":       {Type: "string", Description: "Repository name"},
 					"pullNumber": {Type: "number", Description: "The pull request number", Minimum: jsonschema.Ptr(1.0)},
-					"body":       {Type: "string", Description: "The review body text (optional)"},
+					"body":       {Type: "string", Description: "Review body (optional); Markdown supported"},
 					"event":      {Type: "string", Description: "The review action to perform. If omitted, creates a pending review.", Enum: []any{"APPROVE", "REQUEST_CHANGES", "COMMENT"}},
 					"commitID":   {Type: "string", Description: "The SHA of the commit to review (optional, defaults to latest)"},
 				},
@@ -460,7 +460,7 @@ func GranularSubmitPendingPullRequestReview(t translations.TranslationHelperFunc
 					"repo":       {Type: "string", Description: "Repository name"},
 					"pullNumber": {Type: "number", Description: "The pull request number", Minimum: jsonschema.Ptr(1.0)},
 					"event":      {Type: "string", Description: "The review action to perform", Enum: []any{"APPROVE", "REQUEST_CHANGES", "COMMENT"}},
-					"body":       {Type: "string", Description: "The review body text (optional)"},
+					"body":       {Type: "string", Description: "Review body; Markdown supported"},
 				},
 				Required: []string{"owner", "repo", "pullNumber", "event"},
 			},
@@ -579,7 +579,7 @@ func GranularAddPullRequestReviewComment(t translations.TranslationHelperFunc) i
 					"repo":        {Type: "string", Description: "Repository name"},
 					"pullNumber":  {Type: "number", Description: "The pull request number", Minimum: jsonschema.Ptr(1.0)},
 					"path":        {Type: "string", Description: "The relative path of the file to comment on"},
-					"body":        {Type: "string", Description: "The comment body"},
+					"body":        {Type: "string", Description: "Review comment body; Markdown supported"},
 					"subjectType": {Type: "string", Description: "The subject type of the comment", Enum: []any{"FILE", "LINE"}},
 					"line":        {Type: "number", Description: "The line number in the diff to comment on (optional)"},
 					"side":        {Type: "string", Description: "The side of the diff to comment on (optional)", Enum: []any{"LEFT", "RIGHT"}},
diff --git a/pkg/github/repositories.go b/pkg/github/repositories.go
index d682b5c3d..0ae15a283 100644
--- a/pkg/github/repositories.go
+++ b/pkg/github/repositories.go
@@ -383,19 +383,19 @@ SHA MUST be provided for existing file updates.
 					},
 					"path": {
 						Type:        "string",
-						Description: "Path where to create/update the file",
+						Description: "Repository-relative file path to create or update",
 					},
 					"content": {
 						Type:        "string",
-						Description: "Content of the file",
+						Description: "Raw file content",
 					},
 					"message": {
 						Type:        "string",
-						Description: "Commit message",
+						Description: "Commit message for this change",
 					},
 					"branch": {
 						Type:        "string",
-						Description: "Branch to create/update the file in",
+						Description: "Branch name to create/update the file in",
 					},
 					"sha": {
 						Type:        "string",
@@ -692,7 +692,7 @@ func GetFileContents(t translations.TranslationHelperFunc) inventory.ServerTool
 					},
 					"path": {
 						Type:        "string",
-						Description: "Path to file/directory",
+						Description: "Repository-relative file or directory path",
 						Default:     json.RawMessage(`"/"`),
 					},
 					"ref": {
@@ -1015,15 +1015,15 @@ func DeleteFile(t translations.TranslationHelperFunc) inventory.ServerTool {
 					},
 					"path": {
 						Type:        "string",
-						Description: "Path to the file to delete",
+						Description: "Repository-relative path to the file to delete",
 					},
 					"message": {
 						Type:        "string",
-						Description: "Commit message",
+						Description: "Commit message for the delete commit",
 					},
 					"branch": {
 						Type:        "string",
-						Description: "Branch to delete the file from",
+						Description: "Branch name to delete the file from",
 					},
 				},
 				Required: []string{"owner", "repo", "path", "message", "branch"},
@@ -1199,11 +1199,11 @@ func CreateBranch(t translations.TranslationHelperFunc) inventory.ServerTool {
 					},
 					"branch": {
 						Type:        "string",
-						Description: "Name for new branch",
+						Description: "New branch name, without refs/heads/",
 					},
 					"from_branch": {
 						Type:        "string",
-						Description: "Source branch (defaults to repo default)",
+						Description: "Source branch name; defaults to the repository default branch",
 					},
 				},
 				Required: []string{"owner", "repo", "branch"},
@@ -1312,7 +1312,7 @@ func PushFiles(t translations.TranslationHelperFunc) inventory.ServerTool {
 					},
 					"branch": {
 						Type:        "string",
-						Description: "Branch to push to",
+						Description: "Branch name to push the commit to",
 					},
 					"files": {
 						Type:        "array",
@@ -1323,11 +1323,11 @@ func PushFiles(t translations.TranslationHelperFunc) inventory.ServerTool {
 							Properties: map[string]*jsonschema.Schema{
 								"path": {
 									Type:        "string",
-									Description: "path to the file",
+									Description: "Repository-relative file path",
 								},
 								"content": {
 									Type:        "string",
-									Description: "file content",
+									Description: "Raw file content",
 								},
 							},
 							Required: []string{"path", "content"},
diff --git a/pkg/github/search.go b/pkg/github/search.go
index 9a8d18288..c46391e7a 100644
--- a/pkg/github/search.go
+++ b/pkg/github/search.go
@@ -204,7 +204,8 @@ func SearchCode(t translations.TranslationHelperFunc) inventory.ServerTool {
 			},
 			"sort": {
 				Type:        "string",
-				Description: "Sort field ('indexed' only)",
+				Description: "Sort field. Use 'indexed' to sort by recently indexed files.",
+				Enum:        []any{"indexed"},
 			},
 			"order": {
 				Type:        "string",