MCP server for Chinese eight-ball billiards simulation with hand model injection and calibration challenges
PoolHall MCP defines 9 tools with explicit schemas and descriptions in Chinese. Tool names follow verb_noun patterns (observe_table, take_shot, get_shot_history, open_match, take_match_shot). Schemas are present and typed (Zod). However, descriptions are domain-specific and terse (avg ~80 chars), lacking LLM-optimized guidance on WHEN to use each tool or recovery paths. Parameters are well-typed but descriptions are minimal (e.g., 'angle(度,0=+x,屏幕逆时针为正)' assumes domain knowledge). No error handling guidance, no output schemas documented, no tool annotations. Chinese-language descriptions reduce accessibility for English-speaking LLM agents.
当前比分(进球数 / 杆数 / trial)。
回看本局最近 N 杆的意图与结果(校准的手感原料)。
对局详情:轮次、双方组、已进球、胜负、犯规数。
当前选手视角:turn=你、yourGroup、aimAssists=每球最容易组合的参考瞄点。
获取当前校准挑战的完整观察:母球/目标球坐标、目标袋、六袋坐标、比分。
开一局中式八球对局(必传 nameA/nameB/seed/maxShots)。
读取对手的公开计划(观察/判断/走位/风险/信心)——仅 remote 模式可用。
Descriptions are domain-jargon-heavy and under 100 chars; lack LLM guidance on WHEN to call each tool vs alternatives. E.g., 'observe_table' (获取当前校准挑战的完整观察) does not explain when to call it vs observe_match, or what fields the LLM should extract.
No output schemas documented. Tools return structured data (MatchObserve, MatchShotResult, etc.) but LLM cannot see field names, types, or which fields are required for downstream tool calls. Breaks tool chaining.
No error handling guidance. Tools can fail (invalid angle, out-of-bounds coordinates, illegal ball selection) but descriptions do not explain error conditions or recovery steps. LLM has no guidance on what to do if take_match_shot fails.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 63 | 2026-07-28+ | v2 |
打一杆(必带 targetBall/pocket/aimX/aimY/power)。直线球建议 spin.y<0 防母球跟进。
打一杆:angle(度)+ power(0~1)+ 可选 prediction。手感噪声在此注入。
Descriptions are in Chinese; LLM agents trained primarily on English may misinterpret domain-specific terms (e.g., '母球' = cue ball, '花色' = ball group). Reduces cross-lingual agent compatibility.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint). Agents cannot distinguish safe reads (observe_table) from state-mutating calls (take_shot, open_match) without parsing descriptions. Risks accidental retries of destructive operations.