Skip to main content
Glama
Sign In
onnobos

Volleymetrics MCP Server

by onnobos
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Get Match Tagged Game Actions

get_game_actions
Read-onlyIdempotent

Query chronological volleyball play-by-play touches and DataVolley tags from a match, filtering by set, skill, player, team, or quality to inspect specific tactical events.

Instructions

Query chronologically ordered, event-by-event volleyball touches and DataVolley (.dvw) scout tags from a match with optional set, skill, player, team, and quality filters, unlike get_match_player_stats (aggregate player totals) or download_match_dvw (raw .dvw file export to disk).

When to Use

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

When NOT to Use

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

Behavioral Guarantees & Caching

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

Parameter & Workflow Semantics

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

Returns & Error States

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

Input Schema

NameRequiredDescriptionDefault
teamNoOptional team filter: 'a' (home/primary team), 'b' (away/opponent team), or team name substring.
limitNoMaximum number of chronological touch events to return per page (1 to 200).
offsetNoZero-based pagination offset for stepping through chronological match touches.
playerNoOptional athlete filter matching jersey number (e.g. '17' or '#7') or case-insensitive player name substring.
qualityNoOptional outcome/evaluation filter mapping to DataVolley evaluation codes: 'kill' (# on attack/block), 'error' (=), 'ace' (# on serve), 'perfect_pass' (# on receive), 'assist', or 'in_play'.
match_idYesUnique Volleymetrics match identifier obtained from list_volleyball_matches.
set_numberNoOptional set number (1 to 5) to restrict play-by-play touches to a single set. When None, searches across all sets.
action_typeNoOptional volleyball skill filter mapping to DataVolley skill codes: 'serve' (S), 'receive' (R), 'set' (E), 'attack' (A), 'block' (B), 'dig' (D), or 'free_ball' (F).
force_refreshNoWhen True, bypasses the 7-day local disk cache and fetches raw match events directly from Volleymetrics.
output_formatNoResponse representation format: 'markdown' renders a chronological play-by-play table; 'compact' returns a token-efficient JSON object with total count and filtered breakdown.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?

Goes well beyond the annotations: discloses a 7-day/604800s local disk cache, in-memory post-fetch filtering, a 2 req/s token bucket with burst 4 and auto-retry, and the `force_refresh` bypass. It also documents error states (empty `match_id` validation error, ⚠️ Authentication Error on 401/403), which annotations alone cannot convey.

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?

Well front-loaded and sectioned with headers, and the deliberate routing sentence comes first. It is long, and the return-format section repeats DataVolley code examples already used earlier, but nearly every line carries operational value for a 10-parameter tool.

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?

With no output schema, the description carries the full burden of describing return values, and it does so for both `markdown` and `compact` modes with the exact JSON key set. Combined with caching, rate-limit, pagination and error behavior, nothing an agent needs to invoke 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 coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema cannot express: all filters combine via logical AND before pagination, and the response header reports `total_matching` so the caller advances `offset` by `offset + limit`. It stops short of adding per-parameter detail beyond the schema, so a 4 rather than 5.

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?

Opens with a specific verb and resource ('Query chronologically ordered, event-by-event volleyball touches and DataVolley scout tags') and scopes it to a match. It explicitly contrasts itself with `get_match_player_stats` and `download_match_dvw`, so an agent can disambiguate without opening any 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?

Has explicit 'When to Use' and 'When NOT to Use' sections with concrete filter examples (reception errors, Set 5 kills, hitter tendencies) and names three alternative tools with the exact condition that selects each.

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