MCP Structural Analysis - December 23, 2025

[github-actions[bot]]

Today's analysis evaluated 10 GitHub MCP tools across 9 toolsets, measuring both response sizes and structural usefulness for agentic workflows. Key finding: Most tools (60%) achieve excellent ratings (5/5), but list_code_scanning_alerts remains problematic at 29,700 tokens per call due to embedded documentation.

Full Structural Analysis Report

Executive Summary

Metric	Value
Tools Analyzed	10
Total Tokens (Today)	45,430
Average Usefulness Rating	4.1/5
Best Rated Tools	6 tools @ 5/5 ⭐⭐⭐⭐⭐
Worst Rated Tool	get_me: 1/5 (403 error)
Most Efficient Tool	get_label: 30 tokens
Most Verbose Tool	list_code_scanning_alerts: 29,700 tokens

Usefulness Ratings for Agentic Work

⭐⭐⭐⭐⭐ Excellent (Rating: 5/5)

Tool	Toolset	Tokens	Assessment
get_label	labels	30	Most efficient tool tested. Minimal data with four essential fields. Perfect for label operations.
list_branches	repos	55	Minimal branch data. Three essential fields. Perfect efficiency. No bloat.
list_discussions	discussions	130	Clean structure with pagination. Category info embedded. Excellent for discovery.
list_workflows	actions	170	Compact workflow listing. Essential fields with URL. Perfect balance of completeness and efficiency.
search_repositories	search	420	Efficient search with minimal_output default. Essential repo metadata with topics. Well-structured for discovery.
get_file_contents	repos	1,100	Returns file as MCP resource. Clean content delivery. Perfect for agents needing repository files.

Analysis: These 6 tools represent the gold standard for agentic workflows - minimal overhead, clear structure, immediately actionable data.

⭐⭐⭐⭐ Good (Rating: 4/5)

Tool	Toolset	Tokens	Assessment
list_issues	issues	4,800	Very comprehensive with full body text (5,800+ chars). Nested user and label objects. Rich but verbose due to large body content. Structure excellent, but context-heavy.
list_pull_requests	pull_requests	9,000	Extremely detailed with deep nesting. Full repo objects in head/base. Very long body (3,500+ chars). Rich but extremely verbose even with perPage=1. Context-heavy for basic operations.

Analysis: These tools provide comprehensive data but at a high token cost. The full body text in issues/PRs can be massive. Agents should use these selectively or consider fetching minimal data first, then requesting full details only when needed.

⭐⭐ Limited (Rating: 2/5)

Tool	Toolset	Tokens	Assessment
list_code_scanning_alerts	code_security	29,700	EXTREMELY verbose - 118,915 characters total. Includes full rule documentation with examples, recommendations, and references for EVERY alert. Core data completely buried in educational content. Desperately needs minimal_output option.

Analysis: This tool is problematic for agentic workflows. A single call with just a few alerts can consume 30K+ tokens due to embedded documentation that repeats for each alert. Agents should check alert counts first and fetch individual alerts when needed.

⭐ Poor (Rating: 1/5)

Tool	Toolset	Tokens	Assessment
get_me	context	25	403 error - not accessible with current permissions. Cannot use for agentic workflows in GitHub App token context.

Analysis: This tool is unavailable in workflow contexts using GitHub App tokens. Not useful for this environment.

Schema Analysis

Tool	Type	Depth	Key Fields	Nesting Assessment
get_label	object	1	color, description, id, name	✅ Flat, optimal
list_branches	array	1	name, sha, protected	✅ Flat, optimal
list_workflows	object_with_array	2	total_count, workflows, id, name, path	✅ Shallow, clean
list_discussions	object_with_array	3	discussions, pageInfo, totalCount, number, title	✅ Moderate, well-structured
search_repositories	object_with_array	3	total_count, items, name, full_name, description	✅ Moderate, efficient
get_file_contents	resource	1	content, sha	✅ MCP resource, clean
list_issues	object_with_array	4	issues, pageInfo, number, title, body, labels, user	⚠️ Deep nesting with embedded objects
list_pull_requests	array	5	number, title, user, head, base, assignees	⚠️ Very deep with full repo objects
list_code_scanning_alerts	array	4	number, rule, tool, state, most_recent_instance	⚠️ Deep with massive documentation

