Back to docs

Tool Cognitive Effort

Measure the total cognitive effort for a persona to use a page. Uses the full eight-layer Sequential Transport Chain from the Cognitive Optimal Transport framework.

Usage

npx cbrowser cognitive-effort --url "https://example.com" --persona first-timer

MCP Tool

{
  "name": "cognitive_effort",
  "arguments": {
    "url": "https://example.com",
    "persona": "first-timer",
    "device": "mobile",
    "useValues": false
  }
}

Parameters

Parameter Type Required Description
url string Yes URL to analyze
persona string Yes Persona name (e.g., first-timer, cognitive-adhd, power-user)
device string No Device type: mobile, tablet, desktop
useValues boolean No Turn on motivational value adjustments (default: false)
geoRegion string No Route through a residential proxy in a region
waitAfterLoad number No Extra ms to wait after page loads (e.g., 3000 for translated sites)
waitForSelector string No CSS selector to wait for after load (e.g., [data-translated])
_browserToken string No Reuse an existing browser session for pages that depend on state

Response

Returns a complete cognitive transport analysis:

  • Total CTC -- Overall cognitive transport cost (0 to unlimited, lower is better)

  • Per-layer breakdown -- Cost for each of the eight layers, in chain order:

    1. Saliency -- Can they find the thing they came for? How it is computed: Visual prominence from CIE-Lab centre-surround contrast, against how readily this persona notices change at all.
    2. Cognitive Load -- Is there more on this page than they can hold at once? How it is computed: Information and visual density against working memory, comprehension, and how familiar this persona already is with the site.
    3. Decision -- Are there too many choices to pick between? How it is computed: Choice count under Hick-Hyman, against this persona's tolerance for satisficing, risk and social proof.
    4. Motor -- Can they physically hit the target? How it is computed: Fitts' law throughput and endpoint scatter -- how long the movement takes, and how likely it lands. Two independent things.
    5. Motor Procedure -- Can they get through the whole sequence, not just one click? How it is computed: Number of steps the interaction demands, against how fluently this persona executes a learned sequence. Separate from Motor because hitting a target and completing a procedure fail for different reasons.
    6. Frustration -- How close are they to giving up? How it is computed: Cumulative friction from the layers above, against this persona's patience, resilience and self-efficacy.
    7. Readability -- Can they decode the words on the page? How it is computed: Text complexity, vocabulary and typographic treatment against reading capacity. This is decoding only -- the effort of turning marks into words.
    8. Reading Attention -- Can they hold the line long enough to finish? How it is computed: Total quantity of text and how much competes with it, against sustained attention. Split from Readability because decoding and holding the line are different abilities -- an ADHD reader typically decodes fine and loses the thread, and a single 'reading' score cannot say that.

  • Bottleneck -- Which layer causes the most difficulty

  • Abandonment risk -- How likely the user is to give up (percentage)

  • Motor overlay URL -- Visual overlay showing element accessibility

Related Tools

From the Blog