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. The description still adds real behavioral context beyond the annotations: results are paginated ('one page'), call names are best-effort ('when known'), and the operation is scoped to a single capture rather than global state.

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 pagination constraint and then the record contents. No filler, nothing repeated from 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?

An output schema exists, so return values need not be explained, and the required capture path is fully described in the schema. What is missing is orientation relative to siblings (trace_count for total rows, trace_query for filtering), which matters for a paged reader in a crowded toolset.

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%, so limit, offset, and the capture path constraint (METAL_TRACE_OUT / METAL_TRACE_READ) are already documented. The description's 'one page' phrasing reinforces the paging model but adds no syntax or format detail beyond the schema, so baseline 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?

States a specific verb-and-resource pair: it returns one page of records from a .gputrace command stream, and notes Metal call names are included when known. That is clear enough to distinguish it from the surrounding perf_* tools, though it never explicitly contrasts with trace_query or trace_tables, which operate on similar row data.

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: the tool reads a capture's records, so callers infer it applies after a capture exists. There is no explicit when-to-use guidance, no statement of when to prefer trace_query/trace_tables, and no note that trace_count should be consulted first to page correctly.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral trait — that only the 100 most frequent call ids are returned out of calls_total, i.e. the output is truncated — but says nothing about error behavior, cost, or how much of the trace is actually parsed.

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 key scope ('without Xcode') and the contents appear immediately. The trailing enumeration is dense but each item 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?

An output schema exists, so return values need not be spelled out, and annotations cover the read-only profile; with a single fully documented parameter the definition is nearly complete. The remaining gap is sibling disambiguation against capture_records, which matters given the crowded tool list.

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?

Only one parameter and schema description coverage is 100%; the schema already explains that 'capture' is a path to a .gputrace bundle inside METAL_TRACE_OUT or METAL_TRACE_READ. The description adds nothing about the parameter beyond the resource type, so baseline 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?

Names a specific verb (Reads) and resource (Metal .gputrace capture) and enumerates exactly what the summary contains: command buffers, encoders, draws, debug groups, top-100 call ids. It does not, however, contrast itself with the sibling capture_records, so an agent must infer which capture-reading tool to pick.

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 phrase 'without Xcode' hints at the lightweight/headless use case, but there is no explicit when-to-use, no when-not-to-use, and no reference to the obvious alternative capture_records. The agent gets no routing guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds provenance by noting source URLs are in the result and clarifies that shared limits and footnotes are included, but it does not mention error behavior or caching.

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 sentences, front-loaded with the resource and scope. The colon list is dense but each item clarifies the returned facts.

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?

Low-complexity read-only lookup with a fully described parameter, annotations, and output schema. The description covers scope, result contents, and provenance, leaving no material gap for correct invocation.

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 100% and the single parameter already documents family/chip examples. The description repeats the same valid input forms but adds no formatting or edge-case guidance beyond the schema.

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 it returns Apple's published facts for one GPU family and enumerates result contents: chips, additions, limits, shared limits, and footnotes. It does not explicitly differentiate from sibling perf/trace tools, though those are unrelated categories.

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?

Implies use for looking up GPU family/chip facts and gives example names such as Apple7 and M1 Pro. It never states when to use this instead of related performance tools or what happens for unsupported names.

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

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

Beyond the annotations, it discloses the repeated recording sequence, run-name pattern, substantial read-back time per recording, and the important fact that skip_s changes verdict calculations without truncating the recordings. It does not explain what behavior motivates destructiveHint=true or discuss overwrite and cleanup behavior, which prevents a top score.

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 description front-loads the purpose and experimental design, then efficiently covers environment syntax, artifacts, runtime cost, and skip_s behavior. Each sentence supplies distinct, useful information without unnecessary background or repetition.

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?

