Skip to main content
A friction is a problem that agents hit, tracked across runs and experiments under one stable frc_ ID. Use obss frictions list to decide what to fix first, and obss frictions get to read one friction with its evidence. Frictions explains how Insights find, group, and rank them.

obss 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.
Plugin (MCP) tool: list_frictions Flags --experiment-id to --friction-id are the run scope flags. Also takes the global flags. Examples List the frictions to fix in your product that agents never got past:
List one experiment’s frictions, most runs first, as JSON:
List the frictions of one task version’s runs:
List the frictions of the runs that had one MCP server, on one machine:
List the frictions that occur with another friction:
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: coverage tells an empty result from an incomplete one: 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.

obss 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.
Plugin (MCP) tool: get_friction Arguments Flags These are the run scope flags except --friction-id. Also takes the global flags. Examples Read one friction across the project:
Read the same friction, counted over one experiment’s runs:
List every run where the friction occurred:
Result fields With --output json, the result has scope and the friction. The friction has the fields of obss frictions list (frictionId, title, summary, family, whoActs, fixIn, fixSurface, concentration, origin, runs, unrecoveredRuns, tasks, experiments, firstSeenAt, lastSeenAt, and dashboardUrl), plus these: Notes recentOccurrences holds up to ten of the friction’s runs. To list them all, use obss runs list --friction-id 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.

Family

Each friction has one family, which names its cause. --family filters on these keys. 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.

Sort

Next steps