Skip to main content
Glama
Sign In
Volleymetrics MCP Server

Volleymetrics MCP Server

by onnobos
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Get Match Rotation Breakdown (P1-P6)

get_rotation_breakdown
Read-onlyIdempotent

Analyze team sideout, point-scoring, and first-ball sideout efficiencies by setter rotation P1–P6 for a match to identify rotations leaking points or generating scoring runs.

Instructions

Fetch team tactical sideout, point-scoring, and first-ball sideout (FBSO) efficiencies broken down across setter rotations P1 through P6 for a match, unlike get_match_player_stats (individual player box scores) or get_game_actions (event-level rally touches).

When to Use

  • Diagnose which setter rotation (P1 through P6) is leaking sideout points or generating service scoring runs.

  • Compare Sideout Percentage (Sideout%), First-Ball Sideout Percentage (FBSO%), Point Scoring Percentage (Point Score%), and Setter Distribution tendencies (Left/OH, Middle, Right/Opp, Pipe/Backrow) by rotation.

When NOT to Use

  • Do NOT use for individual athlete kill/dig/pass totals; call get_match_player_stats instead.

  • Do NOT use to inspect which specific player committed reception or attack errors inside a weak rotation; call get_game_actions after identifying the rotation here.

Behavioral Guarantees & Caching

  • Execution Contract: Strictly read-only, idempotent query.

  • Domain Conventions: P1–P6 denote the setter's starting court zone (P1 = Zone 1 right-back, P6 = Zone 6 middle-back, P5 = Zone 5 left-back, P4 = Zone 4 front-left, P3 = Zone 3 front-center, P2 = Zone 2 front-right).

  • Caching Policy: Cached on local disk for 7 days (604800s).

  • Rate Limiting: Client token bucket (2 req/s, burst 4) with automatic retry.

Parameter & Workflow Semantics

  • Typical coaching workflow: call get_rotation_breakdown first to find any rotation with Sideout% < 50%, then call get_game_actions(match_id=..., action_type='receive', quality='error') to pinpoint the exact breakdown cause.

Returns & Error States

  • 'markdown': Table with columns Rotation, SO Opp, SO Pts, Sideout%, FBSO%, Srv Opp, Srv Pts, Point Score%, and Setter Distribution.

  • 'compact': JSON object {"match_id": str, "rotations": [{"rot": str, "so_opp": int, "so_pts": int, "so_pct": float, "fbso_pct": float, "ps_opp": int, "ps_pts": int, "ps_pct": float, "dist": dict}]}.

  • Returns validation error if match_id is empty, or ⚠️ Authentication Error on HTTP 401/403.

Input Schema

NameRequiredDescriptionDefault
team_idNoOptional Volleymetrics team ID (from get_user_teams) to filter P1-P6 rotation analytics to a specific squad. When omitted, analyzes the default primary team in the match.
match_idYesUnique Volleymetrics match identifier obtained from list_volleyball_matches.
force_refreshNoWhen True, bypasses the 7-day local disk cache and recalculates rotation metrics from live Volleymetrics data.
output_formatNoResponse representation format: 'markdown' renders a P1-P6 tactical efficiency table; 'compact' returns a token-efficient JSON object.markdown

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

Beyond the annotations (readOnly/idempotent/non-destructive), the description discloses caching behavior (7-day local disk, 604800s), rate limiting (2 req/s, burst 4, automatic retry), the domain convention mapping P1–P6 to court zones, and error states (validation error on empty `match_id`, authentication error on HTTP 401/403). These are operationally relevant traits an agent could not infer from structured fields.

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?

Content is front-loaded in the first sentence and organized under clear headings, with no filler prose. It is on the long side, and the full P1–P6 court-zone enumeration plus repeated field-name lists add bulk that a shorter table reference could cover, but each section carries usable 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?

For a read-only analytics query with no output schema, the description covers the dimensions needed to call it correctly: purpose, exclusions, return formats with concrete fields, caching/refresh semantics, and error states. Nothing an agent needs in order to invoke it successfully 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 coverage is 100%, so the baseline is 3; the description adds value by spelling out concrete return shapes per `output_format` value (markdown table columns vs. the compact JSON object), which helps an agent choose the format. It also frames `team_id`/`match_id` around the rotation-analysis workflow, though the individual parameter definitions themselves live in the schema.

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?

States a specific verb and resource ('Fetch team tactical sideout, point-scoring, and first-ball sideout (FBSO) efficiencies broken down across setter rotations P1 through P6 for a match') and explicitly names the two siblings it is not: `get_match_player_stats` for individual box scores and `get_game_actions` for event-level touches. An agent can distinguish it 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?

Provides dedicated 'When to Use' and 'When NOT to Use' sections with explicit routing: player kill/dig/pass totals go to `get_match_player_stats`, and identifying the specific player who erred in a weak rotation goes to `get_game_actions`. It also gives a concrete diagnostic threshold workflow (find `Sideout% < 50%`, then drill down with `get_game_actions(action_type='receive', quality='error')`).

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

Deploy Server

Other Tools