Skip to main content
Glama

Run SQL

execute_query
Read-only

Run ad hoc SQL on one connection and return the rows as JSON objects keyed by column name, plus column names, rowCount, duration in ms and a truncated flag. Use it to answer a one-off question. If a saved query already answers it, use run_saved_query instead; to hand the data on as a file, use export_query_results. Read-only: only a single SELECT, WITH or EXPLAIN statement is accepted, and anything else is rejected without running. Refused on an approved_queries connection; use run_saved_query there. A repeated identical query may return a result cached for up to 5 minutes. Each call counts against the company's monthly query quota and a limit of 30 queries per minute (the team can set a lower one per connection). Needs the execute scope and a member role that can edit; viewers get an error. A database error is returned as an error with the database's message. The team can require a person to approve some requests: the call then fails with code APPROVAL_REQUIRED and an approvalUrl. Show the user that link, wait until they say it is approved, then repeat the exact same call with approvalId. An approval works once, for that SQL, within 30 minutes.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "connectionId": "<connectionId>",
      "sql": "<sql>"
    },
    "name": "execute_query"
  }
}

Input Schema

NameRequiredDescriptionDefault
sqlYesThe SQL to run, in the connection's own dialect.
limitNoMaximum rows to return, 1 to 10000. Defaults to 1000. The team can set a lower limit per connection. The result's truncated flag is true when rows were cut.
approvalIdNoOnly when repeating a call that came back with APPROVAL_REQUIRED, after the user approved it. Send the same arguments again.
connectionIdYesConnection id from list_connections.

Output Schema

NameRequiredDescriptionDefault
resultNo
successNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • addedInput schema / properties / approvalId
      Added value: +{
      +  "description": "Only when repeating a call that came back with APPROVAL_REQUIRED, after the user approved it. Send the same arguments again.",
      +  "type": "string"
      +}
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum rows to return, 1 to 10000. Defaults to 1000. The result's truncated flag is true when rows were cut."New value: +"Maximum rows to return, 1 to 10000. Defaults to 1000. The team can set a lower limit per connection. The result's truncated flag is true when rows were cut."
    • changedOutput schema / properties / result / anyOf
      Previous 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"
      -  }
      -]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"
      +        ]
      +      },
      +      "rowLimit": {
      +        "description": "Set when the connection's row limit for AI tools cut the result to this many rows.",
      +        "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"
      +  }
      +]
  2. Changed1 schema field changed
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum rows to return, 1 to 10000. Defaults to 1000."New value: +"Maximum rows to return, 1 to 10000. Defaults to 1000. The result's truncated flag is true when rows were cut."
  3. Changed2 schema fields changed
    • removedInput schema / additionalProperties
      Removed value: -false
    • changedOutput schema / properties / result / anyOf
      Previous 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"
      +  }
      +]
  4. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Far exceeds the annotations: discloses single-statement read-only restriction, that non-SELECT/WITH/EXPLAIN is rejected without running, 5-minute result caching, monthly quota and 30/min rate limit with per-connection overrides, required execute scope and editor role, DB errors surfaced verbatim, and the full APPROVAL_REQUIRED retry protocol with single-use, 30-minute approval validity. Nothing here contradicts readOnlyHint=true or openWorldHint=false.

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 purpose and return shape, then alternative routing, then constraints and error protocol — a logical order with almost no filler. It is long, and restating the return shape when an output schema exists is mildly redundant, but the density of operational detail justifies most of the length.

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?

For a high-stakes query tool with four parameters and an approval flow, the description covers authorization, quota, refusal conditions, error semantics and the retry sequence; the output schema relieves it of further return-value detail. An agent has everything needed to call it correctly and handle APPROVAL_REQUIRED.

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 baseline is 3, but the description adds real meaning about approvalId (send the identical call after user approval, one-time use, 30-minute window) beyond the schema's terse note. It also ties `limit` to the truncated flag, though it does not discuss dialect differences for `sql`.

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?

Opens with a specific verb and resource ("Run ad hoc SQL on one connection") plus the exact return shape, and explicitly contrasts itself with run_saved_query and export_query_results so an agent can route correctly without reading sibling schemas.

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 explicit when-to-use ("one-off question"), names two alternatives with the condition that selects each (saved query exists → run_saved_query; need a file → export_query_results), and states a hard exclusion (refused on an approved_queries connection). No inference required.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources