Provides access to Apple GPU family facts (Apple7 to Apple10, chips, feature limits) and supports GPU profiling on Apple silicon via Instruments' Metal System Trace and Metal .gputrace captures.
Enables recording and profiling of native macOS programs' GPU usage on Apple silicon, including GPU time per frame, frame pacing, FPS, and memory.
Enables recording and profiling of Windows programs running under Wine on Apple silicon, with settings for the Wine directory, prefix, and environment.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@metal-gpu-trace record 30s of my Wine game and show GPU time per frame and FPS"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Measure how a Wine or macOS program uses the GPU on an Apple silicon Mac, from the command line or through an AI
coding agent: GPU time per frame, frame pacing, FPS and memory, recorded with Instruments' Metal System Trace; Metal
.gputrace captures read without Xcode; and Apple's published facts on each GPU family to read the numbers against.
Python 3.9+ standard library, zsh, and Xcode (for xctrace). MIT license. Español.
File | What it does |
| Records a program for N seconds with Metal System Trace and writes |
| Summarizes an existing |
| Reads a Metal |
| Apple7 to Apple10: chips, what each family adds, limits that differ, with Apple's sources. |
| An MCP server over all of the above. |
| Self-check without Instruments: |
PERF_OUT=~/perf-runs zsh perf_record.sh game-d3d12 30 /path/to/wine ~/.wine /path/to/game game.exe
PERF_OUT=~/perf-runs zsh perf_record.sh app-metal 30 native - /path/to/app ./appArguments: label, seconds, a Wine directory holding bin/wine (or native), the Wine prefix, the working directory,
the program and its arguments. Without PERF_OUT, runs go to ./perf-runs. Reading the trace afterwards takes about
a minute on an M1 Pro (87 s for a 10 s recording); through the MCP server the whole call times out 300 s after the
recording. One recording runs at a time; keep other GPU work off the Mac while it records.
Under Wine, give it 30 s: Wine's start-up takes part of the recording. A recording with under 100 frames is too short to compare.
Related MCP server: XcodeTraceMCP
Each recording keeps a JSON summary and three CSVs, about 2 MB for 10 s (most of it the Metal memory samples). The
.trace (tens to hundreds of MB) is deleted unless KEEP_TRACE=1. KEEP_RUNS=N keeps only the newest N recordings.
The server runs with uvx straight from this repo, with nothing to clone
(brew install uv installs it). Recording also needs Xcode installed (xcrun xctrace version prints a version).
uvx --from git+https://github.com/partprogramming09/metal-gpu-trace metal-gpu-traceThis is the command each client below runs. Desktop apps do not see Homebrew's PATH: give them the full path that
which uvx prints (/opt/homebrew/bin/uvx on Apple silicon). uvx keeps the version it first downloaded; run
the command once with --refresh after uvx to get the latest.
The server reads these environment variables:
Variable | What it sets |
| Where recordings go. Give an absolute path: the default, |
| The Wine directory (holding |
| The Wine prefix used when the call names none; |
| More directories the tools may read, separated by |
|
|
|
|
| Keeps only the newest N recordings. |
|
|
claude mcp add --scope user metal-trace -e METAL_TRACE_OUT=$HOME/perf-runs -e METAL_TRACE_WINE=/path/to/wine \
-- uvx --from git+https://github.com/partprogramming09/metal-gpu-trace metal-gpu-trace
claude mcp listclaude mcp list shows metal-trace as connected. --scope user makes it available in every project; leave it out
to add it to the current project only.
These apps do not expand ~ or $HOME: write absolute paths.
{
"mcpServers": {
"metal-trace": {
"command": "/opt/homebrew/bin/uvx",
"args": ["--from", "git+https://github.com/partprogramming09/metal-gpu-trace", "metal-gpu-trace"],
"env": {
"METAL_TRACE_OUT": "/absolute/path/to/perf-runs",
"METAL_TRACE_WINE": "/absolute/path/to/wine"
}
}
}
}Client | File |
Claude Desktop |
|
Cursor |
|
VS Code |
|
In ~/.codex/config.toml:
[mcp_servers.metal-trace]
command = "/opt/homebrew/bin/uvx"
args = ["--from", "git+https://github.com/partprogramming09/metal-gpu-trace", "metal-gpu-trace"]
env = { METAL_TRACE_OUT = "/absolute/path/to/perf-runs", METAL_TRACE_WINE = "/absolute/path/to/wine" }Tool | Reads or records |
| Records a program and returns its summary |
| Lists recordings, newest first, one page at a time |
| Compares two recordings; flags those under 100 frames |
| Lists the tables of a kept |
| One page of rows of one table, optionally one process |
| Summarizes a |
| One page of a |
| Apple's facts for a family or chip ( |
The same facts are MCP resources: metal-trace://gpu-families (all) and metal-trace://gpu-families/apple7 to
apple10. They restate Apple's Metal Feature Set Tables
of 21 May 2026, MTLGPUFamily and the
M3 tech talk; check a device with supportsFamily.
How it follows the MCP specification and Claude Code's limits:
stdout carries only MCP messages; each tool call logs one line to stderr (METAL_TRACE_LOG=off silences it), with
no arguments or paths.
Lists come in pages (offset, limit, default 50, at most 500) with total and next_offset; a result over
40 000 characters is refused with a hint to ask for a smaller page.
Files are read only inside METAL_TRACE_OUT and the directories in METAL_TRACE_READ (separated by :).
Failures come back as isError results that say what to do, without stack traces or local paths. Summaries cut
absolute paths to file names, so they can be shared.
Every xctrace call has a timeout.
The record layout of a .gputrace command stream follows tmc/gputrace (MIT); no
code is copied. The call ids were matched against Xcode's command list on macOS 27.0.1.
GPU family facts: Apple's documents linked above, restated, not quoted.
Returns one page of the records of a .gputrace command stream, with their Metal call names when known.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | rows per page, default 50, at most 500 | |
| offset | No | first row, default 0 | |
| capture | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds genuinely useful context beyond annotations: results are paginated one page at a time and Metal call names are present only 'when known' (i.e., may be absent). It does not explain ordering or how to detect the end of the stream.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler; the paging scope and the return content both land immediately. It is tight, though slightly terse for a tool with three parameters and no usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does carry the burden of describing returns, and it does so partially (records + call names). It omits record ordering, pagination termination, and the expected form of `capture`, leaving gaps an agent would need to resolve by trial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%: limit and offset are documented in the schema with defaults and caps, so the description need not repeat them. The description indirectly clarifies the undocumented `capture` parameter by identifying the domain (.gputrace command stream), but it never says whether that value is a path, identifier, or handle; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: returns a page of records from a .gputrace command stream, including Metal call names. It is clear and distinguishes itself from capture_summary by being record-level and paged, but it never names or contrasts the similar siblings (capture_summary, trace_query).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no prerequisites, and no mention of alternatives, despite seven siblings including capture_summary and trace_query that plausibly overlap. The agent must infer usage from the purpose statement alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reads a Metal .gputrace capture without Xcode: command buffers, encoders, draws, debug groups, call ids.
| Name | Required | Description | Default |
|---|---|---|---|
| capture | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already establishes this as a safe read, and the description usefully adds that no Xcode is required and lists the decoded content. It says nothing about output shape, size, or whether a capture must already be loaded, which are the traits an agent would still want.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One tight sentence with the verb and resource front-loaded and no filler. The parenthetical-style content list is informative rather than padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read tool with no output schema, listing the returned entities is a genuine plus, but the missing parameter format and the disambiguation from capture_records leave it only minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'capture' has 0% schema description coverage, and the description only hints via '.gputrace' that it is a file path. It never states whether the value is a path, a capture name, or an identifier, so the description fails to compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (reads) and resource (Metal .gputrace capture) and enumerates the content returned: command buffers, encoders, draws, debug groups, call ids. It does not, however, differentiate itself from the sibling capture_records, leaving the summary/records split to inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance and no alternatives named. Nothing tells the agent whether to reach for this over capture_records, trace_query, or trace_tables when inspecting a capture.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apple's published facts for one GPU family, by family ("Apple7") or chip ("M1 Pro"): its chips, what it adds, its limits, plus the limits shared by all families and the footnotes. Source URLs are in the result.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | a family (Apple7 to Apple10) or a chip (M1 Pro, M2, M4 Max, A17 Pro) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful behavioral context beyond that: it details the result contents (chips, additions, limits, shared limits, footnotes) and notes that source URLs are included, which helps the agent understand provenance and output shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The definition is a single dense sentence that front-loads the resource and then lists what is returned. Every clause seems to earn its place, though the sentence is somewhat long and could be slightly clearer with separation, keeping it from a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only one parameter and no output schema, the description fully compensates by explaining the return contents in detail, including source URLs. An agent has enough information to understand what to pass and what to expect back.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents the 'name' parameter with examples 'Apple7' to 'Apple10' and chips like 'M1 Pro'. The description repeats the family/chip duality with the same examples, adding little beyond what the schema provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific resource (one GPU family) and enumerates exactly what is returned: its chips, what it adds, its limits, shared limits, and footnotes. It is clearly distinguishable from the perf/trace-oriented siblings, which deal with runtime data rather than static published facts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (to look up Apple-published facts for a GPU family or chip), but it never explicitly contrasts with alternatives or states when not to use it. Given the siblings are in a different domain (performance traces), the need for explicit alternatives is lower, but the guidance remains only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compares two saved recordings (names from perf_runs): each headline number, its change and change in %. Recordings with under 100 frames are flagged: too short to compare.
| Name | Required | Description | Default |
|---|---|---|---|
| a | Yes | ||
| b | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true the safety profile is already covered, and the description goes further by disclosing the return shape (headline number, change, change %) and the notable short-recording flagging behavior. It omits error handling for unknown recording names and says nothing about comparison direction, so it is not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences, no filler, with the core capability and its inputs front-loaded and the caveat about short recordings placed last. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description correctly summarizes the returned metrics, and the annotation covers safety. The remaining gap is procedural: no guidance on parameter ordering or on what happens when a supplied name does not exist.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% — 'a' and 'b' are opaque strings — so the description must carry the burden. It does add real meaning by identifying them as saved recording names originating from perf_runs, but it never says which parameter is the baseline versus the comparison target, leaving the sign of every reported change ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (compares), a specific resource (two saved recordings), and even summarizes the outputs produced (headline number, delta, delta %). It also distinguishes itself by naming perf_runs as the source of the recording names, so an agent can place it in the perf_* workflow without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is clear: it operates on saved recordings whose names come from perf_runs, and the 'under 100 frames are flagged: too short to compare' clause tells the agent when a comparison is not meaningful. It stops short of naming an alternative or stating an exclusion, hence 4 rather than 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Records program (an .exe under Wine, or a macOS binary with wine="native") for seconds with Metal System
Trace and returns its summary: GPU ms per frame, frame intervals, FPS, Metal and resident memory.
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | program arguments as in a shell, quotes included | |
| wine | No | Wine directory holding bin/wine, or native | |
| label | Yes | name for the run: letters, digits, '.', '_', '-' | |
| prefix | No | ||
| program | Yes | 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 about a minute | |
| workdir | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The only annotation is readOnlyHint=false, so the description carries most of the burden. It usefully discloses the return payload (GPU ms/frame, frame intervals, FPS, Metal and resident memory) despite there being no output schema, and it implies process launch plus Wine/native dependency. It omits side-effect and cost context: the schema note that export takes about a minute, potential rate/disk implications, and what happens if the program fails to start.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence opening with the verb 'Records', where each clause (what is recorded, the Wine/native distinction, the metrics returned) carries distinct information. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter mutating tool with no output schema, describing the returned metrics is the right call and is done. However, two parameters (prefix, workdir) have no semantics anywhere, and operational caveats such as the roughly one-minute export live only in schema text, so the definition is adequate but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 71%, above the midpoint, so the schema does most of the work. The description adds real cross-parameter semantics for `program`/`wine` (an .exe under Wine vs a macOS binary with wine="native") and bounds `seconds`, but `prefix` and `workdir` are documented nowhere, so it does not fully compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (records) and resource (a program under Metal System Trace) plus the return content, so an agent knows this is the run-creating tool. It does not, however, name or contrast itself with siblings such as perf_runs or capture_records, leaving that differentiation implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: an agent can infer this is the tool that produces a recording, and the mention of wine="native" hints at the two execution modes. There is no explicit when-to-use/when-not guidance, no pointer to perf_runs/perf_compare for consuming results, and no stated prerequisites beyond what the schema says.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists the saved recordings, newest first, with frames, FPS, GPU ms per frame and memory peaks.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | rows per page, default 50, at most 500 | |
| offset | No | first row, default 0 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already tells the agent this is a safe read. The description adds genuine behavioral context in the form of sort order ('newest first') and the metric set returned per recording, but says nothing about pagination behavior or how many recordings typically exist, so the addition is real but modest.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the resource and ordering before the returned fields. No filler, nothing redundant with the schema or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully enumerates the returned fields (frames, FPS, GPU ms per frame, memory peaks), which is exactly the gap it needs to fill. Paging is handled by the schema; only the absence of guidance on identifying/filtering recordings keeps this from a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% - both limit (default 50, max 500) and offset are fully documented in the schema. The description adds nothing about paging semantics, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb ('Lists') plus a clearly identified resource ('saved recordings') and ordering ('newest first'). An agent can distinguish this from siblings like perf_record (which records) and perf_compare (which compares), though the description never names those siblings explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to use this tool versus perf_record, perf_compare, or capture_summary. Usage is only inferable from the name and the listing verb; no prerequisites or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns one page of rows of one table of a .trace as {column: value}, optionally only one process's rows.
| Name | Required | Description | Default |
|---|---|---|---|
| pid | No | ||
| limit | No | rows per page, default 50, at most 500 | |
| trace | Yes | ||
| offset | No | first row, default 0 | |
| schema | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds genuinely useful behavior beyond that: results are paginated ('one page of rows') and shaped as {column: value}. It says nothing about ordering, error behavior, or what happens when schema names a nonexistent table, so it remains partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence with no filler, and the core behavior (paginated rows of one table) is front-loaded. It is efficient but very compressed, packing the return shape and the pid option into one clause.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter read tool with no output schema, the description covers the return format and pagination, which is the important part. It still leaves the two required parameters (trace, schema) semantically undefined and gives no guidance on discovering valid table names, so it is adequate rather than complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 40% (limit and offset are documented in-schema; trace, schema, and pid are not). The description compensates partly by implying schema is a table name within the .trace and that pid optionally narrows to one process's rows, but it never explains what a trace identifier looks like or what valid schema values are.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (returns rows) and resource (one table of a .trace), and clarifies the row shape ({column: value}). It does not, however, name or contrast itself with siblings like trace_tables, so an agent must infer the boundary between listing tables and querying one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use or when-not-to-use guidance, and no alternative tool is named. The only usage hint is the optional pid filter, which is stated as a capability rather than a condition for choosing this tool over trace_tables or capture_records.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists the data tables (schemas) a .trace recording holds; recordings keep their .trace only with KEEP_TRACE=1.
| Name | Required | Description | Default |
|---|---|---|---|
| trace | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already declares this a safe read, so the bar is lower; the description adds real value with the KEEP_TRACE=1 retention condition (the .trace may not exist otherwise). It does not disclose return shape, ordering, or behavior on a missing/unreadable trace.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the action and resource, and the retention caveat is appended compactly. Nothing wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 1-param read with no output schema, the description names what is listed but never characterizes the result (table names? schema objects?) or the parameter's accepted form. Adequate but leaves gaps an agent would have to probe.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single `trace` parameter has 0% schema description coverage, so the description must carry the semantics. It hints that the value refers to a '.trace recording' but never states whether that is a path, filename, or handle, nor any format constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb ('Lists') plus resource ('data tables (schemas)') plus scope ('a .trace recording') makes the operation unambiguous. It does not explicitly distinguish itself from the similarly-scoped sibling trace_query, but the noun 'tables' vs 'query' implies different outputs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No statement of when to use this versus trace_query, capture_summary, or the other trace siblings. The KEEP_TRACE=1 note is a useful precondition, but it is a caveat about the artifact, not usage routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.0capture_recordscapture_summarygpu_familyperf_compareperf_recordperf_runstrace_querytrace_tablesScored across 8 tools
Tools cluster into three clear groups (perf_* recordings, trace_* .trace exploration, capture_* .gputrace exploration) plus a standalone reference tool, and within each group the actions are distinct. The only mild risk is confusing trace_* and capture_* since both inspect capture files, but the descriptions clearly separate .trace from .gputrace.
All names use consistent snake_case with a group prefix (perf_, trace_, capture_) that maps predictably to the domain area. Minor deviations: perf_runs and trace_tables use nouns rather than the verb style of their siblings, but the pattern remains readable.
Eight tools is well-scoped for a Metal tracing/analysis server, with each tool earning its place across recording, comparison, trace exploration, capture inspection, and reference lookups.
The surface covers the full workflow: record, list, compare, inspect trace tables/rows, and read gputrace captures, plus a GPU-family reference. Minor gaps like no delete/prune of saved recordings or export of results exist, but agents can work around them.
Codebase graphs, caller impact analysis, and recorded project context for AI coding agents.
A read-only verified record of agent-operable GTM tools: search, fetch, compare, track changes.
Privacy-first work tracking with summaries, reports, coaching, and AI-ready long-term memory.
Independent directory of agentic AI tools — search, compare & recommend via MCP. Read-only.
