A FastAPI-based MCP server for language learning with vocabulary and math tools powered by LangChain and OpenAI
This server has critical gaps in tool definition quality. Of 3 tools examined, all lack comprehensive input schema documentation, parameter descriptions, and output schemas. Tool names are somewhat descriptive but not verb-prefixed conventions. ExplainVocab has a trivial input schema (only 'word' string with minimal description). vocab_agent and math_agent accept a generic 'query' parameter with no constraints, validation guidance, or output structure documented. Descriptions exist but are brief (15-62 chars) and lack LLM-optimization guidance (WHEN to use, WHAT is returned, prerequisites). No error handling guidance visible. No input validation or security considerations documented. No tool annotations (readOnlyHint, etc.). The codebase shows agent-based composition but tool definitions are underspecified for reliable LLM invocation.
輸入英文單字,回傳單字意思。
用來處理數學相關的問題,例如:**代數(algebra)**、**方程式(equation)**、**微積分(calculus)**、**幾何(geometry)**或**加減乘除(arithmetic)**計算。
查英文單字意思的智慧助教
Tool names lack action verbs. 'ExplainVocab' should be 'explain_vocab' or 'lookup_vocab'; 'vocab_agent' and 'math_agent' are agent wrappers, not tool names, and lack clear verbs signaling the action.
Input parameters lack descriptions and constraints. 'word' in ExplainVocab has minimal guidance ('English word to explain'). 'query' in vocab_agent and math_agent has no format, length, or valid-value constraints. LLMs cannot infer expected input structure.
No output schema documented. Callers cannot predict the structure returned (string? object with fields? array?). Tool descriptions do not state what fields or structure is returned.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | F | 29 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 19 | - | v1 |
Descriptions are too brief (15 - 62 chars) and lack LLM-optimization. They do not state WHEN to use (vs similar tools), WHAT is returned, or prerequisites. Baseline for A+ tools: 50 - 200 chars with clear WHAT/WHEN/HOW guidance.
No error handling or recovery guidance. If a word is not found, or a math query is invalid, no documentation tells the LLM what to do next (retry, ask user, use alternate tool).
No tool annotations. Tools do not declare readOnlyHint, destructiveHint, or idempotentHint, current MCP spec patterns for communicating tool safety properties to agents.