A FastAPI-based demonstration server providing context retrieval and action execution endpoints with API key authentication
Both tools have descriptions and basic parameter definitions, but critical gaps prevent production use. Tool names lack action verbs (get_context, execute_action are acceptable but generic). Input schemas are present but severely underspecified: parameters lack type definitions (query and action are bare 'object' with no nested schema), no enums for constrained values, no format specifications. Descriptions are present (95-120 chars) but lack WHEN to use, prerequisites, or recovery guidance. No output schema documented. API key exposed as parameter violates secret-injection pattern. No error handling guidance for LLMs.
Execute a simulated MCP action and return the result with status and execution details
Retrieve simulated MCP context based on a query, returning context items from knowledge base and documents with relevance scores
Input schemas lack type definitions. Both tools accept 'query' and 'action' as bare objects with no nested field specifications, violating JSON Schema best practices.
API key exposed as tool parameter (x_api_key header). Credentials must never appear in tool parameters, use server-side secret injection via environment variables. Agent traces log all parameters, leaking secrets into logs and prompt history.
No output schema documented. LLMs cannot plan downstream calls or extract required fields without knowing response structure. Both tools return structured objects but this is not declared in tool definitions.
No error handling guidance. HTTP 401 on invalid API key returns raw HTTPException. LLMs receive no actionable recovery path (e.g., 'Invalid API key. Check credentials and retry.').
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | F | 38 | 2026-07-28+ | v2 |
execute_action lacks idempotency declaration. Tool modifies state (WRITE risk) but no idempotent hint or confirmation step. Agents retrying on ambiguous failures risk duplicate side effects.