readback

run_sql

Read-onlyIdempotent

Run a single read-only DuckDB SELECT or WITH against a named warehouse schema, capped at 500 rows and 10 seconds, returning rows, column units, row count, and a result_id for citation.

Instructions

Run one read only DuckDB statement against one warehouse schema. Only a single SELECT or WITH runs; writes, ATTACH, COPY, INSTALL, LOAD, PRAGMA, SET, file reading functions and tables outside the named schema are refused with the clause named. Unqualified table names are qualified with the warehouse. The limit is capped at 500 rows and the statement stops after 10 seconds. Returns the statement as it ran, the columns with units where the catalog knows them, the rows, the row count before the limit, and a result_id to cite in readback.

Input Schema

Name	Required	Description	Default
`sql`	Yes
`limit`	No
`warehouse`	Yes

Output Schema

Name	Required	Description	Default
`sql`	Yes	the statement as it ran, normalized, with the limit applied
`rows`	Yes
`limit`	Yes
`digest`	Yes
`columns`	Yes
`result_id`	Yes	a handle for readback in the same request chain
`row_count`	Yes	rows the statement returns before the limit
`statement`	No		Answers are drawn from the published tables of three portfolio builds by Ajay Mekala: doorstep (public housing data from FHFA, the Census Bureau, HUD, the CFPB and Freddie Mac), turnaround (public flight data from the Bureau of Transportation Statistics, the FAA and OurAirports, with weather from Open-Meteo under CC BY 4.0) and ledger (a fictional bank, Harborline, with public HMDA, CFPB, FDIC and macro series). No person appears in any table, and questions are redacted before a model sees them. Every number is read back to the warehouse before it is shown. This is a portfolio demonstration, not financial, travel or lending advice.
`warehouse`	Yes
`elapsed_ms`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 24, 2026

TDQS

A4.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the readOnlyHint/idempotentHint annotations: it names what gets refused and how (clause named in the error), states the 500-row cap and 10-second timeout, and describes unqualified-name qualification. This is exactly the enforcement detail an agent needs before composing a query.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense and front-loaded: the single-statement rule leads, then restrictions, then limits, then returns. Sentences are long and clause-heavy but every one carries distinct information; minor trimming possible in the return-value list.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema exists, the description needn't enumerate return fields, yet doing so confirms the result_id/readback workflow, which is genuinely useful. The only real gap is the missing contrast with sibling query/catalog tools for an agent deciding whether to write SQL at all.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate. It does for warehouse (scopes to one named schema; enum values are self-evident) and limit (capped at 500), and sql's purpose is obvious from the tool itself. It stops short of clarifying whether a caller-supplied limit below 500 is honored or how it interacts with the cap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Run one read only DuckDB statement against one warehouse schema') plus exact scope limits (single SELECT/WITH, one schema). An agent can tell this apart from siblings like search_catalog, describe and readback without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Clearly defines the allowed case (single SELECT or WITH against a named warehouse schema) and the excluded cases (writes, ATTACH, COPY, INSTALL, LOAD, PRAGMA, SET, file functions, out-of-schema tables). It also routes the agent forward by telling it the result_id is meant to be cited in readback, though it never explicitly contrasts when to prefer search_catalog or describe over raw SQL.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server