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

Goes well beyond the annotations by disclosing the local write side effect and resulting filename pattern, path sanitization via expanduser/resolve, a fallback that synthesizes a compliant .dvw from JSON events, token-bucket rate limits (2 req/s, burst 4) with retry, and 401/403 error behavior. The annotations only declare the safety flags; the description explains what actually happens on disk and over the network.

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

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

Front-loaded with the core purpose, then cleanly sectioned under headers, so an agent can scan to the relevant block. Slightly over-long, and the parenthetical restating `readOnlyHint=False, destructiveHint=False, idempotentHint=True` duplicates structured annotation data rather than adding to it.

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

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

Covers the full lifecycle an agent needs for a file-writing export tool: precondition, parameters, side effects, failure modes, and the exact shape of the Markdown confirmation (Match ID, absolute path, file size). Nothing material is missing even though there is no output schema.

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

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 earns extra credit by adding workflow provenance for `match_id` (acquire from `list_volleyball_matches` first) and intent guidance for `output_dir` (organize by opponent or tournament folder). It does not add format constraints or edge cases for the path beyond what the schema already documents.

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

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

States a specific verb and resource ('Export and save the official raw DataVolley (.dvw) scouting file') and immediately contrasts it with the sibling `get_game_actions`, which returns parsed events instead of a file. The agent can distinguish this tool 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.

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

Provides explicit 'When to Use' and 'When NOT to Use' sections, naming concrete downstream consumers (DataVolley 4, VolleyStation, OpenVolley/R/Python) and three named alternatives (`get_match_player_stats`, `get_rotation_breakdown`, `get_game_actions`) with the condition that selects them. It also adds a hard precondition: do not call if `has_dvw` is False.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial context beyond them: an idempotent HTTPS GET contract, a 15-minute disk cache with TTL and when to bypass it, a token bucket with 2 req/s and burst 4 plus backoff on 429/5xx, and credential sources (auth_state.json, Keychain, .env). It also discloses the 401/403 error behavior and the remediation step (invoke `login_to_volleymetrics`).

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

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

Front-loaded with the one-line purpose and a sibling contrast, then cleanly sectioned by usage, behavior, parameters and returns. It is long, and the 'Returns' section partly duplicates the `output_format` enum descriptions already in the schema, but the bulk of the text carries non-redundant operational detail.

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

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

For a 2-parameter, zero-required discovery tool with no output schema, the description covers everything an agent needs: what comes back in both formats (with the compact JSON shape), when to call it, when not to, and how auth failures surface. Nothing material is missing.

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

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

Schema coverage is 100%, so 3 is the floor, and the description improves on it by giving decision rules rather than restating types: set `force_refresh=True` only after account membership changes, and prefer `output_format='compact'` when chaining team discovery into automated multi-step calls. That adds genuine selection guidance the schema lacks.

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

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

States a specific verb and resource ('Retrieve all Volleymetrics volleyball team profiles and organization memberships linked to the authenticated account') and immediately contrasts it with `list_volleyball_matches`, which lists match schedules for a single team. An agent can pick between the two 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.

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 name the alternatives (`list_volleyball_matches`) and the exact conditions selecting them, including the nuance that the sibling auto-resolves the active team when `team_id` is omitted. This is about as complete as routing guidance gets.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the 'strictly read-only, idempotent GET' line largely restates structured data. The description does add genuine context beyond annotations: the 15-minute disk cache and when to bypass it, team auto-resolution order, a 2 req/s token bucket with retry on 429/5xx, and the exact 401/403 recovery path via login_to_volleymetrics. The overlap with annotations keeps this from a 5.

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

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

The description is long but strongly front-loaded and uses section headers, so an agent can scan to the needed block. It is slightly padded by restating the read-only/idempotent contract that annotations already carry, which is wasted space rather than harmful.

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

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

There is no output schema, yet the description fully enumerates both return representations including column names and the exact compact JSON keys. Combined with caching, rate limits, auth failure handling, and the downstream dependency on has_dvw, an agent has everything needed to call this correctly and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents limit, team_id, force_refresh, and output_format. The description still adds cross-parameter meaning the schema lacks: that has_dvw must be True for downstream action-level tools to work, that limit can be raised to 50 for full-season aggregation, and the concrete shape of each output_format value. That is useful semantics layered on top of complete schema descriptions.

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

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

