schemagate

semantic_query

Read-only

Use when no column stores the answer: run a read-only SELECT, then have the server model read one text column to keep rows matching a plain-language criterion or add a short answer per row.

Instructions

For questions about what text says when no column records it, e.g. 'which complaints ask for a refund'. Runs one read-only SELECT through the same checks as run_query, then has the server's model read one text column of the returned rows and either keep the rows that meet a criterion or add a short answer per row. Returns columns, rows, how many rows were judged, and which text was sent to the model. Off unless the server enables it (SCHEMAGATE_MCP_SEMANTIC=1), because the row text goes to the model provider; at most 200 rows are judged. Use plain run_query whenever a column already holds the answer.

Input Schema

Name	Required	Description
`sql`	Yes	One read-only SELECT (or WITH ... SELECT) written against the DDL select_schema returned. Writes, DDL and multiple statements are refused, as is any table or column this caller may not read.
`roles`	No	The caller's roles or groups, e.g. ['finance', 'payroll']. Objects and columns restricted to a role are visible only when it is listed here. Omitted = no roles.
`column`	Yes	The result column whose text the model reads, e.g. 'body' or 'complaint_text'. Must be one of the columns the SQL returns.
`extract`	No	Add one short answer per row, e.g. 'which product is mentioned'. Give this or criterion, not both.
`max_rows`	No	Most rows to return (default 50, at most 200). The result says when it was truncated.
`criterion`	No	Keep only rows whose text meets this, in plain language, e.g. 'asks for a refund'. Give this or extract, not both.
`principal`	No	Who is asking, as an identity string such as 'okta:jdoe'. Pass it whenever you know the user: visibility is decided for this identity. Omitted = anonymous, which sees only unrestricted objects.

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.9.0Oct 19, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description still adds material behavior the annotations do not convey: row text is sent to the model provider (a data-egress consequence), the 200-row judging cap, and that it reuses run_query's permission checks. It does not state cost/latency implications of the model call, which keeps it short of a 5.

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?

Front-loaded with the trigger scenario, then mechanics, then the availability caveat and the alternative – every sentence carries information. It is on the long side and some clauses are packed, but nothing is redundant with the annotations or schema.

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

Completeness5/5

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

Given an output schema exists, return values need not be re-explained, yet the description still notes the return shape (columns, rows, judged count, text sent) as useful confirmation. Combined with the environment gate, row cap, and data-egress warning, an agent has everything needed to decide and invoke safely.

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 100%, so the baseline is 3, but the description adds real value beyond the schema by explaining the intent behind criterion ('which complaints ask for a refund') and extract ('which product is mentioned') and the fact that they are alternatives. It still does not spell out how roles/principal interact with the SQL's visibility at call time beyond the schema's own wording.

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+resource (runs a semantic read-only SELECT that has the server's model read one text column) and pins the scope precisely to questions whose answer is not stored in any column. It explicitly contrasts with the sibling run_query, so the agent can route correctly without opening either schema.

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

Usage Guidelines5/5

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

Gives the selecting condition ('when no column records it'), the exclusion ('Use plain run_query whenever a column already holds the answer'), and an availability prerequisite ('Off unless the server enables it (SCHEMAGATE_MCP_SEMANTIC=1)'). Nothing about when to reach for this tool is left to inference.

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

Deploy Server