Skip to main content
Glama
hahastudio

pokemon-battle-mcp

by hahastudio

Pokémon Battle Helper MCP Server

A TypeScript MCP server for Pokémon Champions battle assistance.

For the canonical design, data sources, battle model, tool schemas, solver behavior, and test strategy, see Architecture.md.

Tools

The server registers these MCP tools:

  • get_meta_snapshot

  • get_pokemon_options

  • calculate_stats

  • check_damage_matchup

  • optimize_offensive_spread

  • optimize_survival_spread

  • optimize_speed_spread

  • get_speed_tiers

All tools expose input/output schemas through MCP tools/list.

Related MCP server: Pokémon VGC Damage Calculator MCP Server

Install / build / test

npm install
npm run build
npm test

npm test runs a pretest build and includes MCP stdio e2e tests that start dist/index.js, connect with the real @modelcontextprotocol/sdk client, call tools, and verify tool schemas.

Run as an MCP server

npm run build
node dist/index.js

Example MCP client config:

{
  "mcpServers": {
    "pokemon-battle": {
      "command": "node",
      "args": ["/absolute/path/to/pokemon-battle-mcp/dist/index.js"]
    }
  }
}

Live meta defaults

The implementation uses Pikalytics English live data for the current Pokémon Champions ranked ladder. Default meta URL shape:

https://www.pikalytics.com/api/p/2026-05/battledataregmbs3-1760
https://www.pikalytics.com/api/p/2026-05/battledataregmbs3-1760/garchomp

get_meta_snapshot and get_pokemon_options accept optional format request fields (single/double; default double). Pikalytics' battledataregmbs3 key is the Champions doubles ladder, so format currently does not change the queried dataset. The season/regulation key (battledataregmbs3) and rating cutoff (1760) are internal constants; update them when the live regulation changes. The data month (YYYY-MM) is discovered automatically — a preferred month is tried first, then recent months are probed newest-first — because Pikalytics serves the literal JSON false for months without data.

Pokémon name handling

All tools accept any common spelling of a Pokémon name and normalize it server-side (see src/utils/pokemon-name.ts):

  • Showdown forme names and aliases: Basculegion-F, lando-t, Urshifu-Rapid-Strike.

  • PokeAPI/Pikalytics-style slugs: basculegion-female, urshifu-rapid-strike.

  • Space/punctuation variants: Rotom Wash, Sirfetch'd.

Material corrections (e.g. basculegion-female -> Basculegion-F) are reported in inputCorrections. For get_pokemon_options, a base-species request resolves to the only matching meta forme when unambiguous (Floette -> Floette-Mega, with a formeResolved correction); if several formes are ranked, the tool returns an error listing the candidates. When Pikalytics has no page for the requested forme and base-forme data is used instead, the response carries an explicit warning (formeDataFallback) instead of silently returning the wrong forme's data. Unknown names produce did-you-mean suggestions.

Calc-oriented tool handlers (calculate_stats, check_damage_matchup, and the SP optimizers) also guard against the common LLM mistake of sending a bare base species for a current-format forme request: if the submitted name is a canonical base species and the current meta has exactly one matching forme, the handler rewrites it and reports formeResolved in inputCorrections before doing the calculation. Ambiguous cases still require the client/model to specify the forme.

Recommended client/system instruction:

For Pokémon Champions build, Mega, forme, damage, or speed questions, call get_pokemon_options
first for each named Pokémon and use the returned canonical Pokémon name/build in calculator
tools. Do not guess a base species when the user requested a Mega or forme. Item choices should
be passed exactly as provided by the user; this MCP does not validate item legality.

Mega forme ability handling

When a request uses a Mega forme, the server canonicalizes stale or missing abilities to the fixed Mega ability before calculation and reports the change in inputCorrections plus modifierBreakdown. get_pokemon_options also returns the Mega ability for Mega forme requests, even when move/item/spread data has to come from a base-form meta page.

