Mecatl Perf MCP Interpretation

Interpreting mecatl perf MCP output

mecatl is a streaming agentic loop. Its time is dominated by off-CPU waiting (on the model and on tool I/O), so the usual "run a CPU profile first" instinct measures the wrong thing. Diagnose by reading cheap numeric state first, and reach for the perturbing CPU tools only with a hypothesis to confirm.

Cost discipline — what to call, in what order

1. Start cheap, read state. perf://runtime/summary (goroutines, heap, GC, RSS, uptime) and perf://metrics/summary (latency-histogram quantiles) are free, point-in-time reads. Read them first, and re-read perf://runtime/summary a few times to see trends — a single snapshot rarely diagnoses anything.
2. Cheap tools next. query_metric (one curated metric; omit metric_name to list names), top_allocations (heap rankings, no profiling window), list_slow_turns (per-turn timing) are all cheap and unlimited.
3. Perturbing tools last. top_cpu_functions and capture_cpu_profile start a live CPU profile that PERTURBS the process for duration_seconds, and are rate limited to one capture per cooldown window across both tools. Call them only to confirm a hypothesis, not to explore. A rate-limit hit comes back as an isError result saying to retry — wait, do not retry-spam.
4. Never ingest raw blobs. capture_cpu_profile (with include_raw_link) and capture_flight_recorder return a user-audience resource_link to a loopback /debug/... endpoint. That link now surfaces as a TYPED BLOCK the model can see (URI + name + description) rather than a bare URI — but the model still receives only the reduced summary, never the raw blob bytes. A human downloads the linked artifact (with go tool pprof / go tool trace); if the link is https:// the model MAY fetch it via the FetchMcpResource tool (SSRF-validated through ValidateMediaURL). The perf:// resources on this server are NOT https and stay server-readonly via ReadMcpResource. Do NOT try to read a linked raw artifact into model context; report the summary and point the user at the link (or fetch an https link only if you genuinely need its contents). If a perf tool's JSON result is large and you only need a subset of fields, filter it in memory with CallMcpWithQuery (server + tool + jq_filter) rather than narrowing the call — it runs the remote tool and applies a jq filter before the result enters context (ADR 0063).

The MCP surface (what is actually there)

Resources (cheap, read-only, JSON):

• perf://runtime/summary — goroutines, num_cpu, gomaxprocs, heap_allocs_total_bytes, heap_objects, total_memory_bytes, heap_object_bytes, gc_pause_count, gc_pause_p99_upper_bound_ns, rss_bytes, uptime_seconds, available[]. Note: heap_allocs_total_bytes is a cumulative COUNTER (bytes ever allocated) — a huge value (100+ GB on a long-lived process) is normal, not a leak; the leak signal is the rss_bytes / heap_object_bytes slope.
• perf://runtime/memstats — memory-focused projection (heap_allocs_total_bytes, heap_objects, heap_object_bytes, total_memory_bytes, rss_bytes, available[]).
• perf://metrics/summary — every curated metric reduced: histograms → count + p50/p90/p99 bucket upper bounds (seconds); counters/gauges → a scalar value. Histograms and the tool_calls_total/tokens/turns_total/turn_empty_total/ active_runs counters also carry a bounded by_role breakdown over the CLOSED engine role family main|subagent|member|parallel|usermodel|child (the main engine vs the delegation children — the axis for "which agent family is burning latency/tokens"; never a session id or agent-def name).
• perf://pprof/{profile} — template, {profile} ∈ heap|goroutine|allocs|mutex|block; reduced top-15 functions (function, file basename, flat/cum values).

Tools (all read-only):

• query_metric{metric_name?, quantile?, role?} — one curated metric; aggregated across all roles by default, or one role family's share with role.
• top_cpu_functions{duration_seconds?, limit?} — perturbs, rate-limited.
• capture_cpu_profile{duration_seconds?, limit?, include_raw_link?} — perturbs, rate-limited.
• top_allocations{limit?} — heap top-N + total_heap_bytes.
• list_slow_turns{threshold_ms?, limit?, cursor?, role?} — cursor-paginated, newest first; each turn carries its bounded role family.
• capture_flight_recorder{} — size + one-line summary + user link (needs --flight-recorder).

See references/output-shapes.md for the exact field names of every tool's output (FuncStat, AllocStat, SlowTurn, MetricSummaryEntry).

Honest-precision caveat — do not over-trust the numbers

Every histogram quantile this server returns (in perf://metrics/summary, query_metric, and gc_pause_p99_upper_bound_ns) is the upper bound of the bucket the quantile rank falls in — NOT an interpolated exact quantile. The field is literally named upper_bound for this reason. Read p99 as "at worst this bucket's ceiling," not an exact value. Report it as an upper bound.