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

# oqoqo frictions

> List the frictions agents hit in your runs, filter them by where to fix and by family, and read one friction with its evidence.

A friction is a problem that agents hit, tracked across runs and experiments under one stable `frc_` ID. Use `oqoqo frictions list` to decide what to fix first, and `oqoqo frictions get` to read one friction with its evidence. [Frictions](https://docs.oqoqo.ai/evaluation/frictions.md) explains how Insights find, group, and rank them.

## oqoqo frictions list

List and filter the project's frictions. By default, the frictions with the most runs that the agent never got past come first.

```bash theme={null}
oqoqo frictions list [flags]
```

**Plugin (MCP) tool:** [`list_frictions`](https://docs.oqoqo.ai/mcp-server/frictions#list_frictions)

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--experiment-id` | string | | Runs of this `exp_` experiment. |
| `--schedule-id` | string | | Runs of the experiments this `sch_` schedule launched. |
| `--task-id` | string | | Runs of this `tsk_` task, in any version. |
| `--task-version-id` | string | | Runs of this `tskver_` task version. |
| `--treatment-id` | string | | Runs of this `trt_` treatment (toolset). |
| `--tool-id` | string | | Runs whose treatment had this skill, MCP server, CLI, or SDK (`skl_`, `mcp_`, `cli_`, `sdk_`), in any version. |
| `--tool-version-id` | string | | Runs whose treatment had this tool version (`sklver_`, `mcpver_`, `cliver_`, `sdkver_`). |
| `--file-id` | string | | Runs whose task had this `fld_` file. |
| `--machine-id` | string | | Runs whose task ran on this `env_` machine. |
| `--agent-id` | string | | Runs of this agent key, such as `claude-code`, with any model. |
| `--agent-model-id` | string | | Runs of this `agm_` agent and model. |
| `--friction-id` | string | | Runs where this `frc_` friction occurred. |
| `--fix-in` | string | | Comma-separated places to fix: `product`, `agent`, `setup`, `agent_behavior`. See [Where to fix](#where-to-fix). |
| `--family` | string | | Comma-separated families: `product_gap`, `docs_gap`, `environment_gap`, `agent_harness_gap`, `agent_reasoning_gap`, `task_quality_gap`. See [Family](#family). |
| `--recovery` | string | | Comma-separated recovery values: `recovered`, `unrecovered`, `unknown`. See [Recovery](#recovery). |
| `--query` | string | | Words in the title or summary, up to 200 characters. |
| `--seen-after` | string | | Count only runs created at or after this ISO 8601 date-time. |
| `--sort` | `impact`, `runs`, `recent`, `new` | `impact` | See [Sort](#sort). |
| `--limit` | integer | `25` | Results per page, up to 100 (default 25). |
| `--cursor` | string | | The `nextCursor` from the previous page. |

`--experiment-id` to `--friction-id` are the [run scope flags](https://docs.oqoqo.ai/cli/runs.md#run-scope-flags). Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

List the frictions to fix in your product that agents never got past:

```bash theme={null}
oqoqo frictions list --fix-in product --recovery unrecovered
```

List one experiment's frictions, most runs first, as JSON:

```bash theme={null}
oqoqo frictions list --experiment-id exp_8f2c41d0 --sort runs --output json
```

List the frictions of one task version's runs:

```bash theme={null}
oqoqo frictions list --task-version-id tskver_3a91c7e2
```

List the frictions of the runs that had one MCP server, on one machine:

```bash theme={null}
oqoqo frictions list --tool-id mcp_2e8b6f13 --machine-id env_90c4d1a7
```

List the frictions that occur with another friction:

```bash theme={null}
oqoqo frictions list --friction-id frc_7d20e6b4
```

**Result fields**

With `--output json`, the result has `scope` (each record that your scope flags named, with its `kind`, `id`, current `name`, and `dashboardUrl`), `totalFrictions`, `hasMore`, `nextCursor`, `models` (the **Insights model** and **Experiment insights model** that found and grouped the frictions), and `coverage`. Each friction has these fields:

| Field | Meaning |
| - | - |
| `frictionId` | The `frc_` ID. The ID and title never change. |
| `title`, `summary` | The problem |
| `family` | The cause. See [Family](#family). |
| `whoActs` | The family's group: `product` (**Product**, **Docs & skills**), `agent` (**Agent software**, **Agent reasoning**), or `setup` (**Machine**, **Task quality**). For where to fix, read `fixIn`. |
| `fixIn` | Where to fix it. See [Where to fix](#where-to-fix). |
| `fixSurface` | The place the fix names, by its current name: a tool, treatment, or custom agent, or **API or docs**, **Task**, or **Machine**. `null` when no checked place passed. |
| `concentration` | Where it happens most, by `agent` and by `treatment`, with counts and a ready `sentence` |
| `origin` | `insights`, or `infra` for a run that failed before the agent answered |
| `runs`, `unrecoveredRuns` | Runs in scope with the friction, and the ones the agent never got past |
| `tasks`, `experiments` | How many tasks and experiments it occurred in |
| `firstSeenAt`, `lastSeenAt` | When it was first and last seen |
| `dashboardUrl` | The friction's page in the dashboard |

`coverage` tells an empty result from an incomplete one:

| Field | Meaning |
| - | - |
| `runs` | Runs in scope |
| `insightsOffRuns` | Runs with Insights off. Only frictions from runs that failed before the agent answered can show for them. |
| `unreviewedRuns` | Runs with Insights on that Insights hasn't reviewed yet or couldn't review. Their frictions aren't listed. |
| `ungroupedRuns` | Runs whose frictions Insights found but has not grouped yet |
| `oqoqoErrorRuns` | Runs an Oqoqo error stopped before the agent answered. They aren't frictions: [launch again](https://docs.oqoqo.ai/cli/experiments.md#oqoqo-experiments-rerun). |

**Notes**

* A friction is listed when one of its runs matches every filter. It counts each run once, however often the agent hit it in that run.
* `totalFrictions` counts matches across all pages. Page with `--cursor` while `hasMore` is true.
* A scope ID the project doesn't have fails with `scope_not_found`, not an empty list.
* With `--friction-id`, the list shows the frictions that occur in the same runs.
* An empty or short list isn't proof that the runs went well. Check `coverage` for runs that Insights hasn't reviewed or grouped yet.

## oqoqo frictions get

Read one friction: what goes wrong, why it matters, the suggested fix and where to make it, where it happens most, and its most recent runs.

```bash theme={null}
oqoqo frictions get <friction-id> [flags]
```

**Plugin (MCP) tool:** [`get_friction`](https://docs.oqoqo.ai/mcp-server/frictions#get_friction)

**Arguments**

| Argument | Description |
| - | - |
| `<friction-id>` | Required. The friction's `frc_` ID. |

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--experiment-id` | string | | Runs of this `exp_` experiment. |
| `--schedule-id` | string | | Runs of the experiments this `sch_` schedule launched. |
| `--task-id` | string | | Runs of this `tsk_` task, in any version. |
| `--task-version-id` | string | | Runs of this `tskver_` task version. |
| `--treatment-id` | string | | Runs of this `trt_` treatment (toolset). |
| `--tool-id` | string | | Runs whose treatment had this skill, MCP server, CLI, or SDK (`skl_`, `mcp_`, `cli_`, `sdk_`), in any version. |
| `--tool-version-id` | string | | Runs whose treatment had this tool version (`sklver_`, `mcpver_`, `cliver_`, `sdkver_`). |
| `--file-id` | string | | Runs whose task had this `fld_` file. |
| `--machine-id` | string | | Runs whose task ran on this `env_` machine. |
| `--agent-id` | string | | Runs of this agent key, such as `claude-code`, with any model. |
| `--agent-model-id` | string | | Runs of this `agm_` agent and model. |

These are the [run scope flags](https://docs.oqoqo.ai/cli/runs.md#run-scope-flags) except `--friction-id`. Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

Read one friction across the project:

```bash theme={null}
oqoqo frictions get frc_7d20e6b4
```

Read the same friction, counted over one experiment's runs:

```bash theme={null}
oqoqo frictions get frc_7d20e6b4 --experiment-id exp_8f2c41d0 --output json
```

List every run where the friction occurred:

```bash theme={null}
oqoqo runs list --friction-id frc_7d20e6b4
```

**Result fields**

With `--output json`, the result has `scope` and the friction. The friction has the fields of [`oqoqo frictions list`](#oqoqo-frictions-list) (`frictionId`, `title`, `summary`, `family`, `whoActs`, `fixIn`, `fixSurface`, `concentration`, `origin`, `runs`, `unrecoveredRuns`, `tasks`, `experiments`, `firstSeenAt`, `lastSeenAt`, and `dashboardUrl`), 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` | One observed sentence on what the agent did, beside a product or setup fix. Never an instruction. Otherwise `null`. |
| `byTreatment`, `byAgent` | The rate of runs with the friction per treatment and per agent |
| `recentOccurrences` | Up to ten recent runs, each with its recovery, cited steps, and quotes |
| `models` | The **Insights model** and **Experiment insights model** that found and grouped it, each with the runs it covered |

**Notes**

`recentOccurrences` holds up to ten of the friction's `runs`. To list them all, use [`oqoqo runs list --friction-id`](https://docs.oqoqo.ai/cli/runs#oqoqo-runs-list) with the same scope flags.

`concentration` compares agents and treatments only within an experiment that ran more than one of them. It reports counts, never a cause.

## Where to fix

`fixIn` says where your team can fix the friction. `--fix-in` filters on these keys.

| Key | Label | The suggested fix names |
| - | - | - |
| `product` | **Product** | A tool in the treatment (an MCP server, CLI, SDK, or skill), or the product's API, errors, or docs |
| `agent` | **Custom agent** | Your organization's [custom agent](https://docs.oqoqo.ai/setup/custom-agents.md): its instructions, tools, or code |
| `setup` | **Setup** | The treatment (which tools it gives the agent), the task text or its checks, or the machine |
| `agent_behavior` | **Agent behavior** | No change: the cause is the agent's behavior. `suggestedFix` is `null`. |

## Family

Each friction has one family, which names its cause. `--family` filters on these keys.

| Key | Label | What it means |
| - | - | - |
| `product_gap` | **Product** | The product's API, SDK, or CLI rejected valid usage, returned wrong results, or contradicted its own schema. |
| `docs_gap` | **Docs & skills** | Docs or skill files were missing, wrong, incomplete, or misleading for the task. |
| `agent_harness_gap` | **Agent software** | The agent's own software failed, for example a broken tool, a tool error, a failed install, or a crash. |
| `agent_reasoning_gap` | **Agent reasoning** | The agent made a wrong call, for example bad assumptions, a misread task, dead ends, backtracking, or sloppy output. |
| `environment_gap` | **Machine** | The machine failed the agent, for example with missing environment variables or keys, or broken dependencies. |
| `task_quality_gap` | **Task quality** | The task or its grading was at fault, for example an ambiguous task, a wrong check, or evidence that was not saved or read correctly. |

Check **Machine** and **Task quality** frictions before you trust the results: they can make them unreliable.

## Recovery

For each run with the friction, Insights records whether the agent got past it. `--recovery` filters on these keys.

| Key | Label | Meaning |
| - | - | - |
| `recovered` | **Recovered** | The agent course-corrected and finished the task. |
| `unrecovered` | **Unrecovered** | The agent never recovered from this friction. |
| `unknown` | **Unknown** | Insights could not tell whether the agent recovered. |

## Sort

| Value | Dashboard order | What comes first |
| - | - | - |
| `impact` | **Unrecovered runs** (default) | The most runs the agent never got past, then the most runs, then the most recently seen |
| `runs` | **Runs** | The most runs |
| `recent` | **Last seen** | The most recently seen |
| `new` | **First seen** | The newest friction, by when it was first seen |

## Related

> [card] [Frictions](https://docs.oqoqo.ai/evaluation/frictions.md)
>
> How frictions are found, grouped, and ranked.

> [card] [Find and fix frictions](https://docs.oqoqo.ai/guides/fix-frictions.md)
>
> Work from the top friction to a measured fix.

> [card] [oqoqo runs and results](https://docs.oqoqo.ai/cli/runs.md)
>
> List the runs of a friction and read their traces.

> [card] [oqoqo evals and insights](https://docs.oqoqo.ai/cli/evals-and-insights.md)
>
> Start Insights to find frictions.


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