metal-gpu-trace

Overview Schema Source Related Servers Discussions Admin

perf_panel

Idempotent

Generates a standalone HTML panel from one or two Metal GPU trace recordings, showing per-frame GPU time and hitches, FPS lows, memory, and A/B comparisons in a browser.

Instructions

Writes one HTML file, <name>.panel.html in the runs directory, that shows one or two recordings in a browser without a server: GPU time per frame with the hitches marked, the numbers (FPS and its lows, frame time, jitter, stutter, memory, thermal state), Metal memory over time and, for two runs, A against B. The file holds the data itself, no path, and loads nothing from the network; the viewer can hide and reorder the widgets and export the layout as JSON. preset fps is the timeline, numbers and memory; compare (two runs) puts A against B first. skip_s leaves out the first seconds of each recording (the start-up), as perf_compare does. layout (tab ids in the order to show) is saved as panel.json in the runs directory and becomes the default tab order of every panel, the live one too, until the viewer changes it in the browser; ids left out are hidden but can be switched back on; tabs are summary, ab, frames, encoders, counters, memory and data, and a panel.json you wrote yourself, or copied from the panel's Layout JSON, works the same. Returns the file name, the runs, the frames shown and the file's bytes.

Input Schema

Name	Required	Description
`name`	Yes	name for the panel file: letters, digits, '.', '_', '-'
`runs`	Yes	one or two run names from perf_runs; with two, the first is A, the reference
`layout`	No	tabs to show, in order: summary, ab, frames, encoders, counters, memory, data; saved as panel.json in the runs directory as the default for every panel
`preset`	No	fps (default) or compare (needs two runs)
`skip_s`	No	seconds to leave out at the start of each recording, where shaders compile and resources load; 0 (default) keeps all. The GPU numbers, hitches and Metal memory are recomputed without them

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.18.0Nov 5, 2026

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations, it discloses the real behavioral traits: a file is written into the runs directory, the file is self-contained and loads nothing from the network, and — most importantly — the `layout` argument is persisted as panel.json and becomes the default tab order for every panel, including the live one, until a viewer changes it. That global side effect is exactly the kind of context annotations cannot carry. It stops short of saying what happens on name collision or overwrite of an existing panel.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Content is front-loaded on the artifact, which is right, but the body is a dense run-on with stacked clauses ('The file holds the data itself, no path, and loads nothing from the network') and buries the significant layout/persistence side effect mid-paragraph. Several fragments ('no path', 'A against B') cost parsing effort without adding precision.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a five-parameter write tool it covers everything an agent needs: required inputs, file destination and naming, all preset and layout consequences, and even the return payload (file name, runs, frames shown, byte size) which is also backed by an output schema. Nothing material is missing given the annotation and schema richness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% so the baseline is 3; the prose adds genuine meaning on top by giving the tab id vocabulary (summary, ab, frames, encoders, counters, memory, data), the semantics of omitted ids (hidden but switchable back on), the persistence behavior of layout, and the fact that a hand-written or copied panel.json works identically. skip_s and preset meanings largely restate the schema rather than extend it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a concrete verb and artifact: 'Writes one HTML file, `<name>.panel.html` in the runs directory', then enumerates exactly what the artifact shows (GPU time per frame with hitches, FPS/lows/jitter/stutter/memory/thermal, Metal memory, A vs B). It also anchors itself to siblings by name ('as perf_compare does', runs 'from perf_runs'), so an agent can separate this from perf_ab/perf_compare without reading schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description makes clear what the output is for (viewing one or two recordings in a browser without a server) and explains which preset fits which case ('compare' needs two runs), but it never states when an agent should choose this over perf_compare, perf_ab or the live panel. Usage is implied from the artifact type rather than routed explicitly.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.