Discover the user's accessible team_id values, team names, school/club organizations, conferences, and coaching roles at the start of an analysis workflow.

Verify which team is currently marked active before calling list_volleyball_matches.

Do NOT use to search for external opponent teams or public league rosters not tied to the user's account; call list_volleyball_matches to inspect opponents on your match schedule.

Do NOT call before every match query once team_id is known, as list_volleyball_matches automatically resolves the active team when team_id is omitted.

Execution Contract: Strictly read-only, idempotent HTTPS GET against https://api.volleymetrics.hudl.com.

Caching Policy: Cached on local disk (~/.volleymetrics_mcp/cache) with a 15-minute TTL (900s). Set force_refresh=True only after account membership changes.

Rate Limiting: Governed by a client-side token bucket (2 req/s, burst capacity 4) with exponential backoff on HTTP 429/5xx.

Authentication: Reads Bearer JWT credentials from ~/.volleymetrics_mcp/auth_state.json, OS Keychain, or .env.

Pass the team_id returned by this tool into list_volleyball_matches, get_match_player_stats, or get_rotation_breakdown when the user coaches multiple squads and wants to switch away from their default active team.

Prefer output_format='compact' when chaining team discovery into automated multi-step tool calls to save context tokens.

'markdown': Markdown table with columns Team ID, Team Name, School / Club, Conference, Role, and Active.

'compact': JSON object {"active_team_id": str, "count": int, "teams": [{"team_id": str, "name": str, "school_name": str, "conference": str, "role": str, "is_current": bool}]}.

On missing or expired credentials (HTTP 401/403), returns an actionable ⚠️ Authentication Error instructing the agent to invoke login_to_volleymetrics.

Discover valid match_id identifiers (e.g. '771842') required by all match-level analytics and export tools.

Review season win/loss records, set scores, match dates, opponent names, and whether video breakdown (.dvw) tagging is complete.

Do NOT use to retrieve athlete box scores or hitting percentages; pass a discovered match_id to get_match_player_stats.

Do NOT use to evaluate P1–P6 sideout or point-scoring percentages; pass match_id to get_rotation_breakdown.

Do NOT use to inspect individual rally touches; pass match_id to get_game_actions.

Execution Contract: Strictly read-only, idempotent HTTPS GET query.

Auto-Resolution: When team_id is None, resolves the active team from ~/.volleymetrics_mcp/auth_state.json, .env, or the user profile endpoint.

Caching Policy: Cached on local disk for 15 minutes (900s). Set force_refresh=True when checking if a newly uploaded match has finished processing.

Rate Limiting: Client token bucket (2 req/s, burst 4) with automatic retry on HTTP 429/5xx.

Only matches where has_dvw (DVW Ready) is True contain full play-by-play event tags for get_game_actions, get_rotation_breakdown, and download_match_dvw.

Increase limit (up to 50) when aggregating full-season trends across all matches.

'markdown': Markdown table with columns Match ID, Date, Opponent, Result, Set Scores, Season, and DVW Ready.

'compact': JSON object {"team_id": str, "count": int, "matches": [{"match_id": str, "date": str, "opponent": str, "result": str, "sets": [str], "season": str, "has_dvw": bool}]}.

Returns ⚠️ Authentication Error on HTTP 401/403 (recover via login_to_volleymetrics).

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.

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.

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.

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.

'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.

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.

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.

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.

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.

'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.

