Query Postgres, MySQL, SQL Server, Oracle, BigQuery, ClickHouse and Redshift from your AI client.
Scored across 11 tools
Most tools target clearly distinct resource+action pairs (schedule lifecycle vs. saved-query lifecycle vs. ad-hoc SQL). The one soft overlap is execute_query vs. export_query_results, since both run SQL and only the output format differs, but the descriptions make the distinction explicit enough that misselection is unlikely.
Every tool follows a consistent snake_case verb_noun pattern (list_*, get_*, run_*, create_*, export_*). The only quirk is save_query serving as both create and update, which is a semantic merge rather than a naming inconsistency.
Eleven tools is well within the ideal range and each maps to a concrete step in the workflow (discover connection, inspect schema, write/run SQL, save, export, schedule). Nothing appears redundant or padded.
The query side covers list/get/save/run but has no delete or explicit update path beyond save_query's id overload, and the schedule side has create/list/run-now but no update, pause, or delete schedule. Connection management is read-only (list_connections, get_schema), which may be out of scope but leaves agents unable to clean up or modify schedules and saved queries.
Schedule a saved query to run on a cron cadence and deliver to exactly one destination: Google Sheets or Slack. Each run executes the saved query's SQL, so this needs both the write and execute scopes.
| Name | Required | Description | Default |
|---|---|---|---|
| timezone | No | IANA timezone. Defaults to UTC. | |
| createNew | No | Create a new spreadsheet named spreadsheetName. | |
| sheetName | No | Tab to write to. | |
| startCell | No | A1 notation. Defaults to A1. | |
| savedQueryId | Yes | Saved query id from list_queries. | |
| spreadsheetId | No | Existing spreadsheet to write to. Omit and set createNew with spreadsheetName to make a new one. | |
| cronExpression | Yes | 5-field cron expression, e.g. '0 9 * * 1' for Monday 9am. | |
| includeHeaders | No | Write column names as the first row. Defaults to true. | |
| slackChannelId | No | Slack channel to post to, instead of a spreadsheet. | |
| spreadsheetName | No | Name for a new spreadsheet when createNew is true. | |
| slackChannelName | No | Display name of the Slack channel. | |
| slackMessageTemplate | No | Message template for Slack. Omit to post the raw result. |
| Name | Required | Description |
|---|---|---|
| schedule | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true), so the description only needs to add context — and it does: required OAuth scopes and the fact that each run re-executes the saved query's SQL. It does not warn that writing to an existing spreadsheet at startCell/sheetName may overwrite prior output, which is a meaningful gap for a destructive tool.
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 tightly written sentences with no filler. The core action is front-loaded and the constraint and prerequisite follow in a logical order.
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 12-parameter creation tool with full schema coverage and an output schema, the description supplies the two things structured fields don't: auth scopes and destination exclusivity. Overwrite behavior on existing spreadsheets and whether schedules are editable afterward remain unaddressed but are secondary.
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 coverage is 100%, so the baseline is 3; the description earns an extra point by stating the destination parameters are mutually exclusive (exactly one of Google Sheets or Slack), an exclusivity rule the schema itself does not encode.
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 (schedule a saved query), the trigger mechanism (cron cadence), and the output surfaces (Google Sheets or Slack). This clearly separates it from siblings like list_schedules and run_schedule_now.
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 clear usage context: it requires write and execute scopes and restricts delivery to exactly one destination. It does not explicitly name alternatives such as run_schedule_now for one-off execution, so the when-not guidance is incomplete rather than absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run SQL against a connection and return rows. Connections in read-only mode accept a single SELECT, WITH or EXPLAIN statement.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | The SQL to run, in the connection's own dialect. | |
| limit | No | Maximum rows to return, 1 to 10000. Defaults to 1000. | |
| connectionId | Yes | Connection id from list_connections. |
| Name | Required | Description |
|---|---|---|
| result | No | |
| success | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and openWorldHint=false, so the safety profile is partly covered. The description adds the non-obvious single-statement restriction in read-only mode and that rows are returned, but it never warns that a non-read-only connection accepts writes or DDL, nor mentions timeouts, termination, or result truncation via limit.
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, zero filler, and the core action is front-loaded before the conditional constraint. Nothing is repeated from the schema or title.
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 explanation is not required, and the parameter schema is fully documented. However, for a destructive-flagged arbitrary-SQL executor, the description leaves out what happens on write connections, whether multiple statements are rejected, and any execution limits — meaningful gaps for this tool's risk profile.
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%, with all three parameters documented including the limit bounds/default and the connectionId source. The description adds no parameter-level meaning 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 and resource ("Run SQL against a connection and return rows") plus the statement types accepted in read-only mode. It is clearly distinguishable from run_saved_query or run_schedule_now by implication, but never names a sibling to make that routing explicit.
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?
The read-only-mode constraint (single SELECT, WITH or EXPLAIN) is a useful contextual guideline about when this form is accepted, but it is framed as a backend rule rather than usage guidance. Nothing tells the agent when to prefer run_saved_query, run_schedule_now, or export_query_results instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run SQL and export the rows as csv, json, or xlsx. xlsx is returned base64-encoded.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | The SQL whose result to export. | |
| limit | No | Maximum rows. Omit on PostgreSQL and MySQL to export everything the query returns. | |
| format | Yes | File format of the export. | |
| connectionId | Yes | Connection id from list_connections. |
| Name | Required | Description |
|---|---|---|
| format | Yes | |
| content | Yes | The file body: CSV or JSON text, or base64 for xlsx. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare destructiveHint=true and readOnlyHint=false, signaling that arbitrary SQL is executed with mutation potential. The description adds one genuinely non-schema behavior — that xlsx output is base64-encoded — but says nothing about how csv/json are delivered (inline vs. written to disk), whether writes are committed, or any size/timeout constraints on large exports.
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, zero filler, and the key operational detail (base64 xlsx) is placed front and center. Nothing to trim.
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-value explanation is not required, and the parameter list is fully covered by the schema. The remaining gap is the relationship to execute_query/run_saved_query, which the description never resolves for an agent choosing among four query-running siblings.
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 all four parameters are already documented, including the useful note about omitting limit on PostgreSQL/MySQL. The description only restates the format enum and adds the base64 detail, so it neither needs to nor does add much parameter meaning.
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 states a specific verb and resource ('Run SQL and export the rows') and enumerates the supported output formats, so the purpose is unambiguous. However, it never distinguishes itself from the obvious sibling execute_query, leaving the agent to infer why a separate export tool exists.
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?
There is no statement of when to choose this over execute_query or run_saved_query, and no exclusions or prerequisites (e.g. 'use when you need a downloadable file rather than in-memory rows'). The only usage hint is implicit in the word 'export'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single saved query by id, including its SQL and declared variables.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Saved query id from list_queries. |
| Name | Required | Description |
|---|---|---|
| id | No | |
| sql | No | |
| name | No | |
| isShared | No | |
| updatedAt | No | |
| variables | No | Declared {{name}} variables, filled in by run_saved_query. |
| folderPath | No | |
| connectionId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that SQL and declared variables come back, which is modest extra context, but says nothing about what happens for a missing/invalid id or access scoping.
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?
A single front-loaded sentence with the resource and the returned contents; nothing extraneous and 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?
An output schema exists, so return values need no explanation, and a one-param read-only tool needs little more. Only the error/not-found behavior is left unaddressed.
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 coverage is 100% and the schema already explains the id parameter as coming from list_queries. The description only restates 'by id' without adding format, source, or error semantics 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 specific verb (Get) and resource (a single saved query by id) and notes the payload includes SQL and declared variables, which distinguishes it from list_queries. It does not explicitly name the sibling it displaces, so differentiation is implied rather than stated.
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: fetch one saved query when you have its id. The description gives no explicit when-to-use or when-not, and the pointer to list_queries for obtaining ids lives only in the schema, not the prose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get every table and column for a connection, to write SQL against the real structure.
| Name | Required | Description | Default |
|---|---|---|---|
| connectionId | Yes | Connection id from list_connections. |
| Name | Required | Description |
|---|---|---|
| tables | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered structurally. The description adds that the result is exhaustive ('every table and column'), which is useful, but says nothing about size limits, latency, or behavior on large/complex databases.
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?
One sentence, front-loaded with the resource and scope, with the purpose clause appended. No filler or redundancy.
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 annotations covering the safety profile, the description only needs to convey scope and intent, which it does ('every table and column'). It could mention prerequisites such as knowing the connectionId from list_connections or handling very large schemas, but nothing essential 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 coverage is 100% and the single connectionId parameter is documented with a pointer to list_connections, so the schema does the work. The description only echoes 'for a connection' and adds no format or sourcing 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?
Specific verb+resource: retrieves every table and column for a connection, and adds the downstream intent (writing SQL against the real structure). It does not explicitly distinguish itself from siblings like list_connections or execute_query, so it falls 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?
The phrase 'to write SQL against the real structure' implies the call should precede query authoring, but it never states when not to use it or names an alternative tool. Usage is inferable rather than directed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the database connections available in this SaturnSQL company. Start here: every other tool takes a connection id from this list.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| connections | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds genuinely new workflow context: that the output is the source of connection ids for all sibling tools. It does not discuss pagination or result size, but with an output schema present that burden is partly lifted.
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 with zero waste, and the most actionable information (start here) is front-loaded after the purpose statement.
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?
A zero-parameter, read-only listing with an output schema and annotations covering safety needs only purpose plus workflow position, both of which are provided. 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?
The tool takes no parameters, so there is nothing for the description to disambiguate; the baseline for zero-param tools applies. The description correctly implies an unfiltered, whole-company listing.
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 ('List') and resource ('database connections') scoped to 'this SaturnSQL company', which distinguishes it from siblings like list_queries or list_schedules that list other entity types.
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: every other tool takes a connection id from this list' explicitly tells the agent this is the first call in the workflow and why the other tools depend on it. No exclusion is needed because nothing else returns connection ids.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the team's saved queries, with their SQL, folder and declared variables.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| queries | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description usefully notes what each returned entry contains, but says nothing about result volume, pagination, or ordering across a potentially large team list.
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?
A single well-formed sentence that front-loads the verb and resource, then adds the useful detail about returned fields. Nothing is wasted.
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?
The tool is simple (zero params, read-only) and an output schema exists, so return values need not be spelled out. Only the lack of sibling differentiation and result-set size guidance keeps it from 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?
The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 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 (List) and resource (team's saved queries) and adds the meaningful payload contents (SQL, folder, declared variables). It does not explicitly distinguish itself from the sibling get_query, which retrieves a single query, 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?
There is no guidance on when to use this versus get_query, run_saved_query, or save_query. The agent must infer from the name alone that this is the enumeration entry point.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the company's scheduled query exports, with cadence, destination and last-run status.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| schedules | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the returned fields, but since an output schema exists that is partly redundant, and it says nothing about scoping, pagination, or result size.
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?
A single front-loaded sentence with no filler; the resource comes first and the useful field detail follows.
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, no parameters, and read-only annotations, the description is nearly self-sufficient. The only missing context is scope/pagination behavior for a company-wide 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?
Zero parameters and a fully covered schema, so there is nothing for the description to disambiguate. Baseline 4 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 ('List') and resource ('scheduled query exports') and even names the fields surfaced (cadence, destination, last-run status). It implicitly separates itself from create_schedule and run_schedule_now, but never names a sibling explicitly.
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 implied: this is the discovery/read path versus create_schedule and run_schedule_now. There is no explicit when-to-use, when-not-to-use, or prerequisite statement, so an agent must infer the routing from the verb.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a saved query, substituting its declared {{variables}} from the values supplied.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Saved query id from list_queries. | |
| limit | No | Maximum rows to return, 1 to 10000. Defaults to 1000. | |
| values | No | Variable values keyed by variable name, e.g. {"start": "2026-01-01"}. Omitted variables fall back to their saved defaults. | |
| timeZone | No | IANA time zone for relative date variables such as today, e.g. Europe/Helsinki. Defaults to UTC. |
| Name | Required | Description |
|---|---|---|
| result | No | |
| success | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true and readOnlyHint=false, which is surprising for something called 'Run a saved query', yet the description says nothing about side effects, whether the underlying query may write data, or what permissions are needed. With no annotations-level explanation of the risk, the description's silence on destructiveness is a significant gap (no contradiction, however).
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?
One tight, front-loaded sentence with no filler. It is efficient, though the terseness is partly under-specification rather than deliberate economy.
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 values need not be described, but for a destructive-flagged tool with a nested 'values' object and multiple competing siblings, the description leaves the agent without routing guidance or risk disclosure. It covers the mechanic of variable substitution and nothing else.
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 id, limit, values, and timeZone are already fully documented, establishing a baseline of 3. The description's mention of variable substitution reinforces the 'values' parameter but adds no syntax or fallback behavior beyond what the schema already says.
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 ('Run a saved query') plus a distinctive behavior: substituting declared {{variables}} from supplied values. That distinguishes it reasonably from save_query or list_queries, though it never names the nearest sibling, execute_query, so the reader must infer the difference.
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?
The description gives no when-to-use guidance and never mentions alternatives such as execute_query or run_schedule_now, which are the obvious competing entry points. An agent must infer that a saved query id is required and that this is the ad-hoc execution path rather than the scheduled one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Trigger an existing schedule's export immediately, delivering to its already-configured destination.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Schedule id from list_schedules. |
| Name | Required | Description |
|---|---|---|
| success | No | |
| writtenRange | No | A1 range the export wrote to. |
| slackDelivered | No | |
| spreadsheetUrl | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already disclose that this is a non-read-only, open-world, destructive action, so the description is not the sole carrier of the safety profile. The description adds useful context that delivery goes to the schedule's already-configured destination, but it does not explain potential overwrite behavior, permissions, or other destructive implications beyond what the annotations state.
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?
The description is a single, front-loaded sentence with no wasted wording. It efficiently states the action, immediacy, and destination behavior.
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?
The tool is simple, the output schema exists, annotations cover the safety profile, and the input schema fully documents the only parameter. The description provides enough context for correct invocation, though it could have added a brief note about destructive side effects or prerequisites.
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 the single required 'id' parameter is documented as coming from list_schedules. The description does not add further meaning about the parameter beyond what the schema already provides, 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?
The description uses a specific verb and resource ('Trigger an existing schedule's export') and clarifies that delivery goes to the already-configured destination. It clearly distinguishes this action from creating a schedule, but it does not explicitly name sibling alternatives such as run_saved_query or list_schedules.
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?
The phrase 'immediately' implies when to use the tool: when an existing schedule's export should run now rather than at its normal time. However, the description does not state when not to use it or name alternatives, leaving usage guidance implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save a new query to the team's library, or update an existing one by passing its id.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Id of the saved query to overwrite. Omit to create a new one. | |
| sql | Yes | The SQL to save. | |
| name | Yes | Display name in the query library. | |
| folderPath | No | Single folder label to file it under; null or omitted for the root. | |
| connectionId | No | Connection id from list_connections. |
| Name | Required | Description |
|---|---|---|
| id | No | |
| sql | No | |
| name | No | |
| isShared | No | |
| updatedAt | No | |
| variables | No | Declared {{name}} variables, filled in by run_saved_query. |
| folderPath | No | |
| connectionId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered externally. The description adds useful context that the query is saved to a team library and that an existing query is updated by id, but it does not explain overwrite impact, permissions, or side effects in detail.
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?
The description is a single front-loaded sentence with no waste. It efficiently communicates the core create-or-update behavior.
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?
The tool has a rich schema, full parameter descriptions, annotations, and an output schema, so the description need not restate return values or parameter details. It adequately explains the create/update duality, though it could say more about destructive overwrite behavior beyond what annotations provide.
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 all five parameters are already documented in the schema. The description only echoes the id-based update behavior and adds little parameter meaning beyond the structured fields.
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: save a query to the team's library, including both create and update modes. It is clear what the tool does, though it does not explicitly distinguish itself from siblings such as list_queries or run_saved_query.
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?
The description gives a useful internal rule: omit id to create, pass id to update. It does not explain when to use this tool instead of adjacent tools like run_saved_query or list_queries, so the usage guidance is implied rather than complete.
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.
create_scheduleexecute_query2 fields changedInput schema / additionalPropertiesRemoved value: -falseOutput schema / properties / result / anyOfPrevious value: -[
- {
- "additionalProperties": true,
- "properties": {
- "duration": {
- "description": "Execution time in milliseconds.",
- "type": [
- "number",
- "null"
- ]
- },
- "fields": {
- "anyOf": [
- {
- "items": {
- "additionalProperties": true,
- "properties": {
- "name": {
- "type": [
- "string",
- "null"
- ]
- }
- },
- "type": "object"
- },
- "type": "array"
- },
- {
- "type": "null"
- }
- ]
- },
- "rowCount": {
- "type": [
- "number",
- "null"
- ]
- },
- "rows": {
- "anyOf": [
- {
- "items": {
- "additionalProperties": {},
- "type": "object"
- },
- "type": "array"
- },
- {
- "type": "null"
- }
- ],
- "description": "One object per row, keyed by column name."
- },
- "truncated": {
- "description": "True when the row limit or memory cap cut the result short.",
- "type": [
- "boolean",
- "null"
- ]
- }
- },
- "type": "object"
- },
- {
- "type": "null"
- }
-]New value: +[
+ {
+ "additionalProperties": {},
+ "properties": {
+ "duration": {
+ "description": "Execution time in milliseconds.",
+ "type": [
+ "number",
+ "null"
+ ]
+ },
+ "fields": {
+ "anyOf": [
+ {
+ "items": {
+ "additionalProperties": {},
+ "properties": {
+ "name": {
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "rowCount": {
+ "type": [
+ "number",
+ "null"
+ ]
+ },
+ "rows": {
+ "anyOf": [
+ {
+ "items": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "One object per row, keyed by column name."
+ },
+ "truncated": {
+ "description": "True when the row limit or memory cap cut the result short.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+]export_query_results2 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / limit / maximumAdded value: +9007199254740991get_query2 fields changedInput schema / additionalPropertiesRemoved value: -falseOutput schema / properties / variables / anyOfPrevious value: -[
- {
- "items": {
- "additionalProperties": true,
- "properties": {
- "name": {
- "type": [
- "string",
- "null"
- ]
- },
- "type": {
- "type": [
- "string",
- "null"
- ]
- }
- },
- "type": "object"
- },
- "type": "array"
- },
- {
- "type": "null"
- }
-]New value: +[
+ {
+ "items": {
+ "additionalProperties": {},
+ "properties": {
+ "name": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "type": {
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+]get_schema3 fields changedInput schema / additionalPropertiesRemoved value: -falseOutput schema / properties / tables / items / additionalPropertiesPrevious value: -trueNew value: +{}Output schema / properties / tables / items / properties / columns / anyOfPrevious value: -[
- {
- "items": {
- "additionalProperties": true,
- "properties": {
- "isPrimaryKey": {
- "type": [
- "boolean",
- "null"
- ]
- },
- "name": {
- "type": [
- "string",
- "null"
- ]
- },
- "nullable": {
- "type": [
- "boolean",
- "null"
- ]
- },
- "type": {
- "type": [
- "string",
- "null"
- ]
- }
- },
- "type": "object"
- },
- "type": "array"
- },
- {
- "type": "null"
- }
-]New value: +[
+ {
+ "items": {
+ "additionalProperties": {},
+ "properties": {
+ "isPrimaryKey": {
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "name": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "nullable": {
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "type": {
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+]list_connections1 field changedOutput schema / properties / connections / items / additionalPropertiesPrevious value: -trueNew value: +{}list_queries2 fields changedOutput schema / properties / queries / items / additionalPropertiesPrevious value: -trueNew value: +{}Output schema / properties / queries / items / properties / variables / anyOfPrevious value: -[
- {
- "items": {
- "additionalProperties": true,
- "properties": {
- "name": {
- "type": [
- "string",
- "null"
- ]
- },
- "type": {
- "type": [
- "string",
- "null"
- ]
- }
- },
- "type": "object"
- },
- "type": "array"
- },
- {
- "type": "null"
- }
-]New value: +[
+ {
+ "items": {
+ "additionalProperties": {},
+ "properties": {
+ "name": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "type": {
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+]list_schedulesrun_saved_query3 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / values / propertyNamesAdded value: +{
+ "type": "string"
+}Output schema / properties / result / anyOfPrevious value: -[
- {
- "additionalProperties": true,
- "properties": {
- "duration": {
- "description": "Execution time in milliseconds.",
- "type": [
- "number",
- "null"
- ]
- },
- "fields": {
- "anyOf": [
- {
- "items": {
- "additionalProperties": true,
- "properties": {
- "name": {
- "type": [
- "string",
- "null"
- ]
- }
- },
- "type": "object"
- },
- "type": "array"
- },
- {
- "type": "null"
- }
- ]
- },
- "rowCount": {
- "type": [
- "number",
- "null"
- ]
- },
- "rows": {
- "anyOf": [
- {
- "items": {
- "additionalProperties": {},
- "type": "object"
- },
- "type": "array"
- },
- {
- "type": "null"
- }
- ],
- "description": "One object per row, keyed by column name."
- },
- "truncated": {
- "description": "True when the row limit or memory cap cut the result short.",
- "type": [
- "boolean",
- "null"
- ]
- }
- },
- "type": "object"
- },
- {
- "type": "null"
- }
-]New value: +[
+ {
+ "additionalProperties": {},
+ "properties": {
+ "duration": {
+ "description": "Execution time in milliseconds.",
+ "type": [
+ "number",
+ "null"
+ ]
+ },
+ "fields": {
+ "anyOf": [
+ {
+ "items": {
+ "additionalProperties": {},
+ "properties": {
+ "name": {
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "rowCount": {
+ "type": [
+ "number",
+ "null"
+ ]
+ },
+ "rows": {
+ "anyOf": [
+ {
+ "items": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "One object per row, keyed by column name."
+ },
+ "truncated": {
+ "description": "True when the row limit or memory cap cut the result short.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+]run_schedule_nowsave_query2 fields changedInput schema / additionalPropertiesRemoved value: -falseOutput schema / properties / variables / anyOfPrevious value: -[
- {
- "items": {
- "additionalProperties": true,
- "properties": {
- "name": {
- "type": [
- "string",
- "null"
- ]
- },
- "type": {
- "type": [
- "string",
- "null"
- ]
- }
- },
- "type": "object"
- },
- "type": "array"
- },
- {
- "type": "null"
- }
-]New value: +[
+ {
+ "items": {
+ "additionalProperties": {},
+ "properties": {
+ "name": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "type": {
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+]execute_queryexport_query_resultsget_queryget_schemalist_connectionslist_queriesrun_saved_querysave_queryQuery 40 databases from Claude, ChatGPT, or Cursor — on any device. Read-only, encrypted, audited.
Query BigQuery, Snowflake, Redshift & Azure Synapse with natural language
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Query PostgreSQL databases in plain English — LLM-generated, safety-validated SQL.
Add one secure layer between your agents and this server.
