metal-gpu-trace

Overview Schema Source Related Servers Discussions Admin

perf_baseline_record

Destructive

Records the same program multiple times to build a named baseline for perf_check and returns the range each measured number spans across runs.

Instructions

Records the same program count times in a row with perf_record's arguments and saves the runs as the reference name for perf_check, returning the range each number spans across them. Runs are named name-1, name-2, ... Each recording takes its seconds plus about a minute to read back. skip_s as in perf_baseline: the reference leaves out each run's start-up.

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	reference name: 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
`count`	No	equal recordings to make, default 3
`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
`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; perf_check applies the same cut to the run it judges
`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.

Changed8 schema fields changedv0.18.0Nov 5, 2026

changedInput schema / properties / api / description

Previous value: -"with workload: mtl (native Metal), d3d11 or d3d12 (under wine)"New value: +"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)"

addedInput schema / properties / background

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

addedInput schema / properties / counters

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

addedInput schema / properties / env

Added value: +{
+  "description": "NAME=VALUE pairs separated by spaces, set in the program's environment",
+  "type": "string"
+}

addedInput schema / properties / example

Added value: +{
+  "description": "with a workload that lists examples in workload_list: the one to run",
+  "type": "string"
+}

addedInput schema / properties / memory_free_pct

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

addedInput schema / properties / size

Added value: +{
+  "description": "with a workload that has size_variables (drawstress): the window size, WIDTHxHEIGHT such as 1920x1080",
+  "type": "string"
+}

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; perf_check applies the same cut to the run it judges",
+  "type": "number"
+}

Changed3 schema fields changedv0.10.1Nov 2, 2026

addedInput schema / properties / memory

Added value: +{
+  "description": "default true; false skips the Metal memory table, the slowest to read (about 40 % faster summary): no metal_mib_peak",
+  "type": "boolean"
+}

changedInput schema / properties / seconds / description

Previous value: -"recording length, default 20; use 30 under Wine, whose start-up takes part of it; the export afterwards takes about a minute"New value: +"recording length, default 20; use 30 under Wine, whose start-up takes part of it; the export afterwards takes several minutes under Wine"

changedOutput schema / (root)

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

Addedv0.7.1Oct 19, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true and non-idempotent, so the safety bar is lower; the description still adds real cost and side-effect context — each recording costs its `seconds` plus about a minute of read-back, and run objects are created under fixed names. It does not say what happens when a reference with that `name` already exists, which is the one mutation detail an agent would want.

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?

Four dense sentences, front-loaded with the write-and-name behavior before cost details. Nearly every clause carries information, though the read-back timing remark is slightly buried mid-paragraph rather than separated as a cost caveat.

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 19-parameter destructive recording tool with a full output schema, the description covers the action, the artifact naming convention, the relationship to perf_check, and the run-time cost. Return values need not be explained because an output schema exists, and the remaining gap (overwrite semantics) is narrow.

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 the schema already documents all 19 parameters thoroughly. The description reinforces `count` (equal recordings, default 3) and the skip_s cut, including that perf_check applies the same cut, but adds little syntax or meaning the schema lacks; baseline 3 applies.

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?

States a specific verb and resource: record the same program `count` times, save as reference `name` for perf_check, and return the per-metric range. It explicitly contrasts with perf_record (whose arguments it reuses) and perf_baseline (whose skip_s convention it follows), plus names the artifact naming scheme (`name`-1, `name`-2), so an agent can distinguish it from every sibling.

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?

Usage is clearly implied and partly explicit: the reference is built for perf_check, and repeated recording exists to get the range each number spans. It borrows context from perf_baseline and perf_record rather than stating outright when to pick one of those instead, so there is no explicit exclusion, but the routing signal is strong.

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