Check authoritative indexing-coverage metadata for exact repository-relative paths and bounded path scopes. Use this after graph discovery for every cited or operated-on file; use scopes before negative/exhaustive claims because fully skipped files cannot appear in normal graph results. Returns coverage status separately from filesystem metadata freshness, plus structured parse-error ranges and direct-source fallback actions. The signal is best-effort: indexed_no_recorded_gap is not a completeness guarantee. At least one of 'paths' or 'scopes' is required; the call is rejected at runtime if both are omitted.

Repository-relative files to check exactly. Required if 'scopes' is omitted.

Repository-relative path prefixes; use . for the project root. Required if 'paths' is omitted.

Check index coverage

Delete a project from the index

Delete project

Map a git diff to its BLAST RADIUS. Resolves changed files to the symbols they define, then runs ONE multi-source graph traversal to the transitive impact set. RESPONSE: base + merge_base SHA, changed_files list, then impacted = prefix-grouped tree rows (name label hop; full qn = group prefix + dot + name) + an impacted_modules rollup; impacted_total + truncated are exact. Seeds (the changed symbols) are excluded from impacted; a changed file reached from another changed file is not counted as extra impact. format="json" returns the same model as structured JSON.

Max traversal hops from the changed symbols.

inbound (default) = the blast radius: transitive CALLERS of the changed symbols. outbound = what the changed code depends on. both = union.

Per-symbol impacted rows shown (nearest hops first). impacted_total is always exact and the impacted_modules rollup always complete regardless.

files: changed files only (no traversal). impact (default): files + the transitive impact set.

Git ref or tag to compare from (e.g. HEAD~5, v0.5.0). Diffs <ref>...HEAD.

Detect changes

Get high-level architecture overview. DEFAULT (no aspects) is a compact summary — overview counts, languages, packages, entry_points; request more via aspects:[...] (structure, dependencies, routes, hotspots, boundaries, layers, clusters, file_tree) or ["all"]. 'clusters' runs Leiden community detection over the call/import graph, surfacing the de-facto modules (label, member count, cohesion score, representative top_nodes, binding packages/edge_types) — the real architectural seams, which often cut across the folder layout. Optional path scopes analysis to nodes under that directory prefix (file_path).

Aspects to include. 'all' = everything; 'overview' = compact summary (all except file_tree); omit = all. 'cycles' is opt-in ONLY (never via all/overview): it scans the whole call graph for circular CALLS dependencies (SCCs of size > 1).

all overview structure dependencies routes languages packages entry_points hotspots boundaries layers file_tree clusters cycles

Optional directory prefix to scope architecture (e.g. apps/hoa)

Get architecture

Read source code for a function/class/symbol. IMPORTANT: First call search_graph to find the exact qualified_name, then pass it here. This is a read tool, not a search tool. Accepts full qualified_name (exact match) or short function name (returns suggestions if ambiguous). If the response carries a 'coverage_note', the file was only partially indexed — constructs in the noted line ranges may be missing from the graph (best-effort signal); prefer grep there and treat the returned source as ground truth.

Full qualified_name from search_graph, or short function name

Get code snippet

Get the schema of the knowledge graph (node labels, edge types)

Get graph schema

Index a repository into the knowledge graph. Special mode 'cross-repo-intelligence': skip extraction, only match Routes/Channels across projects to create CROSS_HTTP_CALLS/CROSS_ASYNC_CALLS/CROSS_CHANNEL edges. Requires target_projects param. Ensure target projects have fresh indexes first. COVERAGE: the response reports files that were NOT fully indexed — 'skipped' (not indexed at all: oversized/read/parse failures) and 'parse_partial' (indexed, but constructs inside the listed line ranges could not be parsed and MAY be missing from the graph). The embedded lists carry counts plus a FEW EXAMPLES only; the complete lists are in the per-run 'logfile' (path in the response) and queryable any time via index_status or structurally via query_graph(graph="missed"). Both signals are best-effort: absence of a flag is NOT a completeness guarantee; prefer grep inside flagged ranges. Separately, 'excluded' + 'not_indexed_files' list what was deliberately NOT indexed (gitignore/.cbmignore/skip-lists) — by design, not failures.

All modes run type-aware LSP call/usage resolution (per-file + cross-file). full: all files + similarity/semantic edges. moderate: filtered files + similarity/semantic. fast: filtered files, no similarity/semantic. cross-repo-intelligence: match Routes/Channels across projects.

full moderate fast cross-repo-intelligence

Override the derived project name. Non-ASCII bytes are encoded and unsafe path characters are normalized.

Write compressed artifact to .codebase-memory/graph.db.zst for team sharing. Teammates can bootstrap from the artifact instead of full re-indexing.

Path to the repository

Projects to search for cross-repo links (cross-repo-intelligence mode). Use ["*"] for all indexed projects. Run list_projects to see available projects.

Index repository

Get the indexing status of a project: node/edge counts, root path, git context, and the indexing-COVERAGE report — which files the indexer could NOT fully cover (best-effort signal): 'parse_partial' files WERE indexed but contain line ranges tree-sitter could not parse — constructs there MAY be missing from the graph (some are still recovered); 'skipped' files were not indexed at all (oversized/read/parse failure). Use this before trusting graph completeness on a file: if a file is listed, ALSO grep it (especially the flagged ranges). IMPORTANT: absence from these lists is NOT a completeness guarantee — the signal only marks what the indexer can detect. For structural queries over the misses use query_graph(graph="missed"). The report also carries 'not_indexed' — files/dirs excluded BY DESIGN (gitignore/.cbmignore/skip-lists): deliberate and deterministic, not failures; change the ignore rules and re-index to include them.

Include the git context block (worktree/shadow path variants). Only needed when debugging where an index lives — omitted by default to keep the status lean.

Index status

Ingest runtime traces to enhance the knowledge graph

Ingest traces

List indexed projects with deterministic pagination

Include branch, node/edge counts and database size. Slower.

Deprecated compatibility alias for include_details=false.

List projects

Create or update Architecture Decision Records

Complete replacement document required by update

update replaces the entire ADR document; sections only lists existing headings

Manage ADR

Execute a Cypher query against the knowledge graph for complex multi-hop patterns, aggregations, and cross-service analysis. The response includes 'total' (returned row count). There is a hard 100k row ceiling — for broad queries add LIMIT in the Cypher itself or use search_graph + offset/limit pagination instead. COMPLEXITY / BOTTLENECKS: every Function and Method node carries queryable complexity properties — cyclomatic (complexity), cognitive, loop_count, loop_depth (max nested-loop depth, a polynomial-degree proxy), plus interprocedural transitive_loop_depth (worst-case nested-loop degree propagated along CALLS edges) and a recursive flag. Additional hot-path signals: linear_scan_in_loop (count of find/contains/indexOf-style scans inside a loop — the hidden O(n^2) that loop_depth misses), alloc_in_loop (allocations/appends inside a loop), recursion_in_loop (a self-call inside a loop), unguarded_recursion (recursion with no conditionally-guarded base case), param_count and max_access_depth (structure smells). Find all hot-path candidates in one query, e.g. MATCH (f:Function) WHERE f.transitive_loop_depth >= 3 OR f.linear_scan_in_loop >= 1 RETURN f.qualified_name, f.transitive_loop_depth, f.linear_scan_in_loop ORDER BY f.transitive_loop_depth DESC. MISSED GRAPH: pass graph="missed" to query the best-effort miss graph instead — the file structure of ONLY the files the indexer could NOT fully index (Project → Folder → File nodes with CONTAINS_FOLDER/CONTAINS_FILE edges; each File carries kind ("parse_partial" = indexed but constructs in the flagged line ranges MAY be missing; or a skip phase) and detail (the line ranges / reason)). Example: MATCH (f:File) WHERE f.kind = \"parse_partial\" RETURN f.file_path, f.detail. Absence from this graph is NOT a completeness guarantee.

