pokeapi-mcp-server

Find Pokémon

pokeapi_find_pokemon

Read-onlyIdempotent

Filter Pokémon by generation, type, regional pokédex, or egg group. Returns names and PokéAPI IDs; every returned name works as a pokeapi_get_pokemon identifier, where a species name resolves to its default variety. At least one of generation, type, pokedex, or egg_group is required; the ones provided are combined with AND logic, and query adds strict token matching on name within them. A call with no category filter, with or without query, returns an empty result and a notice naming the requirement.

Input Schema

Name	Required	Description
`type`	No	Type name (e.g. "fire", "psychic"). Filters to Pokémon of this type.
`limit`	No	Maximum results to return. Positive integer; defaults to 50.
`query`	No	Strict token match on name. "chu" matches "pikachu" and "raichu". Case-insensitive. At most 100 characters; whitespace separates tokens, and every token must match.
`offset`	No	Offset into the filtered result set for pagination. Non-negative integer; defaults to 0.
`pokedex`	No	Regional pokédex name (e.g. "kanto", "hoenn", "galar"). Filters to entries in that dex.
`egg_group`	No	Egg group name (e.g. "monster", "fairy", "dragon"). Filters to Pokémon in this egg group.
`generation`	No	Generation name (e.g. "generation-i", "generation-iii"). Filters to Pokémon introduced in this generation.

Output Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Number of results in this response.
`notice`	No	Guidance for missing category filters, zero matches, or an offset beyond the results.
`pokemon`	No	Matching Pokémon entries.
`totalCount`	No	Total matching Pokémon before limit/offset.
`appliedFilters`	No	Effective nonblank filters and pagination controls for this response.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 14, 2026

changedOutput schema / properties / pokemon / items / properties / id / description

Previous value: -"PokéAPI ID: Pokémon record for type filters, species record for generation, pokedex, or egg_group filters. Form IDs are not National Pokédex numbers."New value: +"PokéAPI ID: Pokémon record for type-only searches, species record whenever generation, pokedex, or egg_group is present. Form IDs are not National Pokédex numbers."

Changed7 schema fields changedSep 30, 2026

changedInput schema / properties / query / description

Previous value: -"Strict token match on name. \"chu\" matches \"pikachu\" and \"raichu\". Case-insensitive."New value: +"Strict token match on name. \"chu\" matches \"pikachu\" and \"raichu\". Case-insensitive. At most 100 characters; whitespace separates tokens, and every token must match."

addedInput schema / properties / query / maxLength
```
Added value: +100
```

changedOutput schema / anyOf

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "pokemon",
-      "totalCount",
-      "shown"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "pokemon",
+      "totalCount",
+      "shown",
+      "appliedFilters"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / appliedFilters

Added value: +{
+  "additionalProperties": false,
+  "description": "Effective nonblank filters and pagination controls for this response.",
+  "properties": {
+    "egg_group": {
+      "description": "Normalized egg-group filter, when applied.",
+      "type": "string"
+    },
+    "generation": {
+      "description": "Normalized generation filter, when applied.",
+      "type": "string"
+    },
+    "limit": {
+      "description": "Accepted page size, including the default of 50.",
+      "exclusiveMinimum": 0,
+      "maximum": 9007199254740991,
+      "type": "integer"
+    },
+    "offset": {
+      "description": "Accepted page offset, including the default of 0.",
+      "maximum": 9007199254740991,
+      "minimum": 0,
+      "type": "integer"
+    },
+    "pokedex": {
+      "description": "Normalized pokédex filter, when applied.",
+      "type": "string"
+    },
+    "query": {
+      "description": "Applied lowercase query tokens joined with single spaces. Omitted without a category filter.",
+      "type": "string"
+    },
+    "type": {
+      "description": "Normalized type filter, when applied.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "limit",
+    "offset"
+  ],
+  "type": "object"
+}

changedOutput schema / properties / notice / description

Previous value: -"Guidance when no Pokémon matched the filters."New value: +"Guidance for missing category filters, zero matches, or an offset beyond the results."

changedOutput schema / properties / pokemon / items / description

Previous value: -"Pokémon entry with dex number and name."New value: +"Pokémon entry with PokéAPI ID and name."

changedOutput schema / properties / pokemon / items / properties / id / description

Previous value: -"National Pokédex number."New value: +"PokéAPI ID: Pokémon record for type filters, species record for generation, pokedex, or egg_group filters. Form IDs are not National Pokédex numbers."

Changed6 schema fields changedAug 24, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "pokemon",
+      "totalCount",
+      "shown"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `invalid_filter`: An unrecognized generation, type, pokédex, or egg-group name was provided. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "invalid_filter"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "pokemon",
-  "totalCount",
-  "shown"
-]

Changed8 schema fields changedJul 11, 2026

changedInput schema / properties / limit / description

Previous value: -"Maximum results to return. Defaults to 50."New value: +"Maximum results to return. Positive integer; defaults to 50."

addedInput schema / properties / limit / exclusiveMinimum
```
Added value: +0
```
addedInput schema / properties / limit / maximum
```
Added value: +9007199254740991
```

changedInput schema / properties / limit / type

Previous value: -"number"New value: +"integer"

changedInput schema / properties / offset / description

Previous value: -"Offset into the filtered result set for pagination. Defaults to 0."New value: +"Offset into the filtered result set for pagination. Non-negative integer; defaults to 0."

addedInput schema / properties / offset / maximum
```
Added value: +9007199254740991
```
addedInput schema / properties / offset / minimum
```
Added value: +0
```

changedInput schema / properties / offset / type

Previous value: -"number"New value: +"integer"

First observedJun 7, 2026

TDQS

A4.7/5.0

Behavior4/5

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

Annotations cover the safety profile (readOnly, idempotent, closed-world), so the description focuses on behavior the annotations cannot express: AND-combination of filters, strict token matching for query, and the empty-result-plus-notice outcome. It stops short of describing ordering or pagination semantics beyond what the schema carries.

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?

Three dense sentences, front-loaded with purpose, then the cross-parameter rule, then the failure behavior. No filler and no repetition of schema field descriptions.

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 an output schema present, return-value detail is delegated appropriately, and the description still conveys the identifier-interop guarantee and the empty-result case. Nothing needed to invoke the tool 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 baseline is 3, but the description adds real meaning the schema cannot: the cross-parameter cardinality requirement despite zero required params, and how query composes with category filters. It does not restate the per-parameter formats the schema already 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?

Opens with a specific verb+resource ('Filter Pokémon') and enumerates the four filter axes by name. The get_* siblings are clearly differentiated because this is the only discovery/filter tool, and the description ties its output to pokeapi_get_pokemon identifiers.

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 states the precondition ('At least one of generation, type, pokedex, or egg_group is required'), the combination rule (AND), and the failure mode when no filter is supplied. It also routes the agent downstream to pokeapi_get_pokemon for details.

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

All pokeapi-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.