diff --git a/.github/instructions/github-mcp-server.instructions.md b/.github/instructions/github-mcp-server.instructions.md
index cf6271ccd41..4433cf49933 100644
--- a/.github/instructions/github-mcp-server.instructions.md
+++ b/.github/instructions/github-mcp-server.instructions.md
@@ -70,17 +70,116 @@ tools:
 
 The GitHub MCP server organizes tools into logical toolsets. You can enable specific toolsets, use `[default]` for the recommended defaults, or use `[all]` to enable everything.
 
+:::tip[Best Practice]
+**Always prefer using `toolset:` over listing individual tools with `allowed:`**. Toolsets provide:
+- Better organization and discoverability
+- Complete functionality for each area
+- Reduced configuration verbosity
+- Automatic inclusion of new tools as they're added
+:::
+
 ### Recommended Default Toolsets
 
-[To be filled by workflow with analysis and recommendations]
+The following toolsets are enabled by default when `toolset:` is not specified:
+- `context` - User and environment context (strongly recommended)
+- `repos` - Repository management
+- `issues` - Issue management  
+- `pull_requests` - Pull request operations
+- `users` - User profiles
 
 ### All Available Toolsets
 
-[To be filled by workflow with complete toolset descriptions]
+| Toolset | Description | Common Tools |
+|---------|-------------|--------------|
+| `context` | User and environment context | `get_me`, `get_teams`, `get_team_members` |
+| `repos` | Repository management | `get_repository`, `get_file_contents`, `search_code`, `list_commits` |
+| `issues` | Issue management | `issue_read`, `list_issues`, `create_issue`, `search_issues` |
+| `pull_requests` | Pull request operations | `pull_request_read`, `list_pull_requests`, `create_pull_request` |
+| `actions` | GitHub Actions/CI/CD | `list_workflows`, `list_workflow_runs`, `download_workflow_run_artifact` |
+| `code_security` | Code scanning and security | `list_code_scanning_alerts`, `get_code_scanning_alert` |
+| `dependabot` | Dependency management | Dependabot alerts and updates |
+| `discussions` | GitHub Discussions | `list_discussions`, `create_discussion` |
+| `experiments` | Experimental features | Unstable/preview APIs |
+| `gists` | Gist operations | `create_gist`, `list_gists` |
+| `labels` | Label management | `get_label`, `list_labels`, `create_label` |
+| `notifications` | Notifications | `list_notifications`, `mark_notifications_read` |
+| `orgs` | Organization management | `get_organization`, `list_organizations` |
+| `projects` | GitHub Projects | Project board operations |
+| `secret_protection` | Secret scanning | Secret detection and management |
+| `security_advisories` | Security advisories | Advisory creation and management |
+| `stargazers` | Repository stars | Star-related operations |
+| `users` | User profiles | `get_user`, `list_users` |
+| `search` | Advanced search | Search across repos, code, users |
 
 ## Available Tools by Toolset
 
-[To be filled by workflow with comprehensive tool listings]
+This section maps individual tools to their respective toolsets to help with migration from `allowed:` to `toolset:`.
+
+### Context Toolset
+- `get_me` - Get current user information
+- `get_teams` - List teams the user belongs to
+- `get_team_members` - List members of a specific team
+
+### Repos Toolset
+- `get_repository` - Get repository information
+- `get_file_contents` - Read file contents from repository
+- `search_code` - Search code across repositories
+- `list_commits` - List commits in a repository
+- `get_commit` - Get details of a specific commit
+- `get_latest_release` - Get the latest release
+- `list_releases` - List all releases
+
+### Issues Toolset
+- `issue_read` - Read issue details
+- `list_issues` - List issues in a repository
+- `create_issue` - Create a new issue
+- `update_issue` - Update an existing issue
+- `search_issues` - Search issues across repositories
+- `add_reaction` - Add reaction to an issue or comment
+- `create_issue_comment` - Add a comment to an issue
+
+### Pull Requests Toolset
+- `pull_request_read` - Read pull request details
+- `list_pull_requests` - List pull requests in a repository
+- `get_pull_request` - Get details of a specific pull request
+- `create_pull_request` - Create a new pull request
+- `search_pull_requests` - Search pull requests across repositories
+
+### Actions Toolset
+- `list_workflows` - List GitHub Actions workflows
+- `list_workflow_runs` - List workflow runs
+- `get_workflow_run` - Get details of a specific workflow run
+- `download_workflow_run_artifact` - Download workflow artifacts
+
+### Code Security Toolset
+- `list_code_scanning_alerts` - List code scanning alerts
+- `get_code_scanning_alert` - Get details of a specific alert
+- `create_code_scanning_alert` - Create a code scanning alert
+
+### Discussions Toolset
+- `list_discussions` - List discussions in a repository
+- `create_discussion` - Create a new discussion
+
+### Labels Toolset
+- `get_label` - Get label details
+- `list_labels` - List labels in a repository
+- `create_label` - Create a new label
+
+### Users Toolset
+- `get_user` - Get user profile information
+- `list_users` - List users
+
+### Notifications Toolset
+- `list_notifications` - List user notifications
+- `mark_notifications_read` - Mark notifications as read
+
+### Organizations Toolset
+- `get_organization` - Get organization details
+- `list_organizations` - List organizations
+
+### Gists Toolset
+- `create_gist` - Create a new gist
+- `list_gists` - List user's gists
 
 ## Authentication Details
 