Key Findings:

• Flat structures (depth 1-2) are ideal for agents: faster parsing, lower complexity
• Moderate nesting (depth 3) is acceptable when it provides logical grouping
• Deep nesting (depth 4-5) creates complexity, especially when combined with large payloads

Response Size Analysis by Toolset

Toolset	Avg Tokens	Rating	Tools Tested
labels	30	5.0 ⭐⭐⭐⭐⭐	get_label
context	25	1.0 ⭐	get_me (error)
repos	578	5.0 ⭐⭐⭐⭐⭐	get_file_contents, list_branches
discussions	130	5.0 ⭐⭐⭐⭐⭐	list_discussions
actions	170	5.0 ⭐⭐⭐⭐⭐	list_workflows
search	420	5.0 ⭐⭐⭐⭐⭐	search_repositories
issues	4,800	4.0 ⭐⭐⭐⭐	list_issues
pull_requests	9,000	4.0 ⭐⭐⭐⭐	list_pull_requests
code_security	29,700	2.0 ⭐⭐	list_code_scanning_alerts

Tool-by-Tool Detailed Analysis

Excellent Tools (Use Freely)

get_label (30 tokens, 5/5)

• Structure: Simple object with 4 fields
• Why it's great: Absolutely minimal. Returns exactly what's needed, nothing more.
• Agent recommendation: Use freely for label operations.

list_branches (55 tokens, 5/5)

• Structure: Array of objects with 3 fields each
• Why it's great: Essential branch data only. No unnecessary metadata.
• Agent recommendation: Perfect for branch discovery and management.

list_discussions (130 tokens, 5/5)

• Structure: Object with array, pagination info, category embedded
• Why it's great: Clean pagination support, category context included.
• Agent recommendation: Excellent for discussion discovery. PerPage works correctly.

list_workflows (170 tokens, 5/5)

• Structure: Object with array, includes workflow metadata
• Why it's great: Compact listing with essential fields (id, name, path, state, url).
• Agent recommendation: Ideal for workflow discovery and management.

search_repositories (420 tokens, 5/5)

• Structure: Search results with metadata (total_count, items array)
• Why it's great: minimal_output works by default. Essential repo metadata with topics.
• Agent recommendation: Efficient for repository discovery. Use for finding relevant repos.

get_file_contents (1,100 tokens, 5/5)

• Structure: MCP resource with text content and SHA
• Why it's great: Direct file access. Clean content delivery with version tracking (SHA).
• Agent recommendation: Perfect for reading repository files. Use for configuration, documentation, code review.

Good Tools (Use Selectively)

list_issues (4,800 tokens, 4/5)

• Structure: Object with array, deep nesting (4 levels)
• Why it's good: Comprehensive data including full body text, labels, user info.
• Caveat: Body can be 5,800+ characters. Single issue with perPage=1 consumed 4,800 tokens.
• Agent recommendation: Use with low perPage values. Consider fetching titles first, then full details only for issues you need to analyze.

list_pull_requests (9,000 tokens, 4/5)

• Structure: Array with deep nesting (5 levels), includes full repo objects
• Why it's good: Very comprehensive with branch info, assignees, labels, full body.
• Caveat: Extremely verbose. Single PR with perPage=1 consumed 9,000 tokens. Full repo metadata duplicated in head/base branches.
• Agent recommendation: Use sparingly. Fetch PR list with minimal data first, then get full details only when needed. Consider using get_pull_request for specific PRs instead of listing.

Limited Tools (Use Cautiously)

list_code_scanning_alerts (29,700 tokens, 2/5)

