Uses GitHub as a third-party source for Pokémon TCG Pocket catalog synchronization and enrichment, including meta deck data queries.
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., "@ptcgp-mcp-server Show me my collection stats for rare cards"
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.
Servidor MCP local para un catálogo de Pokémon TCG Pocket y una colección personal en SQLite. Usa el estándar MCP con transporte stdio; no depende de Claude, Anthropic, OpenAI ni de ningún modelo concreto — cualquier cliente compatible con MCP puede lanzar el proceso.
Este es un proyecto en fase de preparación, todavía no publicado. No lo instales pensando en usarlo como paquete público: hoy es un checkout local (package.json marcado como "private": true, sin remoto Git configurado).
Arranca como servidor MCP sobre stdio y expone 17 tools (tabla más abajo). Verificado con npm run smoke, que levanta el binario compilado contra un directorio de datos temporal y lista las tools reales.
Crea una base SQLite local en PTCGP_DATA_DIR (o en ~/.local/share/ptcgp-mcp por defecto) con WAL, claves foráneas y migraciones versionadas forward-only.
Todas las escrituras de colección (individual, masiva, por rango) usan sentencias SQL parametrizadas y corren dentro de una transacción cuando afectan a varias filas.
Las rondas de captura validan un contador de cabecera contra los huecos detectados/confirmados y solo aplican cambios a la colección de forma transaccional, con confirm=true explícito.
Normaliza capturas PNG/JPEG/WebP (con corrección de orientación) y ejecuta OCR local con Tesseract; ninguna imagen sale de la máquina. HEIC/HEIF está en la lista de formatos aceptados en el código pero no está soportado por el build de Sharp instalado en este entorno — no lo des por bueno sin comprobarlo tú mismo.
Incluye tools de sincronización/enriquecimiento de catálogo y de consulta de mazos meta, que dependen de fuentes de red de terceros (GitHub, TCGdex, Limitless TCG) y son la parte menos robusta del proyecto: ver OPEN_SOURCE_GAP_ANALYSIS.md para el detalle de por qué.
Related MCP server: mcp-tcgdex
Node 22 o 24 (.nvmrc fija 24 como preferido; CI cubre ambas). better-sqlite3 es una dependencia nativa: tras cambiar de versión de Node, vuelve a instalar.
npm ci
export PTCGP_DATA_DIR="$(mktemp -d)"
npm test
npm run smokenpm test compila y ejecuta la suite (node --test) sobre un directorio de datos que tú controlas.
npm run smoke arranca el servidor stdio compilado en un directorio temporal propio, lista sus tools y ejecuta PRAGMA quick_check sobre esa base temporal.
npm run verify añade formato (prettier --check), lint (eslint) y npm pack --dry-run — no publica nada.
Nunca ejecutes tests, sync o rondas contra tu PTCGP_DATA_DIR real sin backup previo.
{
"command": "node",
"args": ["/ruta/absoluta/a/ptcgp-mcp-server/dist/index.js"],
"env": {
"PTCGP_DATA_DIR": "/ruta/absoluta/fuera-del-repo/ptcgp-mcp-data"
}
}El servidor usa stdout exclusivamente para el protocolo MCP; nunca escribas ahí manualmente. PTCGP_LOG_LEVEL acepta fatal|error|warn|info|debug|trace|silent (por defecto info) y controla logs estructurados en stderr — hoy el logging operativo es mínimo (solo arranque/errores fatales), así que no confíes en él para depurar el comportamiento de una tool concreta todavía.
Existe un segundo entrypoint pensado para clientes remotos (ChatGPT en Developer Mode, MCP Inspector desde otra máquina, etc.). Expone en /mcp el mismo McpServer pero registrando solo 7 tools de lectura (ptcgp_search_cards, ptcgp_get_card, ptcgp_list_expansions, ptcgp_collection_stats, ptcgp_missing_cards, ptcgp_meta_decks, ptcgp_get_decklist). Las 17 tools de stdio siguen intactas.
Arranque local:
export PTCGP_HTTP_TOKEN="$(openssl rand -hex 32)"
export PTCGP_DATA_DIR=/ruta/absoluta/fuera-del-repo/ptcgp-mcp-data
npm run start:http # escucha en 127.0.0.1:8787 por defectoPrueba con el Inspector: npm run inspect:http (pasa el token en Authorization: Bearer … en la UI). El binario stdio se sigue publicando en bin; el HTTP no.
Guardias implementadas dentro del server:
Token estático obligatorio comparado con crypto.timingSafeEqual.
Allowlist de Host (defensa contra DNS rebinding) y de Origin (por defecto vacía → deniega cualquier cross-site).
Body limit y timeout configurables por env.
Rate limit en memoria por IP (60 peticiones/minuto/IP por defecto), antes de autenticar.
Solo POST/GET en /mcp; el resto devuelve 405 con JSON-RPC válido.
GET /healthz devuelve 200 text/plain "ok" sin filtrar rutas ni versión.
Fuera de alcance de esta fase: OAuth 2.1, acceso multiusuario, publicación en directorios MCP y despliegue automatizado. Antes de exponer datos privados a un endpoint público real hace falta OAuth 2.1 según el spec MCP. Para pruebas privadas puedes tunelizar con OpenAI Secure MCP Tunnel o Cloudflare Tunnel y el token estático. Los templates de systemd, Caddy y environment file viven en deploy/.
Variables (todas opcionales salvo PTCGP_HTTP_TOKEN): PTCGP_HTTP_HOST (default 127.0.0.1), PTCGP_HTTP_PORT (default 8787), PTCGP_HTTP_TOKEN (>= 32 caracteres, obligatoria), PTCGP_HTTP_ALLOWED_HOSTS (CSV, default localhost,127.0.0.1), PTCGP_HTTP_ALLOWED_ORIGINS (CSV, default vacío), PTCGP_HTTP_BODY_LIMIT_KIB (default 1024), PTCGP_HTTP_REQUEST_TIMEOUT_MS (default 30000), PTCGP_HTTP_RATE_LIMIT_MAX (default 60), PTCGP_HTTP_RATE_LIMIT_WINDOW_MS (default 60000) y PTCGP_HTTP_RATE_LIMIT_MAX_KEYS (default 10000).
Grupo | Tools |
Catálogo |
|
Colección |
|
Mazos |
|
Rondas de captura |
|
Flujo seguro de una ronda: round_start → round_analyze_screenshots → revisión humana con round_record → round_status → round_finalize(confirm=true). La comprobación de contadores protege contra muchas lecturas incompletas, pero no prueba por sí sola que las capturas cubran toda la expansión: la revisión visual sigue siendo obligatoria.
No se versiona ninguna base de datos, backup, captura real, .env ni log — .gitignore los excluye y esto se verificó contra git ls-files, no solo se asume.
Haz backup de una base SQLite con WAL usando herramientas conscientes de SQLite y con el servidor parado; copiar solo el .db mientras está activo puede dejarlo inconsistente.
El proyecto no requiere ninguna clave de API. Está bajo licencia MIT pero marcado "private": true para evitar una publicación accidental en npm mientras dure esta fase de preparación.
No hay CLI, transporte Streamable HTTP, backup/restore como funcionalidad del servidor, ni proceso de publicación. Las tools que dependen de red (sync de catálogo, enriquecimiento, mazos meta) no tienen tests de contrato ni protección ante cambios de esquema/maquetación upstream. Antes de ampliar el proyecto, lee HANDOFF.md, ARCHITECTURE.md, ROADMAP.md y OPEN_SOURCE_GAP_ANALYSIS.md.
Actualiza la cantidad poseída de múltiples cartas en una sola llamada transaccional. Cada item: {card_id, quantity}. mode='set' fija valores, mode='add' suma. Ideal al procesar capturas de pantalla de la colección o dictados del usuario. Ids inexistentes se reportan en 'errors' sin abortar el resto.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | set | |
| items | Yes | Lista de cartas y cantidades |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Las anotaciones ya indican que es destructiva, y la descripción añade comportamiento útil: es transaccional, los IDs inexistentes se reportan en 'errors' y no abortan el resto de la operación. También explica la semántica de mode='set' y mode='add'.
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?
La descripción es breve, está bien estructurada y cada frase aporta: funcionalidad principal, formato de items, modos, casos de uso y manejo de errores. No hay contenido redundante ni relleno.
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?
Dado que no hay esquema de salida, la descripción explica cómo se reportan los errores, lo cual es valioso. Cubre los parámetros clave y el efecto de la operación, aunque no detalla el formato completo de la respuesta exitosa; aun así, es suficiente para invocar la herramienta correctamente.
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?
La cobertura del esquema es del 50%: items está documentado, mode no. La descripción compensa explicando qué hace cada modo y que cada item debe tener {card_id, quantity}, añadiendo significado más allá del enum y del arreglo.
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?
La descripción usa un verbo específico y un recurso claro: actualizar cantidades de múltiples cartas en una llamada transaccional. Se distingue de su hermano set_card_quantity al enfatizar el carácter masivo, y explica los dos modos de operación.
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?
Indica cuándo es ideal usar esta herramienta: al procesar capturas de pantalla de la colección o dictados del usuario. No menciona explícitamente alternativas para actualizaciones individuales, pero el contexto y la palabra 'masiva' hacen clara la diferencia.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resumen global de la colección del usuario: cartas únicas poseídas vs total del catálogo, copias totales, desglose por expansión y por rareza. Es el punto de partida para cualquier pregunta general tipo "cómo va mi colección".
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 fully covered. The description adds that the result is a global aggregation rather than a per-item listing, but it does not disclose output format, ordering, or other operational behavior; given the strong annotations, this is adequate.
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 front-loads the core scope ('Resumen global de la colección del usuario') before listing breakdown dimensions, and the second sentence earns its place by giving usage guidance. There is no filler or redundant restating of the schema.
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 parameters, rich read-only annotations, and no output schema, the description carries the responsibility of describing the result, and it does so comprehensively: unique counts, total copies, expansion, rarity, and usage context. The tool is simple enough that nothing needed for correct invocation is missing.
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, so there is no input semantics to document. The description appropriately focuses on what the result contains instead of inventing parameter details, matching the baseline for parameterless tools.
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 identifies the tool as a global summary of the user's collection and enumerates the exact content: unique cards vs catalog total, total copies, expansion breakdown, and rarity breakdown. It lacks an explicit action verb, but it is still specific enough to distinguish from per-card and catalog-management siblings.
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 explicitly says this is the starting point for general 'how is my collection going' questions, giving the agent a clear usage trigger. It does not name alternatives or exclusions such as ptcgp_missing_cards or ptcgp_list_expansions, but the global-scope language helps disambiguate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Descarga de TCGdex los datos de combate (ataques, habilidades, debilidades, retirada, stage, efectos de trainers) para las cartas que aún no los tienen. Incremental: solo procesa cartas pendientes salvo force=true. Con 'expansion' limita a un set (recomendado para llamadas desde conversación; el catálogo completo tarda minutos y conviene hacerlo con 'npm run sync' en shell). Fuentes en cascada: TCGdex primero, y para lo que TCGdex no cubra (sets recién salidos) scrapea las páginas de carta de Limitless TCG, que siempre tiene los sets nuevos. pending_total=0 significa catálogo completo.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | Reprocesar también cartas ya enriquecidas | |
| limit | No | Máximo de cartas a procesar | |
| expansion | No | Limitar a una expansión, ej. b2 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already provide safety hints, and the description adds meaningful behavioral detail: it is incremental, only processes pending cards unless force=true, uses cascading sources, may take minutes for the full catalog, and uses pending_total=0 as a completion signal. This goes well beyond what the annotations alone convey.
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 dense but every sentence earns its place: purpose, incremental behavior, expansion guidance, source fallback, and completion signal are all covered without repetition. It is front-loaded with the core purpose and then gives actionable usage detail.
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 moderately complex enrichment tool with no output schema, the description is complete enough for an agent to decide when and how to invoke it. It covers the main parameters, the external data sources, the expected duration, and the completion signal, while the annotations cover the safety profile.
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 input schema already documents all three parameters well (100% coverage), so the baseline is 3. The description adds extra value by clarifying that force=true reprocesses already-enriched cards and that expansion is the recommended way to limit work during conversational use, though it does not add much about the 'limit' 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 states a specific action and resource: it downloads combat data (attacks, abilities, weaknesses, retreat cost, stage, trainer effects) from TCGdex for cards that lack it. It also distinguishes itself from a full catalog sync by explaining incremental behavior and the recommendation to use 'npm run sync' for the complete catalog.
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 explicitly says when to use the tool ('recomendado para llamadas desde conversación' with an 'expansion' filter) and when not to (full catalog should be done via 'npm run sync' in the shell). It also explains the force parameter and the cascade fallback to Limitless TCG, leaving little ambiguity about invocation context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Detalle completo de una carta por id (ej. 'a1-036'): stats, ataques (coste, daño, efecto), habilidades, debilidades, retirada, stage, línea evolutiva, efecto (trainers), copias poseídas e imagen. El campo battle_data indica si la carta tiene datos de combate (sets muy recientes pueden no tenerlos hasta ejecutar ptcgp_enrich_catalog).
| Name | Required | Description | Default |
|---|---|---|---|
| card_id | Yes | Id de la carta |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only, idempotent, non-destructive, and closed-world. The description adds useful behavioral context beyond those annotations: it explains that battle_data may be absent for very recent sets and that enrichment is needed in that case. This gives the agent realistic expectations about data availability.
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 front-loaded with the core purpose and then provides a compact list of included fields. The second sentence about battle_data is relevant and earns its place. It is slightly dense as one long sentence but remains efficiently organized.
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 single-parameter read-only tool with no output schema, the description is complete: it lists all major return fields, provides an id format example, and explains the special battle_data caveat with a remediation path. An agent can invoke this tool correctly and interpret the response without external information.
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 fully documents the single card_id parameter with a pattern and description, so the baseline is 3. The description adds a concrete example ('a1-036') and clarifies that the id refers to a card identifier, which helps the agent format the value correctly. This is useful but not essential given the schema's coverage.
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 tool's function: retrieving the complete details of a card by its id, and enumerates the exact fields returned (stats, attacks, abilities, weaknesses, evolution line, owned copies, image). This distinguishes it from sibling tools like ptcgp_search_cards or ptcgp_list_expansions, which serve different lookup purposes.
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 clear this is the tool to use when you have a specific card id and want full card details. It also provides actionable guidance about the battle_data field and when to run ptcgp_enrich_catalog for very recent sets. It does not explicitly name alternative tools for cases where the id is unknown, so it falls just short of full usage differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Descarga una decklist real de torneo para un arquetipo (slug de ptcgp_meta_decks) y la cruza con la colección del usuario: cada carta indica 'owned' (copias poseídas) y el resumen 'buildable' dice si el mazo es montable, qué cartas faltan y cuántas. finish_index selecciona qué resultado de torneo usar (0 = mejor finish reciente).
Ejemplo de flujo: ptcgp_meta_decks -> elegir slug -> ptcgp_get_decklist(slug) -> "te faltan 2 Espeon (b3a-020) y 1 Cyrus (a2-150)". Requiere red.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Slug del arquetipo, ej. 'mega-altaria-ex-b1-espeon-b3a' | |
| finish_index | No | Índice del finish de torneo a usar |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and destructiveHint=false, and the description adds meaningful context: it requires network access, reads the user's collection, reports per-card owned copies, and indicates which cards are missing. This goes beyond the annotations without contradicting them.
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 front-loaded with the core action and returns, then offers a compact example flow and the key dependency on network. Every sentence contributes useful information, with no filler or redundant restatement of the schema.
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?
There is no output schema, so the description carries the burden of explaining return semantics, and it does: per-card 'owned' counts, a 'buildable' summary, and missing-card details. It could be more explicit about error/edge cases like invalid slugs or stale collections, but for a read-only decklist helper the essential context is present.
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 coverage is 100%, so the baseline is 3. The description adds extra value by explaining that finish_index selects which tournament result to use and that 0 means the best recent finish, and by clarifying that slug comes from ptcgp_meta_decks.
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 ('Descarga') and resource ('decklist real de torneo para un arquetipo'), then explains it crosses that decklist with the user's collection to produce owned counts and a buildability summary. This clearly differentiates it from sibling tools like ptcgp_meta_decks, which supplies the slug, and ptcgp_missing_cards, which does not focus on tournament decklists.
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 example flow: ptcgp_meta_decks -> choose slug -> ptcgp_get_decklist(slug), and notes that network access is required. It does not explicitly state when not to use this tool or name alternatives, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lista todas las expansiones del juego con sus sobres y el progreso de colección del usuario en cada una: total de cartas, poseídas únicas y porcentaje. Útil como visión general o para decidir en qué set centrarse.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare safe read-only, idempotent behavior. The description adds value beyond that by specifying exactly what the result contains: expansions, their packs, and per-expansion collection progress (total cards, unique owned, percentage). It does not discuss pagination or ordering, but it does not contradict 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?
Two compact sentences with no filler. The first states the core behavior and output details; the second adds practical usage context. Every sentence contributes 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?
There is no output schema, so the description appropriately carries the burden of describing return content, which it does by naming expansions, packs, and the three progress metrics. For a parameterless read-only listing tool with rich annotations, nothing essential is missing.
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 the schema coverage is 100%, so there is nothing for the description to clarify. Per the baseline for parameterless tools, a 4 is appropriate.
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 uses a specific verb-resource pair: 'Lista todas las expansiones del juego', which clearly states both the action and the target. It adds concrete detail about the contents (sobres, total de cartas, poseídas únicas, porcentaje) that distinguishes it from sibling card- and collection-stat 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?
It explicitly identifies when to use the tool: 'Útil como visión general o para decidir en qué set centrarse'. It does not mention alternatives or exclusion cases, so it falls just short of the full 5, but the stated use cases are clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Marca como poseídas (o ajusta) cartas de una expansión por números: numbers acepta lista y rangos, ej. "1,3,7-15,22". Pensado para volcado rápido manual: "del set a1 tengo de la 1 a la 50 menos la 33" se resuelve con dos llamadas (set 1-50, luego set 33 a 0) o una llamada "1-32,34-50". Números que no existan en la expansión se reportan en 'errors'.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | set | |
| numbers | Yes | Números y rangos: "1,3,7-15" | |
| quantity | No | ||
| expansion | Yes | Id de expansión, ej. a1 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true. The description adds useful behavior: it adjusts ownership quantities and reports non-existent numbers in 'errors'. However, it does not clarify whether 'set' overwrites existing quantities or whether other ownership data is affected.
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 compact and front-loads the main purpose. The examples earn their place and the text contains no significant padding, though it is slightly dense in its middle section.
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?
This is a destructive bulk operation with no output schema, and the description covers range parsing and error reporting. Still, the agent is left to infer exact mode and quantity meanings, which are central to invoking it correctly.
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 coverage is 50%, and the description usefully expands the 'numbers' format with examples and hints at quantity adjustments ('set 33 a 0'). But the semantics of 'mode' and 'quantity' are not explicitly explained, despite needing more compensation at this coverage level.
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 action: 'Marca como poseídas (o ajusta) cartas de una expansión por números', with a clear resource and input style. It does not explicitly differentiate itself from siblings like ptcgp_set_card_quantity or ptcgp_bulk_update_collection, which keeps it from a 5.
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 a concrete intended use case ('volcado rápido manual') and demonstrates how to handle exclusions with example calls. It lacks explicit 'use X instead' guidance versus sibling tools, so it does not reach a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Obtiene el ranking actual de arquetipos de mazo de Pokémon TCG Pocket desde Limitless (play.limitlesstcg.com, datos de torneos reales). Devuelve { decks: [{rank, name, slug, count, share}] } donde 'count' es nº de apariciones en torneos y 'share' el porcentaje del meta. El 'slug' se usa con ptcgp_get_decklist para ver la lista concreta. Requiere red.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Número de arquetipos a devolver |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Las anotaciones ya indican readOnlyHint=true, idempotentHint=true y destructiveHint=false, y la descripción no contradice esto. Añade valor al especificar que requiere red, que usa datos de torneos reales, y que el campo 'count' y 'share' tienen significados concretos.
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?
La descripción es compacta y bien estructurada: primero la acción principal, luego el formato de salida, después el uso del slug y finalmente el requisito de red. Cada frase aporta información útil sin relleno ni repeticiones.
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?
Para una herramienta simple con un solo parámetro opcional y sin output schema, la descripción es completa: explica qué devuelve, el significado de cada campo, cómo usar el slug con otra herramienta y el requisito de red. El agente puede invocarla correctamente sin ambigüedad.
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?
El schema cubre al 100% el único parámetro 'limit' con descripción clara ('Número de arquetipos a devolver') y restricciones min/max/default. La descripción no aporta semántica adicional sobre el parámetro, por lo que se mantiene la línea base.
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?
La descripción usa un verbo específico ('Obtiene el ranking actual de arquetipos de mazo'), identifica la fuente (Limitless/play.limitlesstcg.com) y detalla el objeto devuelto con sus campos. Se distingue claramente de herramientas hermanas como ptcgp_get_decklist, y de hecho relaciona el slug con esa herramienta.
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?
El contexto de uso está claro: sirve para obtener el meta actual basado en torneos reales y no para consultar cartas, expansiones o colecciones. Menciona cómo se conecta con ptcgp_get_decklist, pero no declara explícitamente cuándo no usarla frente a otras alternativas.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analiza qué cartas faltan al usuario, agrupadas por sobre (pack), ordenando los sobres por número de faltantes descendente — responde directamente a "qué sobre me conviene abrir". Filtros opcionales por expansión y rareza máxima (ej. max_rarity='d4' ignora ☆/♕, que en la práctica salen por rareza visual, no por pack normal).
Devuelve { packs: [{pack, expansion, missing_count, total_in_pack, missing: [{id, name, rarity}] }] }. Con include_cards=false omite el listado de cartas y devuelve solo el ranking (más compacto).
| Name | Required | Description | Default |
|---|---|---|---|
| expansion | No | Limitar a una expansión, ej. a3 | |
| max_rarity | No | Rareza máxima a considerar: d1-d4 (diamantes). Omite estrellas/corona si se indica | |
| include_cards | No | Incluir listado de cartas faltantes por pack | |
| limit_per_pack | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, and the description adds genuinely useful traits on top: the descending sort by missing count, the exact return shape { packs: [...] }, the include_cards=false compact mode, and a subtle caveat that max_rarity ignores ☆/♕ because they drop via visual rarity rather than normal pack pulls. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly packed paragraphs (~90 words) with the core purpose front-loaded before filters and return format. Every sentence carries information: function, ordering, the answered question, filter caveat, return shape, and mode toggle — no filler.
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?
Despite having no output schema, the description discloses the return shape, ordering, and the include_cards toggle, which largely compensates for the missing structured output. The remaining gaps are the undocumented limit_per_pack semantics and the absence of explicit sibling routing.
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 coverage is 75% and the description adds value beyond it: for max_rarity it gives a concrete example ('d4') and explains why it omits stars, and for include_cards=false it clarifies the compact-ranking consequence. The only gap is limit_per_pack, which remains undocumented in both the schema and the description.
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 ('Analiza qué cartas faltan al usuario, agrupadas por sobre') and ties directly to a user decision ('qué sobre me conviene abrir'). It is clearly distinguishable from siblings like ptcgp_collection_stats (overall stats) and ptcgp_search_cards (card search) because it defines the grouping, ordering, and the question it answers.
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?
Provides a clear use trigger: it directly answers 'which pack should I open', which tells an agent when to select this tool. However, it never names sibling tools or excludes adjacent cases (e.g., when to prefer ptcgp_collection_stats or ptcgp_search_cards), so the guidance is clear context without explicit when-not/alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analiza capturas móviles PNG/JPEG/WebP/HEIC, corrige orientación y normaliza cualquier resolución. Detecta los huecos de la cuadrícula y lee sus números con OCR local, sin enviar imágenes a Internet. Las detecciones quedan en revisión y NO cambian la colección. Las rutas deben ir en el mismo orden en que se recorrió la expansión.
| Name | Required | Description | Default |
|---|---|---|---|
| round_id | Yes | ||
| image_paths | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Aporta comportamiento relevante más allá de las anotaciones: OCR local, corrección de orientación, normalización de resolución, y que las detecciones no modifican la colección. Esto complementa los hints de idempotencia y no-destructividad sin contradecir las anotaciones.
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?
Cuatro frases concisas y sin redundancia: formatos y pre-procesado, función central, efecto colateral, y requisito de orden. Cada frase añade información necesaria y la más crítica está al final.
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?
Para un tool con dos parámetros, sin esquema de salida y con anotaciones limitadas, la descripción cubre entradas, efectos y restricciones de privacidad. El único hueco notable es que no describe la forma exacta de la salida ni cómo se integra con round_status/round_finalize, pero el resto es suficente.
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?
Con cobertura del esquema al 0%, la descripción debe compensar. Aporta significado útil para image_paths (formatos admitidos, orden de recorrido) pero no explica round_id, dejándolo a la inferencia del nombre y los siblings. Compensación parcial, no completa.
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?
La descripción dice exactamente qué hace: analizar capturas móviles, detectar huecos de cuadrícula y leer números con OCR. También diferencia el tool de los de colección al declarar que NO cambia la colección y que las detecciones quedan en revisión.
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?
Establece contexto claro de uso: dentro de una ronda, con capturas locales, sin enviar imágenes a Internet, y con rutas en el orden de recorrido. No nombra explícitamente alternativas ni condiciones de no-uso, pero la restricción de revisión distingue su lugar en el flujo.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Aplica una ronda completa de forma transaccional. Requiere confirm=true y que el total esperado de poseídas coincida exactamente con total_catálogo - huecos. Por defecto solo usa huecos confirmados; use_auto_detections permite detecciones OCR con confianza >=0.84. En modo minimum conserva cantidades superiores existentes.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | Yes | ||
| round_id | Yes | ||
| use_auto_detections | No | ||
| expected_owned_unique | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already mark the tool as destructive and non-read-only, and the description adds valuable behavioral detail beyond that: transactional application, mandatory confirmation, exact-match requirement, the OCR confidence threshold for auto-detections, and preservation of higher quantities in minimum mode. No contradiction exists.
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 compact: three dense sentences that front-load the purpose and then list prerequisites and optional behaviors. There is no filler or repetition of schema information.
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 destructive tool with no output schema and only basic annotations, the description covers the action, required flag, exact matching condition, and optional auto-detection behavior. The main missing piece is explaining what 'minimum mode' is or how it is triggered, since it does not map to any schema parameter.
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?
With 0% schema description coverage, the description compensates well by explaining confirm=true, use_auto_detections's OCR-confidence behavior, and expected owned unique via the total_poseídas condition. It does not explicitly name round_id, but round_id is self-evident from the schema, and 'minimum mode' is mentioned without a corresponding 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 opens with a concrete action, 'Aplica una ronda completa de forma transaccional', and clearly names the resource being operated on. This cleanly distinguishes the tool from siblings like round_start, round_status, and round_record.
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 specifies important invocation preconditions: confirm must be true, expected owned total must exactly match total_catálogo - huecos, and it explains the default vs. use_auto_detections behavior. It does not explicitly name alternatives or say when not to use the tool, but the round_* sibling workflow makes the intended usage reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Registra observaciones confirmadas tras revisar las capturas. missing_numbers son huecos numerados; owned_numbers permite corregir falsos positivos del OCR. En quantity_mode='minimum', una carta visible equivale a cantidad mínima 1. En modo exact debe proporcionarse quantity por carta poseída. Esta operación aún no altera la colección.
| Name | Required | Description | Default |
|---|---|---|---|
| round_id | Yes | ||
| quantities | No | ||
| owned_numbers | No | Números que el OCR marcó por error como huecos | |
| missing_numbers | No | Ej. "2,5-6,20" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal idempotency and non-destructiveness, so the description does not need to repeat those. It adds valuable behavioral nuance by stating that the operation 'aún no altera la colección', which would otherwise be unclear given readOnlyHint=false. It also explains mode-dependent interpretation of card visibility and quantities.
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?
Four dense sentences, all earning their place. The main purpose is front-loaded, followed immediately by parameter-specific semantics and the important non-mutation note. 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?
The description covers the core operation and mode behavior, and the idempotency annotation covers repeat-safety. However, it omits the place of this step in the round workflow (relative to round_analyze_screenshots and round_finalize), and the undocumented quantity_mode parameter is a notable gap for an agent trying to invoke the tool correctly.
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 coverage is 50%, so the description carries part of the burden. It usefully defines missing_numbers as numbered gaps and owned_numbers as OCR false-positive corrections, and explains the quantities behavior. However, it repeatedly references quantity_mode values ('minimum', 'exact') even though no such parameter appears in the schema, which creates ambiguity and cannot fully compensate for the undocumented round_id and quantities parameters.
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 uses a specific verb ('Registra observaciones confirmadas') with a clear resource ('tras revisar las capturas') and immediately clarifies what the tool is for. The closing note 'aún no altera la colección' differentiates it from sibling collection-mutation tools, and the missing/owned distinction makes its role in the round workflow clear.
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 contextual timing ('tras revisar las capturas') and explains the two functional cases: correcting OCR false positives with owned_numbers and recording confirmed missing numbers. It also describes the quantity modes, though it never explicitly names an alternative or says 'use this instead of X'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Crea una ronda para una expansión completa. Una ronda empieza en la primera carta y termina en la última captura de esa expansión. expected_owned_unique debe ser la suma de los contadores visibles de la cabecera (diamantes + estrellas + shiny/corona); se usa para impedir que un OCR incompleto altere la colección. quantity_mode='minimum' es el adecuado para la cuadrícula normal: una carta visible prueba al menos una copia y conserva cantidades superiores ya registradas.
| Name | Required | Description | Default |
|---|---|---|---|
| label | No | ||
| expansion | Yes | Id de expansión, ej. a3a | |
| quantity_mode | No | minimum | |
| expected_owned_unique | No | Total de cartas únicas poseídas mostrado en la cabecera |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide no behavioral hints beyond non-read-only status, so the description carries the burden. It discloses meaningful behavior: the expected_owned_unique guard blocks incomplete OCR effects, and quantity_mode='minimum' preserves already-recorded higher quantities. It does not cover side effects if a round is already active, nor the response format, but it adds substantial behavioral context beyond 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?
The description is three concise sentences with no filler. It puts the core purpose first, then adds the two pieces of parameter guidance that are most likely to be misunderstood. 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 state-changing round-start tool, the description covers the essential invocation semantics well: what a round is, how it behaves across captures, and how to fill the safety-related parameters. It does not describe the return value or what happens when starting a round while another is already in progress, and label is still unexplained, so it is not fully 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 coverage is 50%, and the description compensates well for the two most nuanced parameters: expected_owned_unique is defined as the sum of visible header counters, and quantity_mode='minimum' is explained in terms of preserving superior existing quantities. Expansion is also contextualized as the scope of the round. Only the optional label parameter remains semantically undocumented.
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 uses a specific verb and resource: 'Crea una ronda para una expansión completa.' It also defines the round's lifecycle from first to last captured card, which clearly distinguishes this from sibling round tools like round_record, round_finalize, and round_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 description provides clear context for when to use the tool and how to set the critical parameters: a round is for a full expansion, expected_owned_unique prevents incomplete OCR from corrupting the collection, and quantity_mode='minimum' is appropriate for normal grids. It does not explicitly name alternatives or state when not to use the tool, but the guidance is still practical and unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Muestra una ronda concreta o las rondas recientes, con capturas, detecciones confirmadas y pendientes. No modifica datos.
| Name | Required | Description | Default |
|---|---|---|---|
| round_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false; the description's 'No modifica datos' reinforces rather than extends them. It adds mild context that the result can include one round or recent rounds and captures/confirmed/pending detections, but it does not detail response shape, limits, or auth requirements.
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?
One sentence front-loads the action and scope, followed by a useful non-modification note. No wasted words or repeated schema details.
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 tool with one optional parameter and no output schema, the description states what is shown and explicitly rules out data modification. It could be more explicit about the 'recent' window or exact response structure, but there are no critical gaps for invocation.
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?
With 0% schema description coverage, the description compensates by implying round_id is optional: a concrete round vs recent rounds. This gives the agent enough semantic meaning for the sole optional parameter, even though it does not mention round_id's format or source.
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 uses a specific verb, 'Muestra', and a clear resource: a specific round or recent rounds, listing the included data (captures, confirmed/pending detections). This separates it from sibling round_* tools that start, analyze, record, or finalize rounds.
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?
Usage context is only implied: 'No modifica datos' and the title 'Estado y previsualización' signal a read-only status check, and sibling names suggest the workflow. However, there is no explicit statement of when to prefer this tool or what other sibling would be appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Busca cartas en el catálogo completo de Pokémon TCG Pocket, con cantidad poseída incluida en cada resultado.
Filtros (todos opcionales, combinables):
query: texto parcial del nombre (case-insensitive)
text_search: busca en efectos de ataques, habilidades y cartas trainer (ej. "heal", "discard", "draw")
expansion: id de expansión (a1, a1a, a2, a2a, a2b, a3, a3a, a3b, a4, a4a, a4b, b1, b1a, b2, b2a, b2b, b3, pa, pb)
pack: nombre del sobre (Mewtwo, Charizard, Pikachu, etc.)
rarity: símbolo o alias (d1=◊, d2=◊◊, d3=◊◊◊, d4=◊◊◊◊, s1=☆, s2=☆☆, s3=☆☆☆, crown=♕, promo)
type: Grass|Fire|Water|Lightning|Psychic|Fighting|Darkness|Metal|Dragon|Colorless|Trainer
category: Pokemon|Trainer
stage: Basic|Stage1|Stage2
min_damage: daño mínimo del mejor ataque (para construcción de mazos)
has_ability: true para solo cartas con habilidad
owned_filter: 'all' (defecto) | 'owned' (quantity>0) | 'missing' (quantity=0) | 'duplicates' (quantity>1)
ex: true para solo cartas ex
limit/offset para paginación
Cada resultado incluye max_damage y has_ability. Para ataques/habilidades/efectos completos usa ptcgp_get_card. Los datos de combate provienen de TCGdex; sets muy recientes pueden no tenerlos aún (ejecutar ptcgp_enrich_catalog periódicamente).
Ejemplos: "atacantes de fuego para mi mazo que ya tenga" -> type="Fire", min_damage=100, owned_filter="owned". "cartas que curen" -> text_search="heal".
| Name | Required | Description | Default |
|---|---|---|---|
| ex | No | Solo cartas ex | |
| pack | No | Nombre del sobre | |
| type | No | Tipo de carta | |
| limit | No | ||
| query | No | Texto parcial del nombre | |
| stage | No | ||
| offset | No | ||
| rarity | No | Rareza: d1-d4, s1-s3, crown, promo o símbolo | |
| category | No | ||
| expansion | No | Id de expansión, ej. a1 | |
| min_damage | No | Daño mínimo del mejor ataque | |
| has_ability | No | Solo cartas con habilidad | |
| text_search | No | Buscar en efectos de ataques/habilidades/trainers | |
| owned_filter | No | all |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, the description discloses that results include owned quantity, max_damage, and has_ability. It also warns that combat data comes from TCGdex and may be missing for recent sets, pointing to enrichment. This is substantive behavioral context that helps an agent anticipate incomplete results.
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 every line earns its place: summary, structured filter list, cross-references, data caveat, and usage examples. It is well-organized and front-loaded with the core purpose.
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 the tool has 14 optional parameters and no output schema, the description is unusually complete. It explains what filters do, what results contain, how to get more detail, and when data may be incomplete. An agent can select and invoke this tool correctly with confidence.
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?
With schema coverage at 64%, the description compensates thoroughly: it explains query case-insensitivity, text_search semantics with examples, expansion ID lists, rarity aliases, owned_filter values with quantities, and min_damage's deck-building purpose. This adds significant meaning beyond the raw schema.
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: 'Busca cartas en el catálogo completo de Pokémon TCG Pocket', and explicitly states the output includes owned quantity. It also differentiates itself from siblings by directing users to ptcgp_get_card for full attack/ability details and ptcgp_enrich_catalog for stale combat 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 strong usage context: all filters are optional and combinable, and it provides natural-language examples such as 'type=Fire, min_damage=100, owned_filter=owned'. It explicitly names alternatives for full card details and catalog enrichment, though it does not fully contrast with every potentially relevant sibling like ptcgp_collection_stats or ptcgp_missing_cards.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Registra cuántas copias de una carta posee el usuario. mode='set' fija el valor exacto (defecto); mode='add' suma (admite negativos para restar, nunca baja de 0). Usa ptcgp_bulk_update_collection para varias cartas o ptcgp_mark_range para rangos de números consecutivos.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | set | |
| card_id | Yes | Id de carta, ej. a1-001 | |
| quantity | Yes | Cantidad (set) o delta (add) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal destructive/read-write behavior, so the description need not repeat that. It adds valuable semantics: mode='set' writes an exact value, mode='add' supports negative deltas, and the result never drops below 0. This goes beyond the schema and annotations but stops short of describing side effects beyond the clamp.
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 compact sentences cover purpose, mode semantics, and sibling routing with zero filler. The most essential behavioral detail (mode behavior) is placed first, and alternative-tool guidance is appended efficiently.
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 mutation tool with 3 parameters and no output schema, the description covers the core semantics and alternative routing. It does not mention return behavior, but given the low complexity and supporting annotations, the remaining gap is minor.
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 coverage is 67%, and the description compensates for the undocumented 'mode' parameter by explaining 'set' vs 'add' and the default. It also clarifies quantity semantics for 'add' mode (negative deltas, never below 0), which is not fully captured in the schema description.
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 uses a concrete verb ('Registra cuántas copias... posee el usuario') tied to a specific resource, and it explains the two modes of operation. It also names sibling tools for different use cases, which helps an agent distinguish this tool from ptcgp_bulk_update_collection and ptcgp_mark_range.
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 explicitly tells the agent when to prefer alternatives: use ptcgp_bulk_update_collection for multiple cards and ptcgp_mark_range for ranges of consecutive numbers. This makes the 'when to use vs. alternatives' decision explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Descarga el catálogo completo de cartas y expansiones desde el dataset comunitario (chase-manning/pokemon-tcg-pocket-cards, scrapeado de Limitless TCG) y actualiza la base local. Ejecutar tras el primer arranque y cuando salga una expansión nueva. No toca la colección del usuario. Requiere red.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the operation as non-read-only, idempotent, and non-destructive. The description adds valuable context beyond those annotations by stating that it does not touch the user's collection and requires network access. This is useful behavioral disclosure, though it does not detail return values or failure behavior.
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 three short, purposeful sentences. The first states the core action, the second gives exact trigger conditions, and the third adds two relevant constraints. There is no filler and the most important information is front-loaded.
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 zero-parameter sync operation with annotations covering idempotence and destructiveness, the description covers the source, the timing, the network requirement, and the fact that the user collection is unaffected. It could mention what the tool returns or how progress is reported, but that is not necessary for correct invocation.
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 the schema coverage is effectively complete. The baseline for a zero-parameter tool is 4, and the description does not need to add parameter-level detail because there are none to explain.
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 action: download the complete catalog of cards and expansions from the community dataset and update the local base. It names the exact source and the outcome, making the tool's purpose easy to grasp. However, it does not explicitly differentiate this tool from the sibling ptcgp_enrich_catalog, so it stops short of a 5.
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 timing guidance: run after first startup and when a new expansion is released. It also adds a practical precondition by stating that network access is required. It does not mention when not to use the tool or name an alternative tool, so it lacks the exclusion guidance needed for a 5.
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.
v1.1.0ptcgp_bulk_update_collectionptcgp_collection_statsptcgp_enrich_catalogptcgp_get_cardptcgp_get_decklistptcgp_list_expansionsptcgp_mark_rangeptcgp_meta_decksptcgp_missing_cardsptcgp_round_analyze_screenshotsptcgp_round_finalizeptcgp_round_recordptcgp_round_startptcgp_round_statusptcgp_search_cardsptcgp_set_card_quantityptcgp_sync_catalogScored across 17 tools
The core resources are separated by domain (catalog, collection, decks, round-based OCR import), but several tools blur together: sync_catalog vs enrich_catalog, collection_stats vs list_expansions, and missing_cards vs search_cards with owned_filter=missing all have overlapping coverage and rely heavily on descriptions to disambiguate. The round_* workflow is clearly differentiated.
All tools share the ptcgp_ prefix and snake_case, but the internal convention is mixed: most use verb_object (search_cards, set_card_quantity) while some are noun phrases (collection_stats, missing_cards, meta_decks) and the round tools are noun-first (round_start, round_finalize). Still readable, but not a consistent verb_noun pattern throughout.
17 tools is slightly above the ideal range, but the scope is broad enough that most tools earn a place: catalog sync/enrich, card searching, collection updates, deck data, and a deliberate OCR round workflow. It feels somewhat heavy, especially with five round_* tools, but not bloated.
The surface covers the full collection-management lifecycle: ingest catalog, search/get cards, track owned quantities, analyze missing cards, and import via OCR rounds, plus metagame deck lookup. Minor gaps exist such as no way to discard/delete a round or manage custom saved decks, but these are workable and outside the core stated purpose.
Look up Pokemon TCG Pocket cards, sets, packs, and evaluate decks with battle simulations.
Connect to your CollectHolo Pokémon card collection. Check your portfolio value, look up card, sealed and graded (PSA/BGS/CGC) prices from Cardmarket, TCGplayer, eBay, Goldin and Fanatics, search the catalog in six languages, import a whole collection from a spreadsheet, and add or update holdings in plain language. Every change asks for confirmation.
Provide detailed Pokémon data and information through a standardized MCP interface. Enable LLMs an…
Trading card prices and grading ROI for 1.5M+ Pokémon, Magic, Yu-Gi-Oh! and sports cards. Read-only.