metal-gpu-trace

Overview Schema Source Related Servers Discussions Admin

perf_record

Destructive

Records a Wine or macOS program, or a fetched test workload, with Metal System Trace for a set duration and returns GPU ms per frame, frame intervals, FPS, and memory summary.

Instructions

Records program (an .exe under Wine, or a macOS binary with wine="native"), or a test program fetched with workload_fetch (workload, api, dim), for seconds with Metal System Trace and returns its summary: GPU ms per frame, frame intervals, FPS, Metal and resident memory (memory=false skips the Metal memory table, the slowest to read). When it ends it stops every program of that Wine prefix (wineserver -k), or every process named like the program with native. counters=true also records Metal GPU Counters (gpu_counters in the summary: the units the GPU waited on, its utilization, occupancy and memory bandwidth); it adds about 40 s of read-back per recorded second.

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
`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
`label`	Yes	name for the run: letters, digits, '.', '_', '-'
`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
`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.

Changed7 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"
+}

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"
+}

Changed6 schema fields changedv0.7.1Oct 19, 2026

addedInput schema / properties / api

Added value: +{
+  "description": "with workload: mtl (native Metal), d3d11 or d3d12 (under wine)",
+  "type": "string"
+}

addedInput schema / properties / dim

Added value: +{
+  "description": "with workload drawstress: side of the cube grid, dim^3 draws per frame",
+  "type": "integer"
+}

addedInput schema / properties / prefix / description

Added value: +"Wine prefix, default WINEPREFIX or ~/.wine; ignored with native"

addedInput schema / properties / workdir / description

Added value: +"directory the program starts in, default the program's own"

addedInput schema / properties / workload

Added value: +{
+  "description": "a test program from workload_list, fetched with workload_fetch, instead of program",
+  "type": "string"
+}

changedInput schema / required

Previous value: -[
-  "label",
-  "program"
-]New value: +[
+  "label"
+]

First observedv0.2.0Oct 16, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Critical behavior beyond the annotations is spelled out: at the end it kills every program in the Wine prefix (wineserver -k) or every process named like the program with native — exactly the destructiveHint in concrete terms. It also quantifies costs and risks: counters adds ~40 s read-back per recorded second, memory=false is ~40% faster, background throttling is 18-280x, memory_free_pct can freeze the Mac, and the export takes minutes under Wine.

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 core action and its return value are front-loaded in the first sentence, with caveats following. It is dense and long-sentenced but nearly every clause carries operational information; only the memory=false phrasing is repeated from the schema.

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 17-parameter, destructive, long-running recording tool with an output schema, the description covers prerequisites (workload_fetch/list), side effects (process killing), timing implications, and platform caveats. Nothing an agent needs to call it safely is missing.

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 every parameter, and much of the description's parameter talk (memory=false, counters=true, wine=native, seconds=30) restates it. The added value is mainly the program/workload mutual exclusivity and the consequence of the kill behavior tied to the wine choice, which is a modest increment over the schema.

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 ('Records' a program or a fetched workload under Metal System Trace) and enumerates what the summary contains (GPU ms/frame, frame intervals, FPS, memory). It also draws the program-vs-workload boundary that separates it from workload_fetch/workload_list and the non-recording siblings.

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?

Gives concrete guidance on selecting inputs: pass `program` for a local .exe/binary or `workload` for a test program from workload_list, set wine=native for macOS binaries, use 30 s under Wine because start-up eats into the recording. It does not explicitly say when to prefer perf_attach, perf_ab, or perf_sweep instead, so routing among siblings is left partly implicit.

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