minimax-remaining-mcp
minimax-remaining-mcp
MCP 서버: AI 에이전트가 MiniMax Token Plan 요금제의 남은 할당량을 알 수 있게 하고, 언제 스스로를 일시 중지하여 속도 제한(rate limit)을 피해야 하는지 알려줍니다.
DeepSeek Harness (DSH), Claude Desktop, Cursor 등 MCP 프로토콜을 지원하는 모든 클라이언트와 호환됩니다.
┌──────────────┐ stdio ┌──────────────────────┐ HTTPS ┌──────────────┐
│ AI 代理 │ ──────────► │ minimax-remaining- │ ────────► │ MiniMax │
│ (DSH 等) │ ◄────────── │ mcp │ ◄──────── │ Web API │
└──────────────┘ └──────────┬───────────┘ └──────────────┘
│
▼
┌─────────────┐
│ Camoufox │ 一次性手动登录
│ (Firefox) │ → 持久化会话 cookie
└─────────────┘프로젝트 배경
MiniMax 웹 콘솔의 "5h 한도 / 61% 사용됨 / 2h56m 후 초기화" 패널은 실제로 두 개의 HTTP 인터페이스로 구동됩니다:
/v1/api/openplatform/coding_plan/remains?GroupId=…— 5시간 고정 창의 남은 백분율 + 카운트다운/backend/account/token_plan_credit— 요금제 풀(주 단위)의 누적 할당량
두 인터페이스 모두 웹 UI의 api_key(sk-cp-... 형태)를 Bearer Token으로
허용하지 않습니다 — 사용하면 base_resp = {2062, "no active token plan"}이
반환됩니다. 유일하게 가능한 방법은 웹 세션 쿠키를 사용하는 것입니다(실제
브라우저 로그인 후의 _token). 이 프로젝트는 Camoufox를 사용해 지속적인
Firefox 프로필을 유지하여 MCP 서버 재시작 사이에도 쿠키가 보존되도록 합니다.
Related MCP server: llm-quota-mcp
5시간 고정 창(롤링 창이 아님)
MiniMax 공식 문서에 따르면:
요금제 내 할당량은 5시간 고정 창과 주간 창의 통제를 받으며, 사용하지 않은 요금제 내 할당량은 다음 결제 주기로 이월되지 않습니다.
따라서 창 경계는 고정된 시계 시간대(일반적으로 CST 00:00 10:00 / 15:00 / 20:00
등)이며, 첫 요청 시점부터 롤링되는 것이 아닙니다. 창 전환 몇 초 전에 조회하면
다음 창의 데이터가 반환됩니다. 응답의 interval_start_iso /
interval_end_iso 필드가 정확히 어느 구간인지 알려줍니다.
한 줄 설치
# 方式 1:从 PyPI 安装(推荐)
pip install minimax-remaining-mcp
# 或
uv pip install minimax-remaining-mcp
# 或
uvx minimax-remaining-mcp # 不安装直接运行
# 方式 2:从 GitHub 安装(无需 PyPI 账号)
pip install git+https://github.com/yang-cc/minimax-remaining-mcp.git
# 方式 3:本地开发模式
git clone https://github.com/yang-cc/minimax-remaining-mcp.git
cd minimax-remaining-mcp
uv venv .venv --python 3.12
uv pip install -e .일회성 로그인
Bearer Token 경로가 없으므로 Camoufox에서 먼저 수동으로 한 번 로그인해야 합니다:
# 1. 启动服务器
python -m minimax_remaining_mcp.server
# 2. 在 MCP 客户端里调用:
minimax_login(timeout_seconds=600)Camoufox 브라우저가 팝업되어 MiniMax 로그인 페이지가 열립니다. Cloudflare /
CAPTCHA 인증과 계정 로그인을 수동으로 완료하고 브라우저가 API Keys 페이지에
도달할 때까지 진행하세요. 서버가 _token 쿠키를 자동으로 감지하여 세션을
data/cookies.json에 영구 저장합니다.
🔌 DeepSeek Harness (DSH) 통합
DSH는 @deepseek-ai/dsh-mcp-client를 통해 MCP 서버를 로드합니다.
~/.dsh/profiles/web/cordis.patch.yml에 다음 내용을 추가하세요(패키지
이름은 minimax-remaining-mcp이지만 Python 모듈 경로는
minimax_remaining_mcp.server입니다):
- insert:
- id: minimax-remaining-mcp
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: minimax
transport: stdio
command: <repo>/.venv/Scripts/python.exe # 或 uv 环境的 python
args: ['-u', '-m', 'minimax_remaining_mcp.server']
env:
# 暂停阈值:5h 剩余低于 30% 时触发代理暂停
MINIMAX_PAUSE_THRESHOLD_REMAINING_PCT: '30'
# 储存目录(可选,默认 ./data)
# MINIMAX_DATA_DIR: E:\\codex_dir\\.dsh\\state\\minimax-remaining-mcp
failOnStartupError: false
toolCallTimeoutMs: 180000DSH 통합 핵심 사항
주의 사항 | 설명 |
| Python stdio를 버퍼링 없이 실행하여 DSH 콘솔에서 MCP 서버 로그를 즉시 확인할 수 있습니다. |
Python 인터프리터 경로 | 설치 방식에 따라 다름:• |
최초 시작 시 로그인 필요 | DSH가 MCP 서버를 시작할 때 |
DSH 재시작 |
|
|
|
영구 저장 디렉터리 격리 | 여러 프로젝트가 동일한 DSH를 공유하는 경우 각 프로젝트마다 다른 |
DSH에서의 일반적인 사용법
DSH 시작 후 minimax_status()를 호출하여 남은 할당량을 판단합니다. 에이전트가
MiniMax API 호출 전마다 minimax_status()를 먼저 호출하도록 훈련시킬 수 있으며,
should_pause 필드를 관찰합니다:
remaining_percent_5h < 30 → should_pause=true → 代理应停下来或转做其他事
remaining_percent_5h >= 30 → should_pause=false → 可以继续调用더 철저한 방법은 minimax_wait_for_quota()를 호출하는 것입니다. 이 함수는
할당량이 임계값 이상으로 회복될 때까지 차단(기본값
MINIMAX_PAUSE_THRESHOLD_REMAINING_PCT)되므로 에이전트가 직접 폴링 로직을
작성할 필요가 없습니다.
도구 목록
도구 | 용도 |
| 웹 패널의 모든 수치: 5h 남은/사용 % , 카운트다운, 요금제 누적. 임계값 미만이면 |
| 에이전트 로컬의 5h 관측 창 상태만 반환(MiniMax의 고정 창과는 별개이며 에이전트 자체 속도 제한용). |
| 로컬 창 소비 카운터를 N만큼 증가. MiniMax API 호출 후마다 한 번 호출. |
| 5h 남은 백분율이 ≥ |
| 수동 로그인용 Camoufox 브라우저 창 팝업. |
| 빠른 Camoufox 상태 확인(example.com 열기). |
| 정적 구성 + 최근 세션 메타데이터. |
| cookies / session / window 상태 삭제. |
⚠️ 최초 콜드 스타트(Camoufox)는 느릴 수 있습니다
minimax_smoke()와 minimax_login()이 Camoufox를 처음 시작할 때 영구 저장된
Firefox 프로필 압축 해제, sqlite 데이터베이스 초기화, 확장 프로그램 로드 등을
수행하므로 일반적으로 30-90초(디스크 속도에 따라 다름)가 소요됩니다.
이는 Camoufox 콜드 스타트의 정상적인 현상이며 버그가 아닙니다 — 이후
시작에서는 data/profile/의 캐시를 재사용하여 몇 초 만에 완료됩니다.
최초 호출이 MCP 클라이언트의 toolCallTimeoutMs(DSH 기본값 180초)를 초과하여
중단된 경우 한 번 더 재시도하면 결과를 볼 수 있습니다. 콜드 스타트가 자주
발생할 것으로 예상된다면(예: CI에서 실행), 해당 MCP 클라이언트의
toolCallTimeoutMs를 300000(5분)으로 조정하세요.
minimax_status() 응답 예시
실제 진단 출력(5h 창이 소진되어 일시 중지가 트리거되어야 할 때):

다음은 정규화된 JSON 구조입니다:
{
"ok": true,
"source": "coding_plan",
"remaining_percent_5h": 76, // 5h 窗口剩余 %
"used_percent_5h": 24, // 5h 窗口已用 %
"seconds_until_reset_human": "4h21m35s",
"interval_end_iso": "2026-08-25T12:00:00+00:00",
"interval_status_text": "active", // active | exhausted | inactive
"remaining_percent_weekly": 100,
"seconds_until_weekly_reset_human": "5d08h42m",
"total_credits": 14000, // 套餐累计(周维度)
"used_credits": 3188,
"remaining_credits": 10812,
"user_name": "...",
"group_id": "...",
"should_pause": false, // 低于阈值时为 true
"model_remains": [
{ "model_name": "general", "interval_remaining_percent": 76, "interval_status": 1 },
{ "model_name": "video", "interval_remaining_percent": 100, "interval_status": 3 }
]
}일시 중지 임계값 의미
MINIMAX_PAUSE_THRESHOLD_REMAINING_PCT=30은 5h 창의 남은 백분율이 30% 미만일
때 일시 중지(즉, 70% 이상 사용)를 의미합니다. 비교 대상은
remaining_percent_5h이며, 요금제 누적의 remaining_credits가 아닙니다 —
이 둘은 독립적인 지표입니다.
영구 저장 파일
모든 상태는 data/에 순수 JSON으로 저장됩니다(.gitignore에 포함됨):
data/
├── cookies.json # Camoufox 会话 cookie
├── session.json # 最近一次登录元数据
├── window.json # 代理本地的 5h 观测窗口
├── last_usage.json # 最近一次成功的 API 响应(缓存)
└── profile/ # Camoufox 持久化 Firefox profile(~150 MB)coding_plan/remains가 401/403을 반환하면 전체 응답 본문이
data/last_coding_plan_failure.json에 기록되어 문제 해결에 도움이 됩니다 —
서비스가 다운된 것인지 의심되기 전에 먼저 이 파일을 확인하세요.
환경 변수
모두 선택 사항이며 기본값은 아래 표를 참조하세요.
변수 | 기본값 | 설명 |
|
| 5h 남은 값이 이 값 미만이면 일시 중지. |
|
| 에이전트 로컬 창 길이(5h). |
|
| 로그인 시 브라우저 창 강제 표시. |
| auto |
|
|
| 브라우저 언어. |
|
| API 요청 시간 초과(초). |
|
| cookies / session 저장 디렉터리. |
|
| 콘솔 기본 URL 재정의. |
|
| 요금제 풀 endpoint. |
|
| 5h 창 endpoint. |
|
| 기본 endpoint 실패 시 사용. |
|
| 로그인 랜딩 페이지. |
로컬 개발 및 디버깅
# 启动 MCP 服务器(stdio 模式)
.venv\Scripts\python.exe -u -m minimax_remaining_mcp.server
# 或(Windows)
run.bat
# 直接探测 coding_plan 接口(无需 MCP / 浏览器)
.venv\Scripts\python.exe probe_coding_plan.py
# 检查持久化状态
cat data/cookies.json | head -c 200
cat data/session.json
cat data/last_coding_plan_failure.json # 如果存在PyPI에 패키지 게시(관리자용)
# 安装打包工具
pip install build twine
# 在项目根目录构建 wheel + sdist
python -m build
# → dist/minimax_remaining_mcp-0.1.0-py3-none-any.whl
# → dist/minimax_remaining_mcp-0.1.0.tar.gz
# 检查产物
twine check dist/*
# 上传到 PyPI(需要先 `twine login` 或用 token)
twine upload dist/*
# 或:uv publish dist/*게시 후 누구나 다음을 수행할 수 있습니다:
pip install minimax-remaining-mcp
uv pip install minimax-remaining-mcp
uvx minimax-remaining-mcp # 临时运行제한 사항
Bearer-key 경로 없음. MiniMax는 현재 Coding Plan API용 구독 키를 발급하지 않습니다. 웹 콘솔의
api_key를 Bearer로 사용하면2062 "no active token plan"이 반환됩니다. 유일한 방법은 세션 쿠키입니다.Cloudflare / CAPTCHA는 수동으로 완료해야 함. 최초 로그인은 반드시 실제 사람이 수행해야 합니다. 이 프로젝트는 캡차 해결 서비스를 연동하지 않습니다.
5h 창은 CST 고정 시간대입니다. 창 전환 전에 조회하면 다음 창의 데이터를 받게 됩니다.
interval_start_iso/interval_end_iso가 정확히 어느 구간인지 알려줍니다.요금제 누적(
remaining_credits)은 이월되지 않습니다. 주 단위 누적 풀이며 5h 창 초기화와 함께 0으로 리셋되지 않습니다.
라이선스
MIT — 자세한 내용은 LICENSE를 참조하세요.
Available Tools
8 toolsminimax_clearA
Wipe persisted cookies, session metadata, and window state.
Requires confirm=True to actually delete (otherwise returns
a preview of what would be removed).
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses that deletion only occurs with confirm=True and returns a preview otherwise — a helpful safety behavior. However, it does not mention the irreversible nature of the wipe, potential side effects on other tools, or whether it affects server-side state beyond local cookies. The preview mechanism is a positive step but incomplete for a destructive operation.
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, zero fluff. The primary action is stated first, and the controlling parameter is explained in the second. The structure is front-loaded and efficient, with every word contributing to the tool's usage.
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 tool with one optional parameter and an existing output schema, the description covers what the tool does and the key behavioral toggle. It stops short of warning about the destructive nature or when to use it, but the presence of an output schema handles return-value details. Missing caveats about irreversible consequences and recommended usage contexts keep 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 schema provides zero description coverage (0%), so the description must clarify the parameter. It does exactly that: 'Requires confirm=True to actually delete' and explains the preview when false. This fully conveys the boolean meaning beyond the schema's default of false, making the parameter's role unambiguous.
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 begins with 'Wipe persisted cookies, session metadata, and window state' — a specific verb and resource set that clearly conveys destructive cleanup. It differentiates from siblings like minimax_window (which likely manages rather than clears) and minimax_status (read-only), so the agent can distinguish it without opening the 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?
No guidance is given on when to use this tool versus its siblings (e.g., minimax_window, minimax_login). It only explains the confirm parameter, not the contextual trigger for clearing state. The description would benefit from an explicit note like 'Use when you need to reset session state before re-authentication.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
minimax_consumeA
Increment the local 5h-window consumption counter by delta.
Call this once per MiniMax API call (or batch) your agent makes.
Combined with minimax_status() it lets the agent pace itself
without waiting for MiniMax's 5h rate limit to bite.
| Name | Required | Description | Default |
|---|---|---|---|
| delta | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the operation increments a local counter, implying a state mutation. It does not elaborate on side effects such as persistence, overflow, or reset behavior, but it does mention the 'local' scope and the 5h window. Given the simplicity, a 3 reflects the core disclosure without deep behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, with the primary action front-loaded. Every word serves purpose: the first sentence states the core function, the second provides usage context and integration with a sibling. No fluff or redundancy.
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 tool is extremely simple (one optional integer parameter). The description covers purpose, usage timing, and its role alongside minimax_status. An output schema exists but is not needed to explain return values. All information an agent needs to call it correctly 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 description coverage is 0%, so the description must compensate. It names 'delta' and explains it as the increment amount. This adds meaning beyond the schema, which only gives the type and default. It does not detail edge cases (e.g., negative values), but the meaning is intuitively clear from the context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('increment'), a specific resource ('local 5h-window consumption counter'), and clearly differentiates from siblings by tying usage to per-API-call tracking. It also names the sibling minimax_status as the complementary tool, making its purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to call it ('once per MiniMax API call (or batch)') and explains its role in pacing via minimax_status(). It does not explicitly list exclusions or alternatives, but for a simple counter this guidance is sufficient. The context is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
minimax_infoB
Return static configuration + last-known session metadata.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosing behavior. It mentions 'last-known' metadata, implying the data may not be real-time, which is a useful behavior hint. However, it does not state whether the operation is read-only, whether any side effects occur, or how the tool behaves if no session 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 extremely concise, using a single phrase to convey the core purpose without any filler words. It front-loads the verb and resource, making it easy to scan. Every word 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?
Despite having an output schema and no parameters, the description remains vague. It doesn't clarify what 'static configuration' includes or what 'session metadata' entails, nor does it mention any operational constraints or error conditions. An agent would need to inspect the output schema or call the tool to understand its full behavior.
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 the schema is trivially 100% covered. Per the rubric, a baseline of 4 is appropriate since there is nothing to explain about parameters; the description does not need to add parameter semantics.
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 clear verb (Return) and resource (static configuration + last-known session metadata), which conveys the tool's function. However, it does not explicitly distinguish this from minimax_status, which likely also returns state-related information, so the differentiation is only implicit.
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 no guidance on when to use this tool versus siblings like minimax_status or minimax_window. There is no mention of scenarios, prerequisites, or exclusions, leaving the agent to infer usage from the tool name and description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
minimax_loginA
Launch a headful Camoufox browser so the user can log in manually.
Returns once the _token cookie appears in the browser. The server detects login success automatically; no further action needed.
| Name | Required | Description | Default |
|---|---|---|---|
| timeout_seconds | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses that the browser is headful (visible to the user), that it waits for manual login, and that login success is detected automatically via the _token cookie. It does not mention timeout behavior or error handling, but the core behavioral traits are well communicated.
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 concise—two sentences—and front-loaded with the primary action and then the return condition. Every sentence adds value, and there is no redundant phrasing. The structure is clean and scannable.
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 tool that involves manual user interaction and a login flow, the description covers the main steps but omits important details like what happens on timeout (does it throw? does it close the browser?) and whether repeated calls are allowed. The presence of an output schema (though not shown) may cover return values, but the behavioral context around failure/timeout is missing, leaving the agent with some uncertainty.
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 has one parameter, timeout_seconds, with no description (schema coverage 0%). The description does not mention this parameter at all, leaving the agent without any guidance on what it controls (e.g., how long to wait before giving up). Since the description must compensate for missing schema documentation and fails to do so, the parameter semantics are poorly conveyed.
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: 'Launch a headful Camoufox browser so the user can log in manually.' It specifies the resource (browser), the purpose (manual login), and the completion condition (when the _token cookie appears). It is distinct from sibling tools like minimax_status or minimax_window, which likely handle other aspects of the session.
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 implies this is for logging in but does not explicitly contrast it with alternatives or state when to use it vs. siblings. It does provide context that after login no further action is needed, but it lacks guidance on prerequisites, when to avoid, or how it relates to other minimax tools. Thus, usage guidance is present but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
minimax_smokeA
Quick health check: launch headless Camoufox and load example.com.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states that the tool launches a headless browser and loads a specific URL, which is transparent about its action. It does not mention side effects, but as a smoke test the behavior is self-evident. No contradictions exist between the description and annotations (none provided).
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 a single, tight sentence with no filler. It front-loads the 'Quick health check' label, immediately conveying the tool's niche, and then specifies the exact action. Every word earns its place – highly efficient.
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 parameterless tool with an output schema (present), the description fully covers the action. It does not explain return values or success criteria, but the output schema presumably handles that. The description is complete for an agent to decide when to invoke it and what it will do.
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 the schema coverage is trivially 100%. The description adds no parameter details because none are needed. Per the rule, a 0-parameter tool receives a baseline score of 4; the description is adequate without param information.
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: 'launch headless Camoufox and load example.com.' This is a concrete, scoped health check that clearly differentiates from siblings like minimax_status (which likely reports status) and minimax_window (which manipulates windows). The verb 'launch' and resource 'example.com' make the purpose unambiguous.
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 phrase 'Quick health check' implies a verification use case, but the description does not explicitly state when to use this tool versus alternatives like minimax_status or minimax_info. There is no guidance on exclusions or conditions, leaving the agent to infer that this is for a lightweight setup validation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
minimax_statusA
Return current Token Plan status (the same numbers shown on the page).
Reads the 5h fixed-window remaining/used percent, time until
reset, and weekly window. Use this before any substantial work
that will call MiniMax models. If should_pause is true, the
agent should sleep until the 5h window resets (see
minimax_wait_for_quota).
The web console actually fires two distinct requests; we mirror both so the response matches what the user sees on screen:
/v1/api/openplatform/coding_plan/remains?GroupId={gid}powers the "5h 限额 / X% 已用 / 2h56m 后重置" panel./backend/account/token_plan_creditpowers the "套餐用量" panel (total / used / remaining credits).
Auth for both uses the persisted web-session cookies
(Camoufox capture). When cookies are missing or stale, the
failure body is saved to <data_dir>/last_coding_plan_failure.json
so the cause can be diagnosed.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full transparency burden. It discloses that the tool fires two distinct HTTP requests, uses persisted web-session cookies for auth, and saves a failure body to a file on missing/stale cookies. It stops short of explicitly stating whether the operation is read-only, though the purpose implies it, so a 4 is appropriate.
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 organized and front-loads the purpose and usage, then provides a numbered list of the two requests. It is slightly long but each sentence adds value—the request details and auth handling are necessary for correct use. Minor redundancy exists ('same numbers shown on the page' vs 'matches what the user sees'), but overall it is efficient.
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 zero parameters, an existing output schema, and moderate complexity (multiple requests, auth, failure handling), the description covers all essential context: when to use, what the tool mirrors, auth requirements, and failure handling. It even references the sibling tool for the wait action. 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 takes zero parameters, and the schema has 100% coverage (empty object). The baseline for no parameters is 4; the description correctly avoids padding and simply documents the requested behavior. No further parameter explanation is needed.
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 ('Return') and a clear resource ('current Token Plan status'), then details the exact metrics (5h window remaining/used percent, time to reset, weekly window). It also names the two backend requests it mirrors, making it unambiguous what the tool does and grounding it in observable behavior.
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 states when to use it: 'Use this before any substantial work that will call MiniMax models.' It also gives conditional behavior ('If should_pause is true...') and points to a specific alternative (minimax_wait_for_quota), providing both a when and a corresponding alternative action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
minimax_wait_for_quotaA
Block until the 5h window remaining percent exceeds target_remaining_percent.
Polls minimax_status() every poll_seconds and exits when
the threshold is satisfied (default = pause_threshold_remaining_pct).
Cancellable by closing the MCP connection. Intended for use by an
agent that wants to truly pause (not just sleep a fixed amount).
| Name | Required | Description | Default |
|---|---|---|---|
| poll_seconds | No | ||
| target_remaining_percent | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and discloses blocking behavior, polling interval, cancellation via MCP connection close, and the default threshold source. This is comprehensive and gives an agent confidence about the tool's runtime semantics.
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 reasonably concise and front-loads the primary action, but it repeats the threshold condition ('exceeds' and 'threshold is satisfied') in consecutive sentences. Still, it is efficient and well-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?
Given that an output schema exists, return values need not be described. The description covers blocking, polling, cancellation, and default, which is sufficient for an agent to invoke the tool. Minor gap: no mention of potential indefinite blocking or timeouts, but cancellation is noted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explicitly references both parameters: poll_seconds as the polling interval and target_remaining_percent as the threshold with a default. This adds meaning beyond the raw schema fields.
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 clear verb ('Block') and resource ('5h window remaining percent'), and explicitly contrasts with a fixed sleep. It distinguishes from sibling minimax_status by referencing it as the polling function, making the tool's unique role unambiguous.
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 provides a clear use case ('truly pause' vs. fixed sleep) and implies when to use this tool. However, it does not explicitly enumerate when not to use it or compare with other siblings like minimax_window or minimax_consume, so the guidance 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.
minimax_windowA
Return only the agent-local 5h observation window (no API call).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description bears the full burden of behavioral disclosure. It does disclose the key behavioral trait of making no API call, but it does not mention potential errors, performance characteristics, or state dependencies. For a simple zero-parameter tool this is acceptable but not comprehensive.
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 a single, front-loaded sentence with zero wasted words. It efficiently communicates the core purpose and a critical behavioral distinction, making it perfectly sized for this simple tool.
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's simplicity (zero parameters, no side effects), the description fully covers what an agent needs to know to call it correctly. An output schema exists, so the description correctly omits return-value details. The description clearly states what is returned and its local nature.
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 fully documents that (100% coverage). Per the baseline for 0 parameters, a score of 4 is appropriate. The description adds no parameter-related meaning because there are none, which is acceptable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Return' and the specific resource 'agent-local 5h observation window', and explicitly notes 'no API call', which distinguishes it from sibling tools that likely make network requests. This is precise and leaves no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context via 'only' and 'no API call', indicating this is for when the agent needs local observation data without any network interaction. However, it does not explicitly name alternatives or state when not to use it, so it falls short of fully explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
8 tool updates
v0.1.4- First observed
minimax_clear - First observed
minimax_consume - First observed
minimax_info - First observed
minimax_login - First observed
minimax_smoke - First observed
minimax_status - First observed
minimax_wait_for_quota - First observed
minimax_window
TDQS
Scored across 8 tools
Tools are mostly distinct: minimax_status queries live MiniMax quota, minimax_window returns local tracking state, and consume/wait/login/clear/info each target a single operation. The only realistic confusion is minimax_window vs minimax_status, since both concern the 5h window, but the descriptions explicitly separate local no-API state from server-reported state.
All tools share the minimax_ prefix and split sensibly into noun-style read tools (window, status, info) and verb-style actions (login, consume, clear, wait_for_quota, smoke). It is not a uniform verb_noun pattern, but the convention is predictable and easy to parse.
Eight tools is a well-scoped size for a quota-management server. Each tool earns its place: authentication, live status, local consumption tracking, blocking wait, state reset, health check, and configuration/session info.
The toolset covers the full lifecycle: authenticate, check live quota, track local usage, pause until reset, inspect config, and wipe state. There are no obvious missing operations for the stated purpose.
Maintenance
Related MCP Connectors
Meter, cap, and block AI agent spend before the provider is charged.
Token guard and rate limiter preventing runaway API cost spikes for OpenAI and Anthropic.
Budget & cost control for AI agents — per-agent spend caps + rate limits before each call.
Everything your AI agents need to do their jobs, with a spending cap they can't go over.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables agents to monitor token/usage limits and persist work checkpoints, allowing them to pause, resume, and track progress across sessions.5MIT
- AlicenseNot gradedqualityAmaintenanceEnables agents to check remaining Anthropic and OpenAI rate-limit quotas with reset times, plus Hermes Agent token usage, so bots can throttle or stop before hitting limits.MIT
- AlicenseNot gradedqualityAmaintenanceLets a coding agent inspect its own account's subscription limit windows, usage, and cost history, and decide whether to pause and sleep until a limit resets rather than failing mid-task. Supports multiple accounts and providers such as Claude Code and Codex.27 npmMIT
- AlicenseAqualityCmaintenanceLets an AI agent check its own Claude and Codex usage limits — used percentages and exact reset times for session and weekly windows — so it can plan long-running work around resets instead of dying mid-task. It reads local, credential-free sources by default, always reports which source answered, and ships a hook that pushes quota state into context automatically.1MIT