[mcp-analysis] MCP Structural Analysis - December 9, 2025

[github-actions[bot]]

Analysis of GitHub MCP tool response structures reveals excellent design for agentic workflows. Testing 10 tools across 9 toolsets shows 80% achieve perfect 5/5 usefulness ratings, with most responses under 500 tokens. Key finding: get_label (32 tokens) and list_branches (55 tokens) demonstrate exceptional efficiency, while list_pull_requests (2,800 tokens) trades context cost for comprehensive data. 30-day trend shows stable performance with 8,254 average daily tokens across all tested tools.

Full Structural Analysis Report

Executive Summary

Metric	Value
Tools Analyzed	10
Total Tokens (Today)	6,207
Average Usefulness Rating	4.5/5
Best Rated Tools	8 tools at 5/5
Rating Distribution	⭐⭐⭐⭐⭐: 8, ⭐⭐⭐⭐: 1, ⭐: 1

Usefulness Ratings for Agentic Work

⭐⭐⭐⭐⭐ Excellent (5/5) - 8 tools

These tools provide complete, actionable data with clean structures, perfect for autonomous agents:

Tool	Toolset	Tokens	Assessment
get_label	labels	32	Most efficient tool tested. Minimal, focused data with zero bloat.
list_branches	repos	55	Just essential branch data (name, sha, protected). Perfect simplicity.
list_workflows	actions	180	Clean workflow listing with essential metadata (id, name, path, state).
list_discussions	discussions	250	Pagination support with embedded category info. Well-organized.
search_repositories	search	420	Excellent balance with minimal_output=true. Essential repo metadata only.
list_commits	repos	420	Logical nesting for author/committer objects. Clean commit history.
list_issues	issues	850	Comprehensive with pagination. Embedded user/label objects logical.
get_file_contents	repos	1,200	Raw content with SHA. Efficient despite size (content-dependent).

⭐⭐⭐⭐ Good (4/5) - 1 tool

Tool	Toolset	Tokens	Assessment
list_pull_requests	pull_requests	2,800	Very comprehensive but context-heavy. Deep nesting (5 levels) with full repo objects in head/base. Rich data justified by PR complexity.

⭐ Poor (1/5) - 1 tool

Tool	Toolset	Tokens	Issue
get_me	context	0	403 error - "Resource not accessible by integration". Unavailable in workflow context.

Schema Analysis

Tool	Schema Type	Depth	Key Fields	Notes
get_label	object	1	color, description, id, name	Flattest structure
list_branches	array	1	name, sha, protected	Simple array of objects
list_workflows	object+array	2	total_count, workflows[], id, name	Clean wrapping
list_discussions	object+array	3	discussions[], pageInfo, totalCount	Standard pagination
search_repositories	object+array	3	total_count, items[], name, topics	Efficient search format
list_commits	array	3	sha, commit, author, message	Logical nesting
list_issues	object+array	4	issues[], pageInfo, number, labels[]	Embedded entities
list_pull_requests	array	5	number, user, head, base, _links	Deep nesting for complexity

Key Insight: Most tools maintain 1-3 nesting levels, striking optimal balance between structure and simplicity. Only list_pull_requests reaches depth 5, justified by PR data richness.

Response Size Analysis

Toolset	Avg Tokens	Tools Tested	Efficiency
labels	32	1	🟢 Extremely efficient
repos	558	3	🟢 Efficient (varies by content)
actions	180	1	🟢 Efficient
discussions	250	1	🟢 Efficient
search	420	1	🟢 Efficient
issues	850	1	🟡 Moderate (rich data)
pull_requests	2,800	1	🟡 Context-heavy (justified)

Size Distribution:

• Under 100 tokens: 2 tools (20%) - Ultra-efficient
• 100-500 tokens: 4 tools (40%) - Efficient
• 500-1000 tokens: 1 tool (10%) - Moderate
• Over 1000 tokens: 2 tools (20%) - Context-heavy
• Error: 1 tool (10%)

Tool-by-Tool Detailed Analysis