If the ability has already been changed in battle by Skill Swap, Worry Seed, Entrainment, etc., clients should send the current effective ability and mark it explicitly with pokemon.abilitySource: "battle-changed" or an active ability-change effect such as { "id": "abilitychanged" }, { "id": "skillswap" }, or { "id": "worryseed" }. For ability suppression such as Gastro Acid, keep the actual ability and use state.abilityEffect: "inactive".

Available Tools

8 tools
calculate_statsCalculate Pokémon Champions statsA

Calculate level-50 Pokémon Champions stats from species, nature, and SP; includes stage-modified stats when battle state is present. For user requests about current-format builds or Mega/formes, prefer get_pokemon_options first and pass its returned canonical Pokémon name/build; this tool also resolves unambiguous current-meta base-forme mistakes.

ParametersJSON Schema
NameRequiredDescriptionDefault
contextNo
pokemonYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
rawStatsYes
modifiedStatsNo
inputCorrectionsNo
modifierBreakdownYes

TDQS

A4.2/5.0
Behavior4/5

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

No annotations are provided, so the description must carry the transparency burden. It discloses two important behavioral traits: 1) it includes stage-modified stats only when battle state is present (context-dependent), and 2) it resolves unambiguous current-meta base-forme mistakes server-side. These are non-obvious and useful. It does not mention side effects or auth, but as a calculation tool that is unlikely. The correction behavior is well-highlighted.

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?

The description is two sentences, each earning its place. The first presents the core function, the second provides guidance on when to use alternatives and discloses correction behavior. There is no filler or repetition.

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?

The tool has a complex nested schema with two parameters, and an output schema is provided. The description is sufficient for understanding the primary use case and mentions the key context-dependency (stage-modified stats). It could be more complete by explicitly mentioning that corrections are reported via inputCorrections (a behavioral detail in the schema), but overall it covers the essential context for an agent to select and invoke the tool.

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?

The description names the key inputs 'species, nature, and SP', which maps to pokemon.name, pokemon.nature, and pokemon.sp. It also hints that battle state (likely context) affects stage-modified stats. However, it does not explain the structure of the context object or the exact SP format, leaving those to the schema. Given the context signal of 0% schema description coverage, the description should compensate more, but it adds some value beyond parameter names.

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?

The description opens with a specific verb+resource: 'Calculate level-50 Pokémon Champions stats from species, nature, and SP', and further specifies that stage-modified stats are included when battle state is present. It clearly distinguishes from sibling tools like get_pokemon_options by explicitly mentioning that for current-format builds/Mega/formes, get_pokemon_options should be preferred.

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?

The description gives explicit guidance on when to prefer get_pokemon_options ('For user requests about current-format builds or Mega/formes, prefer get_pokemon_options first') and explains the correction behavior. However, it does not contrast with other siblings like optimization tools (e.g., optimize_offensive_spread) or check_damage_matchup, so it lacks full coverage of when not to use this tool.

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

check_damage_matchupCheck damage matchupA

Run a forward damage calculation with Pokémon Champions SP converted to standard EVs. For build questions, first call get_pokemon_options for each Pokémon and use the returned canonical forme/build when available; item choices are accepted as provided and are not legality-validated.

ParametersJSON Schema
NameRequiredDescriptionDefault
moveYes
contextNo
attackerYes
defenderYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
koChanceYes
damageRangeYes
damageRollsYes
descriptionYes
damageRollRatiosYes
inputCorrectionsNo
modifierBreakdownYes

TDQS

A4.2/5.0
Behavior4/5

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

With no annotations, the description discloses key behavior: SP conversion to standard EVs and that item legality is not validated. It doesn't mention side effects or error handling, but this is a pure calculation, and output schema covers return values. The description adds value beyond the schema by explaining the conversion.

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?

The description is concise, with two sentences: the first states the purpose, the second gives a usage guideline and a caveat. No redundant information.

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?