Which graph to query: the code knowledge graph (default) or the missed graph (only files not fully indexed, laid out as their file structure).

Optional row limit. Default: unlimited up to a 100k row ceiling. No offset support — use search_graph for paginated browsing.

Cypher query

Query graph

Graph-augmented code search. Finds text patterns via grep, then enriches results with the knowledge graph: deduplicates matches into containing functions, ranks by structural importance (definitions first, popular functions next, tests last). Modes: compact (default, signatures only — token efficient), full (source capped at a 60-line window around the first match per hit; source_truncated marks the cut — use get_code_snippet for the complete symbol), files (just file paths). Use path_filter regex to scope results. TRUNCATION: enriched results are capped at limit (default 10). Response carries 'total_grep_matches' (raw grep hit count) and 'total_results' (deduplicated function count) — compare to limit to detect truncation. There is no offset parameter; to see more, raise limit or narrow the query with file_pattern / path_filter.

Lines of context around each match (like grep -C). Only used in compact mode.

Include scope_ms, scan_ms, and enrich_ms phase timing diagnostics.

Glob for grep --include (e.g. *.go)

Max enriched results per call. Default 10. Response includes 'total_grep_matches' and 'total_results' so callers can detect truncation. No offset parameter — raise limit or narrow with file_pattern / path_filter to see more.

compact: signatures+metadata (default). full: with source. files: just file list.

Regex filter on result file paths (e.g. ^src/ or \.(go|ts)$)

Search code

Search the code knowledge graph for functions, classes, routes, and variables. Use INSTEAD OF grep/glob when finding code definitions, implementations, or relationships. Three search modes: (1) query='update settings' for BM25 ranked full-text search with camelCase splitting and structural label boosting — recommended for natural-language discovery; (2) name_pattern='.*regex.*' for exact pattern matching; (3) semantic_query=[...] for vector cosine search that bridges vocabulary (finds 'publish' when you search 'send'). The three modes are independent and can be combined in a single call. RESPONSE: prefix-grouped tree rows by default — a shared (qn-prefix, file) group header printed once, then `name label lines in out` per row (full qn = group prefix + dot + name). in/out = selected degree across CALLS, USAGE, CALL_REFERENCE, INHERITS, and IMPLEMENTS; other edge types are excluded. These are NOT caller/callee counts — use trace_path for callers. Add per-node property columns via fields (e.g. ["complexity","signature","docstring"]); format="json" returns the SAME tree model as structured JSON. PAGINATION: results are capped at limit (default 50). The response always includes 'total' (full match count before limit) and 'has_more' (true when total > offset+returned). Detect truncation with has_more, then page by re-calling with offset=offset+limit until has_more is false. Narrow first via label/file_pattern/min_degree before paginating large result sets.

ids: bare qualified-name enumeration (one column) — cheapest form for wide sweeps where per-row metadata is noise. default: full rows.

Extra per-node property columns, e.g. complexity, cognitive, signature, docstring, return_type, is_test, lines(int). Core row columns (qn/label/file/lines/in/out) are always present — do not request them here. Missing values emit as empty cells.

Response encoding. tree (default): prefix-grouped text rows. json: the SAME tree model as structured JSON (groups + column-ordered row arrays).

Max results per call. Default 50. Response carries 'total' (full match count) and 'has_more' (true if truncated) so callers can detect the limit and paginate.

Skip the first N matching nodes. Combine with 'limit' to page: increment offset by limit and re-call while has_more is true.

Natural-language or keyword full-text search using BM25 ranking. Tokens are split on whitespace; camelCase identifiers are indexed as individual words (updateCloudClient → update, cloud, client). Results are ranked with structural boosting: Functions/Methods +10, Routes +8, Classes/Interfaces +5. Noise labels (File/Folder/Module/Variable) are filtered out. When provided, name_pattern is ignored.

MUST be an ARRAY of keyword strings (e.g. ["send","pubsub","publish"]) — NOT a single string. Each keyword is scored independently via per-keyword min-cosine; results reflect functions that score well on ALL keywords. Requires moderate/full index mode. Results appear in the 'semantic_results' field (separate from 'results').

Search graph

Trace paths through the code graph. Modes: calls (callers/callees), data_flow (value propagation with args at each hop), cross_service (through HTTP/async Route nodes). Use INSTEAD OF grep for callers, dependencies, impact analysis, or data flow tracing. RESPONSE: prefix-grouped tree rows — callees/callers grouped under their shared qn-prefix, `name hop` per row (full qn = group prefix + dot + name); exact callees_total/callers_total on every page = ALL nodes reachable within depth (transitive, not just direct; test files excluded unless include_tests). risk/args flags use a flat table. `truncated: true` + `next` = more rows — pass next back as cursor. format="json" returns the SAME tree model as structured JSON.

Resume token from a previous response's 'next' field. Pass it back with ALL other arguments identical to get the following page with no duplicates. Cursors outlive nothing: after a reindex you get a stale_cursor error — just re-run the original query.

Add how each hop was resolved: a strategy class (lsp | language_rule | heuristic | unresolved) and the resolver's confidence. Off by default — it adds two columns per row. Use it to judge whether an edge is trustworthy, not to find edges.

Include test files in results. When false (default), test files are filtered out. When true, test nodes are included with a test column/marker.

Rows per page. callees_total/callers_total always carry the exact full counts; when a page is truncated the response carries next — see cursor.

calls: follow CALLS edges. data_flow: follow CALLS+DATA_FLOWS with arg expressions. cross_service: follow HTTP_CALLS+ASYNC_CALLS+DATA_FLOWS through Routes, plus CROSS_* cross-repo edges (CROSS_HTTP_CALLS/ASYNC_CALLS/CHANNEL/GRPC_CALLS/GRAPHQL_CALLS/TRPC_CALLS) to hop into other services.

For data_flow mode: scope trace to a specific parameter name

Add risk classification (CRITICAL/HIGH/MEDIUM/LOW) based on hop distance

Trace path


ARIA snapshot of the page or a scoped element. Returns a tree with refs (e1, e2, ...) and a refs map.
Use refs in interaction tools: selector "e1" or "@e1" to click/fill that element. Output includes URL, title, and YAML tree.
Refs are valid until next snapshot or navigation. interactiveOnly: only interactive elements get refs; omit for content roles (headings, etc.) too.
cursorInteractive: true adds refs for clickable elements without ARIA (e.g. div with cursor:pointer/onclick).
Use with a11y_take-ax-tree-snapshot for full UI analysis.

Omit structural nodes without content.

Include cursor:pointer / onclick elements.

Only interactive elements get refs.

Max tree depth; 0 = root only.

Scope to this element; omit for full page.

Includes the page URL, title, and a YAML-formatted accessibility tree with [ref=e1] etc.

Map of ref id to { role, name?, selector, nth? }. Use selector "e1" or "@e1" in interaction tools.

Combines Chromium AX tree with runtime visual diagnostics (bounding box, visibility, viewport).
Use to detect: elements with role/name but hidden or off-screen; layout/geometry issues; overlap/occlusion (enable checkOcclusion).
When investigating UI/layout or when clicks fail on seemingly visible elements, set checkOcclusion:true—it uses elementFromPoint()
at center+corners to find what is actually on top. boundingBox is from getBoundingClientRect() (viewport coords; layout box only).
selectorHint is best-effort (data-testid/data-selector/id). Use with a11y_take-aria-snapshot for full UI analysis.

Use elementFromPoint to detect what is on top.

Include bounding box and visibility.

