[mcp-analysis] MCP Structural Analysis - 2026-02-03

[github-actions[bot]]

This analysis evaluates GitHub MCP tools for response size and structural usefulness for autonomous agents. Testing was performed on 2026-02-03 with 15 representative tools across multiple toolsets.

Key Findings

Most Agent-Friendly Tools (Rating 5/5):

• get_file_contents, list_branches, get_commit, list_tags, search_repositories - These tools return clean, minimal responses with excellent signal-to-noise ratio.

Biggest Concern:

• list_code_scanning_alerts returns 95,000 tokens for a single call, exceeding response limits. This tool needs pagination or filtering to be practical for agents.

Context Budget Winners:

• list_branches (150 tokens), list_tags (200 tokens), get_commit (380 tokens) - Ultra-efficient responses.

Average Usefulness Rating: 3.9/5 across all valid tools

---

Full Structural Analysis Report

Executive Summary

Metric	Value
Tools Analyzed	15
Valid Responses	13
Errors Encountered	2
Total Tokens (All Tools)	121,530
Average Tokens (Valid)	9,348
Average Usefulness Rating	3.9/5
Best Rated Tools	get_file_contents, list_branches, get_commit, list_tags, search_repositories (5/5)
Worst Rated Tools	get_me (1/5), list_projects (2/5), list_code_scanning_alerts (2/5)

Usefulness Ratings for Agentic Work

Tool	Toolset	Rating	Assessment
get_file_contents	repos	⭐⭐⭐⭐⭐	Returns file content directly with SHA - perfect for agents to read files
list_branches	repos	⭐⭐⭐⭐⭐	Extremely concise and useful. Just the essentials
get_commit	repos	⭐⭐⭐⭐⭐	With include_diff=false, returns clean commit metadata without bloat
list_tags	repos	⭐⭐⭐⭐⭐	Minimal and perfect. Just tag name and commit SHA
search_repositories	search	⭐⭐⭐⭐⭐	Minimal output mode works perfectly. Compact, actionable data
list_issues	issues	⭐⭐⭐⭐	GraphQL-style response with pagination. Rich issue data, well-structured
list_workflows	actions	⭐⭐⭐⭐	Clean workflow list with essential fields. Good pagination support
list_discussions	discussions	⭐⭐⭐⭐	GraphQL-style response, concise and well-structured
list_label	labels	⭐⭐⭐⭐	Returns all labels with metadata. Comprehensive but can be verbose
list_commits	repos	⭐⭐⭐⭐	Well-structured commit list with metadata. Good balance
list_pull_requests	pull_requests	⭐⭐⭐	Very verbose with deep nesting. Contains useful data but bloated
list_releases	releases	⭐⭐⭐	Very verbose with full asset details. Useful but context-heavy
list_code_scanning_alerts	code_security	⭐⭐	EXTREMELY verbose (95K tokens). Response exceeded limits. Inefficient
list_projects	projects	⭐⭐	Error - permissions issue. Projects API may need different context
get_me	user	⭐	403 error - integration token not permitted for user endpoint

Schema Analysis

Tool	Type	Depth	Key Fields	Notes
get_file_contents	string	1	content, sha	Direct content return
list_issues	object	3	issues, pageInfo, totalCount	GraphQL pagination
list_pull_requests	array	4	id, number, state, title, user, head, base	Nested repo objects
list_workflows	object	2	total_count, workflows	Clean REST response
list_code_scanning_alerts	array	4	number, state, rule, tool	Deep nesting, verbose
list_discussions	object	3	discussions, pageInfo, totalCount	GraphQL pagination
list_label	object	2	labels, totalCount	Flat structure
search_repositories	object	2	total_count, items	Minimal mode
list_branches	array	1	name, sha, protected	Flat array
list_commits	array	3	sha, commit, author, committer	Moderate nesting
get_commit	object	3	sha, commit, author, committer	Moderate nesting
list_releases	array	4	tag_name, name, body, assets	Deep nesting
list_tags	array	2	name, commit	Flat structure

Response Size Analysis

Toolset	Avg Tokens	Tools Tested	Efficiency
code_security	95,000	1	🔴 Critical - needs optimization
releases	12,000	1	🟡 High - consider filtering
pull_requests	4,200	1	🟡 Moderate-High
labels	3,500	1	🟡 Moderate
actions	2,300	1	🟢 Good
repos	556	4	🟢 Excellent (avg across 4 tools)
issues	900	1	🟢 Good
discussions	450	1	🟢 Excellent
search	400	1	🟢 Excellent

Tool-by-Tool Detailed Analysis

