Reference implementation of secure MCP servers in Python (FastMCP) — allowlist + input validation + fail-closed.
Three tools with complete input schemas and descriptions present. Naming is clear (compute, echo, action) and verb-aligned. Descriptions are in Portuguese and moderately detailed (60-120 chars each). All parameters have type definitions and descriptions. However, descriptions lack LLM-optimized structure (no WHEN to use, no prerequisites, no recovery guidance). Output schemas are not documented. Error handling is present in code but not surfaced in tool descriptions. No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite all being read-only. Parameter constraints (enums, ranges) are mentioned in descriptions but not formalized in JSON Schema.
Executa uma acao da allowlist sobre um payload validado. name: uma de {ping, status} payload: string com no maximo 256 caracteres, sem caracteres de controle Retorna: string com o resultado. Levanta erro em caso de violacao.
Executa uma operacao aritmetica da allowlist sobre dois numeros. operation: uma de {add, sub, mul, div} a, b: numeros finitos com |x| <= 1e9 Retorna: resultado em float. Levanta erro em caso de violacao.
Retorna o texto recebido apos validacao (max 500 chars, sem controles).
Output schemas not documented. Tool descriptions do not specify what fields are returned or their types. LLMs cannot plan downstream calls or extract structured data.
Parameter constraints (enums, ranges) stated in descriptions but not formalized in JSON Schema. 'operation: uma de {add, sub, mul, div}' should be an enum in the schema; 'max 500 chars' should be maxLength.
Tool annotations missing. All three tools are read-only but lack readOnlyHint in schema. Agents cannot distinguish safe tools from destructive ones without explicit hints.
Descriptions lack LLM-optimized structure. No WHEN to use, no prerequisites, no recovery guidance. 'Executa uma operacao aritmetica' is functional but does not guide tool selection or error recovery.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 54 | <=2025-11-25 | v2 |
Error handling present in code (ToolExecutionError, validation logs) but not surfaced in tool descriptions. LLMs do not know what errors to expect or how to recover.