ARIA/AX role names to include; omit for default set. Standard roles: ARIA https://w3c.github.io/aria/#role_definitions, Chromium AX https://chromium.googlesource.com/chromium/src/+/main/ui/accessibility/ax_enum_util.cc (e.g. button, heading, staticText, image, main, navigation). Matching is case-insensitive; "text" also matches staticText, "img" matches image.

display visibility opacity pointer-events position z-index color background-color border-color border-width border-style font-family font-size font-weight line-height letter-spacing text-align text-decoration-line white-space overflow overflow-x overflow-y transform cursor

CSS property names when includeStyles.

Total number of nodes returned by Chromium Accessibility.getFullAXTree before filtering.

Number of DOM-backed AX nodes that passed role filtering before enrichment.

Number of nodes included in the final enriched snapshot output.

List of enriched DOM-backed AX nodes combining accessibility metadata with visual diagnostics.

Unique identifier of the accessibility node within the AX tree.

Chromium backend DOM node identifier used to map AX nodes to DOM elements.

Child AX node ids in the full AX tree (may include nodes not present in the filtered output).

DOM class attribute of the mapped element.

Raw AX description payload associated with the node, if present.

Resolved DOM nodeId from CDP if available; may be null because nodeId is not guaranteed to be stable/resolved.

Frame identifier if the node belongs to an iframe or subframe.

DOM id attribute of the mapped element.

Whether the accessibility node is marked as ignored.

Lowercased DOM tag name of the mapped element (e.g. div, button, input).

Accessible name computed by the browser accessibility engine.

Parent AX node id in the full AX tree. Null if this node is a root.

Additional AX properties exposed by the accessibility tree.

ARIA role of the accessibility node (e.g. button, link, textbox).

Runtime-derived visual information representing how the element is actually rendered.

Height of the element in CSS pixels.

Width of the element in CSS pixels.

X coordinate of the element relative to the viewport.

Y coordinate of the element relative to the viewport.

Bounding box computed at runtime using getBoundingClientRect.

Whether the element intersects the current viewport.

Whether the element is considered visually visible (display, visibility, opacity, and size).

Occlusion detection results. Only present when checkOcclusion=true.

Intersection rect area in CSS pixels squared.

Intersection rect height.

Intersection rect width.

Intersection rect X.

Intersection rect Y.

Intersection box between this element and the occluding element. Null if not occluded or cannot compute.

True if at least one sample point is covered by another element.

Sample points used for occlusion detection (center + corners).

True if elementFromPoint at this point returned a different element that is not a descendant.

Sample point X (viewport coordinates) used for occlusion testing.

Sample point Y (viewport coordinates) used for occlusion testing.

Height of the occluding element bounding box.

Width of the occluding element bounding box.

X coordinate of the occluding element bounding box.

Y coordinate of the occluding element bounding box.

Bounding box of the occluding element (if available).

DOM class of the occluding element (may be null if none).

DOM id of the occluding element (may be null if none).

Tag name of the occluding element.

Best-effort selector hint for the occluding element.

localName id className selectorHint boundingBox

Identity and geometry of the occluding element. Null when not occluded.

samplePoints isOccluded topElement intersection

Best-effort selector hint for targeting this element (prefers data-testid/data-selector/id).

Subset of computed CSS styles for the element as string key-value pairs.

Short preview of rendered text content or aria-label, truncated to the configured maximum length.

Raw AX value payload associated with the node, if present.

axNodeId parentAxNodeId childAxNodeIds role name ignored backendDOMNodeId domNodeId frameId localName id className selectorHint textPreview properties

The document title of the page at the time of the snapshot.

Indicates whether the result set was truncated by an internal safety cap to prevent excessive output size.

The current page URL at the time the AX snapshot was captured.

url title axNodeCount candidateCount enrichedCount truncatedBySafetyCap nodes

Gets the HTML content of the current page.
By default, all <script> tags are removed from the output unless "removeScripts" is explicitly set to "false".

Selector or ref; omit for full document.

The requested HTML content of the page.

Gets the visible text content of the current page.

Truncate after this many characters.

Limit text to this container; omit for full page.

The requested text content of the page.

Saves the current page as a PDF file.

Page size.

Margin (e.g. 1cm).

Background.

Full path of the saved PDF file.

Starts video recording of the browser page.
Recording captures all page interactions until content_stop-recording is called.
Uses Playwright's native screencast API — works in all modes (headless, headed, persistent, CDP attach).
Only supported on Chromium-based browsers.

Name for the video file (without extension). Defaults to "recording".

Directory where the video file will be saved.

Status message.

Wall-clock time (ms since epoch) of the video's first frame. Use this to align video time with other timestamps (logs, network events). A given event's position in the video is `(eventTimestampMs - startTimestamp) / 1000` seconds.

Stops video recording of the browser page and saves the video file.
Must be called after content_start-recording. The video is saved as a WebM file.

Full path of the saved video file.

Takes a screenshot of the current page or a specific element.
Do NOT use for page structure—use ARIA/AX snapshots instead.
Use only for visual verification (design check, visual bug, contrast, layout).
Screenshot is saved to disk; use includeBase64 only when the file cannot be read from the returned path (e.g. remote, container).

Overlay ARIA ref labels.

Annotate headings.

Annotate cursor:pointer elements.

Base64 fallback.

JPEG quality 0–100.

Selector/ref; omit=viewport.

When annotate is true, list of refs and bounding boxes. When selector is set: only annotations overlapping the element, box relative to that element. When fullPage is true: box is document-relative (matches the full-page image). Otherwise: viewport-relative.

Full path of the saved screenshot file.

Image data included only when "includeBase64" input parameter is set to true.

Base64-encoded image data.

MIME type of the image.

Adds a watch expression to be evaluated at every breakpoint hit.
Watch expression results are included in the snapshot's watchResults field.

Examples:
- "user.name"
- "this.state"
- "items.length"
- "JSON.stringify(config)"

Watch expressions are evaluated in the context of the paused frame.

Expression evaluated at every tracepoint hit (e.g. user.name).

The watch expression

Watch expression ID

Status message

Clears snapshots captured by tracepoints, logpoints, and/or exceptionpoints.
Optional `types`: array of `tracepoint`, `logpoint`, `exceptionpoint`. If omitted or empty, clears all.
Optional `probeId`: clear only snapshots for this probe (for tracepoint/logpoint).

Clear only this probe (tracepoint/logpoint).

Clear only these types; omit for all.

Exceptionpoint snapshots cleared

Logpoint snapshots cleared

Status message

Tracepoint snapshots cleared

tracepointCleared logpointCleared exceptionpointCleared message

Removes tracepoints, logpoints, and/or watch expressions. Optional `types`: array of `tracepoint`, `logpoint`, `watches`. If omitted or empty, clears all.

Which probe types to clear: tracepoint, logpoint, watches. If omitted or empty, all are cleared.

Number of logpoints cleared

Status message

Number of tracepoints cleared

Number of watch expressions cleared

tracepointsCleared logpointsCleared watchesCleared message

Retrieves snapshots captured by tracepoints, logpoints, and/or exceptionpoints.
Optional `types`: array of `tracepoint`, `logpoint`, `exceptionpoint`. If omitted or empty, returns all.
Response fields: `tracepointSnapshots`, `logpointSnapshots`, `exceptionpointSnapshots`.
Optional `probeId` filters tracepoint or logpoint snapshots; `fromSequence` and `limit` apply per type.
Output trimming: by default only the top 5 call stack frames are returned, only `local` scope(s) are included, and variables per scope are capped at 20. Override with maxCallStackDepth, includeScopes, maxVariablesPerScope.

Snapshots with sequence > this (polling).

Scope types to include. Default [local] (local only to keep payload small).

global local with closure catch block script eval module wasm-expression-stack

Max call stack frames per snapshot. Default 5.

Max variables per scope. Default 20.

Filter by this probe ID (tracepoint/logpoint).

Return only these types; omit for all.

Exceptionpoint snapshots

Async stack trace

Call stack at exception

Exception information

Exception message

Exception name/class

Stack trace string

Exception type

Watch expression results

id probeId timestamp sequenceNumber url lineNumber captureTimeMs callStack

Logpoint snapshots

Result of log expression evaluation

id probeId timestamp sequenceNumber url lineNumber captureTimeMs

Tracepoint snapshots

Async stack trace

Chain of async segments

Frames in this segment

1-based column number

Function name

1-based line number

Original source location

Script URL

Async boundary (Promise.then, setTimeout, etc.)

Call stack with local variables

1-based column number

Function name

1-based line number

Original source location

Variable scopes

Scope name

Scope type (global, local, closure, etc.)

Variables in this scope

Variable name

Variable type

Variable value

V8 script ID

Script URL

functionName url lineNumber scriptId scopes

Time taken to capture snapshot (ms)

1-based column number

Snapshot ID

1-based line number

Original source location

1-based column number

1-based line number

Original identifier name

Original source file path

Probe ID that triggered this snapshot

Monotonic sequence number for ordering

Unix timestamp (ms)

Script URL where snapshot was taken

Watch expression results

Lists tracepoints, logpoints, and/or watch expressions. Optional `types`: array of `tracepoint`, `logpoint`, `watch`. If omitted or empty, returns all.

List only these types; omit for all.

Logpoints

id urlPattern lineNumber logExpression enabled resolvedLocations hitCount

Tracepoints

id urlPattern lineNumber enabled resolvedLocations hitCount

Watch expressions

Sets the exception tracepoint state:
- "none": Don't capture on exceptions
- "uncaught": Capture only on uncaught exceptions
- "all": Capture on all exceptions (caught and uncaught)

When an exception occurs, a snapshot is captured with exception details.

Current state

Status message

Previous state

Puts a logpoint at the specified location.
When the logpoint is hit, the logExpression is evaluated and the result
is captured in the snapshot's logResult field.

Logpoints are lightweight - they only capture the log expression result,
NOT call stack or watch expressions. Use tracepoints for full debug context.

urlPattern matches script URLs (e.g., "app.js"). Auto-escaped, do not add backslashes.

logExpression: a single JavaScript expression (e.g. "user.name", "JSON.stringify({ a, b })", or "{ discountAmount, finalAmount, n }"). Object literals are supported; for maximum compatibility prefer a single variable or JSON.stringify(...).

Returns resolvedLocations: 0 means pattern didn't match any loaded scripts.

1-based column.

Only log when this expression is true.

Hit-count condition (e.g. > 5).

1-based line in script.

JS expression to evaluate and log (e.g. user.name, JSON.stringify({ a, b }), or { x, y }).

Glob pattern for script URL (e.g. **/app.js).

Column number

Condition expression

Hit count condition

Debug point ID

Line number

Log expression

Number of locations where logpoint was resolved

URL pattern

id urlPattern lineNumber logExpression resolvedLocations

Puts a non-blocking tracepoint at the specified location.
When hit, a snapshot of the call stack and local variables is captured
automatically without pausing execution.

The urlPattern matches script URLs. Special characters are auto-escaped.
Examples:
- "app.js" matches scripts containing "app.js"
- "bundle.min.js" matches scripts containing "bundle.min.js"

