TextQL

View saved version →

---
name: explore-data
description: >-
  Explore your company's data in TextQL: list the connectors you can use,
  browse their tables, and preview rows. Use when someone asks what data
  exists, where a metric lives, or what a table looks like.
---

# Explore data

Read-only. Follow the `refinery` skill for tool details.

1. `refinery_workspace_info`, then `refinery_workspace_context`. Note any definitions or
   preferred tables the org's context names.
2. `refinery_connector_db_list` to list connectors. If the user named a
   source, match it here.
3. `refinery_connector_db_tables` with `connector`, narrowed with `schema`
   or `like` (for example `"%order%"`) when the list is long.
4. `refinery_connector_db_preview` with `connector`, `table` and a small
   `max_rows` (10 is plenty) for the one or two tables that matter.

Answer with a short map: which connector, which tables, what each holds, and
the columns that answer the user's question. Suggest the `query-data` skill
for the next step instead of running a query yourself.

View saved version →

---
name: find-saved-work
description: >-
  Find existing TextQL work before redoing it: saved chats, dashboards,
  agents, apps and artifacts. Use when someone asks for a dashboard, a past
  analysis, or "the report on" something.
---

# Find saved work

Read-only. Follow the `refinery` skill for tool details.

1. Pick the kind the user means: `refinery_workspace_dashboard_list`,
   `refinery_workspace_chat_list`, `refinery_workspace_agent_list`,
   `refinery_workspace_app_list` or `refinery_workspace_artifact_list`.
   When unsure, try the dashboard and chat lists first.
2. Open the best match with the matching `_show` tool (for example
   `refinery_workspace_dashboard_show`) and `ref` (an id or unique name from
   the listing).
3. Summarize what it contains and when it was made. Give its link when the
   result includes one.

Prefer an existing dashboard or analysis over recomputing it. If nothing
matches, say so and offer the `query-data` skill instead.

View saved version →

---
name: query-data
description: >-
  Answer a question from your company's data with TextQL: run SQL or a
  governed TQL query into a Python sandbox, then aggregate, analyze or chart
  the result there. Use for numbers, trends, comparisons and charts.
---

# Query and analyze data

Follow the `refinery` skill for tool details and limits.

1. `refinery_workspace_context`. Use an existing definition or governed
   model before writing raw SQL.
