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

# Tags and data query tools

> MCP tools for listing, adding, removing, renaming, and deleting tags, and running semantic queries over project data.

Organize resources and experiments with [tags](https://docs.oqoqo.ai/experiments/tags.md), or run bounded JSON queries over your results datasets.

* **Badges** are explained under [Approvals](https://docs.oqoqo.ai/mcp-server/overview.md#approvals).
* **`project_id`** is optional on most tools; without it, the server picks a project for that call only ([Projects](https://docs.oqoqo.ai/mcp-server/overview.md#projects)).
* **`expected_organization_id`** is an optional string on every write tool, omitted from parameter tables; pass `organization.id` from [`get_identity`](https://docs.oqoqo.ai/mcp-server/identity-and-projects#get_identity) ([Organization check](https://docs.oqoqo.ai/mcp-server/overview.md#organization-check)).
* **`limit`** values above a tool's maximum are capped, not refused.

## Tools

### list\_tags

**List a project's tags.** Lists every tag with its `tag_` ID, usage by kind, and the `updatedAt` that `rename_tag` and `delete_tag` need. One call returns all of them (at most 500).

Read-only · CLI: [`oqoqo tags list`](https://docs.oqoqo.ai/cli/tags#oqoqo-tags-list)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `query` | string | No | Only tags whose name contains this text, in any case. Up to 40 characters. |

**Result fields**

Each tag has `id`, `name`, `usage` (`total` and `byKind`), `createdAt`, and `updatedAt`.

`inspect_catalog` and `list_experiments` filter by tag with `tags` and `untagged`.

### update\_tags

**Add or remove tags on records.** Adds and removes tags on up to 100 records at once. Adding a name that the project doesn't have yet creates the tag.

Changes data · CLI: [`oqoqo tags add`](https://docs.oqoqo.ai/cli/tags#oqoqo-tags-add), [`oqoqo tags remove`](https://docs.oqoqo.ai/cli/tags#oqoqo-tags-remove)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `resource_ids` | array of strings | Yes | 1 to 100 record IDs: `tsk_`, `fld_`, `env_`, `skl_`, `mcp_`, `cli_`, `sdk_`, `trt_`, or `exp_`. Tags go on the record, not a version. |
| `add` | array of strings | No | Up to 20 tags to add, by name in any case or by `tag_` ID. |
| `remove` | array of strings | No | Up to 20 tags to remove, by name or `tag_` ID. |

**Result fields**

`records` (each record's `id`, `kind`, and all its `tags` after the change) and `createdTags` (the tags this call created).

You can send the same call again safely. A change that would give a record more than 20 tags changes nothing and returns `tag_limit_exceeded`. Tags never change a record's definition, versions, or `updatedAt`.

### rename\_tag

**Rename a tag.** Renames a tag. Every record keeps it, because its `tag_` ID doesn't change.

Changes data · CLI: [`oqoqo tags rename`](https://docs.oqoqo.ai/cli/tags#oqoqo-tags-rename)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `tag` | string | Yes | The tag to rename: its `tag_` ID or its current name. |
| `name` | string | Yes | The new name: at most 40 characters, with no commas. |
| `expected_updated_at` | string (date-time) | Yes | The tag's `updatedAt` from `list_tags`. |

**Result fields**

The renamed `tag`, with its `id`, `name`, `usage`, `createdAt`, and `updatedAt`.

A tag that changed since you read it returns `tag_changed` with the current `updatedAt`. A name that another tag in the project has, in any case, returns `tag_name_taken` with that tag's ID.

### delete\_tag

**Delete a tag from every record.** Deletes a tag and removes it from every record that has it. Tell the person how many records have it, from `list_tags`, before you call it.

Destructive · Irreversible · CLI: [`oqoqo tags delete`](https://docs.oqoqo.ai/cli/tags#oqoqo-tags-delete)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `tag` | string | Yes | The tag to delete: its `tag_` ID or its name. |
| `expected_updated_at` | string (date-time) | Yes | The tag's `updatedAt` from `list_tags`. A stale value returns `tag_changed`. |

**Result fields**

`tag` (the deleted tag's `id` and `name`) and `removedFrom` (how many records had it). A tag the project doesn't have returns `tag_not_found`.

### inspect\_data\_model

**List the data you can query.** Lists every dataset, its fields and types, each field's filters and aggregates, the default order, and the limits.

Read-only · CLI: [`oqoqo data describe`](https://docs.oqoqo.ai/cli/data#oqoqo-data-describe)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |

**Result fields**

`datasets`, each with `name`, `title`, `description`, `grain`, `fields`, `identityFields`, `defaultSelect`, and `defaultOrder`, and `limits`. Each field has `name`, `type`, `nullable`, `description`, `filterOperators`, and `aggregates`.

### query\_data

**Query Oqoqo data.** Runs one bounded query over a dataset. It never accepts SQL or returns internal IDs, secrets, or credential-like values.

Read-only · CLI: [`oqoqo data query`](https://docs.oqoqo.ai/cli/data#oqoqo-data-query)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `dataset` | string | Yes | A dataset from `inspect_data_model`, such as `runs`, `evals`, or `insights`. |
| `select` | array of strings | No | 1 to 12 fields to return. Omit to use the dataset's default columns. |
| `filters` | array of objects | No | Up to 20, each with `field`, `operator` (`eq`, `neq`, `lt`, `lte`, `gt`, `gte`, `in`, `not_in`, `contains`, `starts_with`, `is_null`, `is_not_null`), and `value` (default `[]`). Omit `value` for `is_null` and `is_not_null`; pass up to 100 values for `in` and `not_in`. |
| `groupBy` | array of strings | No | Up to 4 fields to group by (default `[]`). |
| `aggregates` | array of objects | No | Up to 8, each with `function` (`count`, `count_distinct`, `sum`, `avg`, `min`, `max`), optional `field` (`count` omits `field`), and `as` (the column name) (default `[]`). |
| `orderBy` | array of objects | No | Up to 4, each with `field` and `direction` (`asc` default, or `desc`) (default `[]`). |
| `limit` | integer | No | Results per page, up to 200 (default 100). |
| `cursor` | string | No | The `nextCursor` from the previous page (cursor window up to 10,000 rows). A cursor whose row count or order changed returns `stale_cursor`. |

Queries run with a 3-second statement timeout and cap each returned cell at 4,096 bytes.

**Result fields**

`columns`, `rows`, `query` (the query as Oqoqo ran it), `page` (`returned`, `hasMore`, `nextCursor`, `truncated`, and `reasons`), and `limits`. The datasets and their fields are listed under [`oqoqo data`](https://docs.oqoqo.ai/cli/data#datasets), including `evals.mode`, the model fields of `evals` and `insights`, and the per-turn `runTurns` series.

## Related

> [card] [oqoqo tags](https://docs.oqoqo.ai/cli/tags.md)
>
> The matching tag CLI commands.

> [card] [oqoqo data](https://docs.oqoqo.ai/cli/data.md)
>
> All queryable datasets, fields, and query limits.


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