DO NOT escape characters yourself (e.g., don't use "app\.js").

Returns resolvedLocations: number of scripts where the tracepoint was set.
If 0, the pattern didn't match any loaded scripts.

1-based column.

Only trigger when this expression is true.

Hit count (e.g. == 5, >= 10, % 10 == 0).

1-based line.

Column number

Condition expression

Hit count condition

Tracepoint ID

Line number

Number of locations where tracepoint was resolved

URL pattern

id urlPattern lineNumber resolvedLocations

Removes a tracepoint, logpoint, or watch expression by ID.
`type`: `tracepoint`, `logpoint`, or `watch`. `id`: the probe or watch ID (from list-probes).

Probe or watch ID from list-probes.

Status message

Whether the probe or watch was removed

Resolves a generated/bundled code location to its original source via source maps.
Useful for translating minified stack traces or bundle line numbers to original TypeScript/JavaScript source.

Requires a page with debugging context (debugging is auto-enabled on first use).
Input: generated script URL, line, column (1-based).
Output: original source path, line, column when a source map is available.

1-based column; default 1.

1-based line in generated code.

Generated script URL (bundle).

Column number in original source (1-based)

Line number in original source (1-based)

Original identifier name if available

Whether the location was resolved to original source

Original source file path

Returns the current debugging status including:
- Whether debugging is enabled
- Source map status
- Exceptionpoint state
- Count of tracepoints, logpoints, and watches
- Snapshot statistics

Whether debugging is enabled

Exceptionpoint state (none, uncaught, all)

Whether source maps are loaded

Number of logpoints

Snapshot statistics

Number of tracepoints

Number of watch expressions

enabled hasSourceMaps exceptionBreakpoint tracepointCount logpointCount watchExpressionCount snapshotStats

execute

Batch-execute multiple tool calls in a single request via custom JavaScript. Reduces round-trips and token usage.

**IMPORTANT**
- The code is already run inside an async function. Pass only the body (statements).
  Do NOT wrap in `async function() { ... }` or `async () => { ... }` — that causes a syntax error.
  Write `await callTool(...); return x;` directly.

**IMPORTANT:**
- `page` (Playwright Page) is available in the VM — use it for navigation or `page.evaluate()`.
- Prefer interaction tools with refs (e1, e2 from a11y_take-aria-snapshot); use raw Playwright only as last resort.
- `document`/`window` are not in the VM — use `page.evaluate(() => { ... })` to run code in the browser.
- Use `waitForNavigation: true` on interaction_click when the click navigates.
- After navigation, do not continue with refs from the previous page — take fresh refs with a11y_take-aria-snapshot first.

Bindings:
- await callTool(name, input, returnOutput?): async — always use with await. Returns the tool output for in-code use.
  Every callTool invocation is listed in the response toolCalls array (name, in order), whether or not returnOutput is set.
  returnOutput=true additionally attaches that call's full output to its toolCalls entry; false (default) lists the call by name only.
  Throws on failure — execution stops at the first error; calls that ran before the failure are still listed in toolCalls (partial), with logs.
  On failure, failedTool in the response identifies which tool caused the error.
  Max 50 callTool invocations per execution.
- console.log/warn/error: captured in the response logs array.
- sleep(ms): async delay.
- args: the parameterization object passed in the `args` input (default {}). Read values via plain JS, e.g. `const { baseUrl } = args;`.

Built-ins: Math, JSON, Date, RegExp, Number, String, Boolean, Array, Object, Promise, Map, Set, WeakMap, WeakSet,
           Symbol, Proxy, Reflect, URL, URLSearchParams, TextEncoder/Decoder, structuredClone,
           crypto.randomUUID(), AbortController, setTimeout/clearTimeout.
NOT available: require, import, process, fs, Buffer, fetch.

**Example** — fill form, submit (with navigation wait), then snapshot and screenshot:
  await callTool('interaction_fill', { selector: 'e3', value: 'user@test.com' });
  await callTool('interaction_fill', { selector: 'e5', value: 'secret123' });
  await callTool('interaction_click', { selector: 'e7', waitForNavigation: true });
  // Or with page.locator: await page.locator('button').click();
  // Or with page.evaluate: await page.evaluate(() => document.querySelector('button').click());
  await callTool('a11y_take-aria-snapshot', {}, true);
  await callTool('content_take-screenshot', {}, true);

Optional parameterization object exposed to the code as the `args` binding (default {}). Opaque — not validated. Read via plain JS, e.g. `const { baseUrl } = args;`.

JavaScript code: the body only (no async function wrapper). Use await callTool(name, input, returnOutput?) and return for result. Do NOT wrap in async function() { ... }.

Wall-clock timeout for the entire execution in ms, including awaited tool calls and sleep (default: 30000, max: 120000).

Error message on failure. Partial toolCalls/logs are still returned.

Present when a callTool invocation caused the error.

Error message from the failed tool.

Tool name that failed.

Captured console.log/warn/error calls.

Return value of the code (JSON-safe). Undefined on error or when nothing is returned.

Complete, ordered list of every nested callTool invocation. Each entry always has `name`; `output` is present only when the call used returnOutput=true; composite calls (scenario-run) expose the inner run as `children`.

Composite calls (scenario-run) expose the inner run's toolCalls here, recursively.

endTime - startTime (ms).

Epoch ms when the call settled.

Tool name (every nested call, in execution order).

Tool output — present only when callTool used returnOutput=true.

Epoch ms when the call started.

Clicks an element. Accepts selector or ref (e.g. e1, @e1). Set waitForNavigation: true when the click opens a new page — waits for navigation then for network idle so snapshot/screenshot see full content.

CSS selector or ref from a11y snapshot (e.g. e1, @e1).

Wait for element, ms. Default 10000.

Wait for navigation triggered by click (parallel with click). Use when click opens a new page.

Timeout for navigation and for network idle wait (ms). Only when waitForNavigation is true. Default 30000.

Drags an element to a target location. Accepts CSS selectors or refs (e.g. e1, @e1) from the last ARIA snapshot.

CSS selector or ref for the element to drag.

CSS selector or ref for the drop target.

Wait for elements, ms. Default 10000.

Fills out an input field. Accepts a CSS selector or a ref from the last ARIA snapshot (e.g. e1, @e1).

CSS selector or ref from a11y snapshot for the input.

Wait for element, ms. Default 10000.

Hovers an element on the page. Accepts a CSS selector or a ref from the last ARIA snapshot (e.g. e1, @e1).

CSS selector or ref from a11y snapshot.

Wait for element, ms. Default 10000.

Presses a keyboard key with optional "hold" and auto-repeat behavior.

Key facts:
- keyboard.press(key, { delay }) does NOT trigger OS-style auto-repeat.
- Some UI behaviors (especially scrolling) require repeated keydown events.
- Use repeat=true + holdMs to approximate real keyboard holding.

Execution logic:
- If selector is provided, the element is focused first.
- If holdMs is omitted or repeat=false:
  → a single keyboard.press() is executed.
- If holdMs is provided AND repeat=true:
  → keyboard.press() is called repeatedly until holdMs elapses.

Ms between keydown and keyup.

Key name (e.g. Enter, ArrowDown, Space).

Repeat key while holdMs (e.g. for scroll).

Focus this element first; omit for page focus.

Resizes the PAGE VIEWPORT using Playwright viewport emulation (page.setViewportSize).

This affects:
- window.innerWidth / window.innerHeight
- CSS media queries (responsive layouts)
- Layout, rendering and screenshots

Notes:
- This does NOT resize the OS-level browser window.
- Runtime switching to viewport=null (binding to real window size) is not supported by Playwright.
  If you need real window-driven responsive behavior, start the BrowserContext with viewport: null
  and use the window resize tool instead.

Requested viewport configuration.

Requested viewport height (CSS pixels).

Requested viewport width (CSS pixels).

Viewport metrics observed inside the page after resizing.

window.devicePixelRatio after resize.

window.innerHeight after resize (CSS pixels).

window.innerWidth after resize (CSS pixels).

window.outerHeight after resize (CSS pixels).

window.outerWidth after resize (CSS pixels).

innerWidth innerHeight outerWidth outerHeight devicePixelRatio

Resizes the REAL BROWSER WINDOW (OS-level window) for the current page using Chrome DevTools Protocol (CDP).

This tool works best on Chromium-based browsers (Chromium/Chrome/Edge).
It is especially useful in headful sessions when you run with viewport emulation disabled (viewport: null),
so the page layout follows the OS window size.

Important:
- If Playwright viewport emulation is enabled (viewport is NOT null), resizing the OS window may not change page layout.
- On non-Chromium browsers (Firefox/WebKit), CDP is not available and this tool will fail.

Required when state=normal.

When not normal, width/height may be ignored.

Required when state=normal.

Window bounds after resizing.

Window height after resizing.

Window left position after resizing.

Window state after resizing.

Window top position after resizing.

Window width after resizing.

CDP window id for the current target.

Window bounds before resizing.

Window height before resizing.

Window left position before resizing.

Window state before resizing.

Window top position before resizing.

Window width before resizing.

CDP window id for the current target.

Requested window change parameters.

Requested window height (pixels). Null if not provided.

Requested window state.

Requested window width (pixels). Null if not provided.

Page viewport metrics after resizing (helps verify responsive behavior).

window.devicePixelRatio after resizing.

window.innerHeight after resizing (CSS pixels).

window.innerWidth after resizing (CSS pixels).

window.outerHeight after resizing (CSS pixels).

window.outerWidth after resizing (CSS pixels).

Scrolls the page viewport or a specific scrollable element.

Modes:
- 'by': Scrolls by a relative delta (dx/dy) from the current scroll position.
- 'to': Scrolls to an absolute scroll position (x/y).
- 'top': Scrolls to the very top.
- 'bottom': Scrolls to the very bottom.
- 'left': Scrolls to the far left.
- 'right': Scrolls to the far right.

Use this tool to:
- Reveal content below the fold
- Jump to the top/bottom without knowing exact positions
- Bring elements into view before clicking
- Inspect lazy-loaded content that appears on scroll

by=dx,dy; to=x,y; or edge (top/bottom/left/right).

Scrollable container: ref (e.g. from latest <a11y_take-aria-snapshot>), getBy… expression, or CSS. Omit for viewport.

Scroll metrics after the scroll action.

Viewport/container client height after scrolling.

Viewport/container client width after scrolling.

Total scrollable height after scrolling.

Total scrollable width after scrolling.

ScrollLeft after scrolling.

ScrollTop after scrolling.

x y scrollWidth scrollHeight clientWidth clientHeight

Scroll metrics before the scroll action.

Viewport/container client height before scrolling.

Viewport/container client width before scrolling.

Total scrollable height before scrolling.

Total scrollable width before scrolling.

ScrollLeft before scrolling.

ScrollTop before scrolling.

The scroll behavior used.

Whether horizontal scrolling is possible (scrollWidth > clientWidth).

Whether vertical scrolling is possible (scrollHeight > clientHeight).

Whether the scroll position is at the very bottom.

Whether the scroll position is at the far left.

Whether the scroll position is at the far right.

Whether the scroll position is at the very top.

Maximum horizontal scrollLeft (scrollWidth - clientWidth).

Maximum vertical scrollTop (scrollHeight - clientHeight).

The scroll mode used.

The selector of the scroll container if provided; otherwise null (document viewport).

mode selector behavior before after canScrollX canScrollY maxScrollX maxScrollY isAtLeft isAtRight isAtTop isAtBottom

Select an option in a dropdown. Accepts a CSS selector or a ref from the last ARIA snapshot (e.g. e1, @e1).

CSS selector or ref from a11y snapshot for the dropdown.

Wait for element, ms. Default 10000.

Navigates to the previous or next page in history.
- `direction: "back"` — previous page in history.
- `direction: "forward"` — next page in history.

In case of multiple redirects, the navigation will resolve with the response of the last redirect.
If cannot go back/forward, returns empty response.

By default (includeSnapshot: true), an ARIA snapshot with refs is returned. Use `snapshotOptions` for `interactiveOnly` (default false) and `cursorInteractive` (default false), same as a11y_take-aria-snapshot.

When `includeScreenshot: true`, the screenshot is always saved to disk; `screenshotFilePath` is returned. By default `outputPath` is the OS temp dir and `name` is "screenshot" (same as content_take-screenshot). Use `screenshotOptions.includeBase64: true` only when the file cannot be read from the returned path (e.g. remote, container).

Take a screenshot after navigation; saved to disk (default: OS temp dir). Use includeBase64 only when file cannot be read from path.

Return ARIA snapshot with refs.

Options when includeScreenshot is true. Same semantics as <content_take-screenshot> (outputPath/name default to tmp and "screenshot").

Overlay ARIA ref labels on the screenshot. Default: true.

Capture full scrollable page. Default: true.

Include base64 image in response; use only when file cannot be read from path (e.g. remote, container).

Base name for the screenshot file. Default: "screenshot".

Directory to save the screenshot. Default: OS temp dir.

Image format. Default: png.

Options when includeSnapshot is true. Same as <a11y_take-aria-snapshot>.

Include cursor:pointer / onclick elements. Default false.

Only interactive elements get refs. Default false (content roles like headings also included).

Max wait ms. 0=no timeout.

Wait for navigation then for network idle before snapshot/screenshot. Default true.

Timeout for navigation and network idle wait (ms). Only when waitForNavigation is true. Default 30000.

Playwright navigation lifecycle: when the main frame reaches this state. Does not use Playwright networkidle; use waitForNavigation for session network-idle after history navigation.

When includeScreenshot and screenshotOptions.includeBase64 are true: image sent as separate image content part.

Base64-encoded image data.

MIME type of the image.

Contains a boolean stating whether the navigated page was successful (status in the range 200-299) or not.

When includeScreenshot is true: full path of the saved screenshot file.

Contains the status code of the navigated page (e.g., 200 for a success).

Contains the status text of the navigated page (e.g. usually an "OK" for a success).

Contains the URL of the navigated page.

Navigates to the given URL.
**NOTE**: The tool either throws an error or returns a main resource response.
The only exceptions are navigation to `about:blank` or navigation to the same URL with a different hash,
which would succeed and return empty response.

**By default** (`includeSnapshot: true`), an ARIA snapshot with refs is taken after navigation and returned in `output` and `refs`; you can use refs (e1, e2, ...) in interaction tools without calling a11y_take-aria-snapshot separately. Use `snapshotOptions` for `interactiveOnly` (default false) and `cursorInteractive` (default false). Set `includeSnapshot: false` to get only url/status/ok.

When `includeScreenshot: true`, the screenshot is always saved to disk; `screenshotFilePath` is returned. By default `outputPath` is the OS temp dir and `name` is "screenshot" (same as content_take-screenshot). Use `screenshotOptions.includeBase64: true` only when the file cannot be read from the returned path (e.g. remote, container).

Return ARIA snapshot with refs after nav.

Image format. Default: png.

Max wait ms. 0=no timeout.

Playwright navigation lifecycle: when the main frame reaches this state. Does not use Playwright networkidle; use waitForNavigation for session network-idle after navigation.

When includeScreenshot and screenshotOptions.includeBase64 are true: image sent as separate image content part.

Base64-encoded image data.

MIME type of the image.

Contains a boolean stating whether the navigated page was successful (status in the range 200-299) or not.

When includeSnapshot is true: page URL, title, and ARIA tree with refs.

When includeSnapshot is true: map of ref id (e1, e2, ...) to role/name/selector for use in interaction tools.

When includeScreenshot is true: full path of the saved screenshot file.

Contains the status code of the navigated page (e.g., 200 for a success).

Contains the status text of the navigated page (e.g. usually an "OK" for a success).

Contains the URL of the navigated page.

Reloads the current page.
In case of multiple redirects, the navigation resolves with the response of the last redirect.
If the reload does not produce a response, returns empty response.

By default (includeSnapshot: true), an ARIA snapshot with refs is returned. Use `snapshotOptions` for `interactiveOnly` (default false) and `cursorInteractive` (default false), same as a11y_take-aria-snapshot.

When `includeScreenshot: true`, the screenshot is saved to disk; `screenshotFilePath` is returned. Default path/name: OS temp dir and "screenshot" (same as content_take-screenshot). Use `screenshotOptions.includeBase64: true` only when the file cannot be read from the path.

Take a screenshot after reload; saved to disk (default: OS temp dir).

Return ARIA snapshot with refs.

Options when includeScreenshot is true. Same semantics as <content_take-screenshot> (outputPath/name default to tmp and "screenshot").

Overlay ARIA ref labels on the screenshot. Default: true.

Capture full scrollable page. Default: true.

Include base64 image in response; use only when file cannot be read from path (e.g. remote, container).

Base name for the screenshot file. Default: "screenshot".

Directory to save the screenshot. Default: OS temp dir.

Image format. Default: png.

Options when includeSnapshot is true. Same as <a11y_take-aria-snapshot>.

Include cursor:pointer / onclick elements. Default false.

Only interactive elements get refs. Default false (content roles like headings also included).

Max wait ms.

Wait for reload then for network idle before snapshot/screenshot. Default true.

Timeout for reload and network idle wait (ms). Only when waitForNavigation is true. Default 30000.

Playwright navigation lifecycle: when the main frame reaches this state. Does not use Playwright networkidle; use waitForNavigation for session network-idle after reload.

When includeScreenshot and screenshotOptions.includeBase64 are true: image sent as separate image content part.

Base64-encoded image data.

MIME type of the image.

Contains a boolean stating whether the reloaded page was successful (status in the range 200-299) or not.

When includeScreenshot is true: full path of the saved screenshot file.

Contains the status code of the reloaded page (e.g., 200 for a success).

Contains the status text of the reloaded page (e.g. usually an "OK" for a success).

Contains the URL of the reloaded page.

Retrieves console messages/logs from the browser with filtering options.

Keep from start or end when truncating.

Filter by message text.

Incremental: only messages with sequence > this.

Only messages at or after this Unix ms.

Filter by level (this level or higher).

Retrieved console messages.

Console message item.

Location of the console message in the resource.

0-based column number in the resource.

0-based line number in the resource.

URL of the resource.

A monotonically increasing sequence number assigned to each console message.
It reflects the order in which messages were captured and can be used by clients
to retrieve messages incrementally by requesting only those with a higher sequence
number than the last one received.

Text of the console message.

Unix epoch timestamp (in milliseconds) of the console message.

Type of the console message.

Retrieves HTTP requests from the browser with filtering options.

Include request headers in each item. Default false.

Include response body in each item. Default false.

Include response headers in each item. Default false.

Keep from start or end when truncating.

2xx only.

Type filter.

document stylesheet image media font script texttrack xhr fetch eventsource websocket manifest other

Incremental: only requests with sequence > this.

HTTP status range.

Only requests at or after this Unix ms.

Retrieved HTTP requests.

HTTP request item.

HTTP request body if available. Secret JSON keys are redacted; truncated to BROWSER_HTTP_CAPTURE_BODY_MAX_BYTES.

HTTP request duration in milliseconds. "-1" if not available (no response).

Error message of the HTTP request if failed.

HTTP request headers as key-value pairs. Present when includeRequestHeaders was true.

HTTP request method. Valid values are: GET,POST,PUT,PATCH,DELETE,HEAD,OPTIONS

Flag to represent whether the HTTP request successful or failed.
An HTTP request is considered successful only if its status code is 2XX.
Otherwise (non-2XX status code or no response at all because of timeout, network failure, etc ...) it is considered as failed.

HTTP request resource type as it was perceived by the rendering engine.
Valid values are: document,stylesheet,image,media,font,script,texttrack,xhr,fetch,eventsource,websocket,manifest,other

HTTP response.

HTTP response body if available. Present when includeResponseBody was true. Secret JSON keys are redacted; truncated to BROWSER_HTTP_CAPTURE_BODY_MAX_BYTES.

HTTP response headers. Present when includeResponseHeaders was true.

HTTP response status code.

HTTP response status text.

A monotonically increasing sequence number assigned to each HTTP request.
It reflects the order in which requests were captured and can be used by clients
to retrieve requests incrementally by requesting only those with a higher sequence
number than the last one received.

Unix epoch timestamp (in milliseconds) of the HTTP request.

HTTP request url.

url method resourceType timestamp sequenceNumber

Returns the session's currently pinned W3C trace context: the pinned `traceId` / `traceState` (each
present only when set — a trace is pinned iff at least one is returned). Pin one with <o11y_new-trace-id>
or <o11y_set-trace-context>.

Pinned W3C trace id, when set.

Pinned W3C tracestate, when set.

Collects Web Vitals (LCP, INP, CLS, TTFB, FCP) with Google thresholds and recommendations.
Call after navigation or user actions; use waitMs for more stable LCP/CLS/INP.
Some metrics may be unavailable depending on browser and interactions.

Include entry counts and LCP element hint.

Ms to wait before reading (e.g. let LCP settle).

Optional debug details.

Counts of PerformanceEntry types used to compute metrics.

Count of event timing entries.

Count of layout-shift entries.

Count of largest-contentful-paint entries.

Count of navigation entries.

Count of paint entries.

navigation paint lcp layoutShift eventTiming

Best-effort selector hint for the last LCP element (if available).

Tag name of the last LCP element (if available).

Actual wait duration used before reading metrics.

waitMs entries lastLcpSelectorHint lastLcpTagName

Raw metric values (null if unavailable).

Cumulative Layout Shift score.

First Contentful Paint in milliseconds.

Interaction to Next Paint in milliseconds (best-effort approximation).

Largest Contentful Paint in milliseconds.

Time to First Byte in milliseconds.

Notes about metric availability, browser limitations, and interpretation.

Ratings computed from Google thresholds.

CLS rating.

FCP rating.

INP rating.

