Tools
xql_validate, xql_explain, xql_run, and xql_nl_reference.
Tools
The bridge registers four tools, proxying each to its REST equivalent.
| Tool | Equivalent to | Behavior |
|---|---|---|
xql_validate | POST /xql/validate | Parses and plans query, without touching any data store |
xql_explain | POST /xql/explain | Parses and plans query, returns the plan manifest and a human-readable explanation |
xql_run | POST /xql/run | Parses, plans, and executes query against market data |
xql_nl_reference | GET /xql/nl-reference (no arguments) | Returns the natural-language-to-XQL translation reference: the phrase-to-construct dictionary an LLM uses to translate retail-trader language into XQL and paraphrase results back |
xql_validate, xql_explain, and xql_run each take a single required string argument, query, containing raw XQL text: the same text you'd send as the body of the equivalent HTTP API call. They produce results equivalent to their REST counterparts for the same query text: they call the identical underlying engine functions, not a separate implementation.
xql_nl_reference takes no arguments and returns the reference document as plain text. Call it before writing a query, or after any of the other three tools returns isError: true, to see the exact construct you likely got wrong.
Errors Are Tool Errors, Not Protocol Errors
A parse failure, plan failure (including exceeding the 300-bar lookback ceiling), or, for xql_run, a downstream data-fetch failure, is reported as a tool result with isError: true and a content block describing the failure (the same {type, message, position?} shape the REST endpoints use), rather than an MCP protocol-level error. The MCP request itself still completes successfully; check isError on the tool result, not the request status.