Top Chrome main-thread tasks by wall duration: id, name, task_type, thread_name, process_name, dur_ms, cpu_pct (thread_dur/dur), thread_dur_ms. Uses chrome.tasks and thread.is_main_thread = 1 (tid == pid per Linux convention).

Use when: investigating main-thread responsiveness, finding hot tasks during scroll/load, comparing CPU vs wall time, scoping to one renderer in multi-renderer traces.

Don't use for: non-Chrome traces (will error). For background (non-main) thread tasks, drop to execute_sql against chrome.tasks directly.

Parameters (all optional):

• process_name / pid / upid: scope to one process or process type. process_name='Renderer' shows all renderers together; pid is the OS pid (visible in Task Manager but can be recycled mid-trace); upid is the trace-internal unique pid (always precise — prefer over pid for multi-renderer traces). Look up both via list_processes. All AND when set; redundant pairings (e.g. matching upid + pid) are harmless.

• min_dur_ms: minimum task duration. Defaults to 16 (one 60 Hz frame). Pass 0 for ALL tasks; raise to 33 (30 Hz) or 100 to focus on bigger stutters.

• limit: max rows (default 100, capped at 5000). Must be > 0 if set.

Empty result: either no main-thread tasks exceeded min_dur_ms (good performance at that threshold), or thread metadata is incomplete (is_main_thread is NULL). If the latter is suspected, retry with execute_sql filtering on thread_name IN ('CrBrowserMain', 'CrRendererMain') to bypass the is_main_thread filter.

Summarize each page navigation in a Chrome trace: navigation id, URL, FCP / LCP / DCL / load timings in ms. Read-only.

Use when: comparing page-load timings across navigations, finding slow loads, baselining web-vitals before/after a change. Prefer over hand-joining chrome.page_loads — schema is already correct.

Don't use for: non-Chrome traces (will error). For sub-event timings inside one navigation, drop to execute_sql against the chrome.page_loads module.

Parameters: none — operates on the loaded trace.

Empty result: no navigations occurred during capture (e.g. trace started after the page was already loaded).

Summarize the worst scroll jank frames in a Chrome trace: cause_of_jank, sub_cause_of_jank, delay_since_last_frame, event_latency_id, scroll_id, vsync_interval. One row per janky frame, sorted by delay_since_last_frame DESC, limit 100. Read-only.

Use when: investigating jank reports, finding scroll regressions, ranking jank causes. Prefer over hand-rolling SQL on chrome.scroll_jank.scroll_jank_v3 — same data, less code.

Don't use for: non-Chrome traces (will error). For per-frame causes outside the top 100, drop to execute_sql against the same view.

Parameters: none — operates on the loaded trace.

Empty result: no janky frames detected (clean trace) or no scrolls occurred during capture.

Summarize Chrome browser startup events: id, name, launch_cause, startup_duration_ms (first_visible_content_ts - startup_begin_ts), browser_upid. Read-only.

Use when: measuring time-to-first-visible-content for cold starts, comparing launch causes (NEW_WINDOW vs CMD_LINE vs RESTORE_SESSION), regressing startup performance.

Don't use for: non-Chrome traces (will error). Browser-process work during steady state is covered by chrome_main_thread_hotspots.

Parameters: none — operates on the loaded trace.

Empty result: trace started after the browser was already running (most cases — startup is captured only when tracing began before launch).

Rank web content interactions in a Chrome trace by duration: id, ts, dur_ms, interaction_type, renderer_upid. Sorted by dur_ms DESC, limit 100. Read-only.

Use when: INP (Interaction to Next Paint) analysis, reproducing user-felt latency, finding slow click/tap/keyboard handlers.

Don't use for: non-Chrome traces (will error). For interactions outside the top 100 or filtered by interaction_type, drop to execute_sql against chrome.web_content_interactions.

Parameters: none — operates on the loaded trace.

Empty result: no interactions captured (trace started before user input or interaction tracking was disabled in tracing config).

Run a PerfettoSQL query against the loaded trace and return rows as columnar JSON. Read-only against trace data; SQLite operates in-memory per session. Aggregates are strongly preferred over raw row data; results are capped at 5000 rows.

Use when: composing analyses not covered by the dedicated tools — custom aggregations, joins across stdlib modules, or queries against base tables (slice, thread, process, sched).

Don't use for: questions the dedicated chrome_* tools answer — they return the same data with the JOIN shape already correct. Don't hand-roll slice scans with LIKE '%x%' patterns when a stdlib module covers the data; INCLUDE PERFETTO MODULE chrome.tasks is faster and the joins are pre-baked.

Parameters: sql is a single PerfettoSQL statement (the INCLUDE PERFETTO MODULE foo; and SELECT ... can be in the same call). Requires load_trace to have run first.