@@ -139,7 +238,25 @@ Ensure your GitHub token has appropriate permissions for the toolsets you're ena
 
 ## Troubleshooting
 
-[To be filled by workflow with common issues and solutions]
+### Common Issues
+
+**Issue**: Tool not found or not available
+- **Solution**: Check if you're using `allowed:` to restrict tools. Consider using `toolset:` instead to get all related tools.
+- **Verify**: Run `gh aw mcp inspect <workflow-name>` to see which tools are actually available.
+
+**Issue**: Missing functionality after specifying toolset
+- **Cause**: Using a too-narrow toolset that doesn't include all needed tools
+- **Solution**: Either add additional toolsets (e.g., `toolset: [default, actions]`) or use `[all]` for full access
+
+**Issue**: Workflow using `allowed:` list is verbose and hard to maintain
+- **Solution**: Migrate to `toolset:` configuration using the migration guide above
+
+### Best Practices for Debugging
+
+1. **Start with `[default]` toolset**: Most workflows work well with default toolsets
+2. **Add specific toolsets as needed**: Incrementally add toolsets like `actions`, `discussions`, etc.
+3. **Use `gh aw mcp inspect`**: Verify which tools are actually available
+4. **Check tool-to-toolset mapping**: Reference the tables above to find the right toolset
 
 ## References
 
diff --git a/docs/src/content/docs/guides/mcps.md b/docs/src/content/docs/guides/mcps.md
index 26ca609c967..346504bd832 100644
--- a/docs/src/content/docs/guides/mcps.md
+++ b/docs/src/content/docs/guides/mcps.md
@@ -227,12 +227,17 @@ mcp-servers:
 
 GitHub Agentic Workflows includes built-in GitHub MCP integration with comprehensive repository access. See [Tools](/gh-aw/reference/tools/) for details.
 