Tool	Toolset	Tokens	Schema	Depth	Rating	Notes
list_code_scanning_alerts	code_security	95,000	array	4	2	Response exceeded limits. Needs filtering or pagination
list_releases	releases	12,000	array	4	3	Full asset details inflate response. Body text can be long
list_pull_requests	pull_requests	4,200	array	4	3	Includes full repo objects for head/base. Redundant data
list_label	labels	3,500	object	2	4	All labels with metadata. Scales poorly for large repos
list_workflows	actions	2,300	object	2	4	Clean structure with good pagination
get_file_contents	repos	1,500	string	1	5	Direct content with SHA. Perfect for agents
list_issues	issues	900	object	3	4	GraphQL-style with rich data. Well-balanced
list_commits	repos	550	array	3	4	Good balance of metadata and info
list_discussions	discussions	450	object	3	4	Concise GraphQL response
search_repositories	search	400	object	2	5	Minimal mode is excellent
get_commit	repos	380	object	3	5	With diff disabled, very clean
list_tags	repos	200	array	2	5	Minimal, perfect response
list_branches	repos	150	array	1	5	Ultra-efficient

Recommendations

High-Value Tools for Agents (Rating 4-5, Low Tokens):

• ✅ get_file_contents - Best for reading repository files
• ✅ list_branches - Ideal for branch discovery
• ✅ get_commit - Perfect for commit metadata (use include_diff=false)
• ✅ list_tags - Efficient tag enumeration
• ✅ search_repositories - Excellent with minimal_output=true
• ✅ list_commits - Good balance for commit history
• ✅ list_issues - Well-structured issue queries
• ✅ list_workflows - Clean workflow enumeration
• ✅ list_discussions - Efficient discussion queries

Tools Needing Improvement:

• 🔴 list_code_scanning_alerts - 95K tokens is unusable. Needs aggressive filtering or pagination
• 🟡 list_releases - Consider limiting asset details or body text length
• 🟡 list_pull_requests - Too verbose. Could benefit from minimal mode like repos search

Context-Efficient Tools (Low tokens, high rating):

• 🏆 list_branches (150 tokens, 5/5)
• 🏆 list_tags (200 tokens, 5/5)
• 🏆 get_commit (380 tokens, 5/5)
• 🏆 search_repositories (400 tokens, 5/5)

Context-Heavy Tools (High tokens):

• ⚠️ list_code_scanning_alerts (95,000 tokens)
• ⚠️ list_releases (12,000 tokens)
• ⚠️ list_pull_requests (4,200 tokens)

API Improvements Needed:

1. Add filtering to list_code_scanning_alerts (state, severity filters don't reduce enough)
2. Consider minimal_output mode for list_pull_requests and list_releases
3. Fix permissions for get_me with integration tokens
4. Clarify list_projects authentication requirements

Architectural Patterns Observed

GraphQL-Style Responses (Efficient):

• list_issues, list_discussions
• Consistent pagination with pageInfo and cursors
• Good balance of data and structure

REST Responses (Variable):

• Some are efficient (list_branches, list_tags)
• Others are verbose (list_pull_requests, list_releases)
• Deeply nested objects increase token count

Best Practices for Agents:

1. Use minimal parameters (perPage=1 for discovery)
2. Enable minimal_output modes when available
3. Disable diffs/content when metadata is sufficient
4. Prefer tools with flat structures (depth 1-2)
5. Avoid tools exceeding 5K tokens without filtering

Visualizations

Response Size by Toolset

Red bars indicate toolsets with high token usage (>10K). Orange indicates moderate usage (2-10K). Green indicates efficient usage (<2K).

Usefulness Ratings by Toolset

Green bars indicate excellent usefulness (≥4/5). Orange indicates adequate (≥3/5). Red indicates poor usefulness (<3/5).

Tool-by-Tool Ratings

Horizontal view of all tools ranked by usefulness rating.

Token Size vs Usefulness

Ideal tools are in the bottom-left (low tokens, high rating). Tools in the bottom-right (high tokens, low rating) need optimization.

---

Methodology

This analysis tested representative tools from each GitHub MCP toolset with minimal parameters to evaluate:

• Response Size: Measured in tokens (1 token ≈ 4 characters)
• Structure: Data type, nesting depth, key fields
• Usefulness: Rating 1-5 for autonomous agent suitability

Rating Criteria:

• 5: Complete, actionable data with clear structure
• 4: Most needed data present, minor gaps
• 3: Usable but requires additional calls
• 2: Missing key data, hard to parse
• 1: Minimal value for agentic tasks

Data Persistence: Results are stored in /tmp/gh-aw/cache-memory/mcp_analysis.jsonl for 30-day trending analysis.

References:

• §21627963817

AI generated by GitHub MCP Structural Analysis

• expires on Feb 10, 2026, 11:18 AM UTC