Volleymetrics MCP Server

Overview Schema Source Related Servers Discussions Admin

Get Match Player Box Score

get_match_player_stats

Read-onlyIdempotent

Fetch individual athlete box scores and volleyball stats for a single match to evaluate player performance in attacking, serving, passing, blocking, and digging.

Instructions

Fetch aggregated athlete box scores and individual volleyball statistics (attacking, serving, passing, blocking, and digging totals) for a single match, unlike get_rotation_breakdown (team P1–P6 rotation efficiencies) or get_game_actions (chronological touch-by-touch events).

When to Use

Evaluate individual player performance in a match: Kills (K), Attack Errors (E), Total Attacks (TA), Hitting Percentage ((K - E) / TA), Assists (Ast), Service Aces (SA), Service Errors (SE), Receptions (Rec), Reception Errors (RE), Passing Average (0.00–3.00 scale), Digs (Dig), Block Solos (BS), Block Assists (BA), Total Blocks (TB), and Total Points (Pts).
Identify top scorers, pin/middle offensive efficiency, and primary serve-receive passers.

When NOT to Use

Do NOT use to analyze team sideout or point-scoring rates by setter rotation (P1–P6); call get_rotation_breakdown instead.
Do NOT use to inspect individual rally touches, court zones, or set-by-set play sequences; call get_game_actions instead.
Do NOT call with an unknown match_id; call list_volleyball_matches first.

Behavioral Guarantees & Caching

Execution Contract: Strictly read-only, idempotent query.
Derived Metric Integrity: Automatically computes zero-division-safe Hitting Percentage (0.000 when TA == 0), Total Blocks (BS + 0.5 * BA), and Total Points (K + SA + BS + 0.5 * BA).
Caching Policy: Historical match stats are cached on local disk for 7 days (604800s).
Rate Limiting: Client token bucket (2 req/s, burst 4) with exponential backoff.

Parameter & Workflow Semantics

Combine match_id (from list_volleyball_matches) with team_id (from get_user_teams) when you want to isolate a single team's roster; leave team_id=None when comparing both teams head-to-head.

Returns & Error States

'markdown': Box score table with columns #, Player, Pos, SP, K, E, TA, Hit%, Ast, SA, SE, Rec, RE, Pass Avg, Dig, BS, BA, TB, and Pts.
'compact': JSON object {"match_id": str, "player_count": int, "players": [{"name": str, "no": str, "pos": str, "sp": int, "k": int, "e": int, "ta": int, "hit_pct": float, "ast": int, "sa": int, "se": int, "rec": int, "re": int, "pass_avg": float, "dig": int, "bs": int, "ba": int, "tb": float, "pts": float}]}.
Returns validation error if match_id is empty, or ⚠️ Authentication Error on HTTP 401/403.

Input Schema

Name	Required	Description	Default
`team_id`	No	Optional Volleymetrics team ID (from get_user_teams) to restrict athlete box scores to one squad. When omitted, returns athlete statistics for all participating players in the match.
`match_id`	Yes	Unique Volleymetrics match identifier obtained from list_volleyball_matches.
`force_refresh`	No	When True, bypasses the 7-day local disk cache for historical match box scores and forces a live API fetch.
`output_format`	No	Response representation format: 'markdown' renders a standard volleyball box score table; 'compact' returns a token-efficient JSON array of athlete stat objects.	markdown

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 3, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), yet the description adds substantial context beyond them: a 7-day local disk cache with the exact TTL (604800s), a client token bucket of 2 req/s with burst 4 and exponential backoff, zero-division-safe derived-metric formulas, and concrete error states (validation error on empty match_id, Authentication Error on 401/403). The only redundancy is restating 'strictly read-only, idempotent', which annotations already declare.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded and well-sectioned with headers that let an agent skim to the relevant part, but it is long and partially redundant: the full stat-abbreviation glossary in 'When to Use' overlaps heavily with the column list in 'Returns', and 'Strictly read-only, idempotent query' repeats the annotations. Trimming those duplications would make it noticeably tighter without losing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Although there is no output schema, the description fully specifies both return shapes — the markdown column set and the exact compact JSON object shape including field names and types. Combined with caching, rate limits, derived-metric formulas, error states, and parameter workflow guidance, nothing an agent needs to call this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3, and the description earns a bump by adding workflow meaning the schema does not: combining `match_id` from `list_volleyball_matches` with `team_id` from `get_user_teams` to isolate one roster, and explicitly leaving `team_id=None` for head-to-head comparison. It does not add format or syntax detail for `force_refresh` or `output_format` beyond what the schema already says.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence states a specific verb and resource ('Fetch aggregated athlete box scores and individual volleyball statistics... for a single match') and immediately names the two sibling tools it is not (`get_rotation_breakdown` for team P1–P6 rotation efficiencies, `get_game_actions` for touch-by-touch events). An agent can distinguish this from every sibling without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'When to Use' and 'When NOT to Use' sections give the positive case (evaluate individual player performance, identify top scorers, primary pass-receive passers), name the alternative tool for each excluded case, and add a prerequisite ordering constraint ('Do NOT call with an unknown match_id; call list_volleyball_matches first'). Nothing is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server