balatro-agent
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| launch_gameA | Windows: verify Steam AppID 2379780, launch normally and wait for MCP. A new permitted launch also requests an independent bilingual activity window; closing or failing that viewer never controls gameplay. It displays public MCP summaries, submitted reason and run_plan, not internal model reasoning. If already running, verify/show its window; UNKNOWN allows only restoring that window. timeout_s is 0-30 seconds. operation_id is durably deduplicated; identical requests query only, without reopening the viewer. No game clicks, pending-action deletion, paths, commands or process IDs. |
| close_gameA | Under an explicit user close request or standing authorization for necessary maintenance closure in docs/balatro-ai/maintenance.md: normally close the verified Balatro window and confirm exit, without force kill. Requires known current profile, latest observation_id, ready, normal results or idle main menu, and no pending actions. Reject active runs/UNKNOWN. 0-30 seconds; operation_id deduplicates. An uncertain response permits querying the identical operation only. |
| healthA | Read connection, fixed versions, actual native profile and historical test-profile comparison. A profile mismatch is information only. Performs no game action. |
| observeB | Read the player-visible state of the current identified native profile. Unknown actual profiles are reported. server_time is service wall-clock metadata outside the observation ID, usable for run timing, not pure model thinking time. No deck order, seeds or hidden card identity. Game names and descriptions retain their current game language. |
| wait_until_readyA | Poll read-only until normal UI is actionable; default 10 seconds, maximum 30. Returns ready, timeout, disconnected or unsupported. Readiness alone does not confirm an action completed. |
| actA | Submit one native action bound to current observation_id, unique action_id, short reason and actual experience_refs. For the bilingual activity window, reason may use '[zh-CN]Chinese rationale [en]English rationale' (replace placeholders with one concise equivalent sentence in each language, no internal reasoning); plain text remains valid. parameters: select={region,positions}; reorder={region,order}; blind={blind_slot}; buy/sell/use/take={region,position}; select_setup_option={kind:deck or stake,position}; play/discard may use {positions:[complete selection]} with positions-v1, or {} for already selected cards; others={}. native-target-v1 clicks the actual target/button; select consumable hand targets separately. Pack Tarot/Planet/Spectral immediate use is use; select_pack_card takes playing cards/Jokers or explicitly enabled consumables. Choose current visible unlocked candidates; native settings only. Random non-challenge. Identical IDs query, changed content rejects. AWAITING_INPUT: observe, close each native prompt once, query original navigation. Service UNKNOWN: pause gameplay, query the original ID and observe; continue local diagnosis, repair and isolated verification under maintenance policy, without replaying or bypassing pending records. Only an exact host approval-timeout receipt confirming no execution permits one identical client retry after original-ID and unchanged-state checks; see prompts/mcp-evidence.js. |
| action_statusC | Query an action record in this game session and return filtered feedback; never replay it. Session change or missing records remains UNKNOWN; no cross-process exactly-once guarantee. |
| recover_lost_sessionC | First query action_status and observe. Retire only after actual session change and confirmed record loss, with known current profile, fresh observation and ready. Requires a pending intent or, with all checkpoints clear, an unambiguous missing-record status previously delivered by this service in the lost session. A missing record alone never proves non-submission. The original remains UNKNOWN; RETIRED is not success or a normal loss. No game action, replay or save read. Identical recovery_id/parameters query the durable receipt. Reject live old sessions, stale observations or unknown profiles. |
| read_notesA | Actually read disk, local experience over read-only baseline; TEST is separate. Each experience topic has one current.md; revision is an update counter and older content is not retained for reading. Default strategy returns only actionable rules, conditions, counterexamples and confidence, plus short update references. It omits sources, historical facts, timestamps and write IDs. Explicit content/full views include audit information; full also returns the Chinese Markdown guide. Read EXP-GENERAL-GUIDE first, then relevant topics. Omitted IDs read all, [] reads none. index returns truncated previews/revision refs, not full reading or action evidence. query is literal, at most 80 characters; pages contain 20 entries, continue with next_offset. TEST retains historical reads. Existing note text keeps its original language. |
| write_noteB | Atomically replace the same local current.md, never upload or overwrite baseline. First local edit starts from the baseline current content, without copying old versions. Before amending, explicitly read content/full to preserve current strategy and audit fields. Submit the full updated content; it replaces rather than automatically merges text. 0 creates; updates require current expected_revision. The Chinese guide contains strategy only; sources, historical facts and compact hash receipts are separate audit metadata. Default strategy response omits audit fields. Receipts deduplicate write IDs without retaining old strategy content. Legacy local data requires the maintenance migration. TEST remains separate. content: sources[{run_id,steps}], facts, interpretation, conditions, counterexamples, confidence(low/medium/high), revision_reason. Formal run IDs start n5-, TEST starts test-. Model writes from actual feedback. Read back to verify. |
| run_planA | Model-authored short run memory. read actually reads disk; omit other parameters. write requires latest observation_id, expected_revision(first 0), unique write_id and content{objective,priorities:[1-4],recheck_when:[1-4],experience_refs:[up to 6 fully read EXP-XXX@rN]}. For the bilingual activity window, objective and priorities[0] may each use '[zh-CN]Chinese summary [en]English equivalent' (replace placeholders with short matching summaries); plain text remains valid. At most 2000 UTF-8 bytes, 200 characters per item including both languages and tags. Only confirmed start_run/continue_run, actionable current run, no pending action. Same ID/content queries. Revise on material changes, read after compression. Run/profile/session changes invalidate reuse but retain history. No strategy generation or game action. |
| calculateA | Explicit public numbers only. sum/difference/product/quotient/mean/median/variance_population take {values:[numbers]}; combination takes {n,k}; hypergeometric takes {population,successes,draws,min_successes,max_successes}, conditioned on uniform sampling without replacement. Up to 200 values/1000 population. Reject unknown/nonfinite values, zero divisors, extra fields and limits. No game/network reads, action recommendation, expressions or arbitrary code. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 12 tools
Tools cover distinct phases (session lifecycle, observation, action, notes, planning, math) and most purposes are clear. However, observe, action_status, and wait_until_ready all return status-like information, and recover_lost_session overlaps with action_status in record handling, creating minor confusion.
All names use snake_case, but the set mixes single verbs (observe, act, calculate), noun phrases (health, action_status, run_plan), and verb_noun patterns (recover_lost_session, read_notes). This inconsistent structural convention is readable but not predictable.
12 tools fit a complex game-agent domain that spans process control, game interaction, durable notes, run planning, and calculation. Each tool appears to earn its place without excessive redundancy.
The surface covers session lifecycle, observation, action submission, health, notes, run planning, and math. Gaps include no explicit profile-switching or action-listing tool, but these are minor workarounds within the described workflows.