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

[github-actions[bot]]

This analysis evaluates GitHub MCP tool responses for their size (tokens), structural schema, and usefulness for autonomous agentic workflows. Today's analysis covers 10 representative tools across 8 toolsets, with 4 days of historical trending data.

Key Findings: Most GitHub MCP tools are excellently designed for agentic work, with 7 out of 8 toolsets earning perfect 5.0 ratings. The pull_requests toolset is the only exception with a 4.0 rating due to verbose nested repository objects. Context efficiency varies significantly—from 50 tokens (labels) to 3,400 tokens (pull requests)—making tool selection critical for managing context budgets.

Full Structural Analysis Report

Executive Summary

Metric	Value
Tools Analyzed	10
Toolsets Evaluated	8
Total Tokens (Today)	8,340
Average Tokens per Tool	834
Average Usefulness Rating	4.6/5.0
Best Rated Toolsets	repos, issues, actions, discussions, labels (5.0/5.0)
Needs Improvement	context (1.0/5.0 - permission issue)
Most Context-Efficient	get_label (50 tokens, 5.0 rating)
Most Context-Heavy	list_pull_requests (3,400 tokens, 4.0 rating)

Usefulness Ratings for Agentic Work

Tool	Toolset	Rating	Stars	Assessment
get_file_contents	repos	5.0	⭐⭐⭐⭐⭐	Resource-based file access. Clean structure, immediately actionable. Perfect for agents.
list_issues	issues	5.0	⭐⭐⭐⭐⭐	Comprehensive data with pagination. All needed context (labels, users) embedded. Excellent.
list_workflows	actions	5.0	⭐⭐⭐⭐⭐	Compact, well-structured. Perfect balance of completeness and efficiency. Ideal for agents.
list_discussions	discussions	5.0	⭐⭐⭐⭐⭐	Clean structure with pagination. Category info embedded. Excellent for agents.
get_label	labels	5.0	⭐⭐⭐⭐⭐	Minimal, focused data. Zero bloat. Perfect for label operations. Most efficient tool tested.
list_commits	repos	5.0	⭐⭐⭐⭐⭐	Well-structured commit data. Logical nesting (author/committer). Clean and actionable.
list_branches	repos	5.0	⭐⭐⭐⭐⭐	Minimal branch data. Just essentials (name, sha, protected). Perfect efficiency.
list_pull_requests	pull_requests	4.0	⭐⭐⭐⭐	Very detailed but verbose. Deep nesting with full repo objects. Some redundancy for basic tasks.
search_code	search	4.0	⭐⭐⭐⭐	Rich search results with full repository context. Context-heavy due to embedded objects.
get_me	context	1.0	⭐	403 error - not accessible with current permissions. Cannot use in this context.

Rating Distribution

• ⭐⭐⭐⭐⭐ (5.0): 7 tools - Excellent for autonomous agents
• ⭐⭐⭐⭐ (4.0): 2 tools - Good, minor improvements possible
• ⭐ (1.0): 1 tool - Unusable due to permissions

Schema Analysis

Tool	Schema Type	Nesting Depth	Key Fields	Structural Notes
get_file_contents	resource	1	content, sha, encoding	Simple resource wrapper. Clean.
list_issues	object_with_array	4	issues[], pageInfo, totalCount, number, title, state, labels[], user	GraphQL-style pagination. Rich nested objects.
list_pull_requests	array	5	number, title, state, user, head, base, assignees[], draft	Deep nesting. Full repo objects embedded in head/base.
list_workflows	object_with_array	2	total_count, workflows[], id, name, path, state	Shallow nesting. Efficient structure.
list_discussions	object_with_array	3	discussions[], pageInfo, totalCount, number, title, category	GraphQL pagination. Category embedded.
get_label	object	1	color, description, id, name	Flat object. No nesting.
search_code	object_with_array	5	total_count, items[], name, path, repository	Deep nesting. Full repository object per result.
list_commits	array	3	sha, commit, author, committer, message	Moderate nesting. Author/committer objects logical.
list_branches	array	1	name, sha, protected	Minimal nesting. Simple array.
get_me	error	0	-	Returns 403 error. No data structure.

Schema Patterns Observed