Tool	Toolset	Tokens	Schema	Depth	Rating	Notes
get_file_contents	repos	1,200	text_content	1	⭐⭐⭐⭐⭐	Returns raw file content with SHA. Clean and efficient for file reading.
list_issues	issues	850	object+array	4	⭐⭐⭐⭐⭐	Comprehensive issue data with pagination. Includes embedded user and label objects.
list_commits	repos	420	array	3	⭐⭐⭐⭐⭐	Well-structured commit data. Nested author/committer objects logical.
list_workflows	actions	180	object+array	2	⭐⭐⭐⭐⭐	Clean workflow listing with essential metadata. Well-structured and efficient.
list_discussions	discussions	250	object+array	3	⭐⭐⭐⭐⭐	Clean structure with pagination support. Category info embedded.
get_label	labels	32	object	1	⭐⭐⭐⭐⭐	Minimal, focused data. No bloat. Most efficient tool tested.
list_branches	repos	55	array	1	⭐⭐⭐⭐⭐	Minimal, efficient. Just the essential branch data.
search_repositories	search	420	object+array	3	⭐⭐⭐⭐⭐	Efficient search results with minimal_output=true. Good balance of detail and context efficiency.
list_pull_requests	pull_requests	2,800	array	5	⭐⭐⭐⭐	Very comprehensive PR data with deep nesting. Includes full repo objects in head/base. Rich but context-heavy.
get_me	context	0	error	0	⭐	403 error - Resource not accessible by integration. Tool unavailable in this context.

30-Day Trend Summary

Metric	Value
Data Points	100 measurements
Date Range	Nov 26 - Dec 9, 2025 (14 days)
Unique Dates	10 analysis runs
Average Daily Tokens	8,254
Trend	✅ Stable - Consistent tool performance

The trend data shows stable tool behavior across multiple analysis runs, indicating reliable schema consistency.

Recommendations for Agentic Workflows

🏆 Top-Tier Tools (Use These First)

Ultra-Efficient (Rating: 5/5, Tokens < 100):

• get_label - 32 tokens, depth 1 - Perfect for label operations
• list_branches - 55 tokens, depth 1 - Ideal for branch queries

High-Value (Rating: 5/5, Tokens < 500):

• list_workflows - 180 tokens, depth 2 - Excellent for workflow discovery
• list_discussions - 250 tokens, depth 3 - Great for discussion access
• search_repositories - 420 tokens, depth 3 - Optimal search balance
• list_commits - 420 tokens, depth 3 - Clean commit history

✅ Recommended Tools

Rich Data (Rating: 5/5, Higher tokens justified):

• list_issues - 850 tokens, depth 4 - Comprehensive issue data
• get_file_contents - 1,200 tokens, depth 1 - Content size varies by file

⚠️ Use With Caution

Context-Heavy (Rating: 4/5, High token cost):

• list_pull_requests - 2,800 tokens, depth 5 - Very comprehensive but expensive. Consider pagination or filtering.

❌ Avoid

Unavailable:

• get_me - Returns 403 error in workflow context

Key Insights for Tool Selection

1. Efficiency Champions: get_label and list_branches are models of efficiency - minimal tokens, flat structure, complete data.

2. Pagination is Your Friend: Tools with pagination support (list_issues, list_discussions) allow agents to control context usage effectively.

3. Schema Consistency: Most tools maintain 1-3 nesting levels, making response parsing predictable and reliable.

4. Context Trade-offs: list_pull_requests demonstrates that high token costs can be justified when data completeness is essential.

5. Minimal Output Parameters: Tools supporting minimal_output (like search_repositories) should always use it to reduce context.

Best Practices for Agents

1. Start Simple: Use efficient tools like get_label or list_branches when possible.

2. Paginate Aggressively: Always set perPage=1 or small values for exploratory queries.

3. Avoid Deep Nesting: Tools with depth > 3 may require more parsing logic. Prefer shallow structures.

4. Check Availability: get_me fails in this context - verify tool accessibility before designing workflows.

5. Balance Completeness vs Cost: list_issues (850 tokens) vs list_pull_requests (2,800 tokens) - choose based on needs.

Visualizations

Response Size by Toolset

Analysis of today's tool responses shows the repos toolset has the highest variability due to content-dependent sizes (get_file_contents), while labels and branches maintain consistently low token counts.

Usefulness Ratings

80% of toolsets achieve perfect 5/5 ratings. The context toolset shows 1/5 due to get_me accessibility issues. Pull_requests rated 4/5 due to context heaviness, not data quality.

Daily Token Trend

30-day trend shows stable token usage with daily totals averaging 8,254 tokens. The variation reflects different tool combinations tested each day, not schema instability.

Size vs Usefulness

Scatter plot reveals the "sweet spot": most 5-star tools cluster under 500 tokens. Only get_file_contents and list_issues exceed this while maintaining top ratings, proving context cost can be justified by value.

Methodology

This analysis tested representative tools from each GitHub MCP toolset with minimal parameters (perPage=1 where applicable) to evaluate:

• Response size in tokens (1 token ≈ 4 characters)
• Schema structure (type, nesting depth, key fields)
• Usefulness for autonomous agents (1-5 scale)

Ratings criteria:

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

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 #6021.
Fair winds, matey! 🏴‍☠️