MCP Structural Analysis - 2025-12-26

[github-actions[bot]]

Quantitative and qualitative analysis of GitHub MCP tool responses shows most toolsets deliver excellent usefulness for agentic workflows (rating 4-5/5), with efficient tools like get_label (30 tokens) and list_workflows (170 tokens) providing optimal context usage. Notable exception: list_code_scanning_alerts when populated averages 19,900 tokens due to embedded rule documentation, requiring filtering strategies for efficient agent operation.

Full Structural Analysis Report

Executive Summary

Metric	Value
Tools Analyzed	10 unique tools
Total Tokens (Today)	20,430
Average Usefulness Rating	4.5/5
Best Rated Tools	get_file_contents, list_workflows, get_label, list_discussions, search_repositories (5/5)
Most Context-Heavy Tool	list_code_scanning_alerts (avg 19,900 tokens when populated)
Most Efficient Tool	get_label (30 tokens, rating 5/5)
Data Points (30 days)	216 measurements across 22 dates

Key Findings

Excellent Performance (Rating 5/5)

Most GitHub MCP tools demonstrate excellent structural design for agentic workflows:

• Repos toolset: Clean file content delivery (1,150 tokens avg), minimal branch data (55 tokens)
• Actions toolset: Compact workflow listings (170 tokens avg) with all essential metadata
• Labels toolset: Most efficient at 30 tokens with complete label information
• Discussions toolset: Well-structured pagination (130 tokens avg)
• Search toolset: Efficient repository search with minimal_output (420 tokens)

Good Performance (Rating 4/5)

• Pull Requests: Comprehensive but verbose (9,500 tokens today) due to full repo objects in head/base branches
• Issues: Rich data but variable size (1,200-9,400 tokens) depending on body length

Needs Improvement (Rating 2-3/5)

• Code Scanning Alerts: Extremely verbose when populated (8,200-34,750 tokens) due to full rule documentation, help text, examples, and references embedded in EVERY alert. Desperately needs minimal_output option for agent efficiency.

Usefulness Ratings for Agentic Work

Tool	Toolset	Rating	Token Range	Assessment
get_label	labels	⭐⭐⭐⭐⭐	28-60	Most efficient - minimal data, no bloat
list_branches	repos	⭐⭐⭐⭐⭐	55-95	Essential branch data only, perfect efficiency
list_workflows	actions	⭐⭐⭐⭐⭐	170-305	Compact, well-structured, ideal balance
list_discussions	discussions	⭐⭐⭐⭐⭐	20-275	Clean pagination, category embedded
search_repositories	search	⭐⭐⭐⭐⭐	20-430	Efficient with minimal_output default
get_file_contents	repos	⭐⭐⭐⭐⭐	750-1,600	Clean file delivery as MCP resource
list_issues	issues	⭐⭐⭐⭐⭐ / ⭐⭐⭐⭐	850-9,400	Excellent structure, variable due to body length
list_pull_requests	pull_requests	⭐⭐⭐⭐	2,800-9,500	Rich but verbose, deep nesting with full repo objects
list_code_scanning_alerts	code_security	⭐⭐⭐ / ⭐⭐	5-34,750	Context-heavy when populated, needs minimal_output
get_me	context	⭐	0-25	403 error - unavailable in workflow auth context

Schema Analysis

Tool	Type	Depth	Key Fields	Structural Notes
get_label	object	1	color, description, id, name	Flat structure, perfect
list_branches	array	1	name, sha, protected	Minimal nesting, efficient
list_workflows	object_with_array	2	total_count, workflows, id, name, path, state	Well-organized, paginated
list_discussions	object_with_array	3	discussions, pageInfo, totalCount, number, title, category	Clean GraphQL-style pagination
search_repositories	object_with_array	3	total_count, items, name, full_name, description	Efficient search results
get_file_contents	resource	1	content, sha	MCP resource format, clean
list_issues	object_with_array	4	issues, pageInfo, number, title, state, labels, user	Deep but logical nesting
list_pull_requests	array	5	number, title, state, user, head, base, assignees	Very deep due to full repo objects
list_code_scanning_alerts	array	4-6	number, rule, tool, state, most_recent_instance	Deep with embedded documentation

Response Size Analysis

Toolset	Avg Tokens	Min	Max	Tools Tested
labels	38	28	60	get_label
repos (branches)	66	55	95	list_branches
actions	220	170	305	list_workflows
discussions	162	20	275	list_discussions
search	380	20	430	search_repositories
repos (files)	1,310	750	1,600	get_file_contents
issues	2,350	850	9,400	list_issues
pull_requests	5,720	2,800	9,500	list_pull_requests
code_security	13,830	5	34,750	list_code_scanning_alerts

Tool-by-Tool Analysis (Latest - 2025-12-26)

Tool	Toolset	Tokens	Schema	Rating	Key Observations
get_label	labels	30	object (depth 1)	5	Four essential fields, no bloat, perfect for label operations
list_branches	repos	55	array (depth 1)	5	Three fields, minimal, ideal for branch ops
list_workflows	actions	170	object_with_array (depth 2)	5	Essential fields with URL, perfect efficiency
list_discussions	discussions	130	object_with_array (depth 3)	5	Clean pagination, category embedded, efficient
search_repositories	search	420	object_with_array (depth 3)	5	minimal_output default works well, essential metadata
get_file_contents	repos	1,150	resource (depth 1)	5	Clean README delivery as MCP resource, perfect
list_issues	issues	1,200	object_with_array (depth 4)	5	Comprehensive with 1400-char body, excellent structure
list_pull_requests	pull_requests	9,500	array (depth 5)	4	Very detailed with 4200-char body, full repo objects, context-heavy
list_code_scanning_alerts	code_security	8,200	array (depth 4)	3	30 alerts with rule docs, useful but verbose, needs filtering
get_me	context	25	error	1	403 error - not accessible in this auth context

30-Day Trend Summary

Metric	Value
Data Points	216 measurements
Date Range	2025-11-27 to 2025-12-26 (22 unique dates)
Unique Tools	12
Average Daily Tokens	20,158
Average Usefulness Rating	4.4/5 (excluding errors)
Rating Trend	Stable - consistent 4-5 ratings
Most Variable Tool	list_code_scanning_alerts (5 to 34,750 tokens)
Most Stable Tool	get_label (28-60 tokens)

Context Efficiency Insights

Top 5 Most Efficient (Low Tokens, High Usefulness)

1. get_label: 30 tokens, rating 5/5 - Perfect efficiency
2. list_branches: 55 tokens, rating 5/5 - Minimal essential data
3. list_workflows: 170 tokens, rating 5/5 - Ideal balance
4. list_discussions: 130 tokens, rating 5/5 - Clean structure
5. search_repositories: 420 tokens, rating 5/5 - Efficient discovery

Context-Heavy Tools (High Tokens)

1. list_code_scanning_alerts: 19,900 avg (when populated) - Embedded documentation bloat
2. list_pull_requests: 5,720 avg - Full repo objects in head/base branches
3. list_issues: 2,350 avg - Variable due to body length

Optimal Agent Strategies

• Use get_label, list_branches, list_workflows for frequent operations - minimal context cost
• Use list_issues and list_pull_requests with pagination - perPage=1-5 for discovery
• Filter list_code_scanning_alerts by state/severity or get count first - avoid listing all alerts
• Prefer search_repositories with minimal_output for repo discovery
• Avoid get_me - consistently returns 403 in workflow context

Recommendations

For Agents

1. Prioritize high-efficiency tools: Use get_label, list_branches, list_workflows for low context cost
2. Paginate strategically: Set perPage=1-5 for list_issues and list_pull_requests during discovery
3. Filter code scanning alerts: Always use state/severity filters, or check count before listing all
4. Leverage search: Use search_repositories with minimal_output for efficient repo discovery
5. Context budgeting: Budget 170-420 tokens for core operations, 1,000-2,000 for detailed queries

For Tool Improvements

1. list_code_scanning_alerts: Add minimal_output parameter to exclude rule documentation/examples
2. list_pull_requests: Consider minimal_output to exclude full repo objects in head/base
3. list_issues: Add option to truncate or exclude body text for discovery phase
4. get_me: Document 403 limitation in workflow auth context

Visualizations

Response Size by Toolset

This chart shows average response sizes across toolsets. Code security tools are significantly larger due to embedded documentation.

Usefulness Ratings by Toolset

Most toolsets achieve 4-5/5 ratings, indicating excellent structural design for agentic workflows. Green bars (≥4) represent good-to-excellent tools.

Daily Token Usage Trend (30 Days)

Daily token usage remains relatively stable, with spikes corresponding to days when code scanning alerts are populated.

Token Size vs Usefulness Rating

Scatter plot showing the relationship between response size and usefulness. Best tools cluster in the lower-right (low tokens, high rating). Most efficient tools like get_label and list_branches appear at the bottom with 5/5 ratings.

Tool Performance Heatmap

Comprehensive performance visualization across three dimensions: usefulness (higher is better), context efficiency (lower tokens is better), and schema simplicity (lower depth is better). Green indicates better performance.

References:

• Workflow Run §20521305248

AI generated by GitHub MCP Structural Analysis