Skip to main content
Glama

list_saved_queries

Read-only

List the data requests you have saved with save_user_query, newest first.

The entry point to the replay flow: check HERE FIRST, before running
`explore_data_catalogue` for any exploration question — a saved row that matches
the question, exactly OR in shape, means the answer is seconds away via
`run_saved_query` instead of a ~1-5 minute planning job.

Returns {"count": N, "saved_queries": [{"id", "user_request", "queries",
"query_placeholder", "metadata", "created_at", "updated_at"}, ...]}, the calling
user's rows only.

MATCH ON `metadata`, NOT ON THE LABEL. `metadata` describes what the row actually
asks. It is authored after the save and is null until the placeholder task has run
(roughly 10 s to 5 minutes, depending on the size of the queries):
  `summary`        one line with the slots in braces, e.g. "13F positions of
                   {managers} in {symbol}, {date_prior} vs {date_latest}: shares,
                   value, weight, QoQ change"
  `parameters`     [{name, type, description, example}] — the slot schema, one
                   vocabulary across every query in the row. These names are the
                   keys of `run_saved_query(values=...)`.
  `entities`       {slot: resolved example} — what the row was saved for
  `datasets`       the public dataset names the row reads (the same names
                   `explore_data_coverage` reports)
  `topics`         classifier topics for the saved request
  `result_schema`  [{index, summary, slots, columns}] — per query, what its result
                   set holds
  `stale`          true when a query no longer plans (checked nightly)
  `run_count`, `last_run_at`
Match the user's question against `summary` + `parameters` + `datasets`, NOT
against `user_request` — that is only the label the user typed while saving. SKIP
any row marked `stale: true`. For a row whose `metadata` has not landed yet, fall
back to the label and replay `queries` exactly.

Having picked a row:
  - EXACT repeat (same entities, same window) -> `run_saved_query(query_tokens=
    <the row's `queries`>)`; it replays as saved.
  - SAME SHAPE, other values (saved "the past 8 quarters of sales for TGT"; asked
    "KSS's last 8 quarters of sales") -> `run_saved_query(query_tokens=<the row's
    `query_placeholder`>, values={...})`, the values keyed by
    `metadata.parameters`; add a `prompt` only for slots you cannot type.
  - Pick WHICH of the row's queries to run from `result_schema`: the ones that
    answer the question, leaving the `_constituents` companion out — it is a
    7,000-35,000 row payload. Pass `max_rows` (e.g. 500) whatever you run.
  - TELL THE USER which saved row is being reused (its `summary` and `entities`)
    and which values were substituted (the replay's `parameters`).
A row that is merely close in TOPIC but asks a different thing is a DIFFERENT
question; confirm with the user before replaying it.

The other fields:
  - `queries` is the list of opaque query tokens for an exact replay.
  - `query_placeholder` is the list of placeholder-twin tokens, index-aligned with
    `queries`, or null while the placeholder task has not run yet (replay
    `queries` exactly or list again shortly). Never show a token of either kind to
    the user: it is ciphertext, not content, and says nothing about what the query
    does.
  - `user_request` is the user's own label — worth quoting when you say which row
    you reused, but not what to decide on.
  - `id` is what `delete_saved_query` takes.

Duplicate `user_request` values are possible — saving does not upsert.

An HTTP 503 here means the backend's saved-queries table has not been created yet,
NOT that the user has nothing saved — report that difference rather than an empty
list.

Requires auth (your MCP client attaches the OAuth bearer automatically).
Rate-limited 100/min.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoMax rows to return, newest first.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
countYes
saved_queriesYesThe calling user's saved rows, newest first.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only declare readOnlyHint=true, but the description adds substantial behavioral context: the full return shape, that rows are the calling user's only, the metadata-not-label matching rule, null-until-landed metadata with a 10s-5min window, stale-row skip logic, HTTP 503 meaning, auth requirement and a 100/min rate limit. This goes well beyond what the annotation provides.

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?

Well front-loaded (the 'check HERE FIRST' directive comes before all detail) and organized with bulleted sections. However, it is very long and devotes substantial space to the downstream run_saved_query replay procedure and metadata field anatomy, which strains the size appropriate for a one-parameter list tool.

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 an output schema existing, the description fully describes the return payload and every metadata field, plus edge cases (503, stale rows, null placeholder, duplicate user_request). Nothing an agent needs to act on the results is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single `limit` parameter, so the schema already documents it fully. The description adds no additional semantics for `limit` (its 'max_rows' guidance applies to run_saved_query, not this tool). Baseline 3 is appropriate when the schema carries the parameter semantics.

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+resource: 'List the data requests you have saved with `save_user_query`, newest first,' and explicitly names the sibling tool that created the rows. An agent can immediately distinguish this from explore_data_catalogue 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.

Usage Guidelines5/5

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

Unusually explicit routing: it tells the agent to 'check HERE FIRST, before running explore_data_catalogue,' and contrasts the saved-query replay (seconds) against a '~1-5 minute planning job.' It also names exact-repeat vs same-shape alternatives and their conditions, plus the caveat to confirm with the user when a row is merely topic-close.

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