+:::tip[Use Toolsets for GitHub Tools]
+Prefer using `toolset:` instead of `allowed:` for GitHub tools. Toolsets provide better organization and ensure complete functionality. See the [GitHub Toolsets](/gh-aw/reference/tools/#github-toolsets) section for details.
+:::
+
 Configure the Docker image version (default: `"sha-09deac4"`):
 
 ```yaml
 tools:
   github:
     version: "sha-09deac4"
+    toolset: [default, actions]  # Recommended: use toolsets
 ```
 
 ### GitHub Authentication
diff --git a/docs/src/content/docs/guides/packaging-imports.md b/docs/src/content/docs/guides/packaging-imports.md
index 8bab000e709..b22ea8f86d6 100644
--- a/docs/src/content/docs/guides/packaging-imports.md
+++ b/docs/src/content/docs/guides/packaging-imports.md
@@ -70,7 +70,7 @@ imports:
   - shared/mcp/tavily.md
 tools:
   github:
-    allowed: [add_issue_comment]
+    toolset: [issues]
 ---
 
 # Research Agent
diff --git a/docs/src/content/docs/reference/command-triggers.md b/docs/src/content/docs/reference/command-triggers.md
index 3ebc36441f4..de8deed8558 100644
--- a/docs/src/content/docs/reference/command-triggers.md
+++ b/docs/src/content/docs/reference/command-triggers.md
@@ -65,7 +65,7 @@ permissions:
   issues: write
 tools:
   github:
-    allowed: [add_issue_comment]
+    toolset: [issues]
 ---
 
 # Issue Summarizer
diff --git a/docs/src/content/docs/reference/frontmatter-full.md b/docs/src/content/docs/reference/frontmatter-full.md
index e139e5f49c1..1e1da8bc9ac 100644
--- a/docs/src/content/docs/reference/frontmatter-full.md
+++ b/docs/src/content/docs/reference/frontmatter-full.md
@@ -985,7 +985,11 @@ tools:
     github-token: "${{ secrets.GITHUB_TOKEN }}"
 
     # Array of GitHub MCP server toolset names to enable specific groups of GitHub API
-    # functionalities
+    # functionalities. Prefer using toolset over listing individual tools with 'allowed'.
+    # Available toolsets: context, repos, issues, pull_requests, actions, code_security,
+    # dependabot, discussions, experiments, gists, labels, notifications, orgs, projects,
+    # secret_protection, security_advisories, stargazers, users, search
+    # Use [default] for recommended toolsets or [all] for everything.
     # (optional)
     toolset: []
       # Array of Toolset name
diff --git a/docs/src/content/docs/reference/tools.md b/docs/src/content/docs/reference/tools.md
index b85d532340e..4b3a2fe7958 100644
--- a/docs/src/content/docs/reference/tools.md
+++ b/docs/src/content/docs/reference/tools.md
@@ -101,6 +101,10 @@ tools:
 
 ### GitHub Toolsets
 
+:::tip[Prefer Toolsets Over Individual Tools]
+Use `toolset:` to enable groups of related tools instead of listing individual tools with `allowed:`. Toolsets provide better organization, reduce configuration verbosity, and ensure you get all related functionality.
+:::
+
 Enables or disables specific GitHub API groups to improve tool selection and reduce context size.
 
 ```yaml
@@ -109,9 +113,72 @@ tools:
     toolset: [repos, issues, pull_requests, actions]
 ```
 
-**Available Toolsets**: `context` (recommended), `actions`, `code_security`, `dependabot`, `discussions`, `experiments`, `gists`, `issues`, `labels`, `notifications`, `orgs`, `projects`, `pull_requests`, `repos`, `secret_protection`, `security_advisories`, `stargazers`, `users`
+**Available Toolsets**: `context` (recommended), `actions`, `code_security`, `dependabot`, `discussions`, `experiments`, `gists`, `issues`, `labels`, `notifications`, `orgs`, `projects`, `pull_requests`, `repos`, `secret_protection`, `security_advisories`, `stargazers`, `users`, `search`
+
+**Default Toolsets** (when `toolset:` is not specified): `context`, `repos`, `issues`, `pull_requests`, `users`
+
+**Recommended Combinations**:
+- **Read-only workflows**: `toolset: [default]` or `toolset: [context, repos]`
+- **Issue/PR/Discussion management**: `toolset: [default, discussions]` 
+- **CI/CD workflows**: `toolset: [default, actions]`
+- **Security workflows**: `toolset: [default, code_security, secret_protection]`
+- **Full access**: `toolset: [all]`
+
+#### Tool-to-Toolset Mapping
+
+When migrating from `allowed:` to `toolset:`, use this mapping to identify the correct toolset for your tools:
+
+| Tool Name | Toolset | Description |
+|-----------|---------|-------------|
+| `get_me`, `get_teams`, `get_team_members` | `context` | User and environment context |
+| `get_repository`, `get_file_contents`, `search_code`, `list_commits`, `get_commit` | `repos` | Repository operations |
+| `issue_read`, `list_issues`, `create_issue`, `update_issue`, `search_issues`, `add_reaction` | `issues` | Issue management |
+| `pull_request_read`, `list_pull_requests`, `get_pull_request`, `create_pull_request`, `search_pull_requests` | `pull_requests` | Pull request operations |
+| `list_workflows`, `list_workflow_runs`, `get_workflow_run`, `download_workflow_run_artifact` | `actions` | GitHub Actions/CI/CD |
+| `list_code_scanning_alerts`, `get_code_scanning_alert`, `create_code_scanning_alert` | `code_security` | Code security scanning |
+| `list_discussions`, `create_discussion` | `discussions` | GitHub Discussions |
+| `get_label`, `list_labels`, `create_label` | `labels` | Label management |
+| `list_notifications`, `mark_notifications_read` | `notifications` | Notifications |
+| `get_user`, `list_users` | `users` | User profiles |
+| `get_organization`, `list_organizations` | `orgs` | Organization management |
+| `create_gist`, `list_gists` | `gists` | Gist operations |
+| `get_latest_release`, `list_releases` | `repos` | Release management (part of repos) |
+| `create_issue_comment` | `issues` | Issue comments (part of issues) |
+
+**Example Migration**:
+
+Before (using `allowed:`):
+```yaml
+tools:
+  github:
+    allowed:
+      - list_pull_requests
+      - get_pull_request
+      - pull_request_read
+      - list_commits
+      - get_commit
+      - get_file_contents
+```
+
+After (using `toolset:`):
+```yaml
+tools:
+  github:
+    toolset: [default]  # Includes repos and pull_requests
+```
+
+Or for more specific control:
+```yaml
+tools:
+  github:
+    toolset: [repos, pull_requests]
+```
+
+:::note
+Both `toolset:` and `allowed:` can be used together. When specified, `allowed:` further restricts which tools are available within the enabled toolsets.
+:::
 
-Default: `toolset: [all]` enables all toolsets. Currently supported in local (Docker) mode only.
+**Supported Modes**: Toolsets are supported in both local (Docker) and remote (hosted) modes.
 
 ### GitHub Remote Mode
 
diff --git a/docs/src/content/docs/reference/triggers.md b/docs/src/content/docs/reference/triggers.md
index 2cab9e48e04..95339b512e3 100644
--- a/docs/src/content/docs/reference/triggers.md
+++ b/docs/src/content/docs/reference/triggers.md
@@ -109,7 +109,7 @@ permissions:
 engine: claude
 tools:
   github:
-    allowed: [add_pull_request_review_comment]
+    toolset: [pull_requests]
 safe-outputs:
   add-comment:
     max: 5
diff --git a/docs/src/content/docs/reference/workflow-structure.md b/docs/src/content/docs/reference/workflow-structure.md
index 5a9ccbad0da..0ba50455364 100644
--- a/docs/src/content/docs/reference/workflow-structure.md
+++ b/docs/src/content/docs/reference/workflow-structure.md
@@ -27,7 +27,7 @@ permissions:
 
 tools:
   github:
-    allowed: [add_issue_comment]
+    toolset: [issues]
 ---
 
 # Workflow Description