[mcp-analysis] MCP Structural Analysis - November 28, 2025

[github-actions[bot]]

This structural analysis evaluates GitHub MCP tool responses for size, schema quality, and usefulness for agentic workflows. Analysis shows 8/9 toolsets rating 4+ stars, with most tools providing excellent structure for autonomous agents. The pull_requests toolset is notably verbose (3,350 tokens average) while labels toolset is most efficient (55 tokens). Context-efficient high-performers include list_workflows (275 tokens, 5-star), list_branches (90 tokens, 5-star), and get_label (55 tokens, 5-star).

Full Structural Analysis Report

Executive Summary

Metric	Value
Tools Analyzed	10
Total Tokens (Today)	8,210
Average Usefulness Rating	4.5/5
Best Rated Tools	get_file_contents, list_issues, list_workflows, list_discussions, get_label, list_commits, list_branches (all 5/5)
Lowest Rated Tool	get_me: 1/5 (403 permission error)
Most Context-Efficient	get_label (55 tokens, 5/5 rating)
Most Context-Heavy	list_pull_requests (3,350 tokens, 4/5 rating)

Usefulness Ratings for Agentic Work

Tool	Toolset	Rating	Assessment
get_file_contents	repos	⭐⭐⭐⭐⭐	Excellent - Clean resource format, immediately actionable
list_issues	issues	⭐⭐⭐⭐⭐	Excellent - Complete issue data with pagination, perfect for agents
list_workflows	actions	⭐⭐⭐⭐⭐	Excellent - Compact and well-structured, ideal balance
list_discussions	discussions	⭐⭐⭐⭐⭐	Excellent - Clean structure with category info embedded
get_label	labels	⭐⭐⭐⭐⭐	Excellent - Minimal, focused, no bloat
list_commits	repos	⭐⭐⭐⭐⭐	Excellent - Well-structured with logical nesting
list_branches	repos	⭐⭐⭐⭐⭐	Excellent - Minimal and efficient
list_pull_requests	pull_requests	⭐⭐⭐⭐	Good - Rich but verbose, some redundant fields
search_code	search	⭐⭐⭐⭐	Good - Useful but context-heavy with deep nesting
get_me	context	⭐	Poor - 403 permission error, not usable in this context

Schema Analysis

Tool	Type	Depth	Key Fields	Notes
get_me	error	0	[]	403 error - not accessible
get_file_contents	resource	1	content, sha, encoding	Clean resource format
list_issues	object_with_array	4	issues, pageInfo, number, title, state, labels, user	Complete with pagination
list_pull_requests	array	5	number, title, state, user, head, base, assignees, draft	Deep nesting with full repo objects
list_workflows	object_with_array	2	total_count, workflows, id, name, path, state	Well-balanced structure
list_discussions	object_with_array	3	discussions, pageInfo, number, title, category	Category embedded nicely
get_label	object	1	color, description, id, name	Simple flat object
search_code	object_with_array	5	total_count, items, name, path, repository	Full repo context embedded
list_commits	array	3	sha, commit, author, committer, message	Logical author/committer nesting
list_branches	array	1	name, sha, protected	Minimal flat structure

Response Size Analysis

Toolset	Avg Tokens	Tools Tested	Assessment
pull_requests	3,350	1	Very verbose, consider using minimal fields
search	1,475	1	Context-heavy due to embedded repo objects
repos	643	3	Well-balanced across file/commit/branch ops
issues	860	1	Reasonable size for complete issue data
actions	275	1	Excellent balance of detail and efficiency
discussions	240	1	Efficient for full discussion data
labels	55	1	Most efficient toolset
context	25	1	Error response, not representative

Tool-by-Tool Analysis

Tool	Toolset	Tokens	Schema	Rating	Notes
get_me	context	25	error	1	403 error - permission issue
get_label	labels	55	object	5	Most efficient, perfect for agents
list_branches	repos	90	array	5	Minimal branch data, highly efficient
list_discussions	discussions	240	object_with_array	5	Clean with pagination
list_workflows	actions	275	object_with_array	5	Ideal balance
list_commits	repos	415	array	5	Well-structured commit data
list_issues	issues	860	object_with_array	5	Complete issue context
get_file_contents	repos	1,425	resource	5	Clean file access
search_code	search	1,475	object_with_array	4	Useful but context-heavy
list_pull_requests	pull_requests	3,350	array	4	Very detailed but verbose

