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., "@sc2-mcp analyze my latest SC2 replay and tell me what I did wrong"
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 StarCraft2.ai. From Claude Code, Claude Desktop, Cursor or any other MCP client you can:
Ask StarCraft II questions. Answers come from the same knowledge base the AI Coach cites: Liquipedia unit data, current patch notes, strategy articles and pro-game insights.
Upload a replay from a file on your computer or from a download link.
Get an AI Coach report on a game: strengths, mistakes, key moments and what to work on.
Ask follow-up questions about a game ("why did I lose that fight at 8:30?").
You need a StarCraft2.ai account. The tools use your account's minerals, at the same prices as the website:
What | Cost |
Knowledge search, uploads, reading an existing report | free |
AI Coach report on a replay | 1 mineral (free if the replay already has one) |
Follow-up questions on a replay | first 3 free, then 1 mineral per 20 |
A tool never spends minerals unless it's called with confirm_spend: true, and the tool descriptions tell the assistant to ask you first. If your client supports MCP elicitation, the server also asks you directly before spending, so nothing the assistant reads in a replay or a report can approve a purchase for you. Buy minerals at starcraft2.ai/en/billing.
/plugin marketplace add tomkit/sc2-mcp
/plugin install sc2-coach@starcraft2-aiThe plugin adds the MCP server and a skill that tells Claude how to use it. Then ask something like "analyze my latest SC2 replay" and Claude will sign you in.
git clone https://github.com/tomkit/sc2-mcp ~/sc2-mcp
claude mcp add sc2 -- node ~/sc2-mcp/dist/index.jsClone the repo, then add this to the client's MCP config (for Claude Desktop, claude_desktop_config.json):
{
"mcpServers": {
"sc2": {
"command": "node",
"args": ["/absolute/path/to/sc2-mcp/dist/index.js"]
}
}
}It needs Node.js 18.17 or newer on your PATH, including for the Claude Code plugin (Claude Code's native installer doesn't bring Node with it). dist/index.js is a self-contained bundle, so there is nothing to npm install.
Related MCP server: RAG MCP Server
Every tool except login needs you signed in. The login tool opens StarCraft2.ai in your browser. Sign in there if you aren't already, check the request, and click Allow. That's the OAuth 2.1 authorization-code flow with PKCE and a loopback redirect to 127.0.0.1 (RFC 8252). The server never sees your password.
The resulting token is saved to ~/.config/sc2-mcp/credentials.json (%APPDATA%\sc2-mcp on Windows) with owner-only permissions. It lasts 180 days. logout revokes it, and so does Disconnect on starcraft2.ai/auth/mcp, which lists every connected device.
The browser has to run on the same machine as the server, because the sign-in comes back to 127.0.0.1. For a remote box (SSH, a devcontainer, a cloud VM), sign in once on a machine with a browser, copy access_token out of its credentials.json, and set it as SC2_API_TOKEN in the remote server's environment. That variable takes precedence over the saved token, which follows the MCP spec's advice for stdio servers to take credentials from the environment. Treat the token like a password: it can spend your minerals.
Tool | What it does |
| Browser sign-in; revoke and forget the token |
| Mineral balance, claimed SC2 profile, prices |
| Passages from the SC2 knowledge base for general questions |
| Upload a |
| Your uploads, newest first |
| A replay's details and its AI Coach report, if one exists |
| Run the AI Coach (1 mineral, needs |
| Ask the coach a follow-up question about a coached replay |
| 20 more follow-up questions on a replay (1 mineral, needs |
A coach run takes 3–7 minutes. analyze_replay waits up to wait_seconds (default 50) and sends MCP progress notifications while it waits. If the run isn't done by then it returns and the run carries on; get_analysis picks up the report. Runs that fail on the site's side are refunded automatically.
Variable | Default | |
| – | Use this token instead of the browser sign-in |
|
| Site origin (for local development) |
|
| Where the token is saved |
| – |
|
npm install
npm run build # typecheck + bundle to dist/index.js (commit the bundle)
npm test # protocol and credit-gating tests against a mock site
npm run inspect # MCP InspectorThe end-to-end test (real browser sign-in, upload, a paid coach run and follow-ups against a local build of the site) lives in the site's repository.
MIT
Run StarCraft2.ai's AI Coach on an uploaded replay. COSTS 1 MINERAL (the site's paid credits) unless the replay already has a report, which is returned free. Refuses to spend unless confirm_spend is true — tell the user the price and their balance and get a yes first. A run takes 3–7 minutes: this waits up to wait_seconds, then returns and the run continues; call get_analysis to collect it. Failed runs are refunded by the site.
| Name | Required | Description | Default |
|---|---|---|---|
| replay | Yes | Replay id, short id, slug, or a StarCraft2.ai replay URL. | |
| upgrade | No | Re-run an existing report that was made with an older coach version. Free; only works when the report is outdated. | |
| language | No | Report language (default en). | |
| wait_seconds | No | Max seconds to wait before returning (default 50). | |
| confirm_spend | No | Set to true ONLY after the user has explicitly agreed, in this conversation, to spend 1 mineral on this. Never set it on your own initiative. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: discloses credit cost and units, refusal behavior without confirm_spend, the 3–7 minute runtime, the wait_seconds cap and async continuation, and refunds on failure. Annotations only say non-readonly/non-idempotent; the description supplies the real behavioral contract.
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?
Five dense sentences, zero filler, front-loaded with purpose then cost then consent then timing. Every sentence carries an operational fact an agent needs.
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?
No output schema, but the description closes that gap by telling the agent the run is async and that get_analysis collects the result. Cost, consent, timing, and refund paths are all covered for a 5-parameter paid 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 coverage is 100% so the baseline is 3, but the description adds semantics the schema cannot: confirm_spend is framed as a gated consent flag ('tell the user the price and their balance and get a yes first'), and wait_seconds is contextualized as a bounded wait before the run continues asynchronously.
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?
States a specific verb+resource: 'Run StarCraft2.ai's AI Coach on an uploaded replay.' This clearly distinguishes it from siblings like upload_replay (ingestion), get_analysis (retrieval), and ask_about_replay (Q&A).
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?
Explicitly states when the report is returned free (already has a report), when it costs (1 mineral), that confirm_spend must be true with user agreement first, and routes to get_analysis to collect the async result. Alternatives and conditions are all named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ask StarCraft2.ai's coach a follow-up question about a replay that has an AI Coach report (it can check the replay's numbers and the knowledge base). The first 3 questions per replay are free; after that the site needs 1 mineral per 20 more, bought with unlock_more_questions (ask the user first). Shows the remaining free/unlocked questions.
| Name | Required | Description | Default |
|---|---|---|---|
| replay | Yes | Replay id, short id, slug, or a StarCraft2.ai replay URL. | |
| question | Yes | The user's question, in their words. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations mark this non-read-only and non-idempotent, and the description explains exactly why: each call consumes a question from a quota (first 3 free, then 1 mineral per 20). It also discloses the prerequisite report, the confirmation requirement before purchase, and that remaining free/unlocked questions are surfaced. That is rich behavioral context beyond the structured fields.
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 dense sentences, front-loaded with the purpose before the cost model and output note; nothing is wasted. The parentheticals are informative rather than filler, though the cost sentence is packed enough to be slightly hard to parse on first read.
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 still covers the return signal (remaining free/unlocked questions), the precondition (existing AI Coach report), the cost and the escape hatch (unlock_more_questions, with user confirmation). An agent has everything needed to invoke this correctly and to explain the cost to the user.
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% and both parameters (replay, question) are fully documented in the schema, including accepted replay identifier formats. The description adds only the framing that the question is a 'follow-up' in the user's words, which is largely redundant, so the baseline 3 applies.
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?
Names a specific verb and resource (ask a follow-up question about a replay) and states the prerequisite that the replay must have an AI Coach report. It implicitly separates itself from search_sc2_knowledge by noting the coach itself checks the knowledge base, but it never explicitly contrasts with get_analysis or analyze_replay, which an agent would weigh when routing a replay question.
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?
Clear context for use: a follow-up question, on a replay that already has an AI Coach report, with an explicit instruction to ask the user before spending minerals via unlock_more_questions. It lacks a stated 'when not to use' case (e.g., general StarCraft questions should go to search_sc2_knowledge), so the routing is good but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The signed-in user's mineral balance (StarCraft2.ai credits), claimed SC2 profile, and where to buy more minerals.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that the result is scoped to the signed-in user and includes a purchase pointer, but says nothing about auth failure behavior or what happens when no SC2 profile is claimed. Adequate but not rich.
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-loaded with the primary resource (mineral balance) and trailing the secondary items. No filler, no repetition of the title.
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 and no parameters, the description carries the return-value burden and does so by enumerating the three content areas an agent will receive. It stops short of describing structure or whether the purchase link is conditional, which keeps it from a 5.
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 takes zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly implies no input is needed by framing everything as the current user's own data.
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 the exact resource returned: the signed-in user's mineral balance, claimed SC2 profile, and purchase location. This is specific enough to separate it from siblings like login, list_my_replays, and get_analysis, though it never states an explicit verb (e.g. 'retrieve').
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 is only implied: an agent infers you call this to inspect your own account state. There is no statement of when to prefer it over siblings, nor any prerequisite such as being logged in, though the sibling set (login/logout) makes the context fairly obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a replay's details and its AI Coach report if one exists. If this session started a coach run that is still going, waits for it (up to wait_seconds) and returns the report when it lands. Free — never spends minerals.
| Name | Required | Description | Default |
|---|---|---|---|
| replay | Yes | Replay id, short id, slug, or a StarCraft2.ai replay URL. | |
| wait_seconds | No | Max seconds to wait for an in-progress run (default 50). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds real value beyond them: it discloses the blocking wait behavior capped at wait_seconds and the cost profile ('Free — never spends minerals'), which matters in a toolset that contains unlock_more_questions.
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 short sentences, front-loaded with what is read, then the wait condition, then the cost note. Every sentence carries distinct information with no 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?
With no output schema, the description must convey what comes back; it names both payloads (replay details and AI Coach report) but does not describe the report's shape or what happens if no report exists beyond the conditional phrasing. Adequate for a read tool with full schema coverage.
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 both parameters are already documented, including the replay id formats and the wait_seconds default of 50. The description only restates the wait cap, adding no syntax or format detail beyond the schema; baseline 3 applies.
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?
States a specific verb and resource: reads a replay's details plus its AI Coach report. Clear on its own, but does not distinguish itself from siblings like analyze_replay or ask_about_replay, which plausibly overlap in purpose.
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 is implied rather than stated: the description covers the in-progress-run case and the wait behavior, but never says when to pick this over analyze_replay or ask_about_replay. No explicit when-not conditions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The signed-in user's uploaded replays on StarCraft2.ai, newest first, with whether each has an AI Coach report. Free.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many (default 10). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish the safe-read profile (readOnlyHint=true, openWorldHint=true), so the bar is lower. The description still adds real behavioral detail beyond them: results are ordered newest-first, each row carries an AI Coach report flag, and the call is free.
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?
A single dense sentence with the scope front-loaded, followed by ordering, per-item content, and cost. Nothing is wasted and no reading order is required.
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 carries the return-value burden and does so adequately by naming the ordering and the AI Coach report flag, plus the default page size is in the schema. It stops short of describing pagination or other returned fields, but an agent has enough to call 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 description coverage is 100% and the single 'limit' parameter is fully documented in the schema, including its default and 1-50 range. The description adds nothing about the parameter, so the baseline 3 applies.
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 gives a specific verb (list) plus a tightly scoped resource: the signed-in user's own uploaded replays. That scope cleanly separates it from siblings like search_sc2_knowledge, upload_replay, and get_analysis, though no sibling is named explicitly.
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?
There is no statement of when to reach for this tool versus alternatives (e.g. get_analysis or analyze_replay for a single replay). The trailing 'Free.' hints at a cost dimension relative to paid tools, but no condition for choosing this one is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sign in to the user's StarCraft2.ai account. Opens the site's sign-in page in the browser (OAuth with PKCE); the user approves there and this tool finishes. Required before any other tool. If the browser didn't open, show the user the URL from the result.
| Name | Required | Description | Default |
|---|---|---|---|
| wait_seconds | No | How long to wait for the user to finish in the browser (default 45). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by disclosing the interactive flow: a browser page opens, the user approves externally, then the tool completes. It also surfaces a failure mode and recovery step (browser didn't open → show the result URL), which annotations cannot 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?
Three tightly written sentences, front-loaded with purpose and precondition, with no redundant restatement of the name or title.
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?
No output schema exists, and the description compensates by telling the agent what the result contains (a URL) and what to do with it. Combined with the precondition, an agent has everything needed to invoke and handle this 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 100% and the single wait_seconds parameter is fully documented in the schema, so the baseline of 3 applies. The description does not elaborate on the wait behavior beyond implying the tool blocks until the user finishes, adding little over the 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?
States a specific verb (sign in) and resource (the user's StarCraft2.ai account), and explains the mechanism (browser OAuth with PKCE) so it is clearly distinguishable from siblings like logout and get_account.
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?
"Required before any other tool" gives explicit precondition guidance, and the fallback instruction ("if the browser didn't open, show the user the URL from the result") tells the agent what to do on failure. It stops short of naming alternatives or when-not conditions, so it is clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sign out of StarCraft2.ai on this computer: revokes this device's token and deletes it locally.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds genuine value beyond them by specifying exactly what is destroyed (this device's token) and the scope (local machine only), which the annotations alone cannot 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?
A single front-loaded sentence with the action first and the mechanism second. Every clause earns its place, with 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?
For a no-parameter, no-output-schema tool with full annotation coverage, the description provides everything needed to call it correctly: the action, its local scope, and its destructive effect.
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 takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate beyond what the empty schema already shows.
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 ('Sign out') and resource ('StarCraft2.ai on this computer'), and it clarifies the internal action as revoking and deleting this device's token. This clearly distinguishes it from the sibling 'login'.
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 is implied by 'on this computer', which signals device-scoped sign-out, but the description never states when to use this versus a potential global logout or how it interacts with 'login'. No explicit alternatives or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search StarCraft2.ai's StarCraft II knowledge base — Liquipedia unit/building/ability data, current patch notes, strategy and matchup articles, and pro-game insights — the same sources the AI Coach cites. Use it to answer general SC2 questions (unit stats, counters, build orders, patch changes, matchup advice); answer from the passages and cite their URLs. Free.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of passages (default 5). | |
| query | Yes | What to look up, e.g. 'Disruptor Purification Nova damage and cooldown' or 'PvZ vs ling bane all-in defense'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly and openWorld, but the description adds real operational context: it discloses cost ('Free'), source provenance ('the same sources the AI Coach cites'), and an output contract ('answer from the passages and cite their URLs'). It does not mention rate limits or result ranking, which keeps it short of a 5.
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, densely packed with zero filler. The scope/source list is front-loaded and the usage directive follows immediately.
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 usefully tells the agent what to do with the returned passages (answer from them, cite URLs). Combined with the explicit source coverage and cost note, an agent has what it needs; only result ordering/pagination behavior is left implicit.
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% — the schema itself documents 'query' with examples and 'limit' with its default and bounds — so the description need not repeat any of it. It adds no syntax or formatting guidance beyond the schema, so the baseline 3 applies.
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?
States a specific verb ('Search') and a precisely scoped resource ('StarCraft2.ai's StarCraft II knowledge base') and enumerates the corpora it covers (Liquipedia unit/building/ability data, patch notes, strategy/matchup articles, pro-game insights). This clearly separates it from the replay-centric siblings like ask_about_replay and get_analysis.
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?
Gives explicit usage conditions: 'Use it to answer general SC2 questions (unit stats, counters, build orders, patch changes, matchup advice)'. The word 'general' implicitly routes replay-specific questions to ask_about_replay, but that alternative is never named, so the routing is left partly to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Spend 1 MINERAL to unlock 20 more follow-up questions on one replay (same price as the website). Refuses unless confirm_spend is true — only after the user agreed to spend the mineral.
| Name | Required | Description | Default |
|---|---|---|---|
| replay | Yes | Replay id, short id, slug, or a StarCraft2.ai replay URL. | |
| confirm_spend | No | Set to true ONLY after the user has explicitly agreed, in this conversation, to spend 1 mineral on this. Never set it on your own initiative. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only mark this non-read-only and non-idempotent; the description goes further by disclosing the exact cost (1 MINERAL), the quantity granted (20 follow-up questions), the scope (one replay), and the hard refusal rule requiring confirm_spend. This is the behavioral context an agent needs before spending a real resource.
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 tight sentences, front-loading the cost and benefit before the safety precondition. 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?
No output schema exists, so the description should carry the post-call picture; it explains cost, effect and the refusal condition, but not what the agent receives back or whether the unlock persists/changes the replay's state. Minor gap for an otherwise complete definition.
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% and the schema already documents both the replay identifier formats and the confirm_spend guard in detail. The description reinforces the confirm_spend semantics and adds the price, but adds little parameter meaning beyond the schema, so baseline 3 applies.
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?
States a specific verb and resource: spend 1 MINERAL to unlock 20 more follow-up questions on one replay. The scope ('on one replay', 'follow-up questions') is precise enough to separate it from ask_about_replay and the other 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?
Gives a clear precondition — it refuses unless confirm_spend is true, and confirm_spend must only be set after explicit user agreement. It does not name an alternative action for a user who declines to spend, so it falls just short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload a StarCraft II replay (.SC2Replay) — or a Brood War .rep — to StarCraft2.ai from a local file path or a download URL. The site parses it and it is attributed to the signed-in user. Returns the replay id and whether an AI Coach report already exists. Free. On Windows the default replay folder is Documents\StarCraft II\Accounts\…\Replays\Multiplayer; on macOS ~/Library/Application Support/Blizzard/StarCraft II/Accounts/…/Replays/Multiplayer.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | http(s) URL the replay file can be downloaded from. | |
| path | No | Local path to the replay file (~ is expanded). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the bar is lower. The description adds real context beyond them: attribution to the signed-in user, that the site parses the file, and that the response reports replay id plus whether an AI Coach report 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?
Purpose and return values are front-loaded, but the final sentence with Windows and macOS default replay folder paths is operational trivia that does not affect tool invocation and bloats the definition for little selection 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?
With no output schema, the description helpfully states the return shape (replay id and AI Coach report existence) and implies authentication via 'signed-in user'. The only real gap is silence on what happens on duplicate uploads despite the idempotentHint annotation.
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 both parameters are already documented with descriptions and the required/anyOf behavior. The description only restates that either a local path or download URL is accepted, adding no syntax or format detail beyond the schema, so baseline 3 applies.
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?
States a specific verb ('Upload') plus resource ('StarCraft II replay / Brood War .rep') and destination ('StarCraft2.ai'). An agent can distinguish this from siblings like analyze_replay or list_my_replays without opening a schema.
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?
Implies usage via the two input modes (file path or URL) and notes it is free, but never states when to choose this over analyze_replay or how it relates to the downstream AI Coach flow. Context is implied rather than explicit, with no exclusions.
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.0analyze_replayask_about_replayget_accountget_analysislist_my_replaysloginlogoutsearch_sc2_knowledgeunlock_more_questionsupload_replayScored across 10 tools
Each tool targets a distinct action or resource: auth (login/logout), account info, knowledge search, replay upload/list, report reading, coach run, follow-up Q&A, and paid unlocks. The only potential overlaps (get_analysis vs analyze_replay, search_sc2_knowledge vs ask_about_replay) are clearly separated by descriptions as read vs run and general vs replay-specific.
All names use snake_case and mostly follow verb_noun (get_account, upload_replay, list_my_replays, analyze_replay). The bare verbs login/logout are a minor deviation but still unambiguous and consistent within the auth pair.
10 tools is well within the typical 3–15 range and each tool maps to a distinct step in the account/replay analysis workflow. No tool feels redundant or missing from a scope perspective.
The surface covers the core lifecycle: authentication, account info, knowledge search, replay upload/list, report retrieval, coach analysis, follow-up questions, and paid unlocks. Minor gaps exist (e.g., no delete-replay or direct mineral purchase tool), but they are workaroundable or external to the main workflow.
Carbon Voice MCP serves as a bridge that connects AI assistants like ChatGPT, Claude, and Cursor to a user's Carbon Voice account, turning voice messages and conversations into a private, on-demand knowledge base. It provides 28 specialized tools for comprehensive voice messaging management, including creating and sending messages, accessing conversation history with instant transcription, running AI actions (summarization, TLDR generation, meeting notes), and managing workspace collaboration through folders, contacts, and team communications.
Talk to your own gym log. Reps is a free workout tracker for iPhone and Android; connect it to Claude, ChatGPT or any MCP client and ask about your workout history, personal records, exercise progression, weekly summaries, routines and training plan. The assistant can also save a new routine, edit one, save a whole plan, add custom exercises and exercise notes, always after you confirm in the chat. It cannot log a workout or delete your history. Requires a free Reps account created in the app; you sign in with a one-time email code.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Use AI models for chat, image, and video generation from Claude Code and other MCP hosts.
