metal-gpu-trace

Overview Schema Source Related Servers Discussions Admin

perf_sweep

Destructive

Records a program once per value of one variable and reports median FPS, GPU ms/frame, and stutter per value to compare GPU performance.

Instructions

Records the same program once per value of one variable (dim, example, api, size, or env:NAME for an environment variable) and returns, per value, the median of FPS, 1 % low, GPU ms per frame and stutter, and with 3 or more numeric values the straight line GPU ms per frame follows (fixed ms plus ms per draw for dim, per unit otherwise) with its r2. With rounds above 1 the values run in opposite order every other round, so drift hits all alike. Runs are named name--r; each takes its seconds plus about a minute to read back.

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
`env`	No	NAME=VALUE pairs separated by spaces, set in the program's environment
`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
`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	rounds, default 1, at most 5 and at most 24 recordings in all; every other round runs the values in reverse
`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
`values`	Yes	2 to 8 values of the variable, such as [10, 20, 30] for dim
`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
`variable`	Yes	what changes between runs: dim, example, api, size, or env:NAME for an environment variable
`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

A3.8/5.0

Behavior5/5

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

The annotations only declare destructive/not-idempotent; the description goes well beyond them by disclosing real cost ('each takes its seconds plus about a minute to read back'), a hard budget ('at most 5 and at most 24 recordings in all'), the interleaved reverse-order scheduling used to spread drift, and the naming scheme of every run created. These are exactly the traits an agent needs before committing an expensive mutation.

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?

The purpose is front-loaded in one long sentence, but that sentence crams in return-value detail (FPS, 1 % low, GPU ms, stutter, slope and r2) that an output schema already covers, and the phrasing is compressed to the point of ambiguity ('1 % low', 'the straight line GPU ms per frame follows'). Useful content, but not tight.

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?

For a 21-parameter, destructive, long-running sweep the description supplies the critical operational facts: time cost, recording budget, ordering strategy, artifact naming and the memory=false speed trade-off. With an output schema present, return-value explanation is optional, and only the sibling-routing advice is genuinely absent.

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

Parameters3/5

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

Schema description coverage is 100%, so parameters are already documented and the baseline is 3. The description adds only marginal meaning beyond the schema — chiefly the run-naming template tying `name` to values and rounds, and the reversal semantics of `rounds` — while most parameter behavior lives in the schema text.

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 clause states a specific verb and resource: 'Records the same program once per value of one variable', which immediately separates it from a single-run tool like perf_record. The enumerated variable space (dim, example, api, size, env:NAME) and the per-value aggregation make the sweep semantics unmistakable, though no sibling is named explicitly to complete the contrast.

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?

Usage context is implied by the parameter-space enumeration and by notes like 'with rounds above 1...' and 'with 3 or more numeric values', so an agent can infer when the tool fits. However, nothing states when to choose perf_sweep over perf_ab, perf_compare or perf_baseline, and no prerequisites (e.g. needing workload_fetch first) appear in the description itself.

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