MCP server that generates teacher verification documents across countries
Three tools with basic schemas and descriptions, but significant gaps in parameter documentation and error handling. list_countries_tool and list_schools have minimal descriptions (under 100 chars). generate_documents has a complex signature with 8 parameters, but several lack type constraints (gender, document_types, output_dir have no enum/pattern validation). No output schemas documented. Error handling is minimal, generate_documents raises ValueError with a list of school names, but no guidance on recovery or retry logic. Tool names follow verb_noun convention (list_*, generate_*), which is good. However, parameter naming inconsistencies (country vs country_code) and missing descriptions for output fields reduce clarity.
Generate teacher verification documents (employment letter, teacher ID, teaching license).
List all available countries, their display names, and the document types each can generate.
List all schools for a given country code (e.g. 'us', 'uk'). Each entry has name/address/town/postcode/state/phone/lea.
generate_documents has 8 parameters with inconsistent type constraints. 'gender' accepts free-form string ('Random', 'Male', 'Female') instead of enum. 'document_types' is Optional[List[str]] with no validation. 'output_dir' defaults to empty string but description says 'Defaults to output', ambiguous. No enum or pattern constraints prevent LLM hallucination.
Output schemas not documented. generate_documents returns a dict with 'files', 'count', 'output_dir', 'country', 'school', 'document_types', but no schema definition visible. LLMs cannot plan downstream operations without knowing return structure. list_countries_tool and list_schools return List[dict] with no field documentation.
Error handling is minimal. generate_documents raises ValueError('School not found...') with a raw list of school names. No guidance on recovery (e.g., 'Call list_schools(country) to see available options'). No error categorization (retryable vs fatal). LLM receives raw exception with no actionable next step.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 57 | 2026-07-28+ | v2 |
Parameter descriptions are incomplete or missing. 'country' param in list_schools has description 'Country code (e.g. 'us', 'uk')' but no constraint on format (2-letter ISO?). 'first_name', 'last_name', 'position', 'date_of_birth' in generate_documents have no descriptions at all in the schema, only in the docstring, which LLMs may not parse.
Tool descriptions are too brief. list_countries_tool (89 chars) and list_schools (127 chars) lack context on WHEN to call them or what structure they reveal. No discovery guidance. generate_documents description (156 chars) does not explain that it modifies state (writes PNG files to disk) or that school_name is a fuzzy match.