> ## 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.

# Frictions tools

> MCP tools for listing, filtering, ranking, and inspecting frictions encountered across runs and experiments.

Rank recurring problems across your project or inspect one friction with its suggested fix and recent occurrences. See [Frictions](https://docs.oqoqo.ai/evaluation/frictions.md) for families and recovery states.

* **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\_frictions

**List a project's frictions.** Finds what keeps going wrong for agents, in the project or any scope, and what to fix first. By default, the most runs the agent never got past come first.

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

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `experiment_id`, `schedule_id`, `task_id`, `task_version_id`, `treatment_id`, `tool_id`, `tool_version_id`, `file_id`, `machine_id`, `agent_id`, `agent_model_id`, `friction_id` | string | No | Count only the runs that match every one, as in [`list_runs`](https://docs.oqoqo.ai/mcp-server/runs-and-results#list_runs). |
| `fix_in` | array of `product`, `agent`, `setup`, `agent_behavior` | No | [Where to fix](https://docs.oqoqo.ai/cli/frictions.md#where-to-fix): a tool or the product's API, errors, or docs; your custom agent; the treatment, task, or machine; or no change (agent behavior). |
| `families` | array of `product_gap`, `docs_gap`, `environment_gap`, `agent_harness_gap`, `agent_reasoning_gap`, `task_quality_gap` | No | Only these [families](https://docs.oqoqo.ai/cli/frictions.md#family). |
| `recoveries` | array of `recovered`, `unrecovered`, `unknown` | No | Count only runs where the agent recovered, didn't, or Insights couldn't tell. |
| `query` | string | No | Text in the title or summary, up to 200 characters. |
| `seen_after` | string (date-time) | No | Count only runs created at or after this time. |
| `sort` | `impact`, `runs`, `recent`, `new` | No | `impact` (default): most unrecovered runs, then most runs. `runs`: most runs. `recent`: last seen. `new`: first seen. |
| `limit` | integer | No | Results per page, up to 100 (default 25). |
| `cursor` | string | No | The `nextCursor` from the previous page. Send it with the same filters. |

A friction is listed when one of its runs matches every filter.

**Result fields**

| Field | Meaning |
| - | - |
| `scope` | Each record that the scope fields named, with its dashboard page |
| `totalFrictions`, `hasMore`, `nextCursor` | Matches across all pages, and the paging fields |
| `frictions` | Each friction's `frictionId`, `title`, `summary`, `family`, `fixIn`, `fixSurface` (the place its fix names, or null), `concentration` (where it happens most, by agent and treatment, as counts and a `sentence`, never a cause), `whoActs` (retiring; read `fixIn`), `origin`, `runs`, `unrecoveredRuns`, `tasks`, `experiments`, `firstSeenAt`, `lastSeenAt`, and `dashboardUrl` |
| `coverage` | Runs in scope with Insights off (`insightsOffRuns`), not reviewed (`unreviewedRuns`), not grouped yet (`ungroupedRuns`), or stopped by an Oqoqo error (`oqoqoErrorRuns`, which aren't frictions). A short list isn't proof that the runs went well. |
| `models` | The Insights and Experiment insights models that found and grouped the frictions, each with the runs it covered |

Each field is explained under [`oqoqo frictions list`](https://docs.oqoqo.ai/cli/frictions#oqoqo-frictions-list).

### get\_friction

**Read one friction with its evidence.** Returns its summary, impact, suggested fix, what the agent did, where it happens most, and up to ten recent occurrences with run, recovery, cited steps, and quotes.

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

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `friction_id` | string | Yes | The `frc_` friction from `list_frictions`. |
| `experiment_id`, `schedule_id`, `task_id`, `task_version_id`, `treatment_id`, `tool_id`, `tool_version_id`, `file_id`, `machine_id`, `agent_id`, `agent_model_id` | string | No | Count only the runs that match every one, as in [`list_runs`](https://docs.oqoqo.ai/mcp-server/runs-and-results#list_runs). |

**Result fields**

The friction has the fields of `list_frictions`, plus these:

| Field | Meaning |
| - | - |
| `impact` | Why it matters |
| `suggestedFix` | What to change at `fixSurface`. `null` for `agent_behavior`, or when no wording passed its check. |
| `agentNote` | What the agent did, beside a product or setup fix. It's never an instruction. |
| `byTreatment`, `byAgent` | The rate of runs with the friction for each treatment and each agent |
| `recentOccurrences` | Up to ten recent runs, each with its recovery, cited steps, and quotes |
| `models` | The models that found and grouped the friction, each with the runs it covered |

To list all the friction's `runs`, call `list_runs` with `friction_id` and the same scope.

## Related

> [card] [Evals and Insights tools](https://docs.oqoqo.ai/mcp-server/evals-and-insights.md)
>
> Run Insights to find and group frictions.

> [card] [oqoqo frictions](https://docs.oqoqo.ai/cli/frictions.md)
>
> The matching CLI commands and filters.


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