1. GraphQL-Style Pagination: Tools like list_issues and list_discussions use pageInfo with cursors
2. REST-Style Pagination: Tools like list_pull_requests use traditional page numbers
3. Resource Wrappers: get_file_contents returns resources rather than raw JSON
4. Embedded Objects: Many tools embed related entities (users, repos) for completeness
5. Shallow Structures: Highest-rated tools (labels, branches, workflows) have minimal nesting

Response Size Analysis

Toolset	Avg Tokens	Efficiency Rating	Tools Tested
labels	50	Excellent	get_label
repos (branches)	85	Excellent	list_branches
actions	280	Excellent	list_workflows
discussions	250	Excellent	list_discussions
repos (commits)	430	Good	list_commits
issues	870	Good	list_issues
repos (files)	1,450	Moderate	get_file_contents
search	1,500	Moderate	search_code
pull_requests	3,400	Heavy	list_pull_requests
context	25	Error	get_me

Context Budget Implications

• Budget-Friendly (0-300 tokens): labels, branches, workflows, discussions
• Moderate (300-1000 tokens): commits, issues
• Heavy (1000-2000 tokens): file contents, search
• Very Heavy (3000+ tokens): pull requests

Tool-by-Tool Detailed Analysis

High-Efficiency Tools (50-300 tokens, Rating 5.0)

get_label (50 tokens, ⭐⭐⭐⭐⭐)

• Structure: Flat object with 4 fields
• Why Excellent: Zero bloat. Returns exactly what's needed for label operations.
• Best For: Label management, issue categorization
• Agent Tip: Use for quick label lookups without context overhead

list_branches (85 tokens, ⭐⭐⭐⭐⭐)

• Structure: Simple array with essential branch data
• Why Excellent: Minimal but complete. Name, SHA, protection status—nothing more.
• Best For: Branch discovery, protection checks
• Agent Tip: Ideal for pre-flight checks before branch operations

list_workflows (280 tokens, ⭐⭐⭐⭐⭐)

• Structure: Object with workflows array (depth 2)
• Why Excellent: Perfect balance. Total count + essential workflow metadata.
• Best For: Workflow discovery, status monitoring
• Agent Tip: Great for understanding available automation

list_discussions (250 tokens, ⭐⭐⭐⭐⭐)

• Structure: GraphQL-style with pageInfo (depth 3)
• Why Excellent: Clean pagination, embedded category data, efficient.
• Best For: Discussion discovery, community engagement
• Agent Tip: Category field enables smart routing

Mid-Efficiency Tools (400-1500 tokens, Rating 4.0-5.0)

list_commits (430 tokens, ⭐⭐⭐⭐⭐)

• Structure: Array with nested author/committer objects (depth 3)
• Why Excellent: Logical nesting. Author data embedded appropriately.
• Best For: Commit history analysis, attribution tracking
• Agent Tip: Author objects include both user and commit info

list_issues (870 tokens, ⭐⭐⭐⭐⭐)

• Structure: GraphQL-style with rich nested data (depth 4)
• Why Excellent: Comprehensive. Includes labels, users, pagination—all needed context.
• Best For: Issue triage, automated responses, workflow triggers
• Agent Tip: No additional calls needed for basic issue operations

get_file_contents (1,450 tokens, ⭐⭐⭐⭐⭐)

• Structure: Resource wrapper (depth 1)
• Why Excellent: Returns actual file content. Immediately actionable.
• Best For: Code review, file analysis, content extraction
• Agent Tip: Size varies with file size. Use for text files.

search_code (1,500 tokens, ⭐⭐⭐⭐)

• Structure: Object with items array, embedded repo objects (depth 5)
• Why Good: Rich results but context-heavy. Full repository objects embedded.
• Best For: Code discovery, pattern finding across repositories
• Agent Tip: Context cost high due to repo metadata. Use targeted queries.

Heavy Tools (3000+ tokens, Rating 4.0)

list_pull_requests (3,400 tokens, ⭐⭐⭐⭐)

• Structure: Array with deep nesting, full repo objects (depth 5)
• Why Only Good: Very detailed but verbose. Head/base contain full repository objects.
• Redundancy: Repository metadata repeated for each PR.
• Best For: Comprehensive PR analysis when all details needed
• Agent Tip: Consider using minimal_output or fetching individual PRs
• Improvement Opportunity: Add minimal mode without full repo objects