Empty rows means the query matched nothing — distinct from a SQL error, which is returned as an error string with a hint pointing at the most likely cause (missing module, missing column, missing table).

Reference docs (fetch when you need exact column names or function signatures): https://perfetto.dev/docs/analysis/stdlib-docs (24 stdlib packages — chrome / android / sched / slices / linux / wattson / v8 / ...; use per-package anchors like #package-chrome), https://perfetto.dev/docs/analysis/perfetto-sql-syntax (syntax).

List every process captured in the trace: upid (trace-internal id), pid (OS pid), name, start_ts, end_ts. Read-only.

Use when: entry point for Android and Linux trace analysis, or picking the right pid/upid to feed into list_threads_in_process or chrome_main_thread_hotspots.

Don't use for: Chrome traces — the dedicated chrome_* tools answer most common questions without process-level navigation.

Parameters: none — operates on the loaded trace.

Empty result: rare; would mean the trace captured no process metadata at all.

Errors when: no trace is loaded — call load_trace first.

List a curated set of PerfettoSQL stdlib modules. Returns a JSON array — each entry has module (the value for INCLUDE PERFETTO MODULE), domain (chrome / android / generic), views, description, and an illustrative usage query.

Use when: exploring what's available before writing SQL against an unfamiliar trace type, or discovering modules outside the dedicated chrome_* tools (memory, sched, wattson, v8, etc.). Call this before load_trace if you want to scope your analysis upfront — no trace needs to be loaded.

Don't use for: discovering all stdlib modules — this is a curated subset of the most useful ones. The exhaustive list lives at https://perfetto.dev/docs/analysis/stdlib-docs.

Parameters: none.

Then use execute_sql with INCLUDE PERFETTO MODULE <module>; SELECT ... (both can be in one call). If PERFETTO_TP_PATH points to a custom binary, some modules may not exist in that version — verify column names with list_table_structure if a query fails.

Show the columns of a table or view: name, type, nullability, primary-key flag.

Use when: writing or debugging a query — call this immediately after a no such column error to inspect the actual schema rather than guessing. Both stdlib views and base tables have fixed schemas; don't infer columns by analogy across them.

Don't use for: this is a separate MCP tool, not a SQL function — don't write SELECT * FROM list_table_structure inside execute_sql.

Parameters: table_name (string) — the exact table or view name as it appears in list_tables output. Case-sensitive; does not accept GLOB patterns or partial matches. Also accepts the alias name (v0.11.3+).

Errors when: the table doesn't exist or has no columns. Call list_tables first if uncertain about the name.

List tables and views in the loaded trace. Read-only.

Use when: exploring an unfamiliar trace or verifying a table exists before writing SQL. Underlying SQL engine is SQLite, so the catalog tables common in other SQL engines aren't present — this MCP tool is the schema introspection path.

Don't use for: queries against known stdlib modules — go straight to execute_sql with INCLUDE PERFETTO MODULE. Don't reference this tool name inside SQL; it's a separate MCP tool, not a SQL function — call it via the tool API.

Parameters: optional pattern — SQLite GLOB filter (e.g. chrome_* for chrome stdlib views, slice* for the slice table family). Without it, internal stdlib tables (_*) are hidden.

Empty result: no tables matched the pattern. If a doc-listed table is missing, retry with an explicit pattern in case it's marked internal.

Errors when: no trace is loaded — call load_trace first.

List threads inside one process: tid, thread_name, pid, upid. Limit 2000 rows.

Use when: drilling into a specific process picked from list_processes — e.g. finding a renderer's compositor thread, or auditing all threads under system_server.

Don't use for: enumerating ALL threads across the whole trace — use execute_sql against the thread table for that.

Parameters: pass either upid (trace-internal id, precise — prefer when multiple processes share a name like 'Renderer') or process_name (exact match). upid wins when both are set.

Empty result: returned as an error pointing at list_processes for available candidates.

When the 2000-row cap is hit (system_server, Chrome renderer-fork): drill down via execute_sql against the thread table directly.

Load a Perfetto trace file for analysis. Every other tool operates on the trace set here.

Use when: starting any analysis session — call this first.

Don't use for: live trace capture (Perfetto records traces; perfetto-mcp-rs only reads the resulting file) or for streaming URLs (path must be a complete file on local disk).

Parameters: path is an absolute path to a Perfetto trace file (.pftrace, .perfetto-trace, .bin, or any other format trace_processor accepts — content-sniffed, not by extension). Calling again with a new path replaces the active trace; cached trace_processor_shell instances make repeat loads near-zero-cost.

Errors when: the file doesn't exist, isn't a valid Perfetto trace, or trace_processor_shell fails to parse it (corrupt trace, version mismatch). On first run only, also errors if the trace_processor_shell binary fails to download from the Perfetto LUCI bucket.