metal-gpu-trace

Overview Schema Source Related Servers Discussions Admin

perf_cold_warm

Destructive

Records a program twice to isolate first-run shader-compile hitches by comparing pipeline counts, and reports each run's hitch count and graphics compiler time.

Instructions

Records the same program twice in a row and says what the first run suffers that the second does not: hitches whose cause is a shader compile (first-seen pipelines: the first run's count minus the second's, never below 0), with each run's hitch count and graphics compiler time. macOS only. Runs are named name-first and name-second; each recording takes its seconds plus about a minute to read back.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "name": "<name>"
    },
    "name": "perf_cold_warm"
  }
}

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; MTL_SHADER_VALIDATION=1 or MTL_DEBUG_LAYER=1 adds `validation` to the summary: the layers' messages counted by kind
`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
`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.22.0Nov 7, 2026

TDQS

A3.9/5.0

Behavior4/5

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

Annotations already flag destructiveHint=true and idempotentHint=false, so the safety bar is lower; the description nonetheless adds real behavioral context: each recording costs its seconds plus roughly a minute of read-back, and the tool is macOS only. It does not explain why the operation is destructive (it executes arbitrary programs), which would have closed the remaining gap.

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?

Three sentences, front-loaded with the differential purpose before constraints and timing. The parenthetical formula for first-seen pipelines is slightly dense but earns its place; the read-back timing sentence is useful rather than filler.

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?

An output schema exists and the description correctly leaves return-value detail to it while flagging the key reported quantities (first-seen pipelines, hitch count, graphics compiler time). For a 17-parameter, macOS-only, program-executing tool, the definition is nearly complete, though the absence of alternative routing is a minor shortfall.

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 17 parameters in detail; baseline 3 applies. The one genuine addition is the naming convention that runs become `name`-first and `name`-second, which gives `name` meaning the schema does not convey.

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 states a precise verb and operation: records the same program twice and reports what the first run suffers that the second does not, namely first-seen shader pipelines and per-run hitch counts plus compiler time. That differential framing is specific enough to separate it from perf_record and perf_ab 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 Guidelines3/5

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

Usage is implied by the purpose: use this when diagnosing shader-compile stutter that disappears on a warm run. The 'macOS only' constraint is stated, but the description never names an alternative sibling (perf_record, perf_ab, perf_baseline_record) or says when a single recording is the better choice, leaving the agent to infer routing.

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