3-Day Trend Summary

Metric	Value
Data Points	30 (10 tools × 3 days)
Total Tokens (3 days)	24,575
Average Daily Tokens	8,192
Average Rating	4.5/5
Trend	Stable - consistent ratings across all days
Token Variation	Minimal (<5% variance day-to-day)

Recommendations

High-Value Tools for Agents (Rating 4-5, Context-Efficient)

Excellent 5-star performers:

• list_workflows (275 tokens) - Perfect for workflow automation
• list_branches (90 tokens) - Efficient branch operations
• get_label (55 tokens) - Minimal label management
• list_discussions (240 tokens) - Clean discussion access
• list_commits (415 tokens) - Well-structured commit history
• list_issues (860 tokens) - Complete issue data
• get_file_contents (1,425 tokens) - Essential file access

Good 4-star performers:

• search_code (1,475 tokens) - Rich search, acceptable overhead
• list_pull_requests (3,350 tokens) - Complete but verbose

Context-Efficient Champions

Best token-to-value ratio:

1. get_label - 55 tokens, 5-star rating
2. list_branches - 90 tokens, 5-star rating
3. list_discussions - 240 tokens, 5-star rating
4. list_workflows - 275 tokens, 5-star rating

Context-Heavy Tools

Use with care (high token usage):

• list_pull_requests - 3,350 tokens (consider filtering fields)
• search_code - 1,475 tokens (necessary due to repo context)
• get_file_contents - 1,425 tokens (varies with file size)

Tools Needing Attention

• get_me - 403 permission error in workflow context. Consider alternative authentication or use different user info source.

Toolset Quality Rankings

1. labels ⭐⭐⭐⭐⭐ - Ultra-efficient (55 tokens)
2. actions ⭐⭐⭐⭐⭐ - Perfect balance (275 tokens)
3. discussions ⭐⭐⭐⭐⭐ - Clean structure (240 tokens)
4. repos ⭐⭐⭐⭐⭐ - Well-balanced across ops (avg 643 tokens)
5. issues ⭐⭐⭐⭐⭐ - Complete context (860 tokens)
6. search ⭐⭐⭐⭐ - Useful but heavy (1,475 tokens)
7. pull_requests ⭐⭐⭐⭐ - Rich but verbose (3,350 tokens)
8. context ⭐ - Permission issues (not usable)

Visualizations

Response Size by Toolset

Analysis: repos toolset shows good balance across operations, while pull_requests is notably verbose.

Usefulness Ratings by Toolset

Analysis: 8 out of 9 accessible toolsets rate 4+ stars (green/yellow zones), indicating excellent design for agentic workflows.

Daily Token Usage Trend

Analysis: Stable token usage across 3 days (~8,200 tokens/day), showing consistent response sizes.

Token Size vs Usefulness Rating

Analysis: No correlation between size and usefulness. Smaller responses (labels, branches) can be just as useful as larger ones (issues, PRs). Sweet spot appears to be 200-900 tokens with 5-star ratings.

Key Insights

Schema Quality

• Consistent pagination: Most list operations use pageInfo with endCursor/hasNextPage
• Appropriate nesting: 1-3 depth is common, 4-5 depth only when necessary (issues, PRs, search)
• Resource pattern: get_file_contents uses clean resource format vs raw JSON

Agentic Workflow Optimization

• Batch operations: Use pagination to control context usage
• Field selection: Future enhancement could allow field filtering for verbose tools
• Error handling: Tools consistently return structured errors (e.g., get_me 403)

Best Practices for Agents

1. Prefer smaller tools when possible (labels, branches, workflows)
2. Use pagination with perPage=1 for testing or minimal context
3. Cache frequently-accessed data (labels, workflows) to reduce API calls
4. Be cautious with list_pull_requests - consider filtering to specific states

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