The description opens with a specific verb and resource ('List recent volleyball match schedules, opponent names, set scores, and DataVolley availability for a team') and explicitly positions itself as 'the primary match discovery step' before the analytics siblings. An agent can distinguish it from get_match_player_stats, get_rotation_breakdown, get_game_actions, and download_match_dvw 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.

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

Dedicated 'When to Use' and 'When NOT to Use' sections name each alternative sibling and the exact condition that routes to it (box scores, rotation sideout percentages, rally touches). It also states the dependency contract: all those tools require a match_id discovered here.

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

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

Annotations only declare it is non-readonly, open-world, non-idempotent and non-destructive; the description goes far beyond by naming the side effects (visible Playwright window, Bearer tokens written to ~/.volleymetrics_mcp/auth_state.json with 0600 permissions plus OS Keychain, and a full query-cache clear), the zero-password-exposure guarantee, and the auto-close/timeout behaviour. Success and failure return states including the missing-Chromium remedy are also disclosed, so no annotation contradiction arises.

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

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

Headings, bolding and the front-loaded contrast sentence make it scannable despite its length, and every section maps to something an agent needs. It is slightly over-written — the Returns section restates failure modes already implied and the opening sentence is dense — but nothing is truly wasteful for a tool with this many side effects.

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

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

A one-parameter, no-output-schema tool whose annotations are sparse is fully covered here: triggers, exclusions, side effects on disk and keychain, credential handling, timeout behaviour, and both success and failure outputs are all stated. Nothing an agent needs to decide whether and how to call it is missing.

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

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

Schema coverage is 100% and the single parameter is self-explanatory, yet the description adds real decision guidance beyond the schema: keep the default 300s when the user must approve mobile 2FA, drop to 60-120s for quick password-manager autofill. That is workflow meaning the schema's min/max/default numbers cannot convey.

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

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

The opening sentence pairs a specific verb (launch) with the resource (interactive desktop Chromium window for Volleymetrics/Hudl auth) and explicitly contrasts itself with the sibling `refresh_volleymetrics_session` as headless env-var-based. An agent can distinguish this from every sibling list tool 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.

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

Dedicated 'When to Use' and 'When NOT to Use' sections give concrete triggers (recover from a 401, initial setup without plaintext passwords) and explicit exclusions (don't call proactively; don't use in headless CI without a display, use refresh_volleymetrics_session instead). The alternative is named with the condition that selects it.

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

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

Annotations declare a non-read-only, open-world, non-idempotent operation but say nothing about side effects; the description fills that gap by disclosing the password-grant request, headless Playwright fallback, persistence of the JWT to OS Keychain and `.env` with `chmod 0600`, and conditional cache clearing. It also states the zero-network-call behavior when credentials are absent, which is exactly the kind of pre-call safety context annotations 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.

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

Well front-loaded and organized under scannable headings, with the key differentiator in the first sentence. It is somewhat long for a two-parameter tool, and the 'credentials missing' condition is restated three times (When NOT to Use, Fallback Guidance, Returns & Error States), which is mild redundancy.

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

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

For a mutation-style auth tool with no output schema, the description covers what the agent needs: trigger conditions, side effects, parameter choice, success confirmation format (masked JWT), and the actionable error path. Nothing material is left to inference.

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

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 decision-level meaning for `clear_cache` (set True when recovering from an auth error or switching accounts, False to retain 7-day cached match data) that goes beyond the schema's mechanical 'clears the cache after minting' wording. The `timeout_seconds` parameter is never mentioned in the description, which keeps this from a 5.

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

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

States a specific verb and resource (headless OAuth 2.0 token refresh for the Volleymetrics session) and immediately contrasts it with the sibling `login_to_volleymetrics`, which is described as the interactive desktop-browser alternative. An agent can distinguish the two without opening either schema.

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

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

Provides explicit 'When to Use' and 'When NOT to Use' sections, naming the exact conditions (headless/automated environments with `.env` credentials vs. password-manager/SSO/2FA users) and pointing to the concrete alternative tool. It also warns against looping on the 'Interactive Login Recommended' result.

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