Together with the fully documented input schema and existing output schema, the description provides enough context to configure the experiment and understand its cost and analysis behavior. The main remaining gaps are explicit sibling-tool routing and explanation of the destructive or system-side-effect profile signaled by the annotations.

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%, so the baseline is 3, but the description adds useful operational meaning. It clarifies space-separated env_a/env_b encoding, concrete run naming, how seconds affects elapsed time, how rounds repeats the sequence, and the analysis-only effect of skip_s.

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 opening sentence gives a specific action and scope: record one program under two environments in A B B A order and report per-metric B-versus-A verdicts with supporting values. This clearly conveys the combined recording-and-comparison purpose, but it does not explicitly differentiate the tool from perf_record, perf_compare, or perf_sweep.

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 drift-balancing rationale makes the intended context—controlled A/B performance comparisons—clear, and the runtime estimate helps when deciding how many recordings or rounds to request. It lacks explicit selection guidance, such as when to use perf_compare on existing runs or perf_sweep for broader comparisons, and gives no when-not conditions.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and non-idempotent, so the safety profile is covered. The description adds genuinely new behavior: the target keeps running afterwards, the result matches perf_record's summary, and the post-run export takes minutes under Wine. It omits failure modes such as what happens when the pid/name is not found.

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 sentences, front-loaded with the core behavior and scope, then the launcher caveat. Slightly run-on across line breaks but no filler sentences.

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?

Output schema exists and the description references it by equivalence ('same summary as perf_record'), so return values need no explanation. Given a non-destructive attach tool with full schema coverage, only error/not-found behavior and permission needs are missing.

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%, so all three parameters are already documented, including the default of 20 for `seconds`. The description's 'Game.exe under Wine' example reinforces the `process` semantics but does not add syntax or matching rules beyond what the schema states.

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 ('Records a program that is already running') and adds the scope constraint 'by pid or by a name in its command line', which cleanly separates it from perf_record, the sibling that presumably launches its own target. An agent can tell the two apart without opening a schema.

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?

Explicitly says when to use it: for programs that are already running, and for games launched by Steam/CrossOver/NotProton where the agent must start the game in the launcher first. It stops short of naming perf_record as the alternative for not-yet-running programs, leaving that inference to the reader.

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

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.

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.

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.

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.

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.

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.

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

Annotations already declare destructiveHint=true and non-idempotent, so the safety bar is lower; the description still adds real cost and side-effect context — each recording costs its `seconds` plus about a minute of read-back, and run objects are created under fixed names. It does not say what happens when a reference with that `name` already exists, which is the one mutation detail an agent would 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?

Four dense sentences, front-loaded with the write-and-name behavior before cost details. Nearly every clause carries information, though the read-back timing remark is slightly buried mid-paragraph rather than separated as a cost caveat.

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 19-parameter destructive recording tool with a full output schema, the description covers the action, the artifact naming convention, the relationship to perf_check, and the run-time cost. Return values need not be explained because an output schema exists, and the remaining gap (overwrite semantics) is narrow.

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%, so the schema already documents all 19 parameters thoroughly. The description reinforces `count` (equal recordings, default 3) and the skip_s cut, including that perf_check applies the same cut, but adds little syntax or meaning the schema lacks; baseline 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?

States a specific verb and resource: record the same program `count` times, save as reference `name` for perf_check, and return the per-metric range. It explicitly contrasts with perf_record (whose arguments it reuses) and perf_baseline (whose skip_s convention it follows), plus names the artifact naming scheme (`name`-1, `name`-2), so an agent can distinguish it from every sibling.

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 clearly implied and partly explicit: the reference is built for perf_check, and repeated recording exists to get the range each number spans. It borrows context from perf_baseline and perf_record rather than stating outright when to pick one of those instead, so there is no explicit exclusion, but the routing signal is strong.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description goes far beyond by disclosing the exact verdict logic, that frame pacing, short encoders and GPU idle time are reported but never decide, that cross-OS comparisons fall back to FPS alone, and that a skip_s reference trims the run's first skip_s seconds (reported as skipped_s). It also says what is returned: the reasons plus perf_compare's full comparison against the reference's first run.

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 purpose is front-loaded in the first clause and the rules follow in a logical order, with the caveats (non-deciding metrics, cross-OS, skip_s) after the core logic. It is a dense single block of prose, but each sentence carries distinct behavioral information rather than restating the schema.

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?

An output schema exists, so return values need no further explanation, and the description still names the shape of the verdict and returned reasons. For a tool that compares recordings across platforms and time windows, the description covers the decision rules, the exceptions, and the baseline prerequisite without gaps.

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 100%, so both required params and margin_pct are already documented in the schema. The description adds real meaning for margin_pct by explaining it applies to both the FPS floor and the GPU-ms-per-frame ceiling, but it adds nothing for run or baseline beyond what the schema already says.

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: 'Judges a recording against a reference saved with perf_baseline', then enumerates the exact decision rules (FPS under the reference's lowest by more than margin_pct, GPU ms per frame over its highest, encoder/command-buffer counts). It also distinguishes itself from perf_baseline (which saves the reference) and from perf_compare (whose full comparison it returns).

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?

Makes clear the prerequisite (a reference created by perf_baseline) and the conditions under which a run is judged regressed, improved, or same, including the cross-platform Windows/Metal special case. What it does not do is explicitly route the agent away from perf_compare or perf_gate when a raw comparison or a pass/fail gate is wanted, leaving that inference to the sibling names.

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

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

Annotations only say readOnlyHint and openWorldHint=false; the description goes well beyond by disclosing the diagnostic flags it emits (layer, measure, screen, skipped_s), the short-recording threshold that alters the comparison, and exactly which metrics are recomputed under skip_s versus which remain whole-run. That level of disclosure about conditional result semantics is unusual and directly useful for interpreting output.

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 first sentence front-loads the purpose and headline metrics, and subsequent clauses each carry a distinct conditional fact rather than filler. It is dense to the point of being hard to scan (no lists, minor typos like 'a the reference'), but almost no sentence could be deleted without losing a conditional rule.

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 read-only comparison tool with an output schema and two required name parameters, the description covers source of names, comparison semantics, the three cases where the comparison is not apples-to-apples, and the effect of each optional parameter. Nothing an agent needs in order to call it correctly or interpret a flag is missing.

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 100%, so the baseline is 3, but the description adds real meaning beyond the schema for skip_s: thermal state, process memory and encoders stay whole-run while GPU numbers, hitches and Metal memory are recomputed, and skipped_s reports the exclusion. It also ties markdown output to a concrete use (PR comment) and restates short_us's role only lightly.

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 opens with a specific verb and resource: compares two saved recordings from perf_runs, with 'a' as the reference and 'b' as the post-change run, and it enumerates what is compared (FPS, GPU ms, frame pacing, memory, encoder counts, GPU idle). An agent can distinguish this from perf_runs (listing) and from capture tools 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.

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

It gives explicit conditional guidance: recordings under 100 frames are flagged as not comparable, different translation layers mean layer-vs-layer comparison, a Windows-vs-Metal pair should be judged on FPS/lows/stutter/jitter, and a locked-vs-unlocked screen makes FPS non-comparable. It lacks routing against nearby siblings such as perf_ab, perf_gate or perf_check, so the alternative-selection guidance is strong on data conditions but absent on tool selection.

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

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; the description adds genuine context by disclosing the verdict's decision basis (short-encoder share, encoders per frame), reference values from bgfx 17-drawstress on an M1 Pro under Mullion vs native Metal, and an important interpretation caveat that idle time must be read alongside FPS because a vsync-bound program also idles.

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 verdict and evidence list are front-loaded in the first sentence, with the interpretation caveat and the reference numbers following. It is dense but every sentence carries decision-relevant information; the M1 Pro benchmark sentence is long but functions as calibration rather than filler.

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 an output schema present, the description need not enumerate return values, and it correctly focuses on the decision logic, interpretation caveat and reference thresholds. For a four-parameter read-only diagnostic tool this is close to sufficient, missing only explicit routing versus sibling diagnostics.

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 100%, so baseline is 3, but the description earns extra credit by giving concrete calibration values (7 encoders/frame and 50% short under Mullion versus 2 and 2% in native Metal) that tell the agent what magnitudes of short_us, short_share and min_encoders are meaningful. It does not restate the per-parameter defaults that the schema already documents.

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 opens with a specific verdict ('says whether a saved recording splits its GPU work into too many short encoders') plus the secondary axis it inspects (translation layers like DXMT/Mullion/MoltenVK) and the evidence it returns. An agent knows exactly what question this tool answers. It stops short of naming a sibling (e.g. perf_compare or perf_check) to draw the boundary 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?

Usage is implied: the tool takes a run name from perf_runs, so it operates on already-recorded data, and the vsync/idle-time note tells the agent how to interpret results. But there is no explicit when-to-use versus perf_compare, perf_check or perf_baseline, nor any stated prerequisite beyond the run parameter.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=true and openWorldHint=false, so the safety profile is covered; the description adds real value beyond that by naming the output path/filename pattern and disclosing a subtle caveat that a frame's GPU time can be shorter than its wall time when encoders run in parallel. It stops short of stating overwrite behavior for a pre-existing trace file, which would complete the picture.

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 that opens with the action and artifact before descending into slice semantics. It is dense but nearly every clause carries information; the trailing phrase 'with the compute, fragment and vertex split as arguments' is the weakest and slightly ambiguous part.

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 one-parameter tool with an output schema and full annotations, the description covers the output location, format compatibility, and the meaning of the trace contents. Only the runs-directory location and existing-file overwrite semantics are left unstated.

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?

There is only one parameter and schema description coverage is 100%, with the schema itself explaining that 'run' is 'a run name from perf_runs'. The description adds no further syntax or format detail, so the schema is doing all the work and baseline 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?

States a specific verb ('Writes') plus a precise resource ('a recording's GPU frames as a Chrome trace file') and names the exact artifact produced. An agent can immediately distinguish this file-producing export from sibling query tools like trace_query, trace_tables, and capture_summary.

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: the mention that ui.perfetto.dev and chrome://tracing can open the output hints that this is for visual inspection, but the description never says when to prefer this over trace_query or capture_summary, nor when not to use it. No prerequisites (e.g. that a run must already be recorded) are stated.

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

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.

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.

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.

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.

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.

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.

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

Annotations only declare readOnlyHint and openWorldHint, so the description carries the real behavioral load and does so: it states the sort order ('oldest first'), the cross-platform comparability caveat ('Runs from Windows and Metal in one series are flagged: their GPU ms and memory do not compare'), and the noise-floor interpretation rule. These are non-obvious traits an agent could not infer from annotations or schema.

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?

Verb and resource are front-loaded and nearly every clause carries information (ordering, metrics, delta, noise threshold, platform caveat, skip semantics). It is a single dense paragraph whose parentheticals ('the start-up', the translation-layer example) border on redundant given the schema, but nothing is 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?

With an output schema present, return values need not be explained, and the description still covers ordering, comparability caveats, and the interpretation rule that an agent would otherwise miss. The remaining gap is the limit/sort interaction (capped at the newest N but reported oldest-first), which affects how a caller reasons about truncation.

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 100%, and the description largely mirrors it — skip_s as 'the start-up' seconds with recomputed metrics is already spelled out in the schema, and prefix semantics are already there. The one genuinely additive phrase is ordering ('oldest first'), which is not a parameter but interacts with limit ('newest runs to keep, default 50'); the description does not explain that tension.

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?

Opens with a specific verb and resource ('Lists the recordings whose name starts with `prefix`') and then names the exact output content (FPS, 1% low, GPU ms, stutter, hitches, peak Metal MiB) plus the first-to-last delta. It also frames the intended shape of the series ('one recording per version of a translation layer'), which separates it from one-off tools like perf_compare or perf_baseline that it explicitly references.

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?

It gives a clear usage context — following a number across a series of runs — and an interpretive rule ('Read a trend as real only when it exceeds the spread_pct that perf_baseline reports for equal runs'), which is real when-to-use guidance. What it lacks is an explicit exclusion: it never says when an agent should choose perf_compare or perf_ab instead of this tool, only that skip_s behaves 'as perf_compare does'.

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

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

Beyond the annotations, it discloses the real behavioral traits: a file is written into the runs directory, the file is self-contained and loads nothing from the network, and — most importantly — the `layout` argument is persisted as panel.json and becomes the default tab order for every panel, including the live one, until a viewer changes it. That global side effect is exactly the kind of context annotations cannot carry. It stops short of saying what happens on name collision or overwrite of an existing panel.

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?

Content is front-loaded on the artifact, which is right, but the body is a dense run-on with stacked clauses ('The file holds the data itself, no path, and loads nothing from the network') and buries the significant layout/persistence side effect mid-paragraph. Several fragments ('no path', 'A against B') cost parsing effort without adding precision.

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 five-parameter write tool it covers everything an agent needs: required inputs, file destination and naming, all preset and layout consequences, and even the return payload (file name, runs, frames shown, byte size) which is also backed by an output schema. Nothing material is missing given the annotation and schema richness.

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 100% so the baseline is 3; the prose adds genuine meaning on top by giving the tab id vocabulary (summary, ab, frames, encoders, counters, memory, data), the semantics of omitted ids (hidden but switchable back on), the persistence behavior of layout, and the fact that a hand-written or copied panel.json works identically. skip_s and preset meanings largely restate the schema rather than extend it.

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?

Opens with a concrete verb and artifact: 'Writes one HTML file, `<name>.panel.html` in the runs directory', then enumerates exactly what the artifact shows (GPU time per frame with hitches, FPS/lows/jitter/stutter/memory/thermal, Metal memory, A vs B). It also anchors itself to siblings by name ('as perf_compare does', runs 'from perf_runs'), so an agent can separate this from perf_ab/perf_compare without reading schemas.

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 makes clear what the output is for (viewing one or two recordings in a browser without a server) and explains which preset fits which case ('compare' needs two runs), but it never states when an agent should choose this over perf_compare, perf_ab or the live panel. Usage is implied from the artifact type rather than routed explicitly.

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

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.

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.

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.

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.

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.

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.

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered for free. The description contributes two genuinely new facts: result ordering ('newest first') and which metrics are surfaced per row; however, enumerated row fields are largely redundant with the existing output schema, and pagination/truncation behavior is never mentioned.

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 verb and resource plus the ordering guarantee, then the payload. Nothing is padding and nothing essential is buried.

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?

A read-only, two-param list tool with a full output schema and complete annotation coverage needs little more than this, and the description covers scope, ordering and payload. The only real gap is whether more pages exist beyond the returned window and how callers should page through large result sets.

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%, so both `limit` (default 50, max 500) and `offset` (default 0) are already fully documented with defaults and bounds. The description adds nothing about paging strategy or ordering interaction with offset, so the baseline 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?

The description gives a specific verb+resource ('Lists the saved recordings') and enumerates what each row contains (frames, FPS, GPU ms/frame, memory peaks, translation layer), so there's no ambiguity about what the tool returns as opposed to perf_record or perf_compare. It stops short of naming a sibling it is not, which keeps it at 4 rather than 5.

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 by 'Lists the saved recordings' – an agent can infer this is the read-only inventory tool, but the description never says when to reach for it over perf_baseline, capture_records or perf_compare, nor any exclusions. No explicit when/when-not guidance is present.

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

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

The annotations only declare destructive/not-idempotent; the description goes well beyond them by disclosing real cost ('each takes its seconds plus about a minute to read back'), a hard budget ('at most 5 and at most 24 recordings in all'), the interleaved reverse-order scheduling used to spread drift, and the naming scheme of every run created. These are exactly the traits an agent needs before committing an expensive mutation.

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 purpose is front-loaded in one long sentence, but that sentence crams in return-value detail (FPS, 1 % low, GPU ms, stutter, slope and r2) that an output schema already covers, and the phrasing is compressed to the point of ambiguity ('1 % low', 'the straight line GPU ms per frame follows'). Useful content, but not tight.

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 21-parameter, destructive, long-running sweep the description supplies the critical operational facts: time cost, recording budget, ordering strategy, artifact naming and the memory=false speed trade-off. With an output schema present, return-value explanation is optional, and only the sibling-routing advice is genuinely absent.

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%, so parameters are already documented and the baseline is 3. The description adds only marginal meaning beyond the schema — chiefly the run-naming template tying `name` to values and rounds, and the reversal semantics of `rounds` — while most parameter behavior lives in the schema text.

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 opening clause states a specific verb and resource: 'Records the same program once per value of one variable', which immediately separates it from a single-run tool like perf_record. The enumerated variable space (dim, example, api, size, env:NAME) and the per-value aggregation make the sweep semantics unmistakable, though no sibling is named explicitly to complete the contrast.

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 implied by the parameter-space enumeration and by notes like 'with rounds above 1...' and 'with 3 or more numeric values', so an agent can infer when the tool fits. However, nothing states when to choose perf_sweep over perf_ab, perf_compare or perf_baseline, and no prerequisites (e.g. needing workload_fetch first) appear in the description itself.

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

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

Goes well beyond annotations: names the network source (GitHub release), discloses SHA-256 verification against a pinned hash, gives the on-disk location (%LOCALAPPDATA%\metal-gpu-trace), and states the privilege requirement (admin or Performance Log Users group). This is exactly the auth/network/artifact context annotations cannot convey, and it is consistent with readOnlyHint=false/openWorldHint=true.

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?

Front-loads the platform constraint and packs platform, source, verification, destination, reuse semantics, and privileges into three dense sentences with no filler. Slightly long and run-on in the first sentence, but every clause carries distinct information.

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?

Given no parameters, rich annotations, and an output schema to carry return values, the description supplies everything else an agent needs: OS constraint, network dependency, integrity check, install path, idempotency, and privilege prerequisite.

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?

Zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate.

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+resource: downloads Intel's PresentMon console app from its GitHub release and installs it locally. The 'Windows only' qualifier and repeated references to perf_record/perf_attach make it clearly distinguishable from every sibling, which are all consumers rather than installers.

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?

Explicitly states the tool is what perf_record and perf_attach depend on and that later calls reuse the installed copy, so an agent knows to install before recording. It lacks an explicit 'skip this if already installed / use X instead' clause, but idempotentHint and 'later calls reuse it' cover the main decision.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context — counts are aggregated both globally and per process, and zero counts mean a different tool/Xcode is needed — but says nothing about cost, trace size limits, or failure modes when a trace is missing.

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 verb and object, and the rationale clause earns its place by explaining what the counts are for. Only minor cost is the slightly convoluted trailing 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?

Two well-described params, an output schema that carries the return shape, and annotations covering safety — the description supplies the one thing structured fields can't: the interpretive rule that zero rows means a different instrument. Complete enough to call correctly.

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 100%: the trace param already documents the run-name-or-path forms and tables already points at trace_tables with its default. The description adds no parameter-level detail beyond that, so the baseline 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?

States a specific verb and resource: counts rows of tables in a kept .trace, both overall and per process. The triage framing ("so a recording's useful tables show before reading them") makes it distinguishable from the table-listing and querying siblings, though it never names them 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?

"so a recording's useful tables show before reading them" plus the 0-row guidance gives a clear posture: run this as a cheap pre-check before querying, and treat zero-row tables as a signal to switch instruments rather than retry with a larger page. No explicit exclusion or named alternative (trace_query) is given, so it stops short of a 5.

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

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; the description adds genuinely new behavior: results are paginated ('one page'), shaped as {column: value}, and can be scoped to a single process. It stops short of disclosing what happens with an invalid table name or an offset past the end of the data.

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 core behavior (paged row read from one table of a trace) comes first and the optional pid narrowing follows. Nothing could be removed without losing information.

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 an output schema present, the description need not explain return values, and all five parameters are documented in the schema. For a read-only paginated query tool the coverage is nearly complete; only error/edge-case behavior and the trace_tables dependency are unstated.

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%, with limit defaults/maximum, offset default, pid filtering, and the trace_kept/table-name constraints all documented in the schema itself. The description only restates the pid filter ('optionally only one process's rows') and the paging concept, adding little beyond the structured fields, so the baseline 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?

States a specific verb and resource: returns one page of rows from one table of a .trace, plus the return shape ({column: value}) and the optional pid narrowing. It implicitly separates itself from trace_tables (which lists tables) and trace_count (which counts), but never names those siblings, so an agent must infer the division of labor.

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 says what the tool returns but never states when to reach for it versus trace_tables, trace_count, or capture_records. There is no mention of the prerequisite that 'schema' must first come from trace_tables, and no guidance on paging strategy (e.g. advancing offset until a short page). Usage is only inferable from the wording.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds a meaningful behavioral caveat: recordings retain their .trace only when KEEP_TRACE=1, which affects whether this tool can be used at all. It stops short of saying what happens when the trace is absent or not kept.

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 front-loaded sentence with no wasted wording. The KEEP_TRACE=1 clause is relevant but slightly terse and could be mistaken for a condition on this tool rather than on trace retention.

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 read-only listing tool with an output schema, annotations, and full parameter coverage, the description is complete enough to call it correctly. The main missing piece is explicit sibling routing, but the core behavior and trace-retention caveat are present.

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 parameter description already explains that the trace argument can be a run name with trace_kept=true or a .trace path. The tool description does not add format or validation details beyond that. Baseline 3 is appropriate when the schema covers the single parameter thoroughly.

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 and resource: it lists the data tables (schemas) contained in a .trace recording. This distinguishes it from query/count siblings by output type, though it does not name those siblings explicitly. The purpose is clear without opening the schema.

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 a discovery step before querying a trace, but the description gives no explicit when-to-use guidance or comparison to trace_query or trace_count. The KEEP_TRACE=1 note is a retention prerequisite rather than routing guidance.

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

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

Annotations already declare idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the description's job is mostly to add context. It does: network fetch from GitHub, SHA-256 integrity verification against a pinned hash, and a specific cache path in ~/Library/Caches/metal-gpu-trace. It omits what happens on checksum mismatch or offline failure, which keeps it from a 5.

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?

Three sentences, front-loaded with the action and integrity check, followed by cache location and reuse semantics. The provenance sentence about the workloads workflow justifies trust in the binary rather than padding, and no sentence is redundant.

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 rich annotations and an output schema present, the description covers the essential mechanics: source, verification, cache location, and idempotent reuse. The remaining gap is failure behavior (checksum mismatch, no network), which matters for an open-world download but is a modest omission.

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 single `name` parameter is documented in the schema with an example and a pointer to workload_list. The description itself adds no parameter guidance, so the baseline of 3 is appropriate given the schema carries the load.

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 names a specific action and resource: downloading a test program from the project's GitHub releases, verifying its SHA-256, and caching it locally. An agent can distinguish this from read-only siblings like workload_list or perf_run because the caching and download behavior is stated. It stops short of explicitly directing agents to workload_list for valid names, which would sharpen differentiation.

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?

'later calls reuse it' implies the tool is safely re-invoked and that a first call seeds the cache, which is useful implied guidance. However, there is no explicit when-to-use instruction (e.g. 'call before perf_run if the workload is not cached') and no stated alternatives or exclusions relative to workload_list or presentmon_install.

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

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. The description adds useful context about what is enumerated, including the 'whether it is already downloaded' state, which tells the agent results reflect local state rather than a static catalog. No mention of caching or freshness, keeping it from a 5.

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 the resource first and the informative payload (measures, size, license, APIs, download status) following. No filler or restated title.

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?

An output schema exists, so return structure need not be explained; the description still summarizes the fields, and for a zero-parameter read-only list tool nothing an agent needs to invoke it correctly is missing.

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 tool takes zero parameters, so per the baseline there is nothing for the description to disambiguate. Schema coverage is 100% and the description correctly implies a parameterless call.

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 ('Lists the test programs workload_fetch can download') and even gives a concrete example (bgfx's drawstress). It clearly positions itself as the enumeration counterpart to the sibling workload_fetch, so an agent can distinguish them without opening schemas.

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?

By tying the listing to 'programs workload_fetch can download,' it implicitly tells the agent to call this first to discover valid workload names before fetching. It does not explicitly state when-not to use it or name alternatives beyond workload_fetch, so it falls short of a 5.

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