MCP server: query a JSON value with JSONPath ($.foo.bar[*]).
Single-tool server with a focused, read-only operation. The 'query' tool has a complete input schema with proper types and descriptions for all parameters. Tool description is adequate (97 chars) but could be more explicit about when to use it and what it returns. Parameter descriptions are present and reasonably clear. However, output schema is not documented, the tool returns a JSON object with a 'matches' field, but this structure is not declared in the tool definition. Error handling returns actionable messages but lacks recovery guidance. No tool annotations (readOnlyHint) despite being read-only.
Apply a JSONPath expression to a JSON value. result_type: value (default), path, or all.
Output schema not documented. Tool returns {matches: unknown} but this structure is not declared in the tool definition. LLMs cannot plan downstream operations or validate response structure.
Tool description lacks context on when to use it and what it returns. Current: 'Apply a JSONPath expression to a JSON value. result_type: value (default), path, or all.' Should explain: returns matching values/paths, useful for extracting nested data from JSON structures.
Missing tool annotation. Tool is read-only but does not declare readOnlyHint. This prevents clients from optimizing caching or safety policies.
Error messages lack recovery guidance. 'jsonpath failed: <message>' tells the LLM the call failed but not what to do next. Should suggest: 'Invalid JSONPath syntax. Check path format (e.g., $.items[*].price) and try again.'
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 56 | 2026-07-28+ | v2 |
Parameter 'json' lacks type constraint in schema. Declared as {description: 'Any JSON value.'} with no 'type' field. Should be type: 'object' or allow multiple types via oneOf.