Inspect granular play-by-play contacts, video timestamps, start/end court zones (1–9), attack combinations, and DataVolley codes (e.g. *17AT#, a07SM=).

Filter specific tactical subsets, such as all reception errors (action_type='receive', quality='error'), clutch kills in Set 5 (set_number=5, action_type='attack', quality='kill'), or an individual hitter's shot tendencies (player='17', action_type='attack').

Do NOT page through all match touches just to compute a player's kill or dig totals; call get_match_player_stats in a single request instead.

Do NOT use for P1–P6 sideout summary tables; call get_rotation_breakdown instead.

Do NOT use when the user wants a .dvw file saved to disk for external software; call download_match_dvw instead.

Execution Contract: Strictly read-only, idempotent query.

Caching Policy: Raw match touch timelines are cached on local disk for 7 days (604800s); all filtering and pagination execute locally in memory after the initial fetch.

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

All provided filter parameters (set_number, action_type, player, team, quality) combine via logical AND before offset and limit pagination are applied.

The response header always reports total_matching alongside returned_count so you know whether to advance offset (offset + limit) for additional pages.

'markdown': Summary counts by action type followed by a table with columns #, Set, Score, Time, Team, Player, Action, Quality, DVW Code, and Tactical Details.

'compact': JSON object {"match": str, "total_matching": int, "returned_count": int, "by_type": dict, "events": [{"idx": int, "set": int, "score": str, "time": float, "team": str, "no": str, "player": str, "type": str, "quality": str, "dvw": str, "zone": str, "fbso": bool}]}.

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

Save an authentic .dvw file ([3DATAVOLLEYSCOUT] format) to disk for import into DataVolley 4, VolleyStation, Click&Scout, or OpenVolley / R / Python (datavolley) pipelines.

Archive raw match scouting files locally.

Do NOT use when you only need to analyze player stats, rotations, or touches inside the chat; call get_match_player_stats, get_rotation_breakdown, or get_game_actions instead to avoid unnecessary filesystem writes.

Do NOT call if has_dvw is False in list_volleyball_matches.

Side Effects: Remote Volleymetrics interaction is strictly read-only (GET), but this tool writes a local file named match_<match_id>.dvw inside output_dir (hence readOnlyHint=False, destructiveHint=False, idempotentHint=True).

Path Sanitization: Strips unsafe characters from match_id and resolves output_dir via Path.expanduser().resolve() to prevent path traversal.

Fallback Generation: If the native .dvw endpoint returns plain JSON events, automatically synthesizes a standards-compliant .dvw file containing match metadata and [3SCOUT] codes.

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

Acquire match_id from list_volleyball_matches first; pass an explicit output_dir when organizing exports for a specific opponent or tournament folder.

Returns a Markdown confirmation containing Match ID, resolved absolute Local File path, and File Size in bytes.

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

Recover from ⚠️ Authentication Error (401) returned by any Volleymetrics query tool.

Perform initial setup without storing plaintext passwords in .env (supports 1Password, Bitwarden, Apple Passwords / iCloud Keychain, Hudl SSO, and two-factor authentication).

Do NOT call proactively before every query; persisted sessions in ~/.volleymetrics_mcp/auth_state.json remain valid across conversations until token expiry.

Do NOT call in headless CI/server environments without a local display; use refresh_volleymetrics_session with .env credentials instead.

Side Effects: Launches a visible Playwright Chromium window to https://portal.volleymetrics.hudl.com, writes captured Bearer tokens and active team metadata to ~/.volleymetrics_mcp/auth_state.json (permissions 0600) and OS Keychain, and clears the local disk query cache (clear_all_cache()).

Zero Password Exposure: Credentials and 2FA codes are entered directly in the browser by the user and are never read or logged by the MCP server.

Auto-Close & Timeout: Automatically closes the browser the instant a valid JWT session is detected on the dashboard, or aborts after timeout_seconds.

Keep the default timeout_seconds=300 (5 minutes) when the user needs time to approve mobile 2FA prompts; reduce to 60–120 for quick password-manager autofill.

On success: Markdown summary reporting Storage State Saved path and Masked Session Token (eyJhbGci...).

On failure/timeout: Actionable error describing whether Playwright Chromium is missing (playwright install chromium) or the login window timed out.

Refresh an expired Volleymetrics Bearer token in headless or automated environments where VOLLEYMETRICS_EMAIL and VOLLEYMETRICS_PASSWORD are configured in .env.

Test whether stored .env credentials can mint a fresh token without user interaction.

Do NOT use when the user authenticates via password manager, Hudl SSO, or 2FA without storing plaintext credentials in .env; call login_to_volleymetrics instead.

Do NOT call in a loop if this tool returns Interactive Login Recommended, as that indicates .env credentials are not configured.

Side Effects: Executes an OAuth password-grant token request (or headless Playwright fallback), persists the new JWT to OS Keychain and .env (chmod 0600), and optionally clears the local response cache when clear_cache=True.

Fallback Guidance: If .env credentials are absent, performs zero network calls and immediately directs the agent to call login_to_volleymetrics.

Leave clear_cache=True when recovering from an authentication error or switching accounts; set clear_cache=False to retain cached 7-day historical match data across token renewals.

On success: Confirmation message with masked JWT (eyJhbGci...).

When .env credentials are missing or rejected: Actionable instructions to invoke login_to_volleymetrics.