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

[github-actions[bot]]

Analyzed 13 GitHub MCP tools across 11 toolsets. Overall usefulness rating: 4.46/5 with 9 tools rated excellent (5/5). Most efficient tool: get_label (38 tokens, rating 5). Context-heavy tools: list_pull_requests (3,650 tokens), list_releases (3,200 tokens), and list_code_scanning_alerts (2,800 tokens).

Full Structural Analysis Report

Executive Summary

Metric	Value
Tools Analyzed	13
Total Tokens (Today)	13,346
Average Usefulness Rating	4.46/5
Best Rated Tools	9 tools with 5/5 rating
Worst Rated Tool	get_me: 1/5 (403 error)
Most Efficient Tool	get_label: 38 tokens, 5/5 rating
Most Context-Heavy	list_pull_requests: 3,650 tokens

Usefulness Ratings for Agentic Work

⭐⭐⭐⭐⭐ Excellent (Rating 5) - 9 tools

These tools provide complete, immediately actionable data with clean structure:

Tool	Toolset	Tokens	Notes
get_file_contents	repos	1,580	MCP resource format, clean structure, immediate file access
list_workflows	actions	305	Compact, essential fields, ideal balance
list_issues	issues	920	Comprehensive with pagination, all context included
get_label	labels	38	Minimal, no bloat, perfect efficiency
list_discussions	discussions	275	Clean with pagination, category embedded
list_tags	repos	95	Simple structure with commit reference
list_branches	repos	68	Minimal, essential data only
search_repositories	search	180	Efficient with minimal_output=true
get_commit	repos	210	Clean without diff (include_diff=false)

⭐⭐⭐⭐ Good (Rating 4) - 3 tools

Rich data but verbose, requiring supplementary calls or filtering:

Tool	Toolset	Tokens	Notes
list_code_scanning_alerts	code_security	2,800	Detailed security data, nested rules/locations, returns all by default
list_pull_requests	pull_requests	3,650	Very detailed with deep nesting, some redundancy
list_releases	repos	3,200	Full asset list, large markdown body

⭐ Poor (Rating 1) - 1 tool

Tool	Toolset	Tokens	Notes
get_me	context	25	403 error - not accessible with current permissions

Schema Analysis

Tool	Type	Depth	Key Fields	Structure Notes
get_file_contents	resource	1	content, sha, encoding	MCP resource format
list_issues	object_with_array	4	issues, pageInfo, labels, user	Nested user/label objects
list_pull_requests	array	5	number, title, state, head, base	Deep nesting (repo, user, refs)
list_workflows	object_with_array	2	workflows, id, name, path	Shallow, clean structure
list_code_scanning_alerts	array	4	number, rule, tool, location	Nested rule and instance data
list_discussions	object_with_array	3	discussions, pageInfo, category	Category embedded
get_label	object	1	color, description, id, name	Flat structure
search_repositories	object_with_array	2	total_count, items	Compact with minimal_output
get_commit	object	3	sha, commit, author, committer	Nested author/committer
list_branches	array	1	name, sha, protected	Flat array
list_tags	array	2	name, commit	Nested commit object
list_releases	array	4	tag_name, body, assets, author	Deep with full assets

Response Size Analysis

Toolset	Avg Tokens	Tools Tested
pull_requests	3,650	list_pull_requests
repos	1,191	get_file_contents, get_commit, list_branches, list_tags, list_releases
code_security	2,800	list_code_scanning_alerts
issues	920	list_issues
actions	305	list_workflows
discussions	275	list_discussions
search	180	search_repositories
labels	38	get_label
context	25	get_me (error)

Tool-by-Tool Analysis

