Skip to main content
Glama

Run saved query

run_saved_query
Read-only

Run a saved query from the team library by id and return its rows, in the same shape as execute_query. Prefer it over execute_query whenever list_queries has a query that answers the question: the saved SQL runs unchanged on the query's own connection, and you pass only the values for its {{variables}}, never SQL. On an approved_queries connection it is the only way to get data, and only queries shared with the team (isShared true) may run. Call get_query first to see which variables it declares, their types and which are required. Values are type-checked and escaped server side; if any value is missing or invalid, nothing runs and the error names each variable and what is wrong with it. Read-only: the filled-in SQL must be a single SELECT, WITH or EXPLAIN. A repeated identical run may return a result cached for up to 5 minutes unless refresh is true. 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; works for viewers too. Fails if the saved query has no connection or its connection is paused. 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": {
      "id": "<id>"
    },
    "name": "run_saved_query"
  }
}

Input Schema

NameRequiredDescriptionDefault
idYesSaved query id from list_queries.
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.
valuesNoVariable values keyed by variable name, all as strings, e.g. {"start": "2026-01-01", "region": "EU"}. Formats: date YYYY-MM-DD, number plain digits such as 42 or -3.5, boolean true or false, dropdown one of the variable's options. An omitted variable takes its saved default; one sent as an empty string stays empty, which fails if it is required.
refreshNoSkip the result cache and read the database now. Omit to allow a result cached in the last 5 minutes.
timeZoneNoIANA time zone used to resolve relative date defaults such as today or start_of_this_month, e.g. Europe/Helsinki. Defaults to UTC.
approvalIdNoOnly when repeating a call that came back with APPROVAL_REQUIRED, after the user approved it. Send the same arguments again.

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. Changed4 schema fields 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."
    • addedInput schema / properties / refresh
      Added value: +{
      +  "description": "Skip the result cache and read the database now. Omit to allow a result cached in the last 5 minutes.",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / timeZone / description
      Previous value: -"IANA time zone for relative date variables such as today, e.g. Europe/Helsinki. Defaults to UTC."New value: +"IANA time zone used to resolve relative date defaults such as today or start_of_this_month, e.g. Europe/Helsinki. Defaults to UTC."
    • changedInput schema / properties / values / description
      Previous value: -"Variable values keyed by variable name, e.g. {\"start\": \"2026-01-01\"}. Omitted variables fall back to their saved defaults."New value: +"Variable values keyed by variable name, all as strings, e.g. {\"start\": \"2026-01-01\", \"region\": \"EU\"}. Formats: date YYYY-MM-DD, number plain digits such as 42 or -3.5, boolean true or false, dropdown one of the variable's options. An omitted variable takes its saved default; one sent as an empty string stays empty, which fails if it is required."
  3. Changed3 schema fields changed
    • removedInput schema / additionalProperties
      Removed value: -false
    • addedInput schema / properties / values / propertyNames
      Added value: +{
      +  "type": "string"
      +}
    • 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?

Annotations only declare readOnlyHint and openWorldHint; the description adds substantial behavior beyond that: type-checked and escaped values with all-or-nothing failure, single-query-cache up to 5 minutes unless refresh, monthly quota plus 30 queries/minute (and per-connection lower limits), execute scope working for viewers, failure when the connection is missing or paused, and the full APPROVAL_REQUIRED / approvalUrl / approvalId retry dance with a 30-minute single-use window.

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 the execute_query alternative, and nearly every sentence carries a distinct operational fact. It is a long dense paragraph, though, and the approval workflow mixed into the middle would scan better as separated clauses or a short ordered list.

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?

Despite the tool's complexity (6 params, nested values object, approval flow, an output schema), the description covers auth scope, rate limits, caching, error semantics, and the exact approval retry procedure. Nothing an agent needs to call it correctly appears to be missing, and return values are delegated appropriately to the output schema.

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 meaning: values are only for the query's {{variables}} and never SQL, their formats are type-checked, and the agent is pointed to get_query to learn names, types, and required flags. It also ties refresh to the cache and approvalId to the approval retry, though it does not elaborate on limit or timeZone beyond what the schema already says.

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

Purpose5/5

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

States a specific verb and resource ('Run a saved query from the team library by id and return its rows') and immediately anchors the output shape to the sibling execute_query. An agent can tell this apart from execute_query and get_query without opening any 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?

Explicit routing rules: prefer this over execute_query whenever list_queries has a query that answers the question, and on an approved_queries connection it is the only way to get data. It also names prerequisites (call get_query first to see declared variables) and the precondition that only isShared queries may run.

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