The description covers the core purpose, a suggested workflow, and a legality caveat. Given the rich input schema (which documents parameters and nested objects) and the presence of an output schema, this is adequate. It could mention format or that it's read-only, but those are less critical.

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?

The tool description does not enumerate parameters, but it clarifies that 'Pokémon Champions SP' is used and that item choices are accepted as provided, which gives context for the `sp` and `item` fields. The move and context parameters are not addressed. Since the input schema itself has detailed descriptions for each property, the base coverage is decent, but the tool description only partially compensates given the 0% schema_description_coverage.

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?

The description clearly states the tool performs a forward damage calculation with a specific EV conversion, using a verb ('Run') and resource ('damage calculation'). It distinguishes from siblings like calculate_stats by focusing on damage matchup, and the name reinforces it.

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?

It explicitly instructs to call get_pokemon_options first for build questions and use canonical formes/builds, providing an alternative workflow. It also notes item choices are accepted as provided and not legality-validated, giving context. However, it doesn't explicitly state when not to use this tool versus other damage/stat tools.

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

get_meta_snapshotGet Pokémon Champions meta snapshotA

Get popular Pokémon, moves, items, abilities, and common Pokémon Champions SP spreads for the current format.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoDefault 20.
formatNoDefault double.
includeBuildsNoDefault true.

Output Schema

ParametersJSON Schema
NameRequiredDescription
formatYes
sourceNo
pokemonYes
generatedAtYes

TDQS

A4/5.0
Behavior3/5

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

With no annotations, the description discloses that the tool returns popular meta data, but it does not mention data source, freshness, or whether limit applies per category. The output schema covers return structure, so the description does not need to explain that, but additional behavioral details are absent.

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?

The description is a single, focused sentence with no redundant words. It efficiently lists the key elements returned.

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?

The description, combined with the output schema and complete parameter schemas, gives sufficient context for an agent to understand the tool's purpose and return. Minor gap: no mention of how limit affects categories or whether data is cached/live.

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%, with each parameter having a description and default. The tool description adds no extra parameter-level meaning beyond referencing 'current format,' which maps to the format parameter. Baseline 3 is appropriate.

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?

The description clearly states the tool retrieves popular Pokémon, moves, items, abilities, and SP spreads for the current format. The content and verb 'Get' distinguish it from sibling calculation and optimization tools.

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?

The description provides clear context that this is for current format meta data, implying it should be used when snapshot popularity data is needed. It does not explicitly exclude calculation tools, but the nature of the output is unambiguous.

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

get_pokemon_optionsGet Pokémon optionsA

Get common sets, moves, items, abilities, spreads, and optional teammates/counters for one Pokémon.

ParametersJSON Schema
NameRequiredDescriptionDefault
formatNoDefault double.
pokemonYesPokémon name in any common spelling, e.g. 'Basculegion-F', 'basculegion-female', 'Floette'. Base-species names resolve to the meta forme when unambiguous; corrections are reported in inputCorrections/metaNotes.
includeCountersNo
includeTeammatesNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
itemsYes
movesYes
buildsNo
pokemonYes
spreadsYes
countersNo
abilitiesYes
metaNotesNo
teammatesNo
inputCorrectionsNo

TDQS

A3.8/5.0
Behavior3/5

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

With no annotations, the description itself only indicates a retrieval operation, which is non-destructive and safe. However, it does not disclose behaviors such as input normalizations (though schema mentions corrections are reported), default format handling, or any external dependencies, leaving some transparency gaps.

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?

The description is a single, front-loaded sentence listing key outputs without wasted words. It uses consistent comma-separated items, making it easy to scan and understand.

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?

Given the tool's moderate complexity and presence of an output schema, the description adequately lists return content and scopes to one Pokémon. However, it omits guidance on parameter interactions (e.g., default include behavior) and does not differentiate from siblings, making it slightly incomplete for full contextual navigation.

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 50%, with descriptions for 'pokemon' and 'format' but not for the two boolean flags. The description's mention of 'optional teammates/counters' hints at includeTeammates/includeCounters, but it does not explicitly map parameters, so semantics for the booleans remain partially inferred.

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?

The description clearly states the tool retrieves 'common sets, moves, items, abilities, spreads, and optional teammates/counters' for a single Pokémon, using a specific verb and resource. This distinguishes it from siblings like calculate_stats or get_speed_tiers, which focus on calculations and speed tiers.

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

Usage Guidelines3/5

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

The description implies usage when teambuilding needs suggested sets/options for a Pokémon, but it does not explicitly contrast with sibling tools or state when not to use it. For example, it does not mention using calculate_stats for damage calculations instead.

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

get_speed_tiersGet speed tiersB

Return sorted speed benchmarks from the current meta seed/source.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoDefault 50.
filtersNo
includeModifiersNoDefault true.

Output Schema

ParametersJSON Schema
NameRequiredDescription
tiersYes
generatedAtYes

TDQS

B3/5.0
Behavior3/5

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

With no annotations, the description carries the full burden. It discloses that the tool returns sorted data and uses a current meta seed/source, which implies a read-only operation. However, it lacks details about side effects, error handling, or how the seed is determined, so transparency is limited.

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?

The description is a single, concise sentence that is front-loaded with the core functionality. Every word earns its place, with no unnecessary filler or redundancy.

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

Completeness2/5

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

The tool has moderate complexity due to the filters parameter, and although an output schema exists, the description is too brief to explain what 'speed benchmarks' means, how the meta seed/source is selected, or how the filters interact. This is inadequate for an agent to fully understand when and how to invoke the tool correctly.

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

Parameters2/5

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

The schema description coverage is 67%, with descriptions for limit and includeModifiers, but the filters parameter is undocumented. The description adds no parameter information at all, failing to clarify the complex filters structure. This leaves a significant gap in understanding the tool's inputs.

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

Purpose4/5

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

The description clearly states the tool returns sorted speed benchmarks from the current meta seed/source, using a specific verb and resource. It is relatively specific but does not explicitly differentiate itself from sibling tools like optimize_speed_spread, which could also involve speed benchmarks.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives. It only states what it does, without mentioning when it is appropriate or when to choose a sibling tool like get_meta_snapshot or optimize_speed_spread.

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

optimize_offensive_spreadOptimize offensive SP spreadC

Find the minimum attacking SP and nature needed to reach a target damage ratio. Use canonical current-format formes from get_pokemon_options when the user asks about a Mega/forme.

ParametersJSON Schema
NameRequiredDescriptionDefault
moveYes
contextNo
attackerYes
defenderYes
spBudgetNo
offensiveStatNo
allowedNaturesNo
targetDamageRatioYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
koChanceYes
requiredSPYes
inputCorrectionsNo
modifierBreakdownYes
recommendedNatureYes
resultingDamageRangeYes
isFeasibleUnderBudgetYes

TDQS

C2.7/5.0
Behavior2/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the optimization goal but omits details such as damage formula assumptions, how 'minimum' is calculated (e.g., SP budget constraints), failure modes when no spread achieves the target, or whether it accounts for moves/abilities. The mention of get_pokemon_options hints at cross-tool dependency but does not disclose overall behavior.

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?

The description is two sentences and front-loaded with the primary purpose. No filler words; every sentence contributes a distinct point (goal and canonical-naming guidance).

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

Completeness2/5

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

For a complex tool with 8 parameters and a nested schema, the description is too minimal. It lacks mention of expected usage scenarios, relationship to other optimizer tools, and the meaning of the output. Although an output schema exists (reducing the need to explain return values), the description still provides insufficient context for correct invocation.

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

Parameters1/5

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