Unusable Tools

get_me (25 tokens, ⭐)

• Issue: 403 Forbidden - Resource not accessible by integration
• Impact: Cannot retrieve authenticated user info in workflow context
• Workaround: Use GitHub context variables or alternative endpoints
• Note: This is a permissions limitation, not a design issue

4-Day Trend Summary

Metric	2025-11-26	2025-11-27	2025-11-28	2025-12-01	Trend
Total Tokens	8,315	8,425	8,300	8,340	Stable
Avg Tokens/Tool	832	843	830	834	Stable
Avg Rating	4.6	4.6	4.6	4.6	Stable
Tools @ 5.0	7	7	7	7	Stable
Tools @ 4.0	2	2	2	2	Stable

Observations:

• Response sizes remarkably consistent across days (±50 token variance)
• Usefulness ratings stable—indicates consistent API design quality
• No structural changes detected in 4-day window
• Pull request responses show slight growth trend (3200 → 3400 tokens)

Recommendations

For Agentic Tool Selection

High-Priority Tools (Use these first):

1. get_label - Most efficient, perfect for categorization
2. list_branches - Minimal overhead, complete branch info
3. list_workflows - Balanced efficiency and completeness
4. list_discussions - Clean pagination, category support
5. list_commits - Well-structured history access

Context-Efficient Tools (Low token cost, high value):

• labels (50 tokens)
• branches (85 tokens)
• workflows (280 tokens)
• discussions (250 tokens)

Use With Caution (High context cost):

• list_pull_requests (3,400 tokens) - Consider fetching individual PRs
• search_code (1,500 tokens) - Use targeted queries

For MCP Server Improvements

Optimization Opportunities:

1. list_pull_requests - Add minimal_output mode

   • Remove redundant repository objects from head/base
   • Offer lightweight mode with just PR essentials
   • Could reduce from 3,400 → ~800 tokens

2. search_code - Optimize repository metadata

   • Repository object repeated for each result
   • Consider reference-based approach or summary mode
   • Could reduce from 1,500 → ~600 tokens

3. get_me - Permission enhancement

   • Document permission requirements clearly
   • Provide alternative for workflow contexts
   • Consider fallback to GitHub context variables

Agent Workflow Best Practices

Context Budget Management:

1. Start with lightweight tools (labels, branches, workflows)
2. Use targeted queries for search operations
3. Fetch individual resources rather than lists when possible
4. Cache frequently accessed data (labels, branches)

Structural Awareness:

1. GraphQL-style tools (issues, discussions) offer cursor pagination
2. Embedded objects reduce need for follow-up calls
3. Resource wrappers (file contents) provide direct access
4. Nesting depth correlates with context cost

Tool Combinations:

• Issue triage: list_issues (870) + get_label (50) = 920 tokens
• Branch analysis: list_branches (85) + list_commits (430) = 515 tokens
• Workflow monitoring: list_workflows (280) + list_workflow_runs ≈ 800 tokens
• Code search: search_code (1,500) + get_file_contents (1,450) = 2,950 tokens

Visualizations

Average Response Size by Toolset

This chart shows the average token count for each toolset. Labels and branches are highly efficient, while pull requests consume significant context.

Usefulness Ratings by Toolset

Most toolsets earn perfect 5.0 ratings for agentic work. Only pull_requests and search rate 4.0 due to verbosity. Context toolset rates 1.0 due to permission issues.

Daily Token Usage Trend

Four-day trend showing remarkable stability. Total daily token usage varies by less than 150 tokens, indicating consistent API design.

Token Size vs Usefulness Rating

Scatter plot revealing the ideal zone: low token count + high usefulness. Tools like get_label, list_branches, and list_workflows achieve this balance. Pull requests are useful but context-expensive.

---

Methodology: Tools tested with minimal parameters (perPage=1 where applicable) on repository githubnext/gh-aw. Token counts estimated at 1 token ≈ 4 characters. Usefulness ratings based on completeness, actionability, clarity, efficiency, and relationship handling. Historical data maintained 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 #5289.
Fair winds, matey! 🏴‍☠️