metal-gpu-trace

Overview Schema Source Related Servers Discussions Admin

perf_baseline

Idempotent

Save and list performance baselines from repeated runs, returning metric ranges and spread percentages so perf_check can judge changes beyond normal run-to-run noise.

Instructions

Names a reference for perf_check, or lists them. With name and runs (names from perf_runs, several runs of the same program recorded with no change between them), it saves copies of their summaries as the reference name, replacing a previous one, and returns the range each number spans across them: that range, not one run, is what perf_check judges against, since repeated runs differ by a few percent, and spread_pct, each range's width in % of its midpoint: the noise of this program on this machine, which a change must exceed. With name alone it shows that reference; with nothing it lists them. With skip_s the reference keeps each run without its first skip_s seconds (the start-up, as perf_compare's skip_s) and perf_check applies the same cut to the run it judges, so both are steady-state; the runs need their per-frame files for that.

Input Schema

Name	Required	Description
`name`	No	reference name: letters, digits, '.', '_', '-'; alone, shows that reference
`runs`	No	run names from perf_runs to save as this reference, ideally 3 or more equal runs; replaces a previous one
`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

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.18.0Nov 5, 2026

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

Changed1 schema field changedv0.10.1Nov 2, 2026
- changedOutput schema / (root)
```
Previous value: -nullNew value: +{
+  "type": "object"
+}
```
Addedv0.7.1Oct 19, 2026

TDQS

A3.9/5.0

Behavior4/5

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

Annotations declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, but the description adds material facts the annotations don't carry: the call overwrites a previous reference of the same name, and skip_s requires the runs' per-frame files to exist. The overwrite ('replacing a previous one') sits awkwardly with destructiveHint=false, though it is a reversible upsert rather than a true contradiction. The explanation of what the returned numbers mean (ranges, spread_pct as machine noise) also goes beyond the flags.

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?

Every clause carries information — nothing is filler — but the prose is a dense run-on with parenthetical tangents and elided articles, and the three-mode dispatch is buried mid-sentence rather than front-loaded as a list. It is efficient in content but weak in structure, and a re-read is needed to extract the branching logic.

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, so return-value description isn't required; the description instead covers mode selection, overwrite behavior, the skip_s precondition, and how perf_check consumes the result. The remaining gap is sibling positioning against perf_baseline_record, which matters in a family of 20+ perf tools with overlapping names.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3; the description earns the extra point by adding meaning the schema doesn't: runs should be 'several runs of the same program recorded with no change between them', ideally 3+, and skip_s is coupled to per-frame file availability and mirrored by perf_check. That cross-parameter, cross-tool semantics is real added value rather than restatement.

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 — it names or lists baselines used as references for perf_check — and the three modes (name+runs, name alone, nothing) are each spelled out, so an agent can tell what the tool does. It loses a point because the near-identically named sibling perf_baseline_record is never mentioned, leaving ambiguity about which of the two to pick.

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 dispatched explicitly by argument shape: 'With name and runs... it saves copies', 'With name alone it shows that reference; with nothing it lists them' — a genuine when-to-use map. It also states the upstream dependency (runs come from perf_runs) and that the named reference is what perf_check judges against. It gives no exclusions and never contrasts itself with the sibling perf_baseline_record.

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