An MCP server that exposes a natural language to SQL query pipeline with guardrails, row-level security, and cost controls for BigQuery analytics questions
Single tool 'query_semantic_metric' has a detailed, well-structured description (450+ chars) explaining the 6-step pipeline, security context, and provenance. Input schema is present with typed parameters (question: string, on_behalf_of: object with nested properties). However, the schema lacks explicit enum constraints, min/max bounds, and the output schema is not documented in the visible code. The description is excellent for understanding intent but does not follow LLM-optimized brevity (50-200 chars baseline). Parameter descriptions are present but could be more prescriptive about format/constraints. No error handling guidance visible in the tool definition itself.
Execute a plain-English analytics question against BigQuery through a governed pipeline: extract intent, compile to SQL with Layer 1 (semantic compiler), apply Layer 2 (row-level security if identity provided), run guardrails and cost checks, execute the query, and return results with full provenance (compiled SQL, join path, model version, security context applied)
Output schema not documented. Tool description explains what the tool returns (QueryResult with rows, compiled SQL, join path, model version, security context) but the actual JSON schema for the response is not visible in the source code provided. LLMs cannot plan downstream operations without knowing response structure.
No enum constraints on 'question' parameter. The parameter accepts free-form strings, but the underlying system has a restricted semantic model. LLMs may hallucinate invalid measures/dimensions. Should document allowed measures, dimensions, and filters, or provide a discovery tool (list_available_measures, list_available_dimensions).
Error handling not visible in tool definition. The docstring describes ToolError being raised for each layer (intent extraction, compilation, security, guardrails, execution) but the actual error response schema and recovery guidance are not shown. LLMs need to know: is this retryable? What should I try next?
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 53 | <=2025-11-25 | v2 |
Description exceeds LLM-optimized length. At 450+ characters, the tool description is comprehensive but verbose. Baseline for A+ tools is 50-200 chars. The current description reads like internal documentation rather than a concise agent-facing summary. Recommend: shorten to ~150 chars, move pipeline details to parameter descriptions or a separate documentation link.
on_behalf_of parameter lacks format guidance. The object accepts tenant_id and region but does not specify: are these required together? What format (UUID, alphanumeric, regex)? What happens if only one is provided? Undocumented dependencies cause silent misuse.