2. If the table is unknown, find it first with the `explore-data` steps.
3. `refinery_query` with `connector`, `sql` (one SELECT, in the
   connector's dialect) or `tql`, and a `dataframe` name. Do the heavy
   aggregation in SQL. `LIMIT` (sql) and `max_rows` (tql) bound the loaded
   dataframe, not just the inline preview — use them for samples and
   previews, and keep every row the analysis needs. Writes are refused
   unless the connector allows write operations; send only SELECT statements unless
   the user asked for a change.
4. Keep the returned `sandbox_id` and pass it to every later call.
5. `refinery_sandbox_python` with `code` and that `sandbox_id` for anything
   SQL cannot do cleanly: joins across queries, statistics, charts. Print
   only the summary, and set `max_output_chars` when output could be large.

Report the answer first, then the query you ran and any caveat (filters,
date range, rows excluded). If a query fails or a table is refused, show the
error. Never fill gaps with invented numbers.

View saved version →

---
name: refinery
description: >-
  Reference for the TextQL tools: every tool, the rules for
  orgs, sandboxes and governed queries, and how to keep results small. Use
  whenever a task involves the organization's data, connectors, warehouse
  queries, or analysis Python that needs org data.
---

# TextQL Refinery MCP tools

The `refinery_*` tools run against the TextQL deployment this plugin points at,
as the signed-in user. Every call goes through that user's roles, OAuth scopes
and org scoping, so a refusal is a permission answer, not a bug to work around.

Every action is its own tool, taking only that action's fields. Results share
one envelope: `operation`, `label`, `data`, and optionally `source`, `sandbox_id`,
`org`, `warning` and `error`. Read `error` and `warning` before trusting `data`.

| Tool | What it does |
| --- | --- |
| `refinery_workspace_info`, `refinery_workspace_context` | Who you are, scopes and tool availability; the org's standing context (read-only) |
| `refinery_workspace_orgs` | The organizations you belong to (read-only) |
| `refinery_workspace_{chat,agent,dashboard,app,artifact}_{list,show}` | Saved work (read-only) |
| `refinery_connector_db_{list,tables,preview}`, `refinery_connector_api_{list,get}` | Connectors, tables, previews and API connector metadata (read-only) |
| `refinery_query` | SQL or governed TQL into a sandbox dataframe |
| `refinery_sandbox_{new,list,status,rm,python,bash}` | Manage sandboxes and run code in them |
| `refinery_{connector,query,sandbox}_{wait,cancel}` | Follow up on a long call that returned while still running |
| `refinery_ontology_diff`, `refinery_ontology_propose` | Turn a sandbox's `library/` edits into an Ontology patch |
| `refinery_org_set`, `refinery_org_clear` | The organization calls run in when they omit `org` |
| `refinery_rpc_search` | Search the deployment's public RPC methods (read-only) |
| `refinery_rpc_call` | Call one method that `refinery_rpc_search` returned |

## Start here, every session

1. `refinery_workspace_info`: who you are signed in as,
   the org, the scopes the grant carries, and which execution tools the org
   allows. Check it before assuming a capability exists.
2. `refinery_workspace_context`: the organization's
   standing instructions about its own data (definitions, preferred tables,
   rules). The web app applies them on every turn, so read and follow them
   before writing any query. Skipping them is how an answer here ends up
   disagreeing with the app.

## If the tools are missing or not signed in (Codex)

When the `refinery_*` tools are unavailable or every call fails with an
authentication error, and you are running in Codex with a shell, sign in
through Codex's own MCP config. Read the server `url` from `mcp.json` in this
plugin's root (two directories above this skill), then run:

```sh
codex mcp add refinery --url <url>
codex mcp login refinery
```

`login` opens a browser window where the user signs in and approves access.
Tell the user to finish it, then start a new thread so the tools load. Without
a shell, ask the user to run those two commands themselves.

## Find the data before you query it

Use the connector tools before `refinery_query`. They are read-only and cheap:

- `refinery_connector_db_list` lists the org's database and BI connectors.
- `refinery_connector_db_tables` with `connector` (id or exact name) and
  optionally `schema` or `like` (for example `"orders%"`) lists tables.
- `refinery_connector_db_preview` with `connector` and `table` returns a few
  rows. Keep `max_rows` small (the default is 50, the cap is 1000).
- `refinery_connector_api_list` and `refinery_connector_api_get` describe API
  connectors.

Name a table the way `refinery_connector_db_tables` listed it. A name that matches nothing, or
several tables, is refused with the candidates.

Retrieval has a fixed order: look for an existing definition in the org
context, then run a governed `.tql`, then fall back to raw SQL. Python is fo

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: switch-org
description: >-
  See which TextQL organizations you can use, set the one to work in, and
  switch without signing in again. Use when someone names another
  organization, workspace or customer, asks to set or change their org, or
  asks which orgs they have.
---

# Switch organization

1. `refinery_workspace_orgs` lists the organizations, marks the current
   one and the default, and says why any is unavailable.
2. To set the organization to work in, call `refinery_org_set` with `org`
   (its id or exact name). Calls that omit `org` run there from then on, in
   this conversation and later ones, until it is set again or cleared with
   `refinery_org_clear`.
3. After setting it, remember the organization's id and pass it as `org` on
   every tool call, sandbox calls included. Do not rely on the default alone:
   passing `org` keeps each call pinned even if the default changes elsewhere.
4. A `sandbox_id` belongs to the organization that created it, so start a new
   sandbox after switching.
5. Results from another organization carry `org` in the envelope. Name the
   organization in your answer so the user knows where the numbers came from.

If `refinery_workspace_orgs` says the app must be reconnected, tell the user to disconnect and
reconnect it from a browser. The current connection only covers its original
organization until then.