• Structure: Array with deep nesting (4 levels), massive documentation embedded
• Why it's limited: 118,915 characters total. Includes full rule documentation, help text with examples, markdown formatting, and references in EVERY alert.
• Problem: Core alert data (number, state, location) is only ~500 tokens. The remaining 29,200 tokens are educational content that repeats for each alert.
• Agent recommendation: Check alert count first. If > 5 alerts, this tool becomes unusable. Consider using get_code_scanning_alert to fetch individual alerts instead. Desperately needs a minimal_output option to exclude documentation.

Unavailable Tools

get_me (25 tokens error, 1/5)

• Structure: Error response (403)
• Why it fails: Not accessible with GitHub App integration tokens used in workflows.
• Agent recommendation: Do not use in workflow contexts. Use repository/organization context instead.

30-Day Trend Summary

Metric	Value
Total Data Points	197
Date Range	Nov 26 - Dec 23, 2025
Average Daily Total Tokens	18,028
Most Consistent Tool	get_label (28-35 tokens)
Most Variable Tool	list_code_scanning_alerts (5-29,700 tokens)

Trend: Response sizes are generally stable, indicating consistent API behavior. The main variability comes from content-dependent tools (issues/PRs with long bodies, security alerts with many findings).

Recommendations

For Optimal Agentic Workflows

1. High-value, low-cost tools (Rating 5, <500 tokens):

• get_label - Label operations
• list_branches - Branch discovery
• list_discussions - Discussion discovery
• list_workflows - Workflow discovery
• search_repositories - Repository search

2. Context-efficient tools (High rating, reasonable cost):

• get_file_contents - File reading (1,100 tokens)

3. Use selectively (High cost but valuable):

• list_issues - Limit perPage, fetch titles first
• list_pull_requests - Limit perPage, use for specific PRs only

4. Avoid or use extreme caution (Very high cost):

• list_code_scanning_alerts - Check count first, fetch individually

Tool Selection Strategy for Agents

Discovery Phase (Minimize Context):

• Use: list_workflows, list_branches, list_discussions, get_label
• Use: search_repositories with minimal_output
• Avoid: Full issue/PR listings, security alert listings

Analysis Phase (Targeted Fetches):

• Use: get_file_contents for specific files
• Use: list_issues with perPage=5-10 for targeted analysis
• Use: Individual get operations (e.g., get_pull_request) over list operations

Context Management:

• Always use perPage parameter for list operations
• Start with minimal data, expand only when needed
• Prefer specific gets over broad lists

Improvements Needed

Critical: list_code_scanning_alerts needs minimal_output option

• Current: 29,700 tokens with documentation
• Ideal: ~500 tokens with just alert data
• Impact: 98% reduction in token usage

Nice to have: Body truncation option for issues/PRs

• Current: Full body text (up to 10K+ chars)
• Ideal: First 500 chars + truncation indicator
• Impact: 50-80% reduction for verbose issues

Visualizations

Average Response Size by Toolset

This chart shows the dramatic difference between toolsets. Code security tooling averages 29,700 tokens per call due to embedded documentation, while most other toolsets stay under 1,000 tokens.

Usefulness Ratings by Toolset

Six toolsets achieve perfect 5/5 ratings for agentic workflows. Issues and PRs rate 4/5 due to verbosity. Code security rates 2/5 due to extreme overhead.

Daily Token Usage Trend (30 Days)

Token usage remains stable day-to-day, with spikes when code scanning alerts are tested. Average daily testing consumes ~18K tokens.

Token Size vs Usefulness Rating

The ideal tools cluster in the bottom-left: low tokens, high usefulness. Note that usefulness doesn't necessarily correlate with size - get_file_contents at 1,100 tokens is as useful as get_label at 30 tokens.

Top 10 Tools by Response Size

list_code_scanning_alerts dominates at 29,700 tokens - 3x larger than the next tool. Most tools stay under 2,000 tokens.

---

References:

• Workflow Run §20458959938

AI generated by GitHub MCP Structural Analysis

[github-actions[bot]]

This discussion was automatically closed because it was created by an agentic workflow more than 3 days ago.