Schema description coverage is 0%, and the description does not compensate by explaining key parameters like targetDamageRatio, spBudget, allowedNatures, or offensiveStat. The only indirect reference is 'attacking SP and nature,' which duplicates the tool's title. The rich input schema descriptions carry all semantics, so the description adds no value for parameters.

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

Purpose4/5

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

The description clearly states the tool's function: 'Find the minimum attacking SP and nature needed to reach a target damage ratio.' It distinguishes from sibling optimization tools by specifying 'attacking' as the optimization target, but does not explicitly name alternative tools for survival/speed spreads.

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

Usage Guidelines2/5

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

Only a tangential usage note is provided: 'Use canonical current-format formes from get_pokemon_options when the user asks about a Mega/forme.' This addresses input naming for specific cases but does not explain when to choose this tool over sibling optimization tools (e.g., optimize_survival_spread).

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

optimize_speed_spreadOptimize speed SP spreadA

Find the minimum Speed SP and nature needed to outspeed, speed tie, or underspeed a target. Use get_pokemon_options first for current-format Mega/forme requests; this tool also resolves unambiguous current-meta base-forme mistakes.

ParametersJSON Schema
NameRequiredDescriptionDefault
selfYes
targetYes
contextNo
relationYes
spBudgetNo
allowedNaturesNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
marginYes
requiredSpeedSPYes
inputCorrectionsNo
targetFinalSpeedYes
modifierBreakdownYes
recommendedNatureYes
resultingRawSpeedYes
resultingFinalSpeedYes
isFeasibleUnderBudgetYes

TDQS

A3.8/5.0
Behavior3/5

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

No annotations are provided, so the description carries the full burden. It discloses a key behavioral trait ('resolves unambiguous current-meta base-forme mistakes') and the core calculation behavior, but does not mention safety, side effects, or limitations (e.g., how it simulates speed modifiers). It's adequate but not exhaustive.

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?

The description is two sentences, front-loaded with the core purpose, and contains no redundant or filler text. Every clause earns its place, including the sibling-tool guidance.

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

Completeness3/5

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

The description captures the essential purpose and a critical prerequisite, but for a complex tool with nested schema and a separate output schema, it leaves out important context such as how the target should be specified or what the result contains. The output schema mitigates the need to explain return values, but the description still feels minimal for the tool's complexity.

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

Parameters2/5

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

Schema description coverage is 0% at the top level, and the description does not compensate. It only implies that 'Speed SP' and 'nature' are relevant inputs and references 'target' generically, but does not explain relation, spBudget, allowedNatures, or context. This is a significant gap for a tool with nested objects and 6 parameters.

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?

The description states a specific action ('Find the minimum Speed SP and nature') with a clear resource ('Speed SP') and outcome ('outspeed, speed tie, or underspeed a target'). It effectively distinguishes from sibling tools like optimize_offensive_spread and optimize_survival_spread by focusing on speed-related optimization.

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?

Explicitly advises using get_pokemon_options first for current-format Mega/forme requests, providing a clear when-to-use alternative. The note about resolving base-forme mistakes gives additional context, though it does not explicitly mention when not to use this tool or compare to other speed-focused siblings like get_speed_tiers.

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

optimize_survival_spreadOptimize survival SP spreadA

Find the minimum HP plus defense/special-defense SP allocation that survives a specified attack. Use canonical current-format formes from get_pokemon_options when the user asks about a Mega/forme.

ParametersJSON Schema
NameRequiredDescriptionDefault
moveYes
contextNo
attackerYes
defenderYes
spBudgetNo
defensiveStatNo
allowedNaturesNo
survivalThresholdNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
survivesYes
totalSPUsedYes
recommendedSPYesPartial Pokémon Champions SP table. Omitted stats default to 0.
inputCorrectionsNo
modifierBreakdownYes
recommendedNatureYes
resultingDamageRangeYes
isFeasibleUnderBudgetYes

TDQS

A3.7/5.0
Behavior3/5

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

