metal-gpu-trace

Overview Schema Source Related Servers Discussions Admin

perf_gate

Read-only

Checks a Metal GPU recording against FPS, stutter, hitch, GPU-ms and memory budgets, returning pass or fail per limit and failing budgets when data is missing.

Instructions

Checks a recording against budgets and says pass or fail: a floor for FPS and the 1% low, a ceiling for the stutter rate, the p95 GPU ms per frame, the hitch count and the peak Metal MiB. Give at least one. A number the recording lacks fails its budget (value null): a gate must not pass on missing data. Returns each budget with its limit, the value and whether it held. Use it as a bar a change must clear, where perf_check judges against equal runs. skip_s leaves out the first seconds of the recording (the start-up), as perf_compare does.

Input Schema

Name	Required	Description
`run`	Yes	a run name from perf_runs
`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
`fps_min`	No	the FPS must be at least this
`hitches_max`	No	the number of hitches at most this
`metal_mib_max`	No	the peak Metal memory in MiB at most this
`gpu_ms_p95_max`	No	the p95 GPU ms per frame at most this
`fps_1pct_low_min`	No	the 1% low FPS must be at least this
`stutter_rate_pct_max`	No	the share of stutter frames, in %, at most this

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

Behavior3/5

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered structurally. The description adds genuinely useful semantics beyond that: missing data fails its budget rather than passing, and skip_s causes GPU numbers, hitches and Metal memory to be recomputed. Return shape is described but an output schema already exists.

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 pass/fail purpose and the missing-data rule are front-loaded, which is good. However the budget enumeration and the skip_s note are crammed into a run-on block, and the skip_s sentence at the end repeats territory the schema already covers.

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 an eight-parameter read-only gate with a full schema and an output schema, the description covers the non-derivable parts: the at-least-one requirement, the fail-closed policy on missing data, and the sibling routing. Nothing an agent needs to invoke it correctly is 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 the schema already documents every parameter, which sets the baseline at 3. The description contributes the cross-parameter rule ('Give at least one') and the null-fails-on-missing-data semantics for the budget params, but the skip_s explanation largely restates the schema text.

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 ('Checks a recording against budgets and says pass or fail') and immediately enumerates the exact budget dimensions (FPS floor, 1% low, stutter rate ceiling, p95 GPU ms, hitch count, peak Metal MiB). It also explicitly contrasts itself with a sibling: 'where perf_check judges against equal runs.'

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

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

Gives a concrete when-to-use rule ('a bar a change must clear') and names the alternative tool with the condition that selects it (perf_check for equal-run comparison). It also states a hard invocation constraint ('Give at least one' budget) that would otherwise cause a confusing error.

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