getcompetitive

Overview Schema Source Related Servers Discussions Admin

Batch damage matchups

calculate_matchups

Read-onlyIdempotent

Compare one attacker against up to 30 defenders, auto-selecting the hardest-hitting move for each to report damage range, KO chance, immunity, and speed order.

Instructions

Run one attacker against 1-30 defenders in a single call, picking the hardest-hitting move per defender from move or attacker.moves and reporting each matchup’s damage range, KO chance, immunity, and who moves first. Rows carry only those fields — they are structured rather than prose, so that 30 defenders do not cost thirty rendered sentences; call calculate_damage for the single matchup rendered as a Showdown-format line. Use calculate_damage too when side screens and hazards matter (this tool’s field has only gameType, weather, and terrain); use analyze_team for type-synergy, not damage, and calculate_stats for a stat table with no battle. Supply move or a non-empty attacker.moves, else the call errors; defender levels default to 100. Read-only, offline, deterministic; unknown species or move names return an isError naming the offender.

Input Schema

TableJSON Schema

Name	Required	Description
`move`	No	Pin the matchup to this one move, e.g. "Close Combat"; when omitted, `attacker.moves` is searched instead.
`field`	No	Shared battlefield conditions for every matchup; omit for a neutral Singles field. Side hazards and screens are only available on `calculate_damage`.
`attacker`	Yes	The single attacking Pokémon; set `moves` to let the tool choose the best move against each defender.
`defenders`	Yes	1-30 defender sets, each with the same fields as `attacker`; every entry is scored against the same attacker, move set, and field.

Output Schema

TableJSON Schema

Name	Required	Description
`move`	Yes	The fixed move both sides were scored with, or the literal "best of moveset" when the tool picked the hardest-hitting move per defender.
`attacker`	Yes	Canonical species name of the single attacker every matchup was run with.
`matchups`	Yes	One entry per defender, in the order the defenders were supplied.
`attackerSpeed`	Yes	The attacker’s final Speed stat; hoisted here because it is the same for every matchup, and `speed.attackerMovesFirst` compares it against each row’s `speed.defender`.

Schema Changelog

Changes observed during successful MCP inspections.

Changed12 schema fields changedv3.2.0Sep 18, 2026

removedInput schema / properties / attacker / properties / teraType

Removed value: -{
-  "description": "Tera type to use when the move is Terastallized, e.g. \"Fairy\".",
-  "type": "string"
-}

removedInput schema / properties / defenders / items / properties / teraType

Removed value: -{
-  "description": "Tera type to use when the move is Terastallized, e.g. \"Fairy\".",
-  "type": "string"
-}

removedInput schema / properties / generation

Removed value: -{
-  "default": 9,
-  "description": "Generation whose data to use, 1-9 (default 9). Earlier generations omit moves, items, abilities, and forms that did not exist yet.",
-  "maximum": 9,
-  "minimum": 1,
-  "type": "integer"
-}

addedOutput schema / properties / attackerSpeed

Added value: +{
+  "description": "The attacker’s final Speed stat; hoisted here because it is the same for every matchup, and `speed.attackerMovesFirst` compares it against each row’s `speed.defender`.",
+  "type": "number"
+}

removedOutput schema / properties / generation

Removed value: -{
-  "description": "Generation whose data and mechanics were used, 1-9.",
-  "maximum": 9007199254740991,
-  "minimum": -9007199254740991,
-  "type": "integer"
-}

changedOutput schema / properties / matchups / items / properties / bestMove / description

Previous value: -"The hardest-hitting move of the supplied move set against this defender, or null when none of them could be calculated (e.g. every move is unsupported in this generation)."New value: +"The hardest-hitting move of the supplied move set against this defender, or null when none of them could be calculated (e.g. every move is unsupported in the dataset)."

removedOutput schema / properties / matchups / items / properties / description

Removed value: -{
-  "description": "One-line summary of `bestMove` against this defender, e.g. \"252 Atk Garchomp Earthquake vs. 252 HP / 252+ Def Corviknight: 108-128 (27.9 - 33.1%)\"; when no move resolved it explains that instead.",
-  "type": "string"
-}

changedOutput schema / properties / matchups / items / properties / speed / description

