MCP server exposing Geo-Explorer tools for a fictional learning platform with trails, challenges, and certificates
Four tools with complete schemas and descriptions, but naming conventions deviate from English verb_noun patterns (Portuguese names like 'listar_tecnologias', 'buscar_trilha'). All tools have input schemas with type definitions and descriptions. Tool descriptions are adequate (100-150 chars) but lack actionable context for LLM selection. Error handling is present but minimal, no recovery guidance. Tool annotations (readOnlyHint, destructiveHint, idempotentHint) are correctly applied. Output structure is text-only; no structured response schemas documented.
Retorna o plano de estudos completo de uma tecnologia (módulos, badges, XP, nível).
Emite um certificado em Markdown para o estudante que concluiu uma trilha.
Gera um desafio de código aleatório para uma tecnologia e nível. O nível é opcional — se omitido, usa o nível da trilha.
Lista todas as tecnologias disponíveis no Geo-Explorer com seu nível e XP total.
Tool names use Portuguese verbs instead of English verb_noun convention. LLMs trained on English patterns (get_, list_, create_, search_) may struggle to infer intent from 'listar_tecnologias' or 'buscar_trilha'. Baseline: 90% of A+ tools start with English action verbs.
Tool descriptions lack actionable context for LLM selection. E.g., 'Retorna o plano de estudos completo' does not explain WHEN to call this vs listar_tecnologias, or what the LLM should do with the output. Baseline: A+ tools include 'When to use' and 'What to do next' guidance.
Output schema not documented. All tools return text-only responses via { content: [{ type: 'text', text: string }] }, but the structure and content of that text is not formally specified. LLMs cannot plan downstream calls or extract structured data.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 56 | 2026-07-28+ | v2 |
Error handling is minimal. When a technology is not found, the tool returns isError: true with a plain message. No recovery guidance (e.g., 'Call listar_tecnologias to see available options'). Baseline: A+ tools include actionable recovery steps.
Parameter 'nivel' in gerar_desafio accepts both accented and non-accented variants ('Básico', 'basico'). This redundancy is confusing and wastes enum space. Normalize to one canonical form (e.g., 'basico') and handle case-insensitivity server-side.