Skip to main content
Glama

NBA player matchup card: play types and shot zones vs a defense

invoke_nba_player_matchup
Read-onlyIdempotent

Added after you connected: the first call asks you to approve it. One NBA player's matchup against one defense, from stats.nba.com Synergy play types and shot zones, calculated by BankrollSZN. His diet (share of his possessions by play type: PnR ball handler, transition, isolation, spot up and the rest; share of his shots by zone) next to what the opponent allows in each (points per possession or per shot vs the league average, and rank where 30 = allows the most). A PTS matchup score per part (Play, Zone) and a Blend: his shares weighted by the opponent's percent vs league, so +2% means the defense gives up about 2% more than average on the things he does. Also his minutes last 10 games, and his last two seasons of games against that team vs his overall average. No opponent = tonight's opponent. The current season blends with last season early on (sample weights shown). Batch: pass players (up to 15) for a whole lineup in one call. Slate: view slate ranks every player on today's slate by matchup score. Example: player Cade Cunningham, opponent CHA.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "invoke_nba_player_matchup"
  }
}

Input Schema

NameRequiredDescriptionDefault
sortNoslate view: best (default) or worst matchups first.
teamNoslate view: only this team.
viewNoslate = every player on today's slate ranked by matchup score (best first). Default player.
limitNoslate view: rows to return. Default 20. The plan limit applies on top.
playerNoPlayer name. Use for the full card of one player.
seasonNoSeason like 2025-26. Default the current season.
playersNoUp to 15 player names. Returns the matchup scores and best edges of every named player in one call. Use this instead of one call per player. (maxItems: 15)
opponentNoOpponent abbreviation (CHA, NY, GS). Default tonight's opponent.
min_proj_minNoslate view: only players projected for at least this many minutes. Default 15.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, so the description correctly focuses on computation instead: how the Blend is weighted, that the current season blends with last season early on with sample weights shown, and that a first call triggers an approval prompt. The approval caveat is genuinely useful operational context, though the wording 'Added after you connected' is vague about what exactly is being approved.

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

Conciseness3/5

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

Content is substantive but delivered as one long comma-spliced block with a confusing opening sentence about approval that precedes the actual purpose. The core statement of what the tool does should lead; instead the agent must read several clauses before learning it returns a matchup card.

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

Completeness4/5

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

For a 9-parameter, output-schema-less analytics tool, the description does substantial work: it explains the metric construction, defaults, output components (minutes, two seasons of head-to-head), and season blending. Minor gaps remain around what a return payload looks like or how plan limits interact with the batch size, but overall it is callable as written.

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

Parameters3/5

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

Schema coverage is 100% and every parameter — sort, team, view, limit, player, season, players, opponent, min_proj_min — is already documented there. The description's parameters-related claims (batch up to 15, default opponent, use players instead of one call per player) largely restate the schema; its genuine added value is about the scoring metric rather than parameter meaning, so the baseline 3 holds.

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 resource and scope: one NBA player's matchup against one defense, built from Synergy play types and shot zones, with named outputs (PTS matchup score per part, Blend, minutes, head-to-head history). It also carves out the two distinct modes (single player card vs. slate ranking vs. batch lineup), so an agent can tell what it will get without opening the schema.

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

Usage Guidelines4/5

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

Gives concrete routing cues: 'No opponent = tonight's opponent', 'Batch: pass players (up to 15) for a whole lineup in one call', 'Use this instead of one call per player', and 'Slate: view slate ranks every player'. What's missing is any exclusion against the many sibling tools (invoke_nba_matchup, invoke_nba_scheme_matchups, invoke_nba_projections), so the agent must infer when this beats those.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources