Access control for text-to-SQL agents. Before the model sees the schema, schemagate keeps only the tables and columns the caller may read, picks the few a question needs, and refuses hidden ones at query time. This public endpoint serves a sample schema (no real data). Self-hosted it works with Postgres, Oracle, MySQL, SQL Server and SQLite.
Scored across 7 tools
Most tools target distinct operations: list, describe, select, run, refresh, health. The main overlap is `answer`, which duplicates the `select_schema` + `run_query` flow; the description mitigates this by directing most clients to the two-step path, but confusion is still possible.
Five of seven names follow a verb_noun pattern: describe_object, list_objects, refresh_catalog, run_query, select_schema. `answer` is a bare verb and `health` is a noun, so the pattern is mostly consistent with minor deviations.
Seven tools is well within the typical 3-15 range and each covers a distinct part of the read-only schema/query lifecycle. No tool feels excessive or missing by count alone.
The surface covers discovery (`list_objects`), schema selection and DDL (`select_schema`, `describe_object`), query execution (`run_query`), end-to-end answering (`answer`), plus catalog refresh and health. For a read-only, permission-scoped database gateway, this is a complete lifecycle with no obvious dead ends.
Question in, rows out: selects the schema, writes the SQL with the server's own configured model, and runs it, all scoped to the caller. Only available when the server has a model configured; most clients should use select_schema then run_query with their own model instead.
| Name | Required | Description | Default |
|---|---|---|---|
| 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. | |
| top_k | No | How many tables and views to select for the question (default 6). Raise it for questions that span many areas; the caller's visible objects are the upper bound. | |
| max_rows | No | Most rows to return (default 50, at most 200). The result says when it was truncated. | |
| question | Yes | The user's question in plain language, e.g. 'revenue by month' or 'which customers owe us money'. | |
| 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. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds valuable context the annotations cannot: the operation runs a server-side model, is scoped to the caller, and is gated on server configuration. It does not describe failure modes or how a missing model surfaces, keeping 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the input/output contract before the pipeline and the caveats. Every clause earns its place: pipeline, scoping, precondition, and alternative, with no repetition of schema or annotation content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a five-parameter tool with a full input schema, an output schema, and rich annotations, the description supplies exactly what the structured fields do not: the model-configuration precondition, the caller-scoping semantics, and the sibling routing. Return values are covered by the output schema, so no explanation is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents question, roles, principal, top_k and max_rows. The description's only parameter-relevant contribution is the framing that everything is "scoped to the caller," which lightly reinforces principal/roles but adds no syntax or format detail beyond the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a concrete input and output ("Question in, rows out") and spells out the full internal pipeline: schema selection, SQL generation by the server's model, execution, all caller-scoped. It also implicitly separates itself from the sibling tools by naming select_schema and run_query as the manual alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states an explicit availability precondition ("Only available when the server has a model configured") and an explicit routing rule for most clients ("use select_schema then run_query with their own model instead"). When-to-use and when-not-to-use are both present with the alternatives named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full DDL (all visible columns, keys, comments) for one table or view, if the caller may read it. Use it when select_schema's compact DDL is not enough. A restricted or missing object returns the same 'not available' error, so its existence is not revealed.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Table or view name as returned by select_schema or list_objects, bare ('orders') or schema-qualified ('sales.orders'). | |
| 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. | |
| 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. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), but the description adds genuinely new behavioral context: access is permission-gated, and restricted vs. missing objects return an identical 'not available' error so existence is not disclosed. That security-relevant detail is not derivable from annotations or schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with what the tool returns, followed by the routing hint and the error/permission caveat. No repetition of schema or annotation content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description correctly avoids explaining return values and instead covers what structured fields cannot: permission gating, the routing decision against select_schema, and the indistinguishable error response. Nothing needed to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains 'name', 'roles', and 'principal' in detail, including format and defaults. The description adds no parameter-level syntax or semantics beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource with scope: full DDL (columns, keys, comments) for exactly one table or view. It explicitly distinguishes itself from select_schema by contrasting 'full DDL' with 'compact DDL', so an agent can pick between them without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Use it when select_schema's compact DDL is not enough" names the alternative and the exact condition that selects this tool. It also states the precondition ('if the caller may read it'), leaving no inference required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Server status: whether the catalog is loaded, how many objects it holds, the database dialect, and audit-log counts. Takes no arguments; safe to call any time.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description's additions ("takes no arguments", "safe to call any time") largely restate that, and the rest is a list of returned values that the existing output schema already documents.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the resource and its payload, followed by the invocation constraint. Every clause earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-argument diagnostic, the description plus annotations plus an output schema cover everything an agent needs: what it reports, that it is safe and idempotent, and that no inputs are required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline is 4. The description's "takes no arguments" is consistent with the empty schema and removes any doubt about required inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource (server status) and enumerates exactly what it reports: catalog load state, object count, database dialect, and audit-log counts. No sibling tool (answer, run_query, list_objects, refresh_catalog, describe_object, select_schema) overlaps with this diagnostic role, so an agent can route to it unambiguously.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Safe to call any time" gives a clear usage context for a diagnostic tool and implicitly invites pre-flight checks before other operations. It does not, however, name a specific alternative or state exclusions, so it stops short of explicit when/when-not routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every table and view this caller may read, with its kind and column count. Use it to see what exists before asking, or when select_schema did not return what you expected.
| Name | Required | Description | Default |
|---|---|---|---|
| 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. | |
| 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. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds that results are permission-filtered per caller identity, which is meaningful context beyond the annotations, but it says nothing about result size, truncation, or ordering for a tool that lists 'every' object.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, and the scope/payload statement is front-loaded ahead of the usage triggers. Every clause carries information an agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return-value explanation is not required, and the annotations carry the safety profile, so purpose plus usage plus visibility scoping is largely sufficient. The only gap is behavior on large catalogs (pagination or caps), which is minor for a metadata listing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameters (roles, principal) are fully documented in the schema, including defaults and visibility semantics. The description's phrase 'this caller may read' only alludes to that filtering rather than adding syntax or precedence detail, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List every table and view'), plus the scope ('this caller may read') and the payload ('with its kind and column count'). This cleanly separates it from describe_object (detail on one object) and run_query (execution), so an agent can choose without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives two concrete trigger conditions ('to see what exists before asking' and 'when select_schema did not return what you expected') and names the sibling to fall back from. It stops short of stating when not to use it or how it relates to describe_object, so it is clear but not fully exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-read the database structure (new tables, changed columns, changed grants) and swap the index in. If the database is unreachable the previous catalog stays in service and the failure is reported.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, but the description still contributes real behavioral context: the atomic swap semantics and the failure contract ("the previous catalog stays in service and the failure is reported"). It does not mention cost, latency, or whether concurrent refreshes can collide, which is what keeps it from 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action and followed by the failure guarantee. Every clause earns its place; nothing is repeated from the annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with an output schema and full annotation coverage, the description supplies everything an agent needs to decide to call it and what to expect on failure. Nothing material is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so per the rubric the baseline is 4. The description correctly adds no parameter chatter and instead spends its words on behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ("Re-read the database structure") and enumerates the kinds of changes it picks up (new tables, changed columns, changed grants), so the purpose is unambiguous. It never names or contrasts itself with siblings like select_schema, describe_object, or list_objects, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the agent can infer this tool is for picking up schema drift, but there is no explicit "call this after DDL changes" statement and no comparison to select_schema or list_objects. A reader gets the context but must construct the when-to-use rule themselves.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute one read-only SELECT and return the rows (capped by max_rows). Write the SQL against the DDL select_schema returned for the same caller. Refuses writes, multiple statements, and any table or column the caller may not read, with an error that says so ('not available to this caller'), which you can pass on to the user instead of reporting 'no results'.
| Name | Required | Description | Default |
|---|---|---|---|
| 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. | |
| max_rows | No | Most rows to return (default 50, at most 200). The result says when it was truncated. | |
| 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. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: it discloses the exact refusal categories, the verbatim permission error text to relay to users, caller-scoped visibility, and max_rows truncation. That is genuinely actionable behavior an agent could not infer from structured fields alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences with the core action and row cap front-loaded, followed by preconditions and refusal semantics. Every clause carries information; nothing is restated from the annotations or schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return shape need not be explained, and the description still notes truncation reporting and error surfacing. For a read-only, caller-scoped query tool with four fully documented parameters, nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents sql, roles, principal and max_rows thoroughly, which sets the baseline at 3. The description reinforces the caller-scoping requirement ('for the same caller', 'the caller may not read') but adds no new syntax or format detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise verb and resource ('Execute one read-only SELECT and return the rows'), plus the output cap. It also implicitly separates itself from select_schema by framing the DDL from select_schema as input rather than something this tool produces, so an agent can tell the two apart immediately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear precondition and workflow ('Write the SQL against the DDL select_schema returned for the same caller') and states what the tool refuses (writes, multiple statements, unreadable objects). It does not explicitly contrast with the 'answer' sibling, so a small routing gap remains.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start here for any question about the data. Returns the few tables and views the question needs, as compact DDL to write SQL against, scoped to the caller: objects and columns they may not read are absent, not ranked low. Also returns each object's name and why it was picked. Pass principal and roles whenever you know who is asking.
| Name | Required | Description | Default |
|---|---|---|---|
| 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. | |
| top_k | No | How many tables and views to select for the question (default 6). Raise it for questions that span many areas; the caller's visible objects are the upper bound. | |
| question | Yes | The user's question in plain language, e.g. 'revenue by month' or 'which customers owe us money'. | |
| 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. | |
| expand_foreign_keys | No | Also pull in tables joined by foreign key to the selected ones (default true), only where the caller may read them. Set false for the bare top matches. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only/idempotent/non-destructive/non-open-world, so the bar is lower. The description nonetheless adds real behavioral context: results are scoped to the caller and unauthorized objects/columns are 'absent, not ranked low,' which tells the agent how to interpret a sparse result set. It does not add limits or failure behavior, keeping it below 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with the entry-point instruction and no filler. 'Also returns each object's name and why it was picked' is partly redundant given an output schema exists, which keeps it from a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and 100% param coverage, the description only needs to supply scope, auth semantics, and entry-point guidance, all of which it does. The one remaining gap is its silence on how it relates to run_query (the natural next step), which is what keeps it off a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents question, principal, roles, top_k, and expand_foreign_keys in detail. The description reinforces principal/roles ('Pass ... whenever you know who is asking') but largely restates what the schema fields already say, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific action (return the few tables/views a question needs as compact DDL) plus the caller-scoped selection rule, and the opening 'Start here for any question about the data' clearly separates it from list_objects, describe_object, and run_query. An agent can tell what this produces 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Start here for any question about the data' gives a clear entry-point rule, and 'Pass principal and roles whenever you know who is asking' gives a conditional usage instruction. It does not explicitly name siblings or state when to prefer list_objects/describe_object/run_query instead, so it falls short of full alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
answerdescribe_objecthealthlist_objectsrefresh_catalogrun_queryselect_schema
Add one secure layer between your agents and this server.