Loading ToolBench
An MCP server for managing GitHub issues, sub-issues, and milestones via the GitHub API
This server demonstrates solid fundamentals with all 7 tools properly registered and documented. Naming follows verb_noun conventions consistently (get_, list_, add_, remove_, set_). Descriptions are present and adequate (100-200 chars on average), explaining WHAT each tool does and WHEN to use it. Input schemas use Zod and include parameter descriptions. However, several medium-severity gaps reduce quality: (1) Output schemas are NOT documented, responses are plain text summaries without structured field definitions, making it hard for LLMs to chain results; (2) Error handling is basic, errors return text strings but lack recovery guidance or categorization; (3) No input validation guidance in descriptions for constrained values (e.g., per_page max of 100 is documented but not validated against); (4) Some parameter descriptions are terse and lack format/constraint hints. The batch tools (add_sub_issues, remove_sub_issues, set_milestone_for_issues) show partial success/failure handling, which is good, but responses mix success and error text without structured separation. Idempotency is not declared on any tool. The get_* and list_* tools are read-only and safe, but add_*, remove_*, set_* are mutating without explicit confirmation patterns or dry-run support.
Add multiple sub-issues to a GitHub issue using GitHub Sub-Issues API. Supports batch processing for efficiency.
Get the internal GitHub issue ID from an issue number
Get the internal GitHub issue IDs from multiple issue numbers. Supports batch processing for efficiency.
Get the parent issue of a sub-issue using GitHub Sub-Issues API
List sub-issues for a GitHub issue with pagination and filtering support
Remove multiple sub-issues from a GitHub issue using GitHub Sub-Issues API. Supports batch processing for efficiency.
No output schema documentation for any tool. LLMs cannot predict response structure. Responses are free-text summaries without typed fields, making downstream chaining impossible. Example: list_sub_issues returns plain text, but an agent would need structured data (sub-issue IDs, titles, states) to act on results.
No dry-run or confirmation pattern on destructive operations (add_sub_issues, remove_sub_issues). Agents can accidentally delete relationships without approval. Recommendation: add optional 'dry_run' parameter or split into separate tools (e.g., plan_sub_issue_removal + confirm_removal).
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | A | 81 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 8 | - | v1 |
Set milestone for multiple GitHub issues. Supports batch processing for efficiency.
Error handling is weak. Errors are returned as plain text strings without categorization (retryable vs permanent) or recovery guidance. Example: 'GitHub API error: 401 Unauthorized' tells the agent nothing, is this a token issue? A permission issue? Should it retry? Recommendation: return structured errors with explicit guidance like 'Invalid token. Verify X-GITHUB-TOKEN header.' or 'Permission denied. User must have admin:org_hook scope.'
No idempotency declaration. Tools that mutate state (add_sub_issues, remove_sub_issues) should declare whether they are idempotent. Agents retry on ambiguous failures, non-idempotent operations risk duplicate effects (adding the same sub-issue twice). Recommendation: document idempotency in tool descriptions or add optional idempotency_key parameter.
Parameter descriptions lack explicit format/constraint documentation for free-form values. Example: 'labels' parameter in list_sub_issues says 'Comma-separated list of label names' but does not specify: Are spaces allowed? Are label names case-sensitive? Can special chars be used? Recommendation: add explicit format hints or regex patterns to descriptions.
No rate-limiting or timeout guidance in tool descriptions. Batch operations (add_sub_issues, remove_sub_issues) can cause runaway requests if an agent retries in a loop. Recommendation: document rate limits (e.g., 'GitHub API allows 5,000 requests/hour') and suggest max batch sizes.
GitHub token passed as header (X-GITHUB-TOKEN) rather than environment variable. While headers are acceptable, the server accepts optional githubToken in every tool call and does not enforce token presence. Unauthenticated calls to GitHub API will fail silently. Recommendation: either require token at startup (environment variable) or add explicit token validation in each tool with clear error messaging.
No pagination chaining support. list_sub_issues returns a text summary with result count, but does not include a 'next_cursor' or 'has_more' field. If results span pages, the agent must infer pagination by incrementing page numbers, error-prone and wasteful. Recommendation: return structured pagination metadata (total_count, page, per_page, has_next_page).