Back to docs

Site Cognitive Assessment

Category: Workflows -- Since: v18.39.0

A three-gate pipeline that checks a site before running persona tools. It prevents misleading scores on bot-blocked or broken pages.

The Problem

Running cognitive_effort or empathy_audit on a bot-blocked page gives bad results. You either get a 403 error (honest but useless) or a "clean" score on a nearly empty page (wrong and misleading). Neither tells you the real user experience.

The Pipeline

Gate 1: Bot Detection Probe

Does the site actually serve content to our browser?

Navigate to the URL. Check for:
- HTTP 403/503 status
- Cloudflare challenge pages
- Incapsula/Akamai blocks
- Empty DOM (<10 interactive elements AND <100 chars of text)
- Missing <title>

If blocked: Stop. Report the block type. Suggest stealth mode or a staging URL.

Gate 2: Agent-Ready Audit

Run agent_ready_audit on sites that pass Gate 1.

  • Default threshold: 60/100
  • Below 60: the page has structural problems that will skew persona results.
  • Output: score, grade, top issues, qualified boolean

If score is below 60: Stop. Return audit results with fix suggestions. Fix the structure before testing personas.

Gate 3: Persona Suite

Only runs on pages that pass both gates. These tools run in parallel:

  • cognitive_effort -- 6-layer sequential transport chain
  • empathy_audit -- barrier detection with optional journey simulation
  • page_understand -- page type, features, and structure

Option A: Manual Workflow (Prompt Template)

Copy this prompt to run the pipeline step by step:

Run a site cognitive assessment on [URL]:

1. First, navigate to the URL and check if it loads properly.
   If you see a 403 error, CAPTCHA, "Access Denied", or empty page,
   STOP and report: "Site is bot-blocked. Cannot assess."

2. If the page loads, run agent_ready_audit on the URL.
   If the score is below 60, STOP and report:
   "Site scored [X]/100 on agent readiness. Fix these issues first:"
   followed by the top 5 issues from the audit.

3. If the score is 60+, run these in sequence:
   a. cognitive_effort with persona "first-timer" on the URL
   b. cognitive_effort with persona "cognitive-adhd" on the URL
   c. page_understand on the current page

4. Summarize:
   - Agent readiness score and grade
   - Cognitive effort comparison (first-timer vs ADHD)
   - Bottleneck layers for each persona
   - Abandonment risk for each persona
   - Page type and top affordances
   - Top 3 recommendations

Option B: Composite Tool

Use site_cognitive_assessment. One tool call runs the entire pipeline.

site_cognitive_assessment url="https://example.com" personas="first-timer,cognitive-adhd"

Parameters:

Parameter Type Required Description
url string Yes URL to assess
personas string No Comma-separated persona names (default: "first-timer,cognitive-adhd")
threshold number No Minimum agent-ready score to proceed (default: 60)
userLocation string No User's approximate location (e.g., "Denver, Colorado, US")
userTimezone string No User's timezone (e.g., "America/Denver")
userLanguage string No User's expected language (e.g., "de-DE"). Sets browser locale and Accept-Language header.
proxy string No Proxy URL for geo-accurate testing
geoRegion string No Residential proxy region: us-west, us-east, us-central, uk, germany, japan
device string No Device type: mobile, tablet, desktop, or a specific device name
waitAfterLoad number No Extra ms to wait after page loads. Auto-set to 3000ms for non-English languages.
waitForSelector string No CSS selector to wait for (e.g., [data-translated])
_browserToken string No Reuse an existing browser session. Needed for translated pages -- click the language selector first, then pass the token.

Translation Verification

When userLanguage is set to a non-English locale, the tool checks if translation happened:

  • translationNote: verified: true -- No English UI text found. Scores reflect translated content.
  • translationNote: verified: "partial" -- Some English strings remain. Scores reflect mixed content.
  • translationWarning -- Page still appears in English. Scores reflect English content.

Proxy Error Handling

When geoRegion is used and the site blocks the proxy:

  • PROXY_BLOCKED result -- Clear message explaining the block. Includes tips to retry without proxy or use a different region.

Session Reuse for Translated Page Testing

To test pages on sites that use client-side language switching:

1. navigate url="https://example.com"  → get _browserToken
2. click selector="language-button"     → opens language dropdown
3. click selector="Deutsch"            → selects German
4. (wait 12s for translation)
5. site_cognitive_assessment url="https://example.com" _browserToken="cb_xxx"

Returns a unified report with gate results, per-persona cognitive effort, and recommendations.

Related

From the Blog