Tool	Toolset	Tokens	Schema	Depth	Rating	Assessment
get_file_contents	repos	1,580	resource	1	⭐⭐⭐⭐⭐	Perfect for file access
list_workflows	actions	305	object_with_array	2	⭐⭐⭐⭐⭐	Ideal balance
list_issues	issues	920	object_with_array	4	⭐⭐⭐⭐⭐	Comprehensive, complete
get_label	labels	38	object	1	⭐⭐⭐⭐⭐	Most efficient
list_discussions	discussions	275	object_with_array	3	⭐⭐⭐⭐⭐	Clean structure
list_tags	repos	95	array	2	⭐⭐⭐⭐⭐	Simple, effective
list_branches	repos	68	array	1	⭐⭐⭐⭐⭐	Minimal, perfect
search_repositories	search	180	object_with_array	2	⭐⭐⭐⭐⭐	Efficient search
get_commit	repos	210	object	3	⭐⭐⭐⭐⭐	Clean (no diff)
list_code_scanning_alerts	code_security	2,800	array	4	⭐⭐⭐⭐	Rich but verbose
list_pull_requests	pull_requests	3,650	array	5	⭐⭐⭐⭐	Detailed, deep nesting
list_releases	repos	3,200	array	4	⭐⭐⭐⭐	Rich, large bodies
get_me	context	25	error	0	⭐	Permission denied

30-Day Trend Summary

Metric	Value
Data Points	227 records
Date Range	2025-12-04 to 2026-01-02 (22 days)
Average Daily Tokens	23,511
Tools Tracked	18 unique tools
Toolsets	11 categories
Rating Trend	Stable at 4.4-4.5

Key Findings

Context Efficiency Champions (High Rating, Low Tokens)

1. get_label (38 tokens, 5/5) - Most efficient
2. list_branches (68 tokens, 5/5) - Minimal data
3. list_tags (95 tokens, 5/5) - Simple structure
4. search_repositories (180 tokens, 5/5) - With minimal_output=true
5. get_commit (210 tokens, 5/5) - With include_diff=false

Context-Heavy Tools (High Tokens)

1. list_pull_requests (3,650 tokens) - Deep nesting, verbose
2. list_releases (3,200 tokens) - Full assets, large bodies
3. list_code_scanning_alerts (2,800 tokens) - Returns all alerts
4. get_file_contents (1,580 tokens) - File content (justified)
5. list_issues (920 tokens) - Comprehensive context

Optimization Opportunities

Reduce Context Usage:

• Use minimal_output=true for search tools (saves ~1,400 tokens)
• Use include_diff=false for get_commit (saves ~2,000+ tokens)
• Set perPage=1 for pagination when testing (significant savings)
• Filter code_scanning_alerts by state/severity (can save 2,000+ tokens)

Best Practices for Agents:

• Prefer get_label, list_branches, list_tags for lightweight operations
• Use search_repositories with minimal_output for repo discovery
• Request specific commit data without diffs unless needed
• Paginate PR and issue lists to control context
• Filter security alerts before retrieval

Recommendations

High-Value Tools for Agentic Work (Rating 4-5)

Recommended tools that balance usefulness and efficiency:

• get_file_contents - Essential for file operations
• list_workflows - Perfect for workflow discovery
• list_issues - Comprehensive issue management
• get_label - Lightweight label operations
• list_branches - Efficient branch listing
• search_repositories - Fast repo discovery (use minimal_output)

Tools Requiring Careful Use

These tools are useful but context-heavy. Use with pagination and filtering:

• list_pull_requests - Use pagination, avoid when full context not needed
• list_releases - Large bodies, filter by specific versions
• list_code_scanning_alerts - Filter by state/severity

Tools to Avoid

• get_me - Returns 403 error with current permissions, not usable

Schema Design Insights

Excellent Patterns

• MCP Resources: Clean, standardized format (get_file_contents)
• Flat Arrays: Minimal nesting (list_branches, list_tags)
• Pagination Objects: Consistent pageInfo structure across tools
• Optional Parameters: include_diff, minimal_output provide flexibility

Areas for Improvement

• Deep Nesting: list_pull_requests has 5 levels of nesting
• Redundancy: Full repo objects embedded in PRs (could be references)
• Default Verbosity: list_code_scanning_alerts returns all by default

Visualizations

Response Size by Toolset

Usefulness Ratings by Toolset

30-Day Token Usage Trend

Token Size vs Usefulness Rating

Tool Comparison Heatmap

References:

• §20656506662

AI generated by GitHub MCP Structural Analysis