Previous value: -"Who moves first in this matchup, from the two Speed stats alone."New value: +"Who moves first in this matchup, from the two Speed stats alone; the attacker’s side of the comparison is the top-level `attackerSpeed`."

removedOutput schema / properties / matchups / items / properties / speed / properties / attacker

Removed value: -{
-  "description": "The attacker’s final Speed stat, the same number in every matchup.",
-  "type": "number"
-}

changedOutput schema / properties / matchups / items / properties / speed / required

Previous value: -[
-  "attacker",
-  "defender",
-  "attackerMovesFirst"
-]New value: +[
+  "defender",
+  "attackerMovesFirst"
+]

changedOutput schema / properties / matchups / items / required

Previous value: -[
-  "defender",
-  "bestMove",
-  "damageRange",
-  "description",
-  "immune",
-  "speed"
-]New value: +[
+  "defender",
+  "bestMove",
+  "damageRange",
+  "immune",
+  "speed"
+]

changedOutput schema / required

Previous value: -[
-  "generation",
-  "attacker",
-  "move",
-  "matchups"
-]New value: +[
+  "attacker",
+  "attackerSpeed",
+  "move",
+  "matchups"
+]

Changed2 schema fields changedv2.0.2Sep 18, 2026

addedInput schema / properties / attacker / properties / championsPoints

Added value: +{
+  "additionalProperties": {
+    "type": "number"
+  },
+  "description": "Pokémon Champions stat points keyed by stat id (hp, atk, def, spa, spd, spe): whole numbers, each 0-32, totalling at most 66. This is the spread the game’s training screen takes, and an alternative to `evs` — give one or the other, not both. One point is worth 8 EVs, so a converted spread is trimmed from its largest stats to fit the 510 EV cap the calculator enforces.",
+  "propertyNames": {
+    "type": "string"
+  },
+  "type": "object"
+}

addedInput schema / properties / defenders / items / properties / championsPoints

Added value: +{
+  "additionalProperties": {
+    "type": "number"
+  },
+  "description": "Pokémon Champions stat points keyed by stat id (hp, atk, def, spa, spd, spe): whole numbers, each 0-32, totalling at most 66. This is the spread the game’s training screen takes, and an alternative to `evs` — give one or the other, not both. One point is worth 8 EVs, so a converted spread is trimmed from its largest stats to fit the 510 EV cap the calculator enforces.",
+  "propertyNames": {
+    "type": "string"
+  },
+  "type": "object"
+}

Addedv2.0.0Sep 17, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already provide readOnly/idempotent/destructive hints, and the description adds context beyond them: 'offline, deterministic', error behavior ('unknown species or move names return an isError naming the offender'), output shape ('rows are structured rather than prose'), and a field limitation (only gameType/weather/terrain, no side screens/hazards). No contradiction with annotations.

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

Conciseness5/5

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

Front-loaded with the core action in the first sentence, then output format, sibling routing, prerequisites, and error behavior in tight sequence. Every sentence carries distinct information; there is no filler or redundant elaboration despite the description's length.

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 complex nested-parameter tool, the description covers selection logic, batch size, output fields, defaults, error behavior, and exactly which sibling to use in each situation. An output schema exists, so return-value detail is unnecessary; nothing an agent needs to invoke this safely is missing.

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%, so the baseline is 3. The description mostly restates schema details ('defender levels default to 100', field contains only gameType/weather/terrain) rather than adding new parameter meaning; the move-vs-attacker.moves selection logic is also already in the schema. It provides no significant extra parameter semantics beyond what the schema documents.

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 precise verb+resource: 'Run one attacker against 1-30 defenders in a single call, picking the hardest-hitting move per defender from move or attacker.moves' and enumerates exact outputs (damage range, KO chance, immunity, who moves first). It also names sibling tools (calculate_damage, analyze_team, calculate_stats) to draw clear boundaries, so an agent can distinguish this tool without opening schemas.

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?

Explicitly routes usage: 'call calculate_damage for the single matchup rendered as a Showdown-format line', 'Use calculate_damage too when side screens and hazards matter', and 'use analyze_team for type-synergy, not damage, and calculate_stats for a stat table with no battle.' It also states a hard prerequisite: 'Supply move or a non-empty attacker.moves, else the call errors.'

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