[mcp-analysis] MCP Structural Analysis - 2025-12-10

[github-actions[bot]]

The GitHub MCP server provides 10 toolsets with varying response sizes and usefulness ratings. Today's analysis tested representative tools across all major toolsets, measuring both quantitative metrics (token counts) and qualitative assessment (structural usefulness for agentic workflows).

Key Findings: Most toolsets achieve excellent usefulness ratings (5/5), with the notable exception of code_security tools which are extremely verbose. The labels toolset is the most efficient (30 tokens), while code_security can exceed 18,000 tokens per response. Over the 30-day trend, total token usage has grown as issue/PR content increases.

Full Structural Analysis Report

Executive Summary

Metric	Value
Tools Analyzed	10
Total Tokens (Today)	24,538
Average Usefulness Rating	4.4/5
Best Rated Tool	get_label: 5/5
Most Context-Heavy Tool	list_code_scanning_alerts: 18,500 tokens
Data Points (30 days)	110

Usefulness Ratings for Agentic Work

Today's analysis (2025-12-10) - sorted by rating:

Tool	Toolset	Rating	Token Size	Assessment
get_label	labels	⭐⭐⭐⭐⭐	30	Most efficient tool. Minimal, focused label data. Perfect for label operations.
list_branches	repos	⭐⭐⭐⭐⭐	58	Minimal branch data. Just essential fields. Perfect efficiency.
list_discussions	discussions	⭐⭐⭐⭐⭐	85	Empty response - clean pagination structure. Excellent for agents.
list_workflows	actions	⭐⭐⭐⭐⭐	185	Compact, well-structured. Perfect balance of completeness and efficiency.
search_repositories	search	⭐⭐⭐⭐⭐	390	Efficient with minimal_output=true. Well-structured with essential metadata.
list_issues	issues	⭐⭐⭐⭐⭐	920	Comprehensive with pagination. Nested user and label objects provide full context.
get_file_contents	repos	⭐⭐⭐⭐⭐	1,250	Returns file content as MCP resource. Clean and immediately actionable.
list_pull_requests	pull_requests	⭐⭐⭐⭐	2,850	Very detailed with deep nesting. Rich but context-heavy for basic PR operations.
list_code_scanning_alerts	code_security	⭐⭐⭐	18,500	VERY verbose. Includes full help text and examples. Would benefit from minimal_output option.
get_me	context	⭐	0	403 error - Resource not accessible by integration. Tool unavailable in this context.

Schema Analysis

Tool	Type	Depth	Key Fields	Structure Notes
get_label	object	1	color, description, id, name	Flat, simple structure
list_branches	array	1	name, sha, protected	Minimal nesting
list_workflows	object_with_array	2	total_count, workflows, id, name, path	Well-organized wrapper
list_issues	object_with_array	4	issues, pageInfo, totalCount, number, title, labels, user	Deep nesting with embedded objects
list_pull_requests	array	5	number, title, user, head, base, _links	Very deep - full repo objects in head/base
list_code_scanning_alerts	array	6	number, rule, tool, state, most_recent_instance	Extremely deep with full rule documentation

Key Observation: Nesting depth correlates with context usage. Tools with depth 1-2 average <200 tokens, while depth 5-6 tools average >2,000 tokens.

Response Size Analysis by Toolset

Toolset	Avg Tokens	Min	Max	Tools Tested
code_security	18,500	18,500	18,500	1
pull_requests	3,025	2,800	2,850	10
search	1,260	390	1,750	10
repos	820	55	1,575	30
issues	885	850	920	10
actions	235	180	305	10
discussions	225	85	275	10
labels	40	30	65	10
context	15	0	25	10

Tool-by-Tool Analysis (Today's Run)

High-Value, Low-Context Tools (Rating 5, <100 tokens)

• get_label (30 tokens): Most efficient. Flat object, no bloat.
• list_branches (58 tokens): Essential branch data only.
• list_discussions (85 tokens): Clean empty response with pagination.

High-Value, Medium-Context Tools (Rating 5, 100-500 tokens)

• list_workflows (185 tokens): Well-balanced structure.
• search_repositories (390 tokens): Good use of minimal_output parameter.

High-Value, High-Context Tools (Rating 5, >500 tokens)

• list_issues (920 tokens): Deep nesting justified by complete context.
• get_file_contents (1,250 tokens): Returns full file content - expected size.

Good Value, High-Context Tools (Rating 4)

• list_pull_requests (2,850 tokens): Rich but verbose. Includes full repository objects in head/base which may be redundant for many use cases.

Moderate Value, Very High-Context Tools (Rating 3)

• list_code_scanning_alerts (18,500 tokens): Extremely verbose. Each alert includes full rule documentation, help text, and code examples. A minimal_output option would dramatically improve usefulness.

Unavailable Tools (Rating 1)

• get_me (0 tokens): Returns 403 error in this context. Not usable.

30-Day Trend Summary

Metric	Value
Data Points	110 (11 days × 10 tools)
Date Range	2025-11-26 to 2025-12-10
Average Daily Tokens	~7,000
Trend	Gradually increasing as repository data grows
Rating Stability	Consistent - tools maintain ratings across time

Observation: Token counts for data-dependent tools (issues, PRs, commits) slowly increase over time as the repository adds content. Metadata tools (labels, branches, workflows) remain stable.

Recommendations

For Optimal Agentic Workflows

High-efficiency tools (prefer these when possible):

• get_label, list_branches, list_discussions, list_workflows, search_repositories (with minimal_output)

Context-efficient for data access:

• list_issues, get_file_contents - Well-structured despite higher token counts

Use with caution (high context cost):

• list_pull_requests - Consider if full repo context in head/base is needed
• list_code_scanning_alerts - Extremely verbose, reserve for when full rule documentation is required

Improvement Opportunities

1. code_security toolset: Add minimal_output parameter to return just alert metadata without full rule documentation
2. pull_requests toolset: Consider optional flag to exclude full repository objects from head/base
3. context toolset: Address permission issues with get_me for better user context access

Tool Selection Guide for Agents

When to use what:

• Quick metadata lookup: labels, branches, workflows
• Search operations: search_repositories (with minimal_output=true)
• Issue/PR browsing: list_issues, list_pull_requests (paginate with perPage=1-5)
• File access: get_file_contents (efficient for individual files)
• Security scanning: Use sparingly due to extreme verbosity

Visualizations

Response Size by Toolset

code_security toolset is an extreme outlier at 18,500 average tokens. Most other toolsets range from 40-3,000 tokens.

Usefulness Ratings by Toolset

Most toolsets achieve excellent ratings (5/5). Only code_security scores "adequate" (3/5) due to extreme verbosity.

Daily Token Usage Trend (30 Days)

Total daily token usage shows gradual increase as repository data grows. Consistent testing pattern across 30-day window.

Token Size vs Usefulness Rating

Scatter plot reveals the sweet spot: tools in the upper-left quadrant (low size, high rating) are ideal for agentic workflows. The code_security toolset is a clear outlier in the lower-right (high size, moderate rating).

---

Methodology: Analysis based on systematic testing of representative GitHub MCP tools with minimal parameters. Response sizes measured in tokens (1 token ≈ 4 characters). Usefulness ratings assess completeness, actionability, clarity, efficiency, and relationship embedding for autonomous agent workflows. Data collected daily and stored in rolling 30-day window.

AI generated by GitHub MCP Structural Analysis

[github-actions[bot]]

⚓ Avast! This discussion be marked as outdated by GitHub MCP Structural Analysis.
🗺️ A newer treasure map awaits ye at Discussion #6121.
Fair winds, matey! 🏴‍☠️