metal-gpu-trace

Overview Schema Source Related Servers Discussions Admin

perf_ab

Destructive

Compares two environment setups by recording the same program in A B B A order and reports per metric whether B is better, worse, or the same, with all values.

Instructions

Records the same program with two environments in the order A B B A (repeated rounds times, so drift hits both sides equally) and says per metric whether B is better, worse or the same as A, with every value behind it. env_a and env_b are NAME=VALUE pairs separated by spaces; empty means none. Runs are named name-a1, name-b1, ... Each recording takes its seconds plus about a minute to read back. skip_s leaves out the first seconds of every recording (the start-up) when the verdicts are drawn, as perf_compare does; the recordings are whole.

Input Schema

Name	Required	Description
`api`	No	with workload: mtl (native Metal), mtl-x64 (Metal built for x86_64, run under Rosetta like Wine), vk (Vulkan through MoltenVK: set METAL_TRACE_MOLTENVK), d3d11 or d3d12 (under wine)
`dim`	No	with workload drawstress: side of the cube grid, dim^3 draws per frame
`args`	No	program arguments as in a shell, quotes included
`name`	Yes	name for the runs: letters, digits, '.', '_', '-'
`size`	No	with a workload that has size_variables (drawstress): the window size, WIDTHxHEIGHT such as 1920x1080
`wine`	No	Wine directory holding bin/wine, or native
`env_a`	Yes	NAME=VALUE pairs for side A, the reference (empty: none)
`env_b`	Yes	NAME=VALUE pairs for side B, the change under test (empty: none)
`memory`	No	default true; false skips the Metal memory table, the slowest to read (about 40 % faster summary): no metal_mib_peak
`prefix`	No	Wine prefix, default WINEPREFIX or ~/.wine; ignored with native
`rounds`	No	A B B A rounds, default 1 (4 recordings), at most 5
`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
`example`	No	with a workload that lists examples in workload_list: the one to run
`program`	No	path of the .exe, or of the macOS binary with wine=native
`seconds`	No	recording length, default 20; use 30 under Wine, whose start-up takes part of it; the export afterwards takes several minutes under Wine
`workdir`	No	directory the program starts in, default the program's own
`counters`	No	default false; true also records Metal GPU Counters (gpu_counters in the summary); not under Windows; adds about 40 s of read-back per recorded second
`workload`	No	a test program from workload_list, fetched with workload_fetch, instead of program
`background`	No	macOS only, default false; true runs the program under taskpolicy -b, which throttles it hard and unevenly (drawstress: 18 to 280 times slower): repeat the run
`memory_free_pct`	No	macOS only, 20 to 60: holds the whole Mac at this percentage of RAM free while recording (memory_pressure), to see how the program behaves short of memory; lower can freeze the Mac

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 repeated recording sequence, run-name pattern, substantial read-back time per recording, and the important fact that skip_s changes verdict calculations without truncating the recordings. It does not explain what behavior motivates destructiveHint=true or discuss overwrite and cleanup behavior, which prevents a top score.

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

Conciseness5/5

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

The description front-loads the purpose and experimental design, then efficiently covers environment syntax, artifacts, runtime cost, and skip_s behavior. Each sentence supplies distinct, useful information without unnecessary background or repetition.

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

Completeness4/5

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

Together with the fully documented input schema and existing output schema, the description provides enough context to configure the experiment and understand its cost and analysis behavior. The main remaining gaps are explicit sibling-tool routing and explanation of the destructive or system-side-effect profile signaled by the annotations.

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 description coverage is 100%, so the baseline is 3, but the description adds useful operational meaning. It clarifies space-separated env_a/env_b encoding, concrete run naming, how seconds affects elapsed time, how rounds repeats the sequence, and the analysis-only effect of skip_s.

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

Purpose4/5

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

The opening sentence gives a specific action and scope: record one program under two environments in A B B A order and report per-metric B-versus-A verdicts with supporting values. This clearly conveys the combined recording-and-comparison purpose, but it does not explicitly differentiate the tool from perf_record, perf_compare, or perf_sweep.

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?

The drift-balancing rationale makes the intended context—controlled A/B performance comparisons—clear, and the runtime estimate helps when deciding how many recordings or rounds to request. It lacks explicit selection guidance, such as when to use perf_compare on existing runs or perf_sweep for broader comparisons, and gives no when-not conditions.

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