[mcp-analysis] MCP Structural Analysis - February 2, 2026

[github-actions[bot]]

This analysis evaluates GitHub MCP tool responses for both quantitative metrics (token size/context efficiency) and qualitative assessment (structural usefulness for autonomous agents). After 30 days of tracking across 239 data points, we've identified patterns that help agents optimize their tool selection.

Key Findings

Metric	Value
Tools Analyzed Today	12
Total Response Size	43,480 tokens
Average Usefulness Rating	4.00/5 ⭐
Best Performers	get_label, list_branches, list_tags (5/5, minimal tokens)
Problem Areas	list_code_scanning_alerts (2/5, 17.6K tokens), get_me (1/5, permission error)

Executive Summary

What's Working Well:

• Repos toolset (4.8/5): Excellent balance of data and efficiency. File contents, branches, commits, and tags all deliver clean, actionable responses.
• Actions toolset (5/5): Workflow listing is comprehensive yet efficient at 5.8K tokens for 30 workflows.
• Labels & Discussions (5/5): Perfect minimal responses with flat structures - exactly what agents need.

Critical Issues:

• Code Security toolset (2/5): Severe bloat with 70KB response for just 4 alerts. Includes full HTML help text and verbose rule descriptions that should be in separate detail endpoints.
• Context toolset (1/5): get_me fails with 403 permission errors, making it completely unusable for workflow automation.
• Pull Requests (3/5): Moderate bloat at 13.5K tokens for perPage=1 due to deeply nested repository objects in head/base branches.

Full Structural Analysis Report

Response Size Analysis

Average Token Count by Toolset

Efficiency Champions (Green Zone: <1K tokens):

• labels (30 tokens): Flat structure with only essential fields
• repos/branches (50 tokens): Minimal git operation data
• repos/tags (90 tokens): Clean release references
• get_file_contents (150 tokens): Success message with SHA
• discussions (280 tokens): Well-structured GraphQL pagination
• search (320 tokens): Minimal repo metadata

Moderate Size (Orange Zone: 1K-10K tokens):

• repos/commits (420 tokens): Nested author details, reasonable balance
• issues (5.2K tokens): Large body text in this sample (team status issue)
• actions (5.8K tokens): 30 workflows with full metadata

Bloat Zone (Red Zone: >10K tokens):

• pull_requests (13.5K tokens): Redundant repo objects in head/base
• code_security (17.6K tokens): Full HTML help text for 4 alerts

Usefulness Rating for Agentic Work

Toolset	Rating	Assessment
actions	⭐⭐⭐⭐⭐ (5.0)	Perfect - essential workflow metadata, no bloat
discussions	⭐⭐⭐⭐⭐ (5.0)	Excellent - GraphQL pagination, category info
labels	⭐⭐⭐⭐⭐ (5.0)	Perfect - minimal flat structure
repos	⭐⭐⭐⭐⭐ (4.8)	Excellent - file contents, branches, commits, tags all efficient
issues	⭐⭐⭐⭐ (4.0)	Good - rich data with pagination, can be verbose with large bodies
search	⭐⭐⭐⭐ (4.0)	Good - efficient discovery with minimal metadata
pull_requests	⭐⭐⭐ (3.0)	Adequate - comprehensive but bloated with redundant repo objects
code_security	⭐⭐ (2.0)	Limited - severe bloat with full HTML docs, needs summary mode
context	⭐ (1.0)	Poor - permission errors make it unusable

30-Day Trend Analysis

Key Observations:

• Jan 12 Spike: Massive token usage (282K) from list_releases returning 1.1M chars for single release query - catastrophic bloat
• Jan 15 Spike: Pull requests showed extreme bloat (69K tokens for perPage=1)
• Stabilization: Recent days show more consistent patterns around 30-50K tokens per analysis run
• Rating Stability: Average usefulness rating remains steady around 3.5-4.0/5, indicating consistent tool quality

Token Efficiency vs Usefulness

Quadrant Analysis

🌟 Sweet Spot (Low tokens, High value):

• get_label (30 tokens, 5/5): Perfect minimal response
• list_branches (50 tokens, 5/5): Essential git data only
• list_tags (90 tokens, 5/5): Clean release references
• get_file_contents (150 tokens, 5/5): Efficient file operations
• list_discussions (280 tokens, 5/5): Well-structured community data
• search_repositories (320 tokens, 4/5): Good discovery tool
• list_commits (420 tokens, 4/5): Balanced commit history

📦 Data Rich (High tokens, High value):

• list_workflows (5.8K tokens, 5/5): Comprehensive but worth it for 30 workflows

⚠️ Moderate Zone (Medium tokens, Adequate value):

• list_issues (5.2K tokens, 4/5): Rich data, can be verbose
• list_pull_requests (13.5K tokens, 3/5): Useful but bloated

🚫 Bloat Zone (High tokens, Low value):

• list_code_scanning_alerts (17.6K tokens, 2/5): Severe bloat, needs optimization
• get_me (40 tokens, 1/5): Fails with permission error

Schema Structure Analysis

Excellent Structures (Rating 5/5)

get_file_contents (repos)

• Type: String/Resource
• Depth: 1 (flat)
• Key Fields: content, sha
• Why Excellent: Returns file content with verification SHA, minimal metadata, immediately actionable

get_label (labels)

• Type: Object
• Depth: 1 (flat)
• Key Fields: name, color, description, id
• Why Excellent: Perfect minimal response, no nesting, all fields useful

list_branches (repos)

• Type: Array
• Depth: 1 (flat)
• Key Fields: name, sha, protected
• Why Excellent: Essential git operation data, no bloat

list_workflows (actions)

• Type: Object
• Depth: 2
• Key Fields: total_count, workflows[]
• Why Excellent: Clean array with essential metadata, includes URLs and state

list_discussions (discussions)

• Type: Object (GraphQL)
• Depth: 3
• Key Fields: discussions[], pageInfo, totalCount, category
• Why Excellent: Well-structured pagination, includes category context, efficient

Good Structures (Rating 4/5)

list_issues (issues)

• Type: Object (GraphQL)
• Depth: 3
• Key Fields: issues[], pageInfo, totalCount, nested user, labels
• Why Good: Rich data with embedded objects, pagination support, can be verbose with large issue bodies

list_commits (repos)

• Type: Array
• Depth: 3
• Key Fields: sha, commit, author, committer, html_url
• Why Good: Nested author/committer details, reasonable balance of metadata

search_repositories (search)

• Type: Object
• Depth: 2
• Key Fields: total_count, items[], incomplete_results
• Why Good: Efficient with minimal_output mode, good for discovery

Adequate Structures (Rating 3/5)

list_pull_requests (pull_requests)

• Type: Array (REST)
• Depth: 5 (deeply nested)
• Key Fields: number, title, state, body, user, head, base
• Issues:
  • Full repository objects duplicated in both head and base branches
  • Redundant organization metadata
  • 13.5K tokens for perPage=1 is excessive
• Why Adequate: Comprehensive data but bloated, would benefit from repository reference IDs instead of full objects

Limited Structures (Rating 2/5)

list_code_scanning_alerts (code_security)

• Type: Array
• Depth: 4
• Key Fields: number, rule, state, tool, most_recent_instance
• Issues:
  • Includes full HTML-formatted help text in every alert
  • Verbose rule descriptions with complete code examples
  • 17.6K tokens (70KB) for just 4 alerts
  • Should have separate detail endpoint for documentation
• Why Limited: Extremely inefficient for list queries, needs summary mode

Poor Structures (Rating 1/5)

get_me (context)

• Type: Error
• Issues:
  • 403 permission error: "Resource not accessible by integration"
  • Completely unusable for workflow automation
  • Should be documented as requiring different token permissions
• Why Poor: Fails consistently, no value for agentic workflows

Tool-by-Tool Analysis (Latest Data)

Tool	Toolset	Tokens	Schema	Rating	Key Notes
get_label	labels	30	object (depth 1)	⭐⭐⭐⭐⭐	Perfect minimal response, flat structure
list_branches	repos	50	array (depth 1)	⭐⭐⭐⭐⭐	Essential git data only
list_tags	repos	90	array (depth 2)	⭐⭐⭐⭐⭐	Clean release references with commit info
get_file_contents	repos	150	string (depth 1)	⭐⭐⭐⭐⭐	Success message with SHA, efficient
list_discussions	discussions	280	object (depth 3)	⭐⭐⭐⭐⭐	GraphQL pagination, category info
search_repositories	search	320	object (depth 2)	⭐⭐⭐⭐	Minimal metadata, good discovery
list_commits	repos	420	array (depth 3)	⭐⭐⭐⭐	Nested author details, reasonable
list_issues	issues	5,200	object (depth 3)	⭐⭐⭐⭐	Rich data, large body in this sample
list_workflows	actions	5,800	object (depth 2)	⭐⭐⭐⭐⭐	30 workflows with full metadata
list_pull_requests	pull_requests	13,500	array (depth 5)	⭐⭐⭐	Redundant repo objects, bloated
list_code_scanning_alerts	code_security	17,600	array (depth 4)	⭐⭐	Severe bloat with full HTML docs
get_me	context	40	error (depth 1)	⭐	403 permission error, unusable

