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

cognitive_effort is an MCP tool. There is no cognitive-effort CLI command.

{
  "name": "cognitive_effort",
  "arguments": {
    "url": "https://example.com",
    "persona": "first-timer",
    "scope": "viewport",
    "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)
scope string No viewport (default, above the fold), full_page (the whole page), or sequential (each screen in turn, reporting where people stop)
siteFamiliarity number No 0 (first visit) to 1 (daily user) for this persona on this URL
useValues boolean No Turn on motivational value adjustments (default: false)
userLocation string No The user's approximate location, e.g. Denver, Colorado, US
userTimezone string No The user's timezone, e.g. America/Denver
userLanguage string No The user's expected language, e.g. en-US
proxy string No Proxy server URL for geo-accurate testing
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 Measure in an existing browser session, for pages that depend on state

The tool has no device parameter. It measures in the browser it is given: without a token, at the default 1920x1080 page size. To measure a phone layout, start a session with navigate and device: "mobile", then pass that _browserToken.

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

From the Blog