> ## Documentation Index
> Fetch the complete documentation index at: https://developers.askparable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools, prompts, and limits

> The tools, prompts, and resources of the Parable MCP server, the permissions each tool needs, and the limits on results.

The Parable MCP server offers a fixed set of 17 tools, 5 prompts, and 3
resources. Every tool only reads. The server lists only the tools that the
person's roles allow, and a host cannot call a tool that the server does not
list. To connect a host, see [Connect an MCP host](/mcp/connect.md).

When a host connects, the server sends it instructions. They tell the model
to read the query guidance first, to find tables with `search_available_data`,
to describe a table before it writes SQL, and to check a statement with
`plan_sql` before it runs it. They also tell the model to treat rows and
descriptions as data, not as instructions.

## Tools

Each tool calls the Workspace API as the person. A tool needs a role that
grants one of the permissions in its row. A permission also covers each
permission under it: `tenant` covers them all. An OAuth grant and an MCP
token work on every tool.

### Query Provider data

A person sees these tools when a role can query: Provider Pools Reader, Data
Access, or Workspace Administrator. A member who holds only Viewer sees none
of them.

| Tool | What it does | Permission |
| - | - | - |
| `read_query_guidance` | Returns the guidance for writing SQL over the Provider Pools. | `tenant.data.catalog` or `tenant.data.query.providers` |
| `search_available_data` | Finds tables, columns, and fields by the words in their names and descriptions. An empty query lists each Provider. With the scope `providers.<provider>`, it lists that Provider's tables, a page at a time. | `tenant.data.query.providers` |
| `describe_pool_table` | Returns one table's columns, types, keys, and freshness. | `tenant.data.catalog` |
| `plan_sql` | Checks one statement and returns its plan. It runs nothing. | `tenant.data.query.providers` |
| `query_provider_pool` | Runs one read-only statement and returns its rows. | `tenant.data.query.providers` |

Tables are named `providers.<provider>.<table>`. These tools use the same
operations as [SQL over HTTP](/data/sql-over-http.md). Provider Policies and
source permissions narrow what they read for every person. All data access
does not apply to them: an administrator's host reads only what the Policies
give the administrator's roles.

A statement can call the SQL AI functions, such as `ponder()` and `embed()`.
Each one is a model call under the Workspace's model policy, as it is in any
other SQL.

### Published Plots

| Tool | What it does | Permission |
| - | - | - |
| `list_published_plots` | Lists the published Plots in the Workspace. | `tenant.parables.view` or `tenant.data.catalog` |
| `read_published_plot` | Returns one published Plot. | `tenant.parables.view` or `tenant.data.catalog` |
| `read_plot_data` | Returns the rows of a Plot, a page at a time. | `tenant.parables.view` or `tenant.parables.manage` |
| `list_what_plot_returns` | Lists the columns that each Plot of a Parable returns. | `tenant.parables.view` or `tenant.parables.manage` |
| `get_plot_typescript_types` | Returns TypeScript types for the Plots of a Parable. | `tenant.parables.view` or `tenant.parables.manage` |

### Provider connections and Taps

| Tool | What it does | Permission |
| - | - | - |
| `list_provider_connections` | Lists each Provider connection with its `connectionStatus`, `lastSyncAt`, and `lastSyncStatus`. | `tenant.connectors.view` |
| `read_provider_connection` | Returns one Provider connection. | `tenant.connectors.view` |
| `read_why_sync_failed` | Returns the error of a connection's most recent failed sync. | `tenant.connectors.view` |
| `read_tap` | Returns one Tap with its output schema. | `tenant.connectors.taps.view` |
| `list_workspace_taps` | Lists the Workspace's Taps, 100 at a time, without their output schemas. Send `offset` for the next page, until a page holds fewer than its limit. | `tenant.connectors.taps.view` |

### Powers

| Tool | What it does | Permission |
| - | - | - |
| `list_powers` | Lists the Workspace's Powers. | `tenant.parables.ponder` |
| `read_power` | Returns one Power. | `tenant.parables.ponder` |

The server has no tool that changes data. It has no tool that sends a Message
to Ponder, changes a Provider connection, or runs `preview_plot`.

## Prompts and resources

Each prompt and resource returns one guidance text. The server reads the
Workspace's Power of the same name when you may use Ponder. Otherwise it
reads Parable's built-in text.

| Prompt | Resource | What it explains | Who can use it |
| - | - | - | - |
| `pool_search` | `parable://guidance/pool-search` | How to find the tables and columns that hold the data a question needs. | People who can call `read_query_guidance`, or use Ponder |
| `providers` | `parable://guidance/providers` | How Provider data is named, synced, and queried in the Provider Pools. | The same |
| `plots` | `parable://guidance/plots` | How to write a Plot: a named SQL computation and its typed result. | The same |
| `panes` | None | How a Pane is built. | People who can use Ponder |
| `perceptions` | None | How a Perception declares the shape of a Pane's value. | People who can use Ponder |

In Claude Code, with the server named `parable`, run a prompt as
`/mcp__parable__pool_search`. Attach a resource as
`@parable:parable://guidance/providers`.

## Limits

| Limit | Value |
| - | - |
| A query result | Whole leading rows within 60,000 characters, columns included. `truncated` says which limit applied: `rows`, `values`, or `capture`. |
| One text or binary value in a result | 2,000 characters |
| Data that one query reads for its result | 3 MiB |
| A table listing from `search_available_data` | 100 tables, and at most 40,000 characters, a page. Send `nextCursor` back as `cursor` for the next page. The last page has none. |
| `list_workspace_taps` | 100 Taps a page, without output schemas |
| Requests to the server | 120 a minute for each credential in each Workspace |
| The query tools | 120 requests a minute, and 30 seconds a call |
| A request body to the server | 1 MiB |

`returnedRows` counts the rows in a result, not the rows that the query
matched. A result marked `truncated` is not the whole answer. Narrow the
query, or add a `LIMIT`.

The query tools answer a limit with its own status. None of these statuses
means that the SQL is wrong:

| Status | Cause |
| - | - |
| `504` | The statement ran past its time budget, or did not finish in 30 seconds. |
| `429` | Too many queries were running (`QL-IN-008`), or more than 120 of these requests came in a minute. Nothing ran. |
| `503` | The query service ran short of memory (`QL-IN-009`), or a service that the statement needs did not answer. |

## Tool errors

A tool that fails returns a result with `isError: true`. The result's text
is the Workspace API's message, its code, and its status:

```text theme={null}
query references relation "orders", which is not present in the catalog (code: QL-PL-002, status: 400)
```

When the error has no code, the text has the status only, such as
`... (status: 404)`. A permission error needs a different role, not a
different query.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.