Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@@pokemontcgapi/mcp Show me Charizard cards from Japanese sets with prices"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server for the Pokémon TCG API at pokemontcgapi.com. It gives an agent eight tools over a catalogue of 615 sets and 52,337 cards — 379 Japanese sets, 176 international, 60 Simplified Chinese — with card names in six languages, illustrators, images, and prices that carry their source, basis, grade and sample size.
Unofficial. Not produced, endorsed, supported by or affiliated with Nintendo, Creatures Inc., GAME FREAK inc. or The Pokémon Company International. Pokémon and all related marks are trademarks of their respective owners.
Claude Code:
claude mcp add pokemontcgapi --env PTCG_API_KEY=your-key -- npx -y @pokemontcgapi/mcpClaude Desktop — claude_desktop_config.json:
{
"mcpServers": {
"pokemontcgapi": {
"command": "npx",
"args": ["-y", "@pokemontcgapi/mcp"],
"env": { "PTCG_API_KEY": "your-key" }
}
}
}Cursor — .cursor/mcp.json:
{
"mcpServers": {
"pokemontcgapi": {
"command": "npx",
"args": ["-y", "@pokemontcgapi/mcp"],
"env": { "PTCG_API_KEY": "${env:PTCG_API_KEY}" }
}
}
}VS Code — .vscode/mcp.json. Note the top-level key is servers, not mcpServers, and inputs
keeps the key out of the committed file:
{
"inputs": [
{ "id": "ptcg-key", "type": "promptString", "description": "pokemontcgapi key", "password": true }
],
"servers": {
"pokemontcgapi": {
"command": "npx",
"args": ["-y", "@pokemontcgapi/mcp"],
"env": { "PTCG_API_KEY": "${input:ptcg-key}" }
}
}
}Environment: PTCG_API_KEY (optional today), PTCG_BASE_URL (defaults to
https://api.pokemontcgapi.com). Node ≥ 20.
Related MCP server: Pokemon MCP Server
Eight tools, not one per endpoint. tools/list sits in the model's context on every turn, so the
whole surface is just over 9 KB, and each tool is shaped like a question rather than like a route —
the model does not have to chain four calls to answer one thing.
Tool | Answers |
| "Charizard cards from Japanese sets", by name, set, region, rarity, artist or release window |
| Up to 100 ids in one call; |
| Every current observation for a card, with printing, grade, |
| "Every Japanese set released in 2024" |
| The exact strings for types, supertypes and rarities, so filters are not guessed |
| Illustrators and how many cards each drew |
| What the catalogue does and does not contain, measured live |
| "Which card is this a photo of?" — ranked candidates, and an explicit refusal when reprints share the artwork. 25 credits a call |
Every tool is annotated readOnlyHint: true and destructiveHint: false. Nothing here writes.
ptcg_identify_card_from_image is the one marked idempotentHint: false, because the same photo costs
25 credits every time it is sent — a client must not retry it on its own.
The last tool exists because of this section, and it returns these facts from a live call rather than leaving a model to infer them:
No Korean cards. Zero KR sets and zero ko translations. The print region and the locale are
modelled in the schema and carry no data, so filtering on them returns an empty result, not an error.
Card game text is English, and uneven. attacks, abilities, weaknesses, resistances,
subtypes, retreat_cost, rules and flavor_text carry rows since 3 September 2026, on the
20,725 Western printings — attacks on 33% of the whole catalogue and 83% of the Western part,
subtypes on 38%, abilities on 8%. Japanese and Chinese printings carry none, so a null
attacks means we do not hold it, never that the card has no attack.
No format legalities. legalities is empty for every card, and level with it. If the
question is about deck legality, this API cannot answer it.
Both statements are measured, dated in the source, and repeated verbatim in the tool descriptions — so an agent is told before it calls, not after.
There is no printing filter. First Edition, Unlimited, holofoil, reverse holofoil and graded rows all
come back together, so read printing, condition and grading on each row rather than taking the
first number. basis separates GUIDE (published upstream) from DERIVED (computed by us);
PTCG_INDEX is our own composite in EUR and carries sample_n. Every observation has an as_of
date and is delayed by at least a day — never quote a price without it.
Results are capped at 50 rows regardless of what the API allows, sent as aligned tables rather than JSON (about 40% fewer tokens, and models misread them less often), with a compact field projection. Truncation is always announced along with the cursor to continue. Price rows are the one thing never truncated.
Built on @modelcontextprotocol/server v2, which negotiates the
2025-11-25 revision and accepts clients
down to 2024-10-07. stdio transport.
The revision is the library's, not a claim of our own: SUPPORTED_PROTOCOL_VERSIONS in
@modelcontextprotocol/server@2.0.0 tops out at 2025-11-25, so a client that asks for anything
newer is answered with that. Verified against the published package, not read off a changelog.
TypeScript SDK, zero runtime dependencies: @pokemontcgapi/sdk — source
Coverage, measured live: https://pokemontcgapi.com/coverage
npm ci
npm run typecheck
npm run buildNode >= 20. No test suite lives here yet: what CI enforces is that the package
typechecks and builds on both Node 20 and Node 22, and that npm pack produces
the file list the registry is meant to receive.
This package is developed inside the private monorepo that runs pokemontcgapi.com and mirrored here on each release, so a merged pull request travels back by hand rather than by merge button. That is not a reason to send patches elsewhere — open the issue or the PR here, it is the address that gets read.
MIT. Data served by the API carries per-source redistribution terms — see https://pokemontcgapi.com/legal/attribution.
Every current price observation for one card, each with its source, basis, printing, grade, sample size and the day it is for. There is no printing filter: 1st Edition, Unlimited, holofoil, reverse holofoil and graded rows all come back together, so you must read printing, condition and grading on each row rather than taking the first price. basis distinguishes GUIDE (a figure published upstream) from DERIVED (computed by us). PTCG_INDEX is our own composite in EUR and carries sample_n. Every observation carries as_of and is delayed by at least a day — never quote a price without its as_of date and its source.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Card id, e.g. "bs-4" or "base1-4". | |
| currency | No | Only show rows already denominated in this currency. Nothing is ever converted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds substantial behavior beyond annotations: rows for all printings come back together with a warning to inspect each row, basis distinguishes GUIDE from DERIVED, PTCG_INDEX is explained, and data is delayed by at least a day. Annotations only declare readOnly/openWorld/idempotent, so this rich behavioral detail is valuable and consistent.
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 longer than average but each sentence earns its place: it front-loads the core purpose, then necessary caveats about printings, basis, and data delay. No filler or repetition.
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?
Given that there is no output schema, the description thoroughly explains the return structure and semantics: field meanings, multiple-rows behavior, indexing, and time delay. An agent can correctly interpret and use the result without missing critical context.
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 schema already documents id and currency well. The description goes further by clarifying that no currency conversion happens and that results are denominated per the currency parameter, plus contextualizing output fields like basis and PTCG_INDEX, which aids parameter interpretation.
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 states a specific verb and resource: it returns every current price observation for one card, enumerating the fields (source, basis, printing, grade, sample size, day). It clearly scopes to a single card, which distinguishes it from sibling tools like ptcg_search_cards or ptcg_get_cards.
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?
The description gives clear context: use this to fetch all price observations for a single card. It does not explicitly name alternatives or state when not to use it, but the card-level scope and the price-specific semantics make the use case evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one or many cards by id, in a single call. Ids are the printed coordinate — set code, dash, collector number, e.g. "bs-4" — and the alternate legacy id ("base1-4") resolves on the same route. Ids that do not exist are omitted from the result; compare requested against found. Card game text is present since 2026-09-03, in English, and unevenly: attacks on 33% of the catalogue, subtypes on 38%, weaknesses on 31%, flavor_text on 20%, abilities on 8%, rules on 6%. It sits on the 20,725 Western printings, so read against those alone attacks is on 83% of them, while Japanese and Chinese printings carry none. Check the field on the card in hand rather than assuming: a null attacks means we do not hold it, never that the card has no attack. Still empty for every card: level, and legalities — deck legality is a question this API cannot answer, so say so rather than inferring it.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | Card ids, 1 to 100. | |
| lang | No | ||
| include_prices | No | Attach the full price list to each card. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive, but the description goes far beyond that. It discloses that missing ids are omitted, provides detailed data coverage statistics (attacks on 33% of catalogue, etc.), explains that null fields mean 'we do not hold it' rather than absence of the attribute, and explicitly states that legalities cannot be answered. This is exemplary transparency beyond the structured annotations.
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 longer than typical but every sentence carries weight. It is front-loaded with the purpose and id format, then logically proceeds to missing-id behavior, data coverage, null semantics, and limitations. There is no fluff, though the statistical details could be condensed for brevity. It is well-structured and readable.
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 bears the full burden of setting expectations. It covers id format, missing-id handling, field coverage, null semantics, and explicitly states what the API cannot answer (legalities). It even advises the agent to say so rather than infer. This is comprehensive for a tool of this complexity, leaving no critical caveat unaddressed.
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?
The schema already documents ids (with a description) and include_prices (with a description), but lang has no description beyond its enum. The description significantly enriches the ids parameter by explaining the exact format and legacy id resolution, which is critical for correct invocation. It adds no info for lang or include_prices, but those are self-evident from the schema. Given the schema coverage of 67%, the description compensates well for the required parameter.
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 clearly states the verb ('Fetch'), the resource ('cards by id'), and the single-call batching capability. It distinguishes itself from the sibling search tool by being id-based, and even specifies the exact id format (set code-dash-collector number, e.g. 'bs-4') with a legacy alias example, leaving no ambiguity about what this tool does.
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?
The description makes it clear that ids are required, which implies that this tool is for id-based lookup rather than search. It also notes that missing ids are silently omitted, guiding the agent to compare requested vs. found. However, it does not explicitly mention alternatives like ptcg_search_cards for when ids are not available, so it lacks an explicit exclusion clause.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Live counts and coverage for the catalogue: sets per print region, card total, which locales carry card names, and which data is explicitly NOT present. Call this before telling a user what the API can and cannot answer.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, open-world, and non-destructive behavior, so the description only needs to add extra context. It adds that information is live, includes coverage nuances per region and locale, and explicitly reports what data is NOT present, aligning well with the open-world hint.
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 two sentences with no filler, front-loads the substantive output content, and ends with a pragmatic usage directive. Every sentence carries value.
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 no-parameter status tool with no output schema, the description is complete enough: it explains what information the call returns and when to call it. There is no missing guidance needed to select or invoke this tool.
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?
The tool has zero parameters and schema coverage is 100%, so the baseline is 4 and there is no parameter information to add. The description correctly avoids inventing parameter documentation.
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 names a specific verb-resource pair ('live counts and coverage for the catalogue') and defines its scope by enumerating content: sets per print region, card total, and locale name coverage. This clearly distinguishes it from sibling card search, pricing, and reference tools.
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?
The description gives an explicit call trigger: 'Call this before telling a user what the API can and cannot answer.' It does not name alternative tools or say when not to use it, but for a status tool this is a clear and actionable usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The exact strings the catalogue uses for types, supertypes, subtypes and rarities. Call this before filtering on a rarity or a type rather than guessing the wording — "Rare Rainbow" and "Rainbow Rare" are not the same string, and only one of them matches.
| Name | Required | Description | Default |
|---|---|---|---|
| vocabulary | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description does not need to repeat those. It adds valuable behavioral context by explaining that the strings are exact and that 'Rare Rainbow' and 'Rainbow Rare' are different, implying the tool returns canonical strings with no fuzzy matching. This goes beyond the annotations.
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 two sentences with no filler. It leads with the core purpose, then gives a practical usage note. Every sentence earns its place, and the example is concrete without being verbose.
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 simple one-parameter tool with no output schema, the description covers what it does, when to use it, and why exactness matters. It does not explicitly state the return format (e.g., a list of strings), but that is strongly implied by 'The exact strings the catalogue uses'. Given the low complexity and annotations covering safety, this is sufficient.
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 0%, so the description must explain the parameter. It does so by listing the vocabulary categories (types, supertypes, subtypes, rarities) that map directly to the enum values. It clarifies that the tool returns the exact strings for the chosen vocabulary, adding meaning beyond the raw enum names.
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 states the tool returns the exact strings the catalogue uses for types, supertypes, subtypes and rarities, which is a specific verb+resource. The title 'List the closed vocabularies' reinforces this. It is clearly distinct from siblings like ptcg_search_cards or ptcg_list_sets, as it focuses on vocabulary reference data.
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?
The description gives explicit guidance: 'Call this before filtering on a rarity or a type rather than guessing the wording'. This tells the agent when to use it and why, using a concrete example of string mismatch. While it does not name alternative tools, the scenario is specific enough to avoid confusion with search or listing tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recognise a Pokemon card from a photograph and return ranked candidates. Use this instead of guessing from what you see in an image: reprints share their artwork, so visual identification alone cannot name a printing, and this tool says so when it cannot. Costs 25 credits per call against 1 for a lookup — do not call it in a loop. Pass set or region when the user has told you either.
| Name | Required | Description | Default |
|---|---|---|---|
| set | No | Set code to restrict to, e.g. "sv3". Resolves reprint ties. | |
| top_k | No | Candidates to return. Default 3. | |
| region | No | Print region to restrict to. | |
| image_base64 | Yes | The photograph, base64-encoded. A data: URL prefix is accepted and stripped. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds valuable context: the credit cost (25 vs 1) and the behavior that the tool 'says so when it cannot' identify. It also explains the inherent limitation of reprints sharing artwork. No contradiction with annotations, and the added behavioral detail goes beyond the structured hints.
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?
Three sentences, each carrying weight: purpose, usage caution with rationale, and cost plus parameter hints. Front-loaded with the core action, no filler or redundant wording. Efficiently structured for an agent to parse quickly.
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 should convey what the tool returns—'ranked candidates' covers that. It also addresses cost, failure behavior, and optional parameter triggers. While it doesn't specify the exact candidate structure (e.g., card fields), that is likely inferable from the tool's purpose and sibling tools. Given the tool's simplicity and the annotations covering read-only, this is reasonably complete.
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. The description adds one piece of parameter guidance—'Pass set or region when the user has told you either'—which helps the agent decide when to supply optional params. This is a modest but real addition beyond the schema's own per-parameter 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: 'Recognise a Pokemon card from a photograph and return ranked candidates.' It clearly distinguishes itself from sibling tools (search, prices, sets, etc.) by focusing on image-based identification, and it explicitly notes that reprints share artwork, so visual identification alone cannot name a printing—this differentiates it from a plain image-to-name lookup.
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?
It gives explicit when-to-use guidance: 'Use this instead of guessing from what you see in an image' and warns against looping with 'do not call it in a loop' due to credit cost. It also instructs when to pass optional parameters: 'Pass set or region when the user has told you either.' This is clear, actionable, and covers both usage and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Illustrators with the number of cards each has drawn, deduplicated across 30 years of printings. Use the returned name with the artist argument of ptcg_search_cards to get their cards.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Illustrator name or part of it. | |
| limit | No | ||
| cursor | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: deduplication across 30 years of printings, and the fact that the returned name is meant to be reused as an argument. It does not disclose pagination behavior, but the cursor parameter is visible in the schema.
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?
Two sentences, no filler. The core purpose and deduplication behavior are front-loaded, and the cross-tool usage hint is placed second. Every sentence earns its place.
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 list tool with no output schema, the description is nearly complete. It explains what the tool returns (illustrators with card counts), the deduplication behavior, and how to use the result. The only minor gap is that it doesn't describe the exact output shape (e.g., whether counts are numbers or strings), but the absence of an output schema makes that less critical for a simple list tool.
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 only 33% (only 'name' has a description). The description adds meaning by explaining that the returned name is used with the artist argument of ptcg_search_cards, which clarifies the purpose of the name parameter. However, it does not explain the limit or cursor parameters beyond what the schema shows (max/min for limit, type for cursor). Baseline 3 is appropriate because the description partially compensates for the schema gap but not fully.
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 states a specific verb ('List'), a resource ('illustrators'), and the key behavior ('deduplicated across 30 years of printings'). It also distinguishes itself from siblings by explicitly connecting to ptcg_search_cards via the artist argument, making its purpose unmistakable.
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?
The description clearly implies when to use this tool: when you need an illustrator name to pass to ptcg_search_cards. It names the sibling tool and the argument, providing a concrete usage path. It does not explicitly state when not to use it, but the context is clear enough for an agent to select it correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every set with its code, series, print region, release date and printed total. One call answers questions like "every Japanese set released in 2024". Print regions are WEST (176 sets), JP (379 sets) and CN (60 sets, Simplified Chinese), measured 2026-08-27. Japanese sets are not translations of Western ones: they have their own boundaries, their own numbering and their own release dates, so a Japanese set and its international counterpart are two different rows.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Set name or part of it. | |
| limit | No | ||
| cursor | No | ||
| region | No | ||
| series | No | Era or series name, e.g. "Scarlet & Violet". | |
| order_by | No | e.g. "-release_date" (default) or "release_date". | |
| released_to | No | ISO date, inclusive upper bound. | |
| released_from | No | ISO date, inclusive lower bound. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only and non-destructive behavior, so the description adds valuable context: row fields, region counts, and especially the non-obvious fact that Japanese sets are separate rows from their international counterparts. This prevents a realistic misinterpretation.
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?
Three sentences with no filler. The output fields are front-loaded, followed by useful counts and the crucial Japanese-set caveat. Every sentence earns its place.
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 list tool with eight filter parameters and no output schema, the description explains the returned row contents, region distinctions, and a subtle data-model behavior. It does not explicitly discuss pagination or default ordering, but cursor/limit and order_by are present in the 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?
The schema already covers most parameters with descriptions, and the description adds useful domain context around regions and date-based queries. However, it does not add parameter-level meaning for limit, cursor, or filtering behavior beyond what the schema provides.
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 clearly names the resource (Pokémon TCG sets) and the exact fields returned: code, series, print region, release date, and printed total. This is distinct from sibling tools that focus on cards, prices, artists, or catalogue status.
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?
The example 'every Japanese set released in 2024' tells an agent when to call this tool and implies which filters apply (region and release dates). It does not explicitly name alternatives or exclude them, but the intended use case is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the Pokémon TCG card catalogue by name, set, print region, rarity, artist or release window. Returns one row per printing with its set, rarity, illustrator and euro price index. Print regions are WEST (176 sets), JP (379 sets) and CN (60 sets, Simplified Chinese), measured 2026-08-27. Japanese sets are not translations of Western ones: they have their own boundaries, their own numbering and their own release dates, so a Japanese set and its international counterpart are two different rows. Card names exist in six locales: en, ja, fr, de, es, it. Passing lang= replaces the name field itself and falls back to English when a translation is missing. Set names are not translated. Card game text is present since 2026-09-03, in English, and unevenly: attacks on 33% of the catalogue, subtypes on 38%, weaknesses on 31%, flavor_text on 20%, abilities on 8%, rules on 6%. It sits on the 20,725 Western printings, so read against those alone attacks is on 83% of them, while Japanese and Chinese printings carry none. Check the field on the card in hand rather than assuming: a null attacks means we do not hold it, never that the card has no attack. Still empty for every card: level, and legalities — deck legality is a question this API cannot answer, so say so rather than inferring it.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Escape hatch: raw Lucene-style query. Field names are camelCase and dotted (set.code, set.releaseDate, nationalPokedexNumbers) while response keys are snake_case. Only use this when the named arguments above cannot express the question. | |
| set | No | Set code, e.g. "bs", "sv3". Use ptcg_list_sets to find it. | |
| lang | No | Return card names in this locale. | |
| name | No | Card name or part of it, e.g. "charizard". | |
| limit | No | Rows, capped at 50. | |
| artist | No | Illustrator name. | |
| cursor | No | Opaque cursor from a previous call. Never construct one. | |
| rarity | No | Exact printed rarity. Use ptcg_get_reference to list valid values. | |
| region | No | Print region of the set the card belongs to. | |
| order_by | No | e.g. "-set.releaseDate", "name". Sorting always ends with id. | |
| released_to | No | ISO date, inclusive upper bound on the set release date. | |
| released_from | No | ISO date, inclusive lower bound on the set release date. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context beyond that: the regional data asymmetry (JP sets are not translations, CN has 60 sets), the coverage statistics for card game text (attacks on 33%, etc.), the null-means-not-held semantics, and the explicit statement that legalities are empty and cannot be answered. This is exactly the kind of behavioral disclosure that prevents an agent from making wrong inferences.
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 information-dense, and every sentence earns its place: search dimensions, return shape, regional asymmetry, language behavior, coverage statistics, null semantics, and explicit exclusions. It is front-loaded with the core purpose and return shape, then layers caveats. It could be slightly tightened (the coverage statistics sentence is long), but the density is justified given the tool's complexity and the number of traps an agent could fall into.
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 12-parameter search tool with no output schema, the description is remarkably complete. It covers what the tool returns, how to use the parameters, what the data quality caveats are, and what the tool cannot answer. The only thing not explicitly described is pagination mechanics, but the cursor parameter's schema description ('Opaque cursor from a previous call. Never construct one.') already covers that. The description fully compensates for the absence of an 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 description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the lang parameter's fallback behavior ('falls back to English when a translation is missing'), clarifying that set names are not translated, and giving the q parameter its escape-hatch role. It also explains the region enum values with counts (WEST 176, JP 379, CN 60). The description doesn't add per-parameter syntax details for every field, but the schema already covers those, and the description's additions are genuinely useful.
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 ('Search the Pokémon TCG card catalogue') and enumerates the searchable dimensions (name, set, print region, rarity, artist, release window), which clearly distinguishes it from siblings like ptcg_get_cards or ptcg_get_card_prices. It also states the return shape (one row per printing with set, rarity, illustrator, euro price index), so an agent knows exactly what this tool produces.
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?
The description gives explicit guidance on when to use this tool versus alternatives: it names ptcg_list_sets for finding set codes, ptcg_get_reference for valid rarity values, and ptcg_list_artists implicitly through the artist parameter. It also tells the agent when NOT to use it: deck legality is explicitly out of scope ('say so rather than inferring it'). The escape-hatch q parameter is scoped to cases where named arguments cannot express the question.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.4ptcg_get_card_pricesptcg_get_cardsptcg_get_catalogue_statusptcg_get_referenceptcg_identify_card_from_imageptcg_list_artistsptcg_list_setsptcg_search_cardsScored across 8 tools
Each tool targets a clearly distinct operation: search, lookup by ID, price observations, set listing, reference strings, artists, catalogue status, and image recognition. Potential overlap between search results and price data is resolved by explicit descriptions of what each returns.
All tools follow the ptcg_ prefix with a consistent verb_noun structure: search_cards, get_cards, list_sets, get_reference, list_artists. The one longer name, identify_card_from_image, still follows the same pattern and fits naturally.
Eight tools is well-scoped for a Pokémon TCG catalogue and pricing API. Each tool covers a distinct functional area without redundancy or excessive granularity.
The set covers search, ID-based retrieval, pricing, set metadata, reference values, artist lists, catalogue health, and image identification. The catalogue status tool explicitly addresses unsupported data like legalities, closing what would otherwise be a gap.
Gateway between LLM agents and world data through eight tools and a bundled endpoint catalog.
62 real-world tools for agents: search, scraping, social, enrichment, image, video, voice.
SEC filings and financial data for AI agents: 59 tools for statements, valuation and supply chains.
Discover, inspect and run 63,000+ agent tools from one balance. Pay per call, no subscriptions.