With no annotations, the description carries the transparency burden. It discloses that the tool optimizes only HP and defensive stats, and it specifies the canonical-forme requirement, which is useful behavioral context. However, it does not state whether the operation is read-only, what the output contains, or assumptions about other stats, leaving gaps in transparency.

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?

The description is two sentences, each informative: the first states the core optimization goal, and the second gives a critical input-format guideline. There is no redundancy or filler, making it exceptionally concise and well-structured.

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

Completeness2/5

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

Despite having an output schema, the tool has 8 parameters with deep nesting. The description covers only the basic optimization goal and the forme-canonicalization rule, leaving many optional parameters and usage nuances undocumented. For a tool of this complexity, the description is not complete enough.

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

Parameters2/5

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

Schema description coverage is 0%, so the description must compensate for parameter meaning. It gives only implicit hints: 'HP plus defense/special-defense' maps to defender SP stats and the defensiveStat parameter, and 'specified attack' maps to move. It does not explain spBudget, survivalThreshold, context, or allowedNatures, so the description is insufficient.

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?

The description clearly states the tool's function: 'Find the minimum HP plus defense/special-defense SP allocation that survives a specified attack.' This uses a specific verb ('Find') and a precise resource (defensive SP allocation), making it distinct from offensive or speed optimization tools. The additional note about canonical formes further clarifies its scope.

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?

The description provides clear context: it is for defensive survival optimization, and it gives a concrete usage instruction to use canonical formes from get_pokemon_options for Mega/forme requests. However, it does not explicitly mention alternatives like optimize_offensive_spread or state when not to use this tool, so it does not fully meet the 'when/when-not' standard.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 8 tool updatesv0.1.0
    • First observedcalculate_stats
    • First observedcheck_damage_matchup
    • First observedget_meta_snapshot
    • First observedget_pokemon_options
    • First observedget_speed_tiers
    • First observedoptimize_offensive_spread
    • First observedoptimize_speed_spread
    • First observedoptimize_survival_spread

TDQS

A3.8/5.0

Scored across 8 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: meta snapshot, single Pokemon options, stat calculation, damage calculation, and three specific optimize tools for offensive, survival, and speed spreads, plus speed tiers. The descriptions also include cross-references that further clarify when to use each tool.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern using lowercase snake_case (get_meta_snapshot, calculate_stats, check_damage_matchup, optimize_offensive_spread). The actions are descriptive and the pattern is uniform.

Tool Count5/5

8 tools is well-scoped for a Pokemon battle assistant, covering meta information, stat calculation, damage calculation, and optimization. Each tool serves a distinct function without unnecessary redundancy.

Completeness5/5

The tool set covers the full workflow of building Pokemon sets: gathering meta information, obtaining specific Pokemon options, calculating stats, checking damage, and optimizing offensive, defensive, and speed spreads. There are no obvious dead ends or missing operations for the stated purpose.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • F
    license
    B
    quality
    D
    maintenance
    An MCP server that provides detailed Pokémon information by integrating with the PokeAPI, allowing users to fetch comprehensive data about Pokémon and simulate battles.
    2
    2
    -
  • A
    license
    B
    quality
    D
    maintenance
    An MCP-compliant server that enables AI agents to perform accurate Pokémon battle damage calculations using the Smogon calculator, supporting comprehensive input handling for Pokémon stats, moves, abilities, and field conditions.
    1
    27 npm
    1
    MIT
  • F
    license
    Not graded
    quality
    C
    maintenance
    An MCP server that enables accurate status and damage calculations for third-generation Pokémon games, including support for complex factors like weather, abilities, and items. It also provides tools for calculating optimal effort value (EV) distributions through brute-force damage matrix simulations.
    -
  • A
    license
    Not graded
    quality
    A
    maintenance
    MCP server for Pokémon battle advising: provides type matchups, damage calculation, party analysis, and move/ability data for AI agents like Claude Code and Codex.
    19
    MIT