Recommendations

For Agent Developers

1. Prefer High-Efficiency Tools

When you have a choice, use these sweet-spot tools:

• ✅ get_label, list_branches, list_tags for git operations (30-90 tokens)
• ✅ list_discussions, search_repositories for discovery (280-320 tokens)
• ✅ list_commits for history (420 tokens)

2. Use Pagination Parameters Wisely

• For list_pull_requests: Always use perPage=1 or minimal values, as responses are extremely nested
• For list_issues: Be aware that issue bodies can be very large (20KB+ for team status issues)
• For list_workflows: Reasonable to use higher limits, well-optimized

3. Avoid These Tools

• ❌ get_me: Fails with 403 errors, unusable
• ❌ list_code_scanning_alerts for list queries: Use only when you need detailed rule documentation
• ⚠️ list_pull_requests: Use sparingly, consider getting just PR numbers first

For MCP Server Developers

1. Add Summary/Detail Modes

Tools with severe bloat should support two modes:

// Summary mode (default for lists)
list_code_scanning_alerts({ summary: true })
// Returns: { number, rule.id, severity, state } - ~100 tokens per alert

// Detail mode (explicit opt-in)
get_code_scanning_alert({ alertNumber: 539 })
// Returns: Full rule documentation, instances, locations

2. Reduce Redundant Nesting

list_pull_requests should use repository references instead of full objects:

// Current (bloated)
{ head: { repo: { /* full repo object */ } }, base: { repo: { /* full repo object */ } } }

// Proposed (efficient)
{ head_repo_id: 1036865607, base_repo_id: 1036865607, head_ref: "...", base_ref: "..." }

3. Fix Permission Documentation

get_me consistently fails with 403 errors. Either:

• Document that it requires different token permissions
• Remove it from the available tools for workflow contexts
• Provide a fallback that returns minimal user context

For Optimal Context Usage

Context Budget Guidelines:

Token Range	Tool Category	Example Tools
<100	Ultra-efficient	get_label, list_branches, list_tags
100-500	Efficient	get_file_contents, list_commits, search
500-5K	Moderate	list_discussions, list_issues, list_workflows
5K-15K	Heavy	list_pull_requests (use sparingly)
>15K	Bloat	list_code_scanning_alerts (avoid for lists)

Sample Agentic Workflow Context Budget:

For a typical 200K context window:

• 30 file reads (150 tokens each) = 4.5K tokens
• 10 issue lookups (5K each) = 50K tokens
• 5 branch/tag checks (50-90 each) = ~400 tokens
• 2 workflow queries (5.8K each) = 11.6K tokens
• Total: ~66K tokens (33% of budget)
• Remaining: 134K for actual code analysis and decision-making

Historical Patterns (30-Day Window)

Data Coverage:

• Date Range: January 5 - February 2, 2026
• Total Data Points: 239 measurements
• Unique Tools: 21 different tools tested
• Unique Toolsets: 12 categories analyzed

Notable Events:

1. Jan 12: list_releases catastrophic bloat (282K tokens for single release with 14 binary assets)
2. Jan 15: Pull requests showed extreme nesting (69K tokens for perPage=1)
3. Jan 16: More granular tool testing introduced (workflow runs, commits, search)
4. Jan 23-30: Stable measurement period with consistent patterns
5. Feb 2: Current analysis shows improved balance

Trend Direction:

• Token usage has stabilized after early spikes
• Average usefulness rating remains steady at 4.0/5
• Best practices emerging: prefer repos, labels, discussions toolsets
• Problem areas identified: code_security needs optimization

Next Steps

1. Immediate: Avoid get_me and list_code_scanning_alerts in agentic workflows
2. Short-term: Prefer repos, labels, and discussions toolsets for efficiency
3. Long-term: Advocate for summary/detail modes in bloated endpoints

This analysis will continue tracking MCP structural efficiency daily. Historical data is maintained in a 30-day rolling window at /tmp/gh-aw/cache-memory/mcp_analysis.jsonl.

References:

• §21587890521

AI generated by GitHub MCP Structural Analysis

• expires on Feb 9, 2026, 11:22 AM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-02-09T11:22:23.210Z.

Closed by Workflow