Top Chrome main-thread tasks by wall duration: id, ts, name, task_type, thread_name, process_name, upid, pid, nullable machine_id, dur_ms, overlap_dur_ms, full_task_cpu_pct/full_task_thread_dur_ms, overlap_cpu_pct/overlap_thread_dur_ms; legacy cpu_pct/thread_dur_ms are full-task. Uses chrome.tasks, thread.is_main_thread = 1, and Chrome's Cr*Main fallback. Pass a returned id to slice_descendants_breakdown for child-slice breakdowns.

Use when: investigating responsiveness, scroll/load stalls, CPU vs wall time, or one renderer.

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 / machine_id / upid: scope to one process/type. Prefer upid; add machine_id to disambiguate multi-machine pids. All filters AND.

• page_load_id / navigation_id / phase: scope to a page-load window. IDs match chrome_page_loads.id and .navigation_id respectively and are mutually exclusive. phase: navigation_to_fcp, navigation_to_load, dcl_to_fcp, fcp_to_load. If an id is set without phase, defaults to navigation_to_fcp; phase-only uses the latest page load.

• start_ts_ns / end_ts_ns: raw trace timestamp bounds in nanoseconds (end_ts_ns exclusive); aliases start_ts / end_ts are accepted; intersect page-load windows. overlap_dur_ms is clipped to that window.

• min_dur_ms: minimum full-task duration, or clipped overlap duration when a window is set. Defaults to 16 ms. Pass 0 for all positive-overlap tasks.

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

• max_string_len: optional cap for returned string cells. Unset preserves full strings for precision. Must be > 0 if set.

Output: metadata-first JSON preserving columns / rows; truncated=true means an extra-row probe found more rows; string_truncated=true means cell text was shortened.

Empty result: no detected main-thread tasks exceeded min_dur_ms at the selected process/window threshold, or the trace uses non-standard main-thread names outside the Cr*Main fallback.

Rank URL-bearing Chrome resource/request slices in a page-load/raw window. Returns timing, overlap, process/thread/machine_id, URL. Use after chrome_page_load_resource_summary to drill into slow URL slices. Filters: page_load/window, min_dur_ms default 50, limit, max_string_len. slice_duration_status='incomplete_duration' means dur=-1; overlap is measured to window end or trace_end().

Drill into one Chrome page-load resource URL and join lifecycle/request spans with script/style/layout signals. Use after chrome_page_load_resource_summary with example_slice_id or url_substring. Returns timing facts, match evidence, resource ends, primary/detail slice evidence (detail is not a root-cause claim), URL/ancestor-correlated resource result source/hit, machine-id sets, incomplete count, and evidence_boundary. Parameters: URL seed required; optional window filters, url_grouping, limit default 30, max_string_len.

URL-level Chrome resource/request summary for a page-load/raw window. Returns URL key, process/machine/priority sets, span, max/summed overlap, primary/detail slice evidence (detail is not a root-cause claim), navigation/renderer relation including target_renderer_source, example_slice_id, incomplete_duration_slice_count. Use before chrome_page_load_resource_hotspots; rank by max overlap.

Rank renderer main-thread script groups in a Chrome page-load/raw window: URL/name/process/thread/machine_id, wall/CPU totals, style/layout ms, example_slice_id. Read-only.

Use when: slow FCP/load needs post-resource JS attribution; expand example_slice_id with slice_descendants_breakdown.

Parameters: optional process filters (process_name/pid/machine_id/upid), page-load/window filters shared with chrome_main_thread_hotspots, min_total_ms (default 20), limit, max_string_len. Empty result: no matching script groups.

Summarize each page navigation in a Chrome trace: navigation id, URL, raw boundary timestamps, 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: optional limit (default 100, capped at 5000) and max_string_len. Operates on the loaded trace.

Output: metadata-first JSON; row_count exact; truncated=true means more rows exist; string_truncated=true means shortened text.

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. 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 custom filters, use execute_sql against the same view.

Parameters: optional limit (default 100, capped at 5000) and max_string_len. Operates on the loaded trace.

Output: metadata-first JSON; row_count exact; truncated=true means more rows exist; string_truncated=true means shortened text.

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: optional limit (default 100, capped at 5000) and max_string_len. Operates on the loaded trace.

Output: metadata-first JSON; row_count exact; truncated=true means more rows exist; string_truncated=true means shortened text.

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

Rank Chrome web content interactions by total_duration_ms: id, ts, total_duration_ms, longest_event_dur_ms, interaction_type, renderer_upid. Read-only.

Use when: INP analysis, reproducing user-felt latency, finding slow click/tap/keyboard handlers.

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

Parameters: optional limit (default 100, capped at 5000) and max_string_len. Operates on the loaded trace.

Output: metadata-first JSON; row_count exact; truncated=true means more rows exist; string_truncated=true means shortened text.

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). Optional output shaping (head/limit, columns_only, summary, include_row_count, max_string_len) only changes what this tool returns; it does not rewrite the SQL. Blob cells render as blob:hex:<hex>. String results may be redacted by the server privacy policy before they are returned, preserving diagnostic structure while masking sensitive URL/header/cookie/path values. 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, machine_id, 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 curated PerfettoSQL stdlib modules as JSON entries with domain, module, views, description, and usage. Use when choosing an INCLUDE PERFETTO MODULE ... target; no trace has to be loaded.

Optional filters: domain (chrome, android, generic), query (case-insensitive search over module/view/description), and limit. For longer guidance, read resource://perfetto-mcp/stdlib-quickref.

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; stdlib views may need an INCLUDE first.

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. For stdlib views, run execute_sql with INCLUDE PERFETTO MODULE ... first; otherwise retry an explicit pattern for internal tables.

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

List threads in one process or same-named process set: tid, thread_name, pid, upid, machine_id. Limit 2000, cap 5000.

Use when: drilling into a process from list_processes.

Don't use for: ALL trace threads — use execute_sql on thread.

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. Optional limit and offset page large result sets; both accept numbers or numeric strings.

Output: exact row_count, returned_rows, truncated/has_more; rows are ordered by pid/tid. process_counts reports per-upid counts for same-name fan-out.

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

When truncated=true, increase offset or drill down with upid.

Load a Perfetto trace file for analysis and return a lightweight routing summary (trace type/profile, duration, platform, process/thread counts, capabilities, and recommended next tools). 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 unless the same path's metadata/content fingerprint changed since it was loaded.

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.

Recursive child-slice expansion under known slice.id roots, aggregated as a bounded breakdown per (depth, name) group. Use to drill into a long task — after chrome_main_thread_hotspots or execute_sql returns a slice id — without hand-writing WITH RECURSIVE CTEs over slice.parent_id. Required: slice_ids. Optional bounds: min_dur_ms, max_depth, limit, include_args, max_string_len. The response echoes summary_scope, applied_filters, and missing_root_ids (missing root slice ids). Returned columns: root_id, depth, name, slice_count, inclusive_total_ms (do not sum across depths), self_ms (direct-child time subtracted, clamped at zero), max_ms, first_ts_ns (raw nanoseconds, not ms), example_slice_id (longest-duration descendant per group), and optionally example_args. incomplete_descendant_count counts dur<0 descendants excluded from duration aggregates.