LCP rating.

Rating based on Google thresholds.

Thresholds used for rating.

Upper bound for the "good" rating.

Lower bound for the "poor" rating.

Unit of the metric.

Metric value (null if unavailable).

TTFB rating.

Recommendations based on the measured values and their ratings.

Recommendations for improving CLS.

True if all Core Web Vitals are rated "good".

Recommendations for improving FCP.

General measurement and debugging notes.

Recommendations for improving INP.

Recommendations for improving LCP.

High-level summary and prioritization guidance.

Recommendations for improving TTFB.

coreWebVitalsPassed summary lcp inp cls ttfb fcp general

Unix epoch timestamp (ms) when the metrics were captured.

Current page title.

Current page URL.

url title timestampMs metrics ratings recommendations notes

Generates a fresh W3C / OpenTelemetry-compatible trace id (32 hex chars) and pins it on the session so
subsequent calls share one correlation root — the platform propagates it into outgoing requests. Use
<o11y_set-trace-context> to pin a specific id / tracestate, or <o11y_get-trace-context> to inspect the
current pin.

The newly generated, now-pinned 32-hex W3C trace id.

Sets or clears the session-pinned W3C trace context. Two independent slots:

  - `traceId`: hex string up to 32 chars (short ids are zero-padded by the platform). Empty string clears
    the pinned trace id. Must not be all-zero.
  - `traceState`: opaque W3C `tracestate` value (comma-separated key=value list). Empty string clears.

At least one of `traceId` / `traceState` must be supplied; omitted fields are left untouched. Use
<o11y_new-trace-id> to generate one, or <o11y_get-trace-context> to inspect the current pin.

Hex string up to 32 chars to pin, or empty string to clear. Omit to leave unchanged.

W3C tracestate value to pin, or empty string to clear. Omit to leave unchanged.

The resulting pinned trace id (post-set), if any.

The resulting pinned tracestate (post-set), if any.

Finds React component(s) for a DOM element via React Fiber (best-effort). Give selector or (x,y); we resolve the element,
find __reactFiber$ on it or ancestors, then build the component stack from the host fiber that owns that node.
Fiber is not a public API—results vary by dev/prod build; names can be displayName, wrappers, or minified.
wrappersDetected/wrapperFrames help with memo/forwardRef/context. If hostMapping.strategy is ancestor-fallback,
use a more specific selector or deeper node for better accuracy.

If true, includes a best-effort, truncated props preview for the nearest component.

Maximum characters for props preview (after safe stringification).

Target element; takes precedence over x/y.

Viewport X when selector omitted.

Viewport Y when selector omitted.

DOM hint of the element where fiber pointer was found (target or ancestor).

Whether the initial fiber pointer was found directly on the target element.

Whether we found the exact host fiber for target element (fiber.stateNode === targetEl) via subtree scan.

Mapping strategy used to produce the final stack.

Maximum fiber nodes allowed to scan (safety cap).

Number of fiber nodes scanned during subtree search.

DOM hint of the actual target element.

fiberOnTargetElement anchorDomHint targetDomHint hostFiberMatchedTarget subtreeScanNodesScanned subtreeScanMaxNodes strategy

detected detectionReason fiberKey hostMapping nearestComponent componentStack componentStackText wrappersDetected wrapperFrames notes

selector point found domHint elementPath

Maps a React component instance to the DOM elements it renders (DOM footprint) by traversing the Fiber graph.
Prefer an anchor (anchorSelector or anchorX/anchorY) to target the instance; optionally add a query
(componentName, fileNameHint, lineNumber) to search Fiber. With both, we rank candidates and pick the best match near the anchor.
React DevTools hook gives reliable root discovery (getFiberRoots); without it we fall back to DOM scan for __reactFiber$ (best-effort).
For more reliable roots in a persistent browser, install the React Developer Tools Chrome extension.
Debug source is best-effort and may be missing in some builds.

Anchor selector/ref.

Viewport X when anchorSelector omitted.

Viewport Y when anchorSelector omitted.

File hint.

Ranked candidate matches (best-first).

score nameMatched debugSourceMatched anchorRelated

name displayName debugSource componentStack selection domFootprintCount

name displayName debugSource componentStack selection

tagName id className selectorHint textPreview boundingBox isVisible isInViewport

True if DOM appears to contain React Fiber pointers (__reactFiber$...).

True if __REACT_DEVTOOLS_GLOBAL_HOOK__ looks available.

How roots were discovered.

reactDetected fiberDetected rootDiscovery component candidates elements notes

scenario-add

Adds a new scenario. A scenario is a reusable JS script (like execute) that can call tools via callTool().
Scenarios are stored on disk as one file per scenario (project-level by default, or global with scope="global").
Optionally declare a params contract (name + optional description/type/default/example/required): the script reads each param via the args binding, defaults are applied when a run omits the arg, and declared types are shallow-validated by <scenario-run>. Without params, args stays fully opaque.
An optional free-form metadata object is persisted and returned verbatim (devtools never interprets it).
The store also stamps createdAt / updatedAt timestamps automatically.

Description of what this scenario does.

Opaque free-form metadata, persisted and returned verbatim (devtools never interprets it). On update it replaces the stored metadata wholesale when provided; omit to keep the existing value.

Unique scenario name (used as key).

Optional declared parameter contract. Each entry: name (the arg key) plus optional description/type/default/example/required. Defaults are applied when the caller omits an arg; a required param with no value and no default rejects the run; object/array are shallow-validated (kind only). On update, a provided array replaces the stored one wholesale; omit to keep the existing params. Declaring params is opt-in — a scenario with no params keeps fully-opaque args passthrough.

Applied when the caller omits this arg; for object/array it also doubles as the concrete shape example.

Documentation-only concrete example (never validated/injected).

Arg key read inside the script.

Reject the run when no value and no default. Default false.

