MCP server for querying Brazilian postal code (CEP) information via ViaCEP API
Single tool (getCep) with basic but incomplete definition. Tool name starts with verb (good), but description is minimal (21 chars). Input schema present with CEP parameter, but parameter description is weak and contains an example value (59154310) which violates LLM best practice. No output schema documented. No error handling guidance. Tool is marked READ_ONLY, but lacks idempotentHint or readOnlyHint annotations. Spring AI annotation-based approach (@Tool, @ToolParam) is properly used but constraints are missing.
Consulta de endereço via CEP
Minimal tool description (21 chars). Describes WHAT but not WHEN to use or what it returns. Should be 50-200 chars with context on postal code lookup purpose and return structure.
Parameter description contains example value (59154310). LLMs latch onto examples and may reuse them literally in real calls. Replace with format constraint: 'Brazilian postal code (8 digits, with or without hyphen)'.
No documented output schema. CepResponse DTO has 13 fields but LLMs cannot see the structure without explicit documentation. Must document all return fields (cep, logradouro, bairro, localidade, uf, etc.) with types and descriptions.
No error handling guidance. API calls can fail (invalid CEP, network timeout, API down). Must return actionable error messages, e.g., 'Invalid CEP format: must be 8 digits' or 'CEP not found in database. Verify the CEP and retry.'
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | F | 38 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 34 | - | v1 |
Missing tool annotations. Should include readOnlyHint=true and idempotentHint=true since getCep is a safe, read-only lookup. Spring AI MethodToolCallbackProvider does not automatically infer these, must be added explicitly.