metal-gpu-trace

Overview Schema Source Related Servers Discussions Admin

perf_compare

Read-only

Compares two saved GPU performance recordings—reference and after-change—to show FPS, frame pacing, memory, encoder, and command-buffer changes, with optional Markdown tables for PR comments.

Instructions

Compares two saved recordings (names from perf_runs), a the reference and b the run after a change: the headline numbers (FPS, GPU ms, frame pacing, memory), then what changed in the GPU work and where: encoders and command buffers per frame, the share of encoders under short_us, the GPU's idle time, and each encoder label's count and GPU ms per frame, largest change first. layer says whether both ran on the same translation layer: with different layers it compares layers, not one change. A Windows run against a Metal run has measure: the GPU ms and Metal memory differ in kind and the encoders exist only in Metal, so use FPS, its lows, stutter and jitter. Recordings with under 100 frames are flagged: too short to compare. With markdown true the result also has markdown: the same numbers as tables for a PR comment. skip_s leaves out the first seconds of each recording, where shaders compile and resources load: the GPU numbers, hitches and Metal memory are recomputed from the per-frame files without them, and skipped_s says it; thermal state, process memory and encoders stay whole-run. screen appears when one run was recorded with the screen locked and the other not: FPS is then not comparable.

Input Schema

Name	Required	Description
`a`	Yes	run name from perf_runs: the reference, such as the run before a change
`b`	Yes	run name from perf_runs: the run to compare against a
`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
`markdown`	No	also return the numbers as Markdown tables, default false
`short_us`	No	an encoder under this GPU time counts as short: 10, 25 (default), 50, 100, 250, 500 or 1000

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.18.0Nov 5, 2026

addedInput schema / properties / skip_s

Added value: +{
+  "description": "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",
+  "type": "number"
+}

Changed2 schema fields changedv0.10.1Nov 2, 2026

addedInput schema / properties / markdown

Added value: +{
+  "description": "also return the numbers as Markdown tables, default false",
+  "type": "boolean"
+}

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "type": "object"
+}

Changed3 schema fields changedv0.7.1Oct 19, 2026

addedInput schema / properties / a / description

Added value: +"run name from perf_runs: the reference, such as the run before a change"

addedInput schema / properties / b / description

Added value: +"run name from perf_runs: the run to compare against a"

addedInput schema / properties / short_us

Added value: +{
+  "description": "an encoder under this GPU time counts as short: 10, 25 (default), 50, 100, 250, 500 or 1000",
+  "type": "integer"
+}

First observedv0.2.0Oct 16, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations only say readOnlyHint and openWorldHint=false; the description goes well beyond by disclosing the diagnostic flags it emits (layer, measure, screen, skipped_s), the short-recording threshold that alters the comparison, and exactly which metrics are recomputed under skip_s versus which remain whole-run. That level of disclosure about conditional result semantics is unusual and directly useful for interpreting output.

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

Conciseness4/5

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

The first sentence front-loads the purpose and headline metrics, and subsequent clauses each carry a distinct conditional fact rather than filler. It is dense to the point of being hard to scan (no lists, minor typos like 'a the reference'), but almost no sentence could be deleted without losing a conditional rule.

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 read-only comparison tool with an output schema and two required name parameters, the description covers source of names, comparison semantics, the three cases where the comparison is not apples-to-apples, and the effect of each optional parameter. Nothing an agent needs in order to call it correctly or interpret a flag is missing.

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, but the description adds real meaning beyond the schema for skip_s: thermal state, process memory and encoders stay whole-run while GPU numbers, hitches and Metal memory are recomputed, and skipped_s reports the exclusion. It also ties markdown output to a concrete use (PR comment) and restates short_us's role only lightly.

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?

The description opens with a specific verb and resource: compares two saved recordings from perf_runs, with 'a' as the reference and 'b' as the post-change run, and it enumerates what is compared (FPS, GPU ms, frame pacing, memory, encoder counts, GPU idle). An agent can distinguish this from perf_runs (listing) and from capture tools without opening any schema.

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

Usage Guidelines4/5

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

It gives explicit conditional guidance: recordings under 100 frames are flagged as not comparable, different translation layers mean layer-vs-layer comparison, a Windows-vs-Metal pair should be judged on FPS/lows/stutter/jitter, and a locked-vs-unlocked screen makes FPS non-comparable. It lacks routing against nearby siblings such as perf_ab, perf_gate or perf_check, so the alternative-selection guidance is strong on data conditions but absent on tool selection.

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