Declared kind (string/number/boolean/object/array). Absent → no type check. object/array are shallow-validated (top-level kind only).

Storage scope (default: project).

JavaScript code to execute. Same sandbox as <execute>: use await callTool(name, input, returnOutput?) to invoke tools.

Arg key read inside the script.

name description script createdAt updatedAt

scenario-delete

Deletes a scenario by name.

Name of the scenario to delete.

Storage scope (default: project).

Whether the scenario was found and deleted.

scenario-list

Lists scenarios. When scope is omitted, returns scenarios from both project and global scopes (project overrides global for same name).
Optionally filter by metadataMatch: a subset/containment filter over the opaque metadata (a partial template the stored metadata must contain). Objects match recursively (extra sibling keys are ignored), arrays require the stored array to contain all listed elements, a scalar against a stored array uses membership, and scalars use equality. Keys are never interpreted (devtools-agnostic). Use this to find scenarios by what they cover, e.g. metadataMatch={"ironbee":{"coveredPaths":["src/auth/login.ts"]}}.

Subset/containment filter over the opaque metadata — a partial template the stored metadata must contain. Objects match recursively (a query key must exist; extra sibling keys are ignored), so { "ironbee": { "coveredPaths": ["src/auth/login.ts"] } } matches metadata that also has other ironbee.* keys. Arrays require the stored array to contain all listed elements; a scalar against a stored array uses membership; scalars use equality. All top-level keys must match (AND); keys are never interpreted. Omit for no filter.

Filter by scope. Omit to list from both (project overrides global).

Arg key read inside the script.

scenario-run

Runs a saved scenario by name. Looks up the scenario in project scope first, then global.
The scenario's JS script runs in the same sandbox as execute: callTool(), console, sleep, and args are available.
Pass optional args to parameterize the run (base URL, test user, record id, …); the script reads them via the args binding (default {}), e.g. const { baseUrl } = args;.
If the scenario declares params, args is validated against them: declared defaults fill omitted args, required params with no value reject the run, and declared types are shallow-checked. Undeclared args (and scenarios without any params) pass through unchanged.
For CLI ergonomics you can also pass repeatable key=value pairs via param (the --param flag) instead of hand-writing args JSON; each value is coerced to the matching declared param's type and merged over args (param overrides args per key).
Scenarios can compose other scenarios via callTool('scenario-run', { name: '...', args: { ... } }).
Max recursion depth: 5.

Optional parameterization exposed to the scenario script as the `args` binding (default {}). Validated against the scenario's declared params when it has any (defaults applied, required enforced, declared types shallow-checked); otherwise passed through opaquely. Read via plain JS, e.g. `const { baseUrl } = args;`.

Name of the scenario to run.

CLI ergonomics: repeatable key=value pairs (the --param flag). Each value is coerced to the matching declared param type and merged over `args` (param overrides args per key). Prefer `args` over MCP; use this from the CLI to avoid hand-writing --args JSON.

Wall-clock timeout in ms (default: 30000).

Arg key read inside the script.

Complete, ordered list of every nested call the scenario made (from the delegated execute). Each entry always has `name`; `output` only when returnOutput=true; composite calls expose the inner run as `children`.

Composite calls (scenario-run) expose the inner run's toolCalls here, recursively.

endTime - startTime (ms).

Epoch ms when the call settled.

Tool name (every nested call, in execution order).

Tool output — present only when callTool used returnOutput=true.

Epoch ms when the call started.

scenario-search

Full-text search over scenario name + description across both project and global scopes.
Uses configurable search strategy (SEARCH_STRATEGY or SCENARIO_SEARCH_STRATEGY env var).
Returns matching scenarios (including their metadata) ranked by relevance.
Optionally narrow the corpus with metadataMatch (subset/containment over the opaque metadata) before ranking — e.g. text-search only among scenarios that cover a given path. For a pure metadata lookup with no text query, use scenario-list with metadataMatch.

Maximum number of results (default: 10).

Search query.

Arg key read inside the script.

name description script createdAt updatedAt score

scenario-update

Updates an existing scenario's description, script, params, and/or metadata.
Params and metadata write semantics are shallow replace: when an array/object is provided it replaces the stored one wholesale; omit it to keep the current value. The store refreshes updatedAt automatically.

New description (omit to keep current).

Name of the scenario to update.

Applied when the caller omits this arg; for object/array it also doubles as the concrete shape example.

Documentation-only concrete example (never validated/injected).

Arg key read inside the script.

Reject the run when no value and no default. Default false.

Declared kind (string/number/boolean/object/array). Absent → no type check. object/array are shallow-validated (top-level kind only).

Storage scope (default: project).

New script (omit to keep current).

Arg key read inside the script.

Clears stubs installed.

- If stubId is provided, clears only that stub.
- If stubId is omitted, clears all stubs for the current session/context.

Remove this stub; omit to clear all.

Number of stubs removed.

Installs a request interceptor stub that can modify outgoing requests before they are sent.

Use cases:
- A/B testing / feature flags (inject headers)
- Security testing (inject malformed headers / payload)
- Edge cases (special characters, large payload)
- Auth simulation (add API keys / tokens in headers)

Notes:
- pattern is a glob matched against the full request URL (picomatch).
- This modifies requests; it does not change responses.
- times limits how many times the interceptor applies (-1 means infinite).

Changes to apply to the request.

Override method (e.g. GET, POST).

URL glob (picomatch).

Max applications; -1 = infinite.

Applied artificial delay in milliseconds.

Whether the stub is enabled.

Stub kind.

Glob pattern.

Unique id of the installed stub.

Max applications (-1 means infinite).

stubId kind pattern enabled delayMs times

Lists currently installed stubs for the active browser context/session.
Useful to debug why certain calls are being mocked/intercepted.

For mock_response: fulfill/abort.

Artificial delay in ms.

Whether stub is enabled.

Stub id.

Stub kind.

Glob pattern (picomatch).

For mock_response: HTTP status (if set).

Max applications (-1 means infinite).

How many times it has been applied.

id kind enabled pattern delayMs times usedCount

Installs a response stub for matching requests using glob patterns (picomatch).

Use cases:
- Offline testing (return 200 with local JSON)
- Error scenarios (force 500/404 or abort with timedout)
- Edge cases (empty data / huge payload / special characters)
- Flaky API testing (chance < 1.0)
- Performance testing (delayMs)

Notes:
- pattern is a glob matched against the full request URL.
- stubs are evaluated in insertion order; first match wins.
- times limits how many times the stub applies (-1 means infinite).

Probability 0–1; omit=always.

URL glob.

Response.

Error code when action=abort.

Max times to apply; -1=infinite.

Applied action.

Apply probability (omit means always).

Whether the stub is enabled.

Stub kind.

Glob pattern.

HTTP status (present when action=fulfill).

Unique id of the installed stub (use it to clear later).

Max applications (-1 means infinite).

stubId kind pattern enabled delayMs times action

Waits until the page is network-idle: in-flight requests <= maxConnections for at least idleTimeMs (server-side tracking, no page globals).
Use before SPAs, screenshots, or AX snapshots for stable results. With long-polling, increase maxConnections or use shorter idleTimeMs.

Network must stay idle for this many ms to resolve.

Idle when in-flight requests <= this.

Polling interval ms.

Max wait ms before failing.

The last observed number of in-flight requests at the moment the tool returned.

Idle duration required for success (milliseconds).

Idle threshold used: in-flight requests must be <= this value.

How long the in-flight request count stayed <= maxConnections right before returning (milliseconds).

Polling interval used to sample the in-flight request count (milliseconds).

Maximum allowed wait time (milliseconds).

Total time waited until the network became idle or the tool timed out (milliseconds).

waitedMs idleTimeMs timeoutMs maxConnections pollIntervalMs finalInFlightRequests observedIdleMs