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., "@pix-mcp Show the top 5 most expensive GPU events in the last capture."
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.
An MCP server for Microsoft PIX for Windows GPU/timing captures and GDK PIX Xbox GPU captures.
It drives pixtool.exe, PIX's own CLI, so anything PIX can do headlessly is reachable here. Every one of pixtool's 24 commands is covered by a tool, plus an escape hatch (pix_run_pixtool) for raw pipelines. On top of that, pix-mcp adds the parts pixtool leaves to you: an artifact cache (a 4.5 GB capture takes ~18 s to open, every time), paged responses, id-based navigation, and correct handling of two pixtool behaviours that are easy to get silently wrong (see pixtool quirks).
pixtool is not all of PIX, though. The queue list, the resource table, and the Pipeline State view exist only in the UI — there is no command for any of them. And pixtool can record a timing capture but has no command that opens one, so the CPU/GPU timeline was unreadable headlessly. So pix-mcp also ships a small C# sidecar that hosts PIX's own analysis engines in-process, which is where deep analysis and timing captures come from. It is optional: without it everything else still works.
Windows-only, by nature of PIX.
Requires Python 3.10+ and PIX for Windows. The server finds pixtool.exe under C:\Program Files\Microsoft PIX\<version>\, preferring the newest install.
pip install -e .Add it to an MCP client — for Claude Code:
claude mcp add pix -- pix-mcpOr, without installing, point at the checkout:
{
"mcpServers": {
"pix": {
"command": "python",
"args": ["-m", "pix_mcp"],
"env": { "PYTHONPATH": "C:\\path\\to\\pix-mcp\\src" }
}
}
}Start any session with pix_get_server_status; it reports which PIX installs were found, whether pixtool answers, and the current limitations.
The deep-analysis tools and the timing-capture tools go through bridge/, a C# sidecar that loads PIX's own analysis assemblies. Building it needs the .NET 8+ SDK and a local PIX install:
dotnet build bridge/pixbridge.csproj -c ReleaseOr ask the server to do it: pix_build_bridge. pix_get_bridge_status says whether it is available and why not. Everything else works without it.
Xbox captures use GDK PIX, not the Windows pixtool.exe. The server recognizes the
3XIP container and its GPU platform tag, reports capture_kind: "xbox_gpu", and
routes it to an independent xbox-bridge/ process. Install the Microsoft GDK and
the .NET 8 Windows Desktop runtime plus a .NET 8 or newer SDK, then build:
dotnet build xbox-bridge/pixbridge-xbox.csproj -c Release
# For a nondefault GDK location:
dotnet build xbox-bridge/pixbridge-xbox.csproj -c Release '-p:GdkPixDir=C:\GDK\bin'The same build is available as pix_build_bridge(platform="xbox"). Check it with
pix_get_bridge_status(platform="xbox"); server status reports Windows and Xbox
availability independently. SDK assemblies and capture files are not included in Git.
The workflow is:
pix_open_capture(capture_path="C:\\captures\\GPU 1.xpix").
Read pix_list_queues, pix_list_gpu_events, pix_list_resources and the stored
screenshot with pix_save_screenshot. These do not start GPU replay.
Call pix_start_analysis(capture_id=..., device_address="<devkit IP>") to authorize
replay. The address must match the analysis device configured in GDK PIX.
Replay can interrupt the title running on that devkit. wait_seconds=0 starts
it without waiting; subsequent calls poll the same replay.
Windows-only pix_open_capture flags, including remote, are rejected for Xbox.
Once ready is true, collect exact counter names, rank timings, inspect pipeline
bindings, and export RTV/depth PNGs with pix_save_resource(global_id=..., rtv=0, ...).
pix_close_capture releases the native document. LRU eviction and file changes
also release it. A hung bridge is terminated so later requests can recover.
Xbox timing uses the GDK's nanosecond counters, reported as time_unit.
Use leaves_only=true for timing rankings: API draws and their native child events
can carry the same duration. Queue-relative index and native global_id are
different IDs; pipeline queries use the former and resource exports the latter.
Xbox capability | Support |
Event paging/search/tree and CSV export | Supported, with cached repeat queries |
Counter catalog and selected per-event counters | Supported; select at most 64 new counters per call |
GPU replay and timing ranking | Explicit devkit selection required |
Resource descriptors and names | Supported |
Pipeline resource bindings and slots | Supported after replay |
Stored screenshot and bound RTV/depth export | PNG; resource export requires an explicit |
Floating-point texture PNG | PIX-rendered display visualization; values can clip to the display range |
Root-signature layout and complete resource view history | Not implemented; returns |
Windows pixtool-only operations, Xbox live capture/recapture | Not implemented by this backend |
The GDK adapter uses the local SDK's Automation runtime plus internal document and request types, so compatibility must be rechecked after a GDK update. Compatibility testing covers a limited set of SDK builds and Xbox GPU capture variants; other versions and variants require separate validation.
Variable | Purpose |
| Full path to a specific |
| A PIX install directory to search instead of the default locations. |
| Where extracted artifacts live. Defaults to |
| Per-invocation pixtool timeout. Defaults to 1800. |
| Open captures kept before the least-recently-used is evicted. Defaults to 8. |
| Full path to |
| Per-request bridge timeout. Defaults to 300. |
| Set to |
| Set to |
| GDK |
| Full path to |
| Set to |
Related MCP server: RenderDoc MCP
Tool | |
| Register a |
| Frame, event, and category statistics. |
| Find which named contexts the capture exposes. |
| Session bookkeeping. |
Tool | |
| Paged event list, filterable by category or name. |
| Glob search over event names. |
| One event by global id, with its ancestry. |
| Depth- and node-bounded hierarchy. |
| Write the full CSV somewhere you choose. |
Tool | |
| The catalog, grouped and searchable (2,365 counters on an RTX 5080). |
| Rank events by a counter; picks a duration counter if you don't name one. |
| Attach chosen counter values to events. |
| Turn a counter name into the regex that selects it. |
| Time-series counter capture to CSV. |
Through the bridge, not pixtool. Each of these answers something pixtool has no command for, and none of them re-open the capture.
Tool | |
| The real queue table: id, name, type, event count. |
| Events from one queue, optionally with the decoded D3D12 call and its arguments. |
| PIX's resource table — every texture and buffer, with dimensions, format, and debug name. |
| One resource in full: descriptor, heap, initial state, view summary. |
| Every view of a resource and the events that bind it — where a texture is actually used, and as what. |
| PIX's Pipeline State view for one event: program type, root signature, bound views. |
| The binding layout alone, when the bound-view detail is noise. |
| Replay the capture on a GPU, which is where PIX's timing comes from. ~25 s for a 4.5 GB capture, once. |
| Per-event GPU timing off that timeline: start and duration for every event in a queue, ranked by cost on request. |
| Bridge health and one-command build. |
pix_get_event_timing is the cheap way to find the expensive work in a frame.
pix_get_counter_hotspots replays the capture once per counter; this replays it once for
everything, then reads a timeline that already exists. The ranking is dominated by marker
scopes — Frame, then Scene, then PostProcessing — which is the shape of the frame;
leaves_only ranks the individual draws and dispatches inside instead.
.wpix names two unrelated file formats. A GPU capture is one frame, frozen and replayable — PIX's own GFXA container, and what every tool above reads. A timing capture is seconds of the whole machine's CPU and GPU timeline, and it is a SQLite database. Nothing that reads one can read the other, which is why PIX's GPU-capture API rejects a timing capture with SQLITE_NOTADB rather than a format error. pix_open_capture tells them apart by their header — the extension settles nothing — and reports capture_kind; a tool handed the wrong kind says so by name instead of failing somewhere deeper.
pixtool records these (pix_capture_timing) and cannot open them. The bridge can: PIX's timing views run on a managed assembly beside pixtool, and it turns out to run standalone — no UI, no GPU, no document.
Tool | |
| The window, the machine, and which tables actually have data. Start here. |
| Every process alive during the capture, busiest first — a timing capture is machine-wide. |
| One process's threads, with what was recorded for each. |
| Where one thread's CPU time went: when it ran, and on which core. |
| Every time a thread came on or off a core, and the wait reason it left for. |
| The inverse view: everything that ran on one core, whoever owned it. |
| The GPU queues the capture saw. |
| Named PIX scopes on a thread or a queue, with nesting. |
| The present timeline, one row per frame, plus frame pacing over the page. |
| What the GPU made resident, evicted, or paged — and which object it was. |
| Counters reported live during the capture, per process. |
| Disk activity: which device, which file, how long it blocked. |
| One thread's page faults, hard ones separated from the cheap kinds. |
| Any metric as a series over time: a counter's values, one core's utilisation, one process's video memory. |
| Named D3D12 work on one thread — a pipeline compile, a resource creation — as spans. |
| Which command lists a queue executed, and which of them went in on one |
| Allocations the driver migrated between heaps, or demoted out of video memory for good. |
| Lanes the title recorded itself, plus PIX's own per-monitor VSync train. |
| Controller reads — where an end-to-end input-latency measurement starts. |
pix_get_context_switches is the one that separates a thread that is slow because it is
computing from one that is slow because it is blocked — a distinction a sample count cannot
make, since a blocked thread simply produces fewer samples and looks idle. File I/O, page
faults and residency are the same argument in three other places: a thread waiting on a
synchronous read is off-core and reads as idle, and an allocation evicted and paged back over
PCIe costs milliseconds on a frame whose draw calls are unchanged. None of it is visible in a
GPU capture at all.
pix_get_core_activity answers the question the per-thread tools cannot: not "where did my
thread's time go" but "was this core mine at all". It reports idle_share_of_page separately
from busiest_process_share, because process 0 is Windows' Idle process — counting it as the
busiest would turn "this core was a third idle" into "something else owned a third of this
core", which is the opposite finding.
pix_get_metric_values is the other half of that answer, and the only tool here that returns a
series rather than a list of events. The same core can be asked about twice — once for one
process, once for all_processes — and the gap between the two answers is exactly how much of
a busy core belonged to somebody else. The other lanes are the counters over time (the catalog
pix_list_timing_counters returns is only their definitions), and per-process video memory.
Latency is reachable here and nowhere else. A GPU capture is one frame with no before and
no after, so it cannot contain the span a player actually feels. A timing capture can:
pix_get_controller_input timestamps the read, pix_get_gpu_frames timestamps the present,
and the monitor lane in pix_get_custom_data timestamps the VSync that put the result on the
display. PIX's own Dynamic Latency Instrumentation, when a device has it, anchors the first of
those to the hardware rather than inferring it — latency_instrumented on
pix_list_controllers says which.
Times are nanoseconds on the capture's own clock, and every window argument is in those
units. pix_get_timing_summary reports both duration_seconds (first event to last) and
recorded_seconds (the requested recording window); they differ because trailing ETW events
land after the stop.
What was verified how. Checked against real rows on real captures — a 144 MB attach to a
running Unreal editor and a 1 GB 180-second launch capture, the latter reading 17.6 M context
switches: the summary, process, thread, CPU-sample, context-switch and GPU-queue queries;
pix_list_timing_counters (12 counters, Local Budget / Local Usage / Local Resident in
MB, grouped per adapter); pix_get_core_activity (3,080 samples on core 0, cross-process, and
a core 63.8% owned by a process that was not the captured title); and
pix_get_residency_operations (4 MakeResident rows naming an nv.sl.chi.heap.gpu descriptor
heap).
Also on real rows:
pix_get_metric_values on the counter lane, checked against the bytes rather than against
PIX: the Local Budget counter for the discrete adapter returns 15947.792384 MB, and
decoding the PixCounterRange blob out of the capture's own table gives the same double.
That is the RTX 5080's 16 GB. Ask for it by metric_id from pix_list_timing_counters and
by that capture's ids — the same machine numbers its adapter groups differently between two
recordings, so the counter that is 7 in one is 1 in the other.
The same tool on the cpu_usage lane, over all 85 samples of the 8.9-second capture at its
100 ms cadence: core 0 averaged 30.9% across every process and core 12 averaged 75.2% —
the same imbalance pix_get_core_activity found from the other direction. Asking again with
process_id instead of all_processes is what makes it a finding: the captured editor
accounts for 8.1% of core 0 but only 1.2% of core 12, so that core was busy with
somebody else almost entirely.
pix_get_custom_data on the monitor lane: 10,879 VSync markers over 180 seconds, reported
as 16.666 ms median / 60.0 Hz — and a longest interval of 33.346 ms, which is exactly two
refresh periods, so the display missed one. On the shorter capture the longest gap is
49.995 ms, three periods. pix_list_custom_data_types names the lane
Monitor #1 (NVIDIA GeForce RTX 5080).
pix_get_api_objects: one span, Pipeline State Compilation, 177.7 µs — on one thread out
of the 554 that process had.
pix_get_metric_values on the api_object_memory lane: the captured editor's D3D12 objects
grew 131,072 → 196,608 bytes, which is the sum PIX records against those objects. Every
other process on the machine returns an empty series with its reason, which is the correct
answer for a process that never created a D3D12 object.
The API object result is also the caveat. pix_get_timing_summary reports api_objects: true
from the object catalog, but the events are per thread and there may be a single one in the
whole capture, so querying an arbitrary thread returns nothing and looks broken.
api_object_events on each pix_list_timing_threads row is how to find a thread that has any,
and the empty answer says so.
The rest run clean and return S_OK with zero rows on every capture obtainable here, for
reasons that are facts about the recording rather than about the code:
pix_get_thread_timeline, pix_get_gpu_timeline, pix_get_gpu_frames and the PIX-marker
path need a process that calls PIXBeginEvent and presents a D3D12 swapchain. No
PIX-instrumented title was available to capture.
pix_list_storage_devices, pix_get_file_io, pix_get_page_faults and the two device
lanes of pix_get_metric_values need ETW providers that pixtool take-new-timing-capture
cannot enable — its only options are --duration, --sampleRate, --noCpuSamples,
--noCallstacks and --noGpuTimings. Confirmed by scanning 129 threads across six
processes for a single page fault, and by both captures reporting zero storage devices. A
capture recorded from the PIX UI with file I/O turned on will populate them.
pix_get_command_lists, pix_get_allocation_moves, pix_list_controllers and
pix_get_controller_input have empty source tables in both captures:
ApiQueueExecutionCommandList, AllocationMigrations, DemotedAllocations, InputDevice
and InputMarkerRange all hold zero rows. No controller was attached, video memory was
never short, and neither capture carries GPU timings.
Those last row counts are counted, not inferred, and that is worth stating because it is the
one place this file format helps: a timing capture is a SQLite database, so
tools/probe_capture_tables.py opens it with Python's own sqlite3 and counts the table
directly. "The query found nothing" and "there is nothing to find" are different claims, and
this is the only part of the surface where the second one can be checked without going through
PIX at all. Field mapping for the still-unpopulated tables above comes from PIX's own query
metadata rather than from observed rows. Each returns a note explaining which kind of empty it
is, so an empty answer is never ambiguous between "no data" and "broken".
Two things about recording, both learned the hard way: a process pixtool launch starts
dies when pixtool exits, so launch and capture must be one command line; and attaching to
an already-running process gives you the full CPU tables but no GPU frames and no PIX
events, because D3D12 instrumentation has to be in the process before it creates its device.
pix_run_debug_layer · pix_collect_occupancy · pix_perform_playback · pix_recapture_playback · pix_recapture_region
pix_save_screenshot · pix_save_resource · pix_export_to_cpp · pix_upgrade_capture
pix_capture_app · pix_capture_uwp_app · pix_capture_attached_process · pix_capture_programmatic · pix_capture_timing
These launch or attach to a process, so they are annotated openWorldHint. pixtool has no daemon: launching a target and capturing from it must happen inside one pixtool process, which is why these are single tools rather than a launch/capture pair.
pix_run_pixtool builds an arbitrary command pipeline. Use it for anything the typed tools don't reach.
These cost real time to discover, and both fail quietly — worth knowing whether or not you use this server.
--counters takes a regular expression, not a glob. pixtool expands * to .* and then runs a case-sensitive regex_search. So a name copied straight out of list-counters usually matches nothing: TOP to EOP Duration (ns) reads as a group around a literal ns, and . matches any character. You get an empty column rather than an error. pix-mcp escapes and anchors names passed as counters, so they select exactly themselves; counter_regexes takes raw patterns when you actually want a family. An unbalanced paren is worse — it surfaces as an opaque PIXTOOL99999 ... 0x8000ffff that aborts the rest of the pipeline, after the capture open has been paid for, so patterns are validated up front.
Quotes must open after the =. pixtool parses the raw command line itself rather than going through CommandLineToArgvW, and only honours a quote that begins after the =. --queue-name="3D Queue" parses; "--queue-name=3D Queue" — which is what Python's subprocess list quoting produces — is rejected as an invalid command line. pix-mcp quotes the value, not the token. A value containing a double quote cannot be expressed at all, so those are rejected with an explanation rather than silently mangled.
Two smaller ones: a failing command aborts the remaining commands in the pipeline, so batched extraction puts the most important command first; and pixtool exits non-zero even when --help succeeds.
Every query re-opens the capture. pixtool has no interactive mode, so a "session" here is bookkeeping plus a cache directory, not a live process. Opening the 4.5 GB reference capture costs ~18 s — and roughly 90 s each if four opens run concurrently, so the server does not parallelise them. Artifacts are cached under a fingerprint of path, size, and mtime; repeat queries return in milliseconds, and editing the capture invalidates the cache.
Except through the bridge, which keeps it open. The sidecar holds the document, so the same 4.5 GB capture opens once in ~0.3 s and every query afterwards is effectively free. That is why the deep-analysis tools are not cached: there is nothing to amortise. It stays a separate process rather than a Python binding because the API is COM-with-C#-extensions, and because a crash in PIX's engine should not take the server with it.
The bridge hosts two engines, not one. A GPU capture goes through the COM document API; a timing capture goes through Microsoft.PIX.Core's managed query engine over the SQLite file. They share only the sidecar process and the handle table, so pix_open_capture has to decide which one a file belongs to before it can open it at all — hence the header sniff rather than a trial open, which on a 4.5 GB file would cost 18 seconds to learn nothing.
Responses are small by default. Lists are paged, text is chunked, and events are addressed by global_id, so an agent can navigate a large capture without flooding its context.
Errors are data. A failed tool returns {"ok": false, "error": {"code", "message", "details"}} with a message that says what to do next, rather than a transport-level failure.
Counters are expensive. Each matched counter costs another replay pass, which is why the default is exact selection rather than a wildcard.
pip install -e . --group dev # or: uv sync
pytest
ruff check .
mypytests/test_server.py holds the parity check: a table mapping all 24 pixtool commands to the tool that covers each. Add a command to pixtool and nothing covers it, and that test fails.
The tests are hermetic — no PIX install needed. tools/smoke.py is the end-to-end run against a real capture:
tools/smoke_full.py launches an independent server and exercises the real MCP
stdio transport. It checks nonempty results, event/CSV consistency, numeric
counter values, paging, cache reuse, PNG headers/dimensions, expected errors and
native handle release. It writes each result and report.json; an unexpected
failure exits nonzero. Choose a fresh output directory for a cold-cache run.
Image contents still need visual inspection; a valid PNG alone cannot prove a
texture is meaningful.
python tools/smoke_full.py 'C:\captures\GPU 1.xpix' --device-address '<devkit IP>' --output-dir '_probe/full-xbox'
python tools/smoke_full.py 'C:\captures\GPU 1.wpix' --output-dir '_probe/full-windows'
python tools/smoke_full.py 'C:\captures\timing.wpix' --output-dir '_probe/full-timing'The earlier scripts are useful for narrower probes:
python tools/smoke.py "C:\path\to\capture.wpix"
python tools/smoke_mcp.py "C:\path\to\capture.wpix" # through FastMCP
python tools/smoke_analysis.py "C:\path\to\capture.wpix" # the bridge-backed tools
python tools/probe_timing_bridge.py "C:\path\to\timing.wpix" # the timing engine
python tools/probe_timing_objects.py "C:\path\to\timing.wpix" # objects, metrics, input
python tools/probe_objects_via_mcp.py "C:\path\to\timing.wpix" # the same, as tools
python tools/probe_capture_tables.py "C:\path\to\timing.wpix" # row counts, via sqlite3tools/probe_*.py are the scripts used to establish the pixtool behaviours above, kept because they are how you'd re-verify them against a future PIX release.
MIT
Compile the pixbridge sidecar. Needs the .NET SDK and a local PIX install.
| Name | Required | Description | Default |
|---|---|---|---|
| platform | No | windows | |
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover idempotence and non-destructive safety. The description adds prerequisite dependencies, which is useful behavioral context, but it does not mention build side effects, output artifacts, or what happens on failure. No contradiction with annotations 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 description is a single, focused sentence with the action front-loaded and no filler. Every word contributes either to the core purpose or to essential prerequisites.
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?
It covers the core action and prerequisites, and an output schema exists to describe results. However, missing parameter semantics and lack of detail about build outputs or failure conditions leave some gaps for an agent deciding how to invoke the tool.
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 0%, and the description says nothing about 'platform' or 'timeout_seconds'. The parameter names and defaults provide minimal clues, but valid platform values and timeout behavior are left undocumented.
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 uses a specific verb and resource: 'Compile the pixbridge sidecar.' This clearly distinguishes it from the many sibling tools, which are all capture/analysis operations, and there is no other build tool among them.
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 gives important prerequisites ('.NET SDK' and 'a local PIX install') but does not explicitly state when to use this tool or when to avoid it. Usage is implied by the unique compile action rather than clearly contrasted with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Launch a D3D12 executable, take GPU captures, and save them.
| Name | Required | Description | Default |
|---|---|---|---|
| winml | No | ||
| frames | No | ||
| remote | No | ||
| setenv | No | ||
| executable | Yes | ||
| capture_key | No | ||
| force11on12 | No | ||
| output_file | No | ||
| command_line | No | ||
| capture_count | No | ||
| timeout_seconds | No | ||
| output_directory | No | ||
| working_directory | No | ||
| capture_from_start | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is not read-only and not idempotent. The description adds that launching an external executable and saving capture files are the side effects. It does not contradict the annotations, but it leaves out important behavioral details such as output locations, capture termination, timeouts, and effects on the launched process.
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 is a single, front-loaded sentence with no filler. It is easy to parse and communicates the main action efficiently, though the brevity contributes to the lack of parameter and usage detail.
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 tool with 14 parameters, no schema descriptions, and side-effectful behavior, this description is not complete enough to support correct invocation beyond supplying the required executable. It does not explain preconditions, capture configuration, output defaults, or how this tool relates to sibling capture tools. The presence of an output schema helps with return shape but not with input semantics.
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?
With 0% schema description coverage and 14 parameters, the description needed to provide substantial parameter meaning, but it only hints at the executable and saving output. Most parameters, such as frames, capture_key, force11on12, remote, setenv, and output_directory, remain unexplained.
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 action ('Launch a D3D12 executable'), a clear resource, and outcomes ('take GPU captures, and save them'). This makes the core purpose understandable and helps distinguish it from sibling tools that target UWP apps or already-running processes, though it does not explicitly name those alternatives.
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 this tool is for launching an executable and capturing GPU data, but it provides no explicit guidance on when to choose it over closely related sibling tools such as pix_capture_attached_process or pix_capture_uwp_app. The usage context is inferable but not directly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Attach to a running process and capture it.
| Name | Required | Description | Default |
|---|---|---|---|
| winml | No | ||
| frames | No | ||
| remote | No | ||
| process_id | Yes | ||
| output_file | No | ||
| capture_count | No | ||
| timeout_seconds | No | ||
| output_directory | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds a minimal behavioral detail—that the tool attaches to an existing process—beyond the annotations, but it does not disclose side effects, required permissions, whether the process is paused, output behavior, or failure modes. With non-read-only and non-idempotent annotations, more behavioral context would be expected.
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 is a single concise sentence with no filler, which satisfies conciseness. However, it lacks structure or any breakdown of steps/inputs, making it under-specified for a tool with eight parameters.
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 8-parameter tool with no parameter documentation, no usage guidance, and capture-related side effects, a one-line description is far from complete. The existence of an output schema does not compensate for missing parameter semantics and behavioral expectations.
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 0%, and the description names none of the eight parameters (process_id, frames, remote, output_file, capture_count, timeout_seconds, output_directory, winml). The description does not compensate for the schema's lack of semantic explanations, leaving the agent unable to infer how to configure a capture.
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 uses a specific verb ('Attach') and a clear resource ('a running process'), which distinguishes it from sibling launch-and-capture tools like pix_capture_app or pix_capture_uwp_app. 'Capture it' is somewhat vague about what is captured, but in context it adequately identifies the operation.
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 guidance about when to choose this tool over alternatives such as pix_capture_app, pix_capture_uwp_app, or pix_capture_timing. The only implied usage is that the target process must already be running; no exclusions or decision rules are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Wait for the app to trigger a programmatic capture, then save the results.
The app must call the PIX capture API (for example PIXBeginCapture) itself.
| Name | Required | Description | Default |
|---|---|---|---|
| remote | No | ||
| setenv | No | ||
| executable | No | ||
| process_id | No | ||
| until_exit | No | ||
| command_line | No | ||
| timeout_seconds | No | ||
| output_directory | Yes | ||
| working_directory | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (readOnlyHint=false, destructiveHint=false, idle hints absent), so the description carries most of the burden. It discloses a wait-then-save behavior and the app-side requirement, but it does not clarify whether this tool launches, attaches to, or monitors the target app, despite parameters like executable, process_id, command_line, and until_exit that suggest such behavior.
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 is extremely concise: two short sentences, with the core behavior front-loaded. There is no redundant wording, and every sentence adds meaning.
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 9 parameters, no parameter descriptions, and many sibling capture tools, the description is far too minimal. It does not explain how to specify the target app, what the optional parameters do, or how this mode relates to the other capture tools, leaving an agent with insufficient information to invoke it 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?
The input schema has 9 parameters with 0% description coverage, and the description compensates for none of them. It never names output_directory, timeout_seconds, executable, process_id, or any other parameter, so an agent gets no help understanding what these values mean or how they control the capture.
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 clearly states that the tool waits for the app to trigger a programmatic capture and then saves results, naming a concrete example (PIXBeginCapture). This distinguishes it from the sibling capture tools, though it does not explicitly name them or contrast with them.
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 second sentence provides an explicit prerequisite: the app itself must call the PIX capture API. This implies the tool is for app-driven captures, but it does not say when to prefer this over pix_capture_app, pix_capture_attached_process, or pix_capture_timing, nor does it mention any when-not conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record a PIX timing capture (CPU/GPU timeline) of a launched or attached app.
| Name | Required | Description | Default |
|---|---|---|---|
| remote | No | ||
| setenv | No | ||
| executable | No | ||
| process_id | No | ||
| duration_ms | No | ||
| output_file | Yes | ||
| sample_rate | No | ||
| command_line | No | ||
| no_callstacks | No | ||
| no_cpu_samples | No | ||
| no_gpu_timings | No | ||
| timeout_seconds | No | ||
| working_directory | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds 'CPU/GPU timeline' and the launch/attach scope, which is useful, but it doesn't disclose operational behavior such as creating an output file, potentially long-running capture, requiring an active connection, or the effects of toggles like no_cpu_samples or no_gpu_timings.
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 is a single, front-loaded sentence with no filler; the core action and resource are immediately clear. However, it is so terse that it omits essential operational context, which prevents 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?
For a 13-parameter capture tool with 0% schema coverage, this one-liner is far from complete. It fails to explain target selection, duration, sampling rate, callstack/timing toggles, timeout, working directory, and remote execution, leaving a large operational gap despite the presence of an output schema.
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 0%, and the description does not compensate for it. None of the 13 parameters, including the required output_file or key fields like executable, process_id, duration_ms, remote, and working_directory, are explained. This leaves an agent with almost no semantic guidance for constructing arguments.
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 clearly states the action ('Record a PIX timing capture'), the object ('CPU/GPU timeline'), and the target ('launched or attached app'). However, it doesn't explicitly differentiate this from sibling capture tools like pix_capture_app or pix_capture_attached_process, so full sibling distinction is missing.
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 guidance on when to use this tool versus alternatives. The phrase 'launched or attached app' implies two target modes, but it doesn't explain how to choose between launching, attaching, or using pix_capture_programmatic or other capture tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Launch a UWP app and capture it.
Get the package and application ids from the PIX UI: PC Connection / Select Target Process / Launch UWP, right-click the app, 'Copy pixtool Launch Command'.
| Name | Required | Description | Default |
|---|---|---|---|
| winml | No | ||
| frames | No | ||
| remote | No | ||
| force11on12 | No | ||
| output_file | No | ||
| ignore_d3d11 | No | ||
| capture_count | No | ||
| application_id | Yes | ||
| timeout_seconds | No | ||
| output_directory | No | ||
| package_full_name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is not read-only and not idempotent. The description adds the key behavioral fact that the tool launches a UWP app, implying a side effect beyond capture. However, it does not disclose other behavioral aspects such as file creation, app state changes, or timeout effects. No contradiction with annotations.
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 is compact and front-loaded: the purpose is stated in the first sentence, followed by a practical tip. It is efficiently written without unnecessary 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?
For a tool with 11 parameters, zero schema descriptions, and no usage guidance, the description is incomplete. It addresses only the required parameters and gives no example invocation, optional parameter semantics, or environmental prerequisites. While the output schema presumably covers return values, the parameter landscape remains largely unexplained.
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 0%, so the description carries the burden of explaining parameters. It does helpfully describe how to obtain the two required parameters (package_full_name and application_id) via the PIX UI. However, it offers no explanation of the nine optional parameters such as frames, output_file, capture_count, and timeout_seconds, leaving substantial semantic gaps.
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 clearly states a specific action and resource: 'Launch a UWP app and capture it.' This distinguishes it from sibling capture tools that target attached processes or programmatic capture, though it does not explicitly name those alternatives.
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 provides a how-to tip for obtaining package and application IDs, but no explicit guidance on when to use this tool versus sibling capture tools like pix_capture_attached_process or pix_capture_programmatic. With many similar capture tools in the sibling list, selection criteria are notably absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete cached artifacts for a capture so the next query re-extracts them.
| Name | Required | Description | Default |
|---|---|---|---|
| capture_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description meaningfully adds behavioral context beyond the annotations: it specifies that cached artifacts are deleted and that subsequent queries will re-extract them. This is consistent with the annotations (idempotent, not read-only, non-destructive to source data) and gives the agent a clear mental model of the operation's effect.
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 is a single, front-loaded sentence with no filler words. It conveys the action, the target, and the consequence efficiently, earning every word it uses.
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 cache-clearing tool, this description is nearly complete. It covers the core behavior and effect, and the presence of an output schema means return-value details are not required in the description. The main gap is the lack of explicit usage guidance, but the tool's simplicity keeps this from being a major deficiency.
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 0%, so the description carries the burden of explaining the parameter. 'For a capture' only mirrors the parameter name 'capture_id' and adds little detail about what the capture identifier refers to or how to obtain it. The agent must infer the parameter semantics from the parameter name alone.
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 action ('Delete cached artifacts') and a specific resource ('for a capture'), plus the intended consequence ('so the next query re-extracts them'). This clearly identifies the tool's purpose among many capture-query siblings, though it does not explicitly name which sibling it is not.
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 this tool: before a query when cached artifacts should be re-extracted. However, it provides no explicit guidance on when not to use it or how it compares to alternatives like re-opening or recapturing a capture.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Close a capture session, optionally deleting its cached artifacts.
| Name | Required | Description | Default |
|---|---|---|---|
| capture_id | Yes | ||
| clear_cache | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description contradicts the annotations: it says 'optionally deleting its cached artifacts' while destructiveHint is false. This is a direct conflict about whether the tool performs destructive operations, so the description is behaviorally misleading.
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 states the core action and the optional modifier without wasted words. Every word contributes to understanding the tool's behavior.
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?
The tool is simple and has an output schema, so return values need no explanation. However, the description leaves the destructive nature of cache deletion ambiguous relative to the annotations, and it does not clarify what happens to the capture session when clear_cache is true or false.
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 0%, so the prose must carry parameter semantics. The phrase 'optionally deleting its cached artifacts' gives meaning to clear_cache, but capture_id is only implied by its name and type. The description partially compensates for the missing schema descriptions but does not fully document both parameters.
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 clearly states the operation: 'Close a capture session' with a specific verb and resource, and adds the optional cache-deletion behavior. This distinguishes it from sibling tools like pix_open_capture and pix_list_open_captures 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?
The lifecycle language implies it should be used when finished with a capture session, but there is no explicit when-to-use, when-not-to-use, or comparison with alternatives such as pix_clear_capture_cache. The optional clear_cache behavior is surfaced but without guidance on when to set it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replay the capture collecting counters, returning per-event counter values.
counters takes exact names from pix_list_counters and escapes them. Use
counter_regexes to match families, remembering that every counter matched is
another replay pass over the capture.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| cursor | No | ||
| refresh | No | ||
| counters | No | ||
| capture_id | Yes | ||
| queue_name | No | ||
| counter_groups | No | ||
| counter_regexes | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond annotations: it reveals that the tool replays the capture, that counter names must be escaped exact names, and that matching multiple regexes means multiple replay passes. This performance cost is important for an agent to know before invocation.
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 is compact and front-loaded: the first sentence states the core purpose, followed by the most important parameter usage notes and a cost caveat. Every sentence earns its place, with no redundant restatement of the tool name or schema properties.
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?
This is a 9-parameter tool with no schema-level parameter descriptions, and the tool description only covers two of those parameters plus a performance warning. While the output schema may document return values, the input semantics for pagination, queueing, refresh behavior, and timeouts are missing, leaving the agent under-informed 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?
With 0% schema description coverage, the description must compensate for undocumented parameters. It explains 'counters' and 'counter_regexes', but says nothing about capture_id, limit, cursor, refresh, queue_name, counter_groups, or timeout_seconds. The schema provides only names and defaults, so most parameters remain semantically opaque to the agent.
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 clearly states that the tool replays a capture and collects counters, returning per-event values. This is a specific action with a clear resource and output. It does not explicitly name sibling tools, but the 'per-event counter values' phrasing helps distinguish it from counter-listing tools like pix_list_counters.
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 gives operational guidance on how to specify counters using exact names from pix_list_counters or regex families, and warns that each regex match costs an additional replay pass. However, it does not explicitly state when to use this tool versus alternatives like pix_get_counter_hotspots or pix_list_counters, leaving the selection mostly implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replay the capture collecting GPU occupancy data.
| Name | Required | Description | Default |
|---|---|---|---|
| capture_id | Yes | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds a 'replay' behavior but does not disclose what replay implies operationally, such as whether it requires an open capture or may take significant time. It does not contradict the annotations.
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 is a single, short sentence with no redundant wording. It is front-loaded with the action and resource, but it is so brief that it sacrifices useful detail.
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?
The tool is simple: two params, one required, with an output schema and safety annotations. However, the description omits practical context such as the need for an open capture, how this relates to sibling capture-collection tools, and what 'replay' means operationally. It is minimally adequate but leaves several 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?
The schema has 0% description coverage, so the description carries the burden of explaining parameters. It only mentions 'the capture' indirectly and says nothing about timeout_seconds, its units, default behavior, or why someone might set it. Parameter names are somewhat self-explanatory but that is not enough given the complete absence of parameter documentation.
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 uses a specific action ('Replay') with a clear resource ('the capture') and outcome ('collecting GPU occupancy data'). It distinguishes itself from sibling tools by specifying GPU occupancy, though it does not explicitly contrast with tools like pix_collect_counters.
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 guidance on when to use this tool versus alternatives such as pix_collect_counters or timing-related tools. It does not mention prerequisites like having a capture open, nor does it state that this should be used specifically for occupancy analysis rather than other data collection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find which named contexts (command queues) a capture exposes.
With the analysis bridge available this is the real queue table, read from PIX's engine. Without it, pixtool has no command that lists queues, so each candidate name has to be tried and a miss still costs a full capture open; results are cached per capture, so asking twice is free.
| Name | Required | Description | Default |
|---|---|---|---|
| refresh | No | ||
| capture_id | Yes | ||
| candidate_names | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, and non-destructive behavior. The description goes well beyond that by revealing two distinct operational modes (with the analysis bridge vs. fallback probing), the cost of misses, and per-capture result caching. This is exactly the kind of behavioral detail an agent needs.
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 is compact and front-loaded: the core purpose appears in the first sentence, and the second sentence packs meaningful operational detail without filler. 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?
The description covers the core task, bridge dependency, fallback behavior, and caching well, and an output schema exists so return values do not need to be documented. Still, it leaves uncertainty about optional parameters and does not position the tool against the similarly named sibling pix_list_queues, so it is not fully 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?
With 0% schema description coverage, the description must compensate, and it does explain candidate_names through the fallback probing behavior and capture_id through per-capture caching. However, it leaves timeout_seconds unexplained and does not clarify what happens when candidate_names is null while no bridge is available.
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 first sentence clearly states a specific action and resource: find which named contexts/command queues a capture exposes. It is unambiguous about what the tool does, though it does not explicitly contrast itself with sibling tools like pix_list_queues or pix_list_timing_gpu_queues.
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 conveys clear context for when this would be used: to discover queue names in a capture, especially when no other command lists queues. However, it never explicitly says when not to use it or names alternatives, so the usage guidance is mostly implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write a full event-list CSV to a caller-chosen path (pixtool save-event-list).
| Name | Required | Description | Default |
|---|---|---|---|
| counters | No | ||
| capture_id | Yes | ||
| queue_name | No | ||
| destination | Yes | ||
| counter_groups | No | ||
| counter_regexes | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey idempotency and non-destructiveness, so the description need not repeat those. It adds that the output is a full CSV at a user-selected path, but it does not disclose overwrite behavior, failure modes, or whether the file is created/truncated. There is no contradiction with the annotations.
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 states the core behavior immediately and includes a useful command reference without any filler. Every element 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?
Although an output schema exists, the tool has seven parameters with no schema-level descriptions and the description omits the required capture_id and all optional controls. An agent cannot reliably construct a correct call without additional external knowledge.
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 0%, so the description must compensate. It only clarifies that 'destination' is a caller-chosen path; the required 'capture_id' and all optional parameters such as counters, queue_name, counter_groups, counter_regexes, and timeout_seconds are left unexplained.
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 verb ('Write'), a clear resource ('full event-list CSV'), and a destination ('caller-chosen path'). It also differentiates from sibling listing/search/export tools by emphasizing CSV export, and the parenthetical 'pixtool save-event-list' reinforces the operation.
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 this tool is for saving a complete event list to a file, but it does not explicitly say when to prefer it over siblings like pix_list_events or pix_export_to_cpp. No alternatives or exclusion conditions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export the captured frame as a standalone C++ D3D12 project.
use_winpixeventruntime and use_agility_sdk acknowledge the WinPixEventRuntime and DirectX 12 Agility SDK licenses respectively.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | ||
| capture_id | Yes | ||
| timeout_seconds | No | ||
| use_agility_sdk | No | ||
| output_directory | Yes | ||
| use_winpixeventruntime | No | ||
| use_replay_time_executeindirect_buffers | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotence, non-read-only, and non-destructive behavior. The description adds a useful licensing caveat for use_winpixeventruntime and use_agility_sdk, but does not explain side effects like output directory creation, overwrite behavior, or what 'force' affects.
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 is appropriately short and front-loaded with the main purpose. The second sentence is compact but somewhat awkwardly formatted; overall, there is no wasted wording.
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?
This is a complex export tool with seven parameters and no schema-level descriptions, yet the description covers only the purpose and two license-related flags. Missing context includes force, timeout, replay-time execute-indirect buffers, and output directory semantics. The presence of an output schema reduces the need to describe return values, but the documentation is still insufficient for reliable 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 description coverage is 0%, so the description must compensate. It only explains two of the seven parameters (use_winpixeventruntime and use_agility_sdk) and leaves capture_id, output_directory, force, timeout_seconds, and use_replay_time_executeindirect_buffers undocumented.
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 uses a specific verb ('Export'), a clear resource ('captured frame'), and a distinct deliverable ('standalone C++ D3D12 project'). This clearly differentiates it from sibling tools like pix_save_screenshot or pix_export_event_list.
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 intended use case is clear: export a captured frame as a standalone C++ D3D12 project. It does not explicitly name alternatives or exclusions, but the purpose statement provides enough context for an agent to select this tool for that specific task.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Allocations the driver moved between heaps, or demoted out of video memory.
The other half of pix_get_residency_operations. Residency says an allocation was evicted and made resident again; a migration says it was moved between heaps and whether that worked, and a demotion says it was pushed into system memory for good. A demoted texture still reads, just over PCIe on every frame that touches it, so the cost is permanent rather than a one-off.
kind selects "migration" or "demotion"; omitting it returns both in time order. Empty is the normal answer for a title inside its video memory budget.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | ||
| limit | No | ||
| end_time | No | ||
| capture_id | Yes | ||
| start_time | No | ||
| cursor_position | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds useful context: migration records whether the move worked, demotion is permanent, results are time-ordered, and empty results are normal for titles within budget. No contradiction with annotations.
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 is front-loaded with the core subject and each paragraph adds useful context: the concept, the sibling relationship, kind behavior, and expected results. The PCIe analogy is slightly elaborate but supports understanding of why demotion is costly.
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?
The domain semantics are well covered, including the meaning of migration vs. demotion, kind filtering, time ordering, and the normal empty result. An output schema exists, so return-value documentation is not the description's burden. Optional parameter semantics remain somewhat thin, but the core invocation guidance is sufficient.
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 0%, so the description carries the burden for parameter meaning. It meaningfully explains kind and its omission behavior, but the other six parameters, including limit, start_time, end_time, cursor_position, timeout_seconds, and capture_id, receive no semantic explanation beyond their names in 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?
The description states a specific resource and operation: allocation moves between heaps or demotions out of video memory. It also explicitly positions this tool as 'the other half of pix_get_residency_operations,' making the distinction from a key sibling unambiguous.
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 names pix_get_residency_operations and contrasts residency vs. migration/demotion. It also gives clear selection guidance for the kind parameter, states the default behavior when kind is omitted, and sets the expectation that an empty result is normal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Named D3D12 API work on one thread, as spans.
This is PIX's API object lane: a span for each named piece of driver-level work the thread did, such as "Pipeline State Compilation". It is what turns an object id in some other table into a name, and what shows a compile or a resource creation landing on a thread that was supposed to be doing something else.
It is per thread and sparse. pix_list_timing_threads reports api_object_events on every row, which is how to find a thread that has any before querying one that does not.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| end_time | No | ||
| thread_id | Yes | ||
| capture_id | Yes | ||
| start_time | No | ||
| cursor_position | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond the annotations: results are per-thread and sparse, represented as spans, and act as an object-id-to-name mapping lane. It does not mention pagination or timeout behavior, but the annotations lower the burden and the added context is meaningful.
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 is front-loaded with a crisp one-sentence summary, then adds purposeful detail about what the data means and how to discover populated threads. Every sentence earns its place; there is no fluff or repetition of schema/annotation 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 the output schema exists, the description need not explain return values. It covers what the tool returns, why it matters, how it relates to object ids, and how to find a thread with data before querying. The main gap is parameter semantics, but that is already captured under parameter_semantics; for agent selection and safe invocation, the context is largely sufficient.
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 0%, so the description must compensate for parameter meaning. It implies thread_id via 'one thread' and 'per thread', and start_time/end_time via 'as spans', but it does not explain capture_id, limit, cursor_position, or timeout_seconds. With seven parameters and no schema descriptions, more parameter-level guidance is needed for correct invocation.
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 and behavior: named D3D12 API work on one thread, as spans, and identifies this as PIX's API object lane. It clearly distinguishes itself from timing/event tools by explaining it maps object ids to names and shows compiles/resource creation on threads, which is unique among the sibling tools.
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 gives explicit practical guidance: this tool is per-thread and sparse, and pix_list_timing_threads reports api_object_events on every row so the agent knows how to find a thread that has data before querying. It does not enumerate when-not-to-use cases against other siblings, but the primary discovery alternative is named and the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report whether the deep-analysis bridge is available, and how to build it.
| Name | Required | Description | Default |
|---|---|---|---|
| platform | No | windows |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Read-only and idempotent behavior is already encoded in annotations, and the description consistently adds that the tool returns availability plus build instructions. This clarifies expected behavior without contradicting the annotation safety profile.
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?
Single sentence, front-loaded with the verb and resource, and every clause earns its place. It is concise without sacrificing the key availability and build-instruction behavior.
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 status tool with an output schema and safety annotations, the description covers the core behavior and build guidance. The main gap is the undocumented platform parameter, but it is optional with a default, so completeness is only mildly reduced.
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 schema has one optional 'platform' parameter with default 'windows' and 0% description coverage, but the tool description never mentions platform or allowed values. The agent must guess whether platform controls which bridge status is checked or how build instructions are customized.
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 ('Report') and resource ('deep-analysis bridge availability'), and extends to build instructions. It clearly differs from siblings like pix_build_bridge, which would perform the build, and pix_get_server_status, which targets server-level status.
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 the tool is for checking bridge availability and mentions how to build it, hinting at the related build tool. It does not explicitly say when to prefer pix_get_bridge_status over pix_build_bridge or other status tools, so routing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return frame, event, and category statistics for an open GPU capture.
| Name | Required | Description | Default |
|---|---|---|---|
| refresh | No | ||
| capture_id | Yes | ||
| queue_name | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds only the open-capture prerequisite and the fact that it returns aggregated statistics; it doesn't disclose refresh, queue_name, or timeout behavior. No contradiction with annotations.
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?
Single sentence, 10 words, front-loaded with the primary action and object. No filler or redundant content.
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?
While an output schema exists, the four parameters lack any description and the sibling set is large. An agent cannot determine the meaning of refresh, queue_name, or timeout_seconds, nor when this tool is preferable to related summary/frame/event tools, making the definition insufficient for correct autonomous 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?
The schema has 0% description coverage, so the description must explain the parameters, but it only implies capture_id via 'an open GPU capture'. refresh, queue_name, and timeout_seconds are left completely unexplained.
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 uses the specific verb 'Return' and names the resource 'frame, event, and category statistics' for an open GPU capture. This identifies the tool's subject matter and distinguishes it from siblings that focus on individual frames or events, though it does not explicitly name an alternative.
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 'for an open GPU capture' implies a prerequisite, but the description does not explain when this overview should be selected over related tools like pix_get_timing_summary or pix_get_gpu_frames. There is no explicit when-to-use guidance or alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The command lists one GPU queue executed, grouped by submission.
pix_get_gpu_timeline says which named scopes the GPU ran; this says which command lists carried them. Rows sharing an execution_id went in on one ExecuteCommandLists call, and parallel_level is how PIX stacks lists that overlap - which distinguishes real parallelism from a submission that got split.
Omit queue_id for the busiest queue. Empty means the capture was recorded without GPU timings, which is what the --noGpuTimings switch does.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| end_time | No | ||
| queue_id | No | ||
| capture_id | Yes | ||
| start_time | No | ||
| cursor_position | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the operation as read-only, idempotent, and non-destructive, so the description's added behavioral context is valuable rather than redundant. It explains the output semantics of execution_id, parallel_level, and the distinction between real parallelism and split submissions. It also discloses the empty-result case and its cause (capture without GPU timings), going well beyond the structured annotations.
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 is compact and front-loaded with the core purpose before diving into semantics. The three short paragraphs each serve a distinct role: purpose, technical interpretation, and usage caveats. Minor grammatical awkwardness and a slightly dense concluding clause prevent a perfect score, but there is no fluff.
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 that an output schema exists and annotations cover the safety profile, the description adequately explains the tool's core return semantics, grouping behavior, and empty-result meaning. It also clarifies an important queue-selection default. However, it leaves time-range and pagination parameters to ambient inference and does not define how 'busiest queue' is determined, so it is not fully complete for all calling scenarios.
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?
With schema description coverage at 0%, the description must compensate for the absence of parameter documentation. It only explains the queue_id parameter's omission behavior; the other six parameters (limit, end_time, start_time, cursor_position, capture_id, timeout_seconds) receive no explanation. Property names are somewhat self-explanatory, but the description does not add meaningful semantics to most parameters.
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: it lists the GPU queue command lists executed, grouped by submission. It further differentiates itself from pix_get_gpu_timeline by explicitly stating that the sibling reports named scopes while this tool reports which command lists carried them. That makes the tool's distinctive purpose unambiguous.
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 gives a clear usage cue by contrasting with pix_get_gpu_timeline, telling an agent when the command-list perspective is needed. It also provides practical guidance on omitting queue_id to get the busiest queue and explains what an empty result means. It does not enumerate when not to use the tool or compare with other siblings such as pix_list_gpu_events, so it is just short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One thread's scheduling history: every time it came on or off a core, and why.
A row where from_thread_id is this thread is the thread losing the core, and from_thread_wait_reason says what for. That is the column that separates a thread that is slow because it is computing from one that is slow because it is blocked - a distinction a sample count cannot make, since a blocked thread simply produces fewer samples and looks idle.
Wait reasons are the Windows KWAIT_REASON values: 0 is Executive, 1 FreePage, 5 Suspended, 6 UserRequest, 7 WrExecutive, 13 WrQueue, 31 WrDispatchInt.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| end_time | No | ||
| thread_id | Yes | ||
| capture_id | Yes | ||
| start_time | No | ||
| cursor_position | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint/idempotent/destructive annotations, the description discloses row-level semantics: a row where from_thread_id is the requested thread represents the thread losing the core, and from_thread_wait_reason encodes why. It also enumerates relevant KWAIT_REASON values, adding useful interpretative context. No contradiction with annotations.
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 is front-loaded with the core definition, and each paragraph earns its place by adding interpretive value: row direction, the computing-versus-blocked distinction, and wait-reason values. The KWAIT_REASON list is somewhat detailed but directly useful and not redundant with 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?
The description is strong on result interpretation and the central use case, and an output schema exists to cover return fields. However, it offers no guidance on time filtering, pagination, timeout behavior, or how to choose this tool over siblings, leaving several optional parameters under-specified.
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?
With 0% schema description coverage, the description needed to compensate by explaining the parameters, but it only clarifies thread_id's role and the meaning of from_thread_id/from_thread_wait_reason in the result. capture_id, start_time, end_time, limit, cursor_position, and timeout_seconds are left entirely to inference from their names.
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 first sentence defines the resource precisely: one thread's scheduling history, covering every on-core/off-core transition and the reason. It does not explicitly name sibling tools, but the context-switch semantics distinguish it from nearby tools like pix_get_cpu_samples or pix_get_thread_timeline.
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 gives a concrete diagnostic use: distinguishing a thread that is slow because it is computing from one that is slow because it is blocked, and explicitly notes that a sample count cannot make this distinction. It does not name alternative tools or exclusion conditions, but the guidance is clear enough to route an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Controller reads, which is where an input latency measurement starts.
Each row is one read of a controller's state, timestamped when the title read it. Paired with pix_get_gpu_frames and the monitor lane from pix_get_custom_data, the span from an input row to the VSync that displayed its consequence is end-to-end latency - the number a player feels, and the one no GPU capture can produce.
Omit controller_id for the busiest device. Empty means no controller was present or the title reads input through an API PIX does not instrument.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| end_time | No | ||
| capture_id | Yes | ||
| start_time | No | ||
| controller_id | No | ||
| cursor_position | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool read-only and idempotent, and the description adds valuable behavioral context: rows are timestamped when the title read the controller, omitting controller_id selects the busiest device, and empty results have a specific meaning. These details go beyond what annotations or the schema provide. No contradiction with annotations 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 description is compact and front-loaded: it states the tool's purpose, then adds row semantics, pairing guidance, and a key parameter tip. All three sentences carry useful information, though the phrase 'the number a player feels' is somewhat motivational rather than strictly necessary.
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?
The description provides strong conceptual context for the tool's role in input latency measurement and explains two key edge cases: empty results and controller selection. However, with seven parameters and zero schema descriptions, the lack of detail on time filtering, pagination, and timeout semantics leaves an agent guessing at core call options. It is adequate but not fully 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 input schema has 0% property description coverage, so the description must compensate, but it only explains controller_id behavior. Parameters like start_time, end_time, limit, cursor_position, and timeout_seconds are left entirely unexplained. The required capture_id is also only implicit in the schema, not elaborated in the description.
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 clearly identifies the tool as retrieving controller reads/state reads, explaining that each row is one timestamped read of a controller's state. It also frames the tool as the starting point for input latency measurement, which distinguishes it from GPU/capture-focused siblings like pix_get_gpu_frames.
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 explicitly instructs users to omit controller_id to target the busiest device and explains that an empty result means no controller was present or the title uses an uninstrumented API. It also gives concrete pairing guidance with pix_get_gpu_frames and pix_get_custom_data for measuring end-to-end latency. It does not name explicit alternatives or exclusions, but the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Everything that ran on one core, whichever process it belonged to.
pix_get_cpu_samples answers "where did this thread's time go". This answers "what was on this core", which is the question behind an affinity or contention problem: a core pinned by another process is a cause of stutter that no amount of looking at the title's own threads will reveal. threads_in_page is the page's own breakdown, and process_id on each row is how to tell whose thread it was.
busiest_process_share names the busiest real process; idle_share_of_page is the part of the page that was process 0, the Windows Idle process, which is the core having nothing to do rather than a competitor for it. A core with a low idle share and a busiest process that is not the title is the contention case.
core is an index; pix_get_timing_summary reports how many this machine had. Empty means either nothing ran there or the capture was taken with cpu_samples disabled.
| Name | Required | Description | Default |
|---|---|---|---|
| core | Yes | ||
| limit | No | ||
| end_time | No | ||
| capture_id | Yes | ||
| start_time | No | ||
| cursor_position | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them by explaining idle_share_of_page as Windows Idle process 0, the meaning of busiest_process_share, and the empty-result condition (nothing ran or cpu_samples disabled). This contextualizes the operation without contradicting the annotations.
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 is front-loaded with a one-sentence summary and every subsequent sentence earns its place by explaining output fields, idle semantics, contention detection, or the meaning of empty results. There is no 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?
For the core concept and output interpretation it is very complete, especially because an output schema exists. However, it does not cover the time-window, limit, pagination, or timeout parameters, and leaves 'core is an index' slightly ambiguous about whether it is zero-based, so it is not fully 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?
With 0% schema description coverage, the description carries the burden for parameter meaning, but it only clarifies 'core' ('core is an index; pix_get_timing_summary reports how many this machine had'). The other six parameters (limit, end_time, start_time, cursor_position, timeout_seconds) receive no semantic explanation beyond their names/types, and cursor_position is left unexplained.
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 states the resource and scope precisely: 'Everything that ran on one core, whichever process it belonged to.' It also distinguishes the tool from pix_get_cpu_samples ('where did this thread's time go' vs 'what was on this core') and from threads_in_page, so an agent can tell it apart from 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?
It explicitly contrasts with pix_get_cpu_samples and explains the target question behind affinity or contention problems. It also gives a concrete detection rule ('A core with a low idle share and a busiest process that is not the title is the contention case') and points to pix_get_timing_summary for core count.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rank events by a counter to find the most expensive GPU work.
With nothing specified the capture's best per-event duration counter is picked automatically, which is the usual starting point for a performance investigation.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| counter | No | ||
| refresh | No | ||
| counters | No | ||
| ascending | No | ||
| capture_id | Yes | ||
| queue_name | No | ||
| counter_groups | No | ||
| counter_regexes | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds meaningful behavioral context beyond those annotations: the automatic selection of the capture's best per-event duration counter when nothing is specified. It does not mention refresh or caching behavior, but the annotation coverage lowers the burden.
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 is two sentences with no filler. The main purpose is front-loaded, and the second sentence adds a useful and non-obvious default behavior for omitted parameters.
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 complex tool with 10 parameters and zero schema descriptions, this description is not complete enough for correct advanced invocation. An agent can use the default capture_id-only path, but has no guidance on filtering, ordering, timeouts, or counter selection beyond the automatic default. The output schema covers return values, but parameter semantics remain underspecified.
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 0%, so the description must compensate for the 10 parameters. It only clarifies the counter parameter's omission behavior; parameters such as counter_groups, counter_regexes, refresh, ascending, and queue_name receive no semantic explanation.
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 ('Rank') and resource ('events by a counter') and states the goal ('find the most expensive GPU work'). It is clear, but it does not explicitly differentiate from sibling analysis tools such as pix_collect_counters or pix_get_timing_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?
The description gives clear context by identifying this as the 'usual starting point for a performance investigation' and explains the default behavior when no counter is specified. It does not provide explicit when-not-to-use guidance or name alternative sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Where one thread's CPU time went, as PIX's sampler saw it.
One row per sample: the sampler interrupted the machine, found this thread running, and recorded when and on which core. Counting samples in a time range is how much of that range the thread spent executing; the spread of core ids is whether the scheduler kept it in one place.
No instruction pointer comes back with these - resolving a sample to a function needs PIX's symbol server, which is a UI concern - so this answers when a thread ran, not what line it was on.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| end_time | No | ||
| thread_id | Yes | ||
| capture_id | Yes | ||
| start_time | No | ||
| cursor_position | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the sampling mechanism (sampler interrupts, records when and on which core) and the key limitation (no instruction pointer, so call-stack resolution is not provided). This goes beyond the readOnlyHint annotation by explaining the data nature and what it can and cannot answer.
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 is informative and well-structured, using a clear narrative to explain the purpose and limitations. It avoids unnecessary jargon and stays focused on the tool's behavior, though it is slightly verbose in explaining the sampling concept.
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 the presence of an output schema (not shown in the input), the description still provides essential context about the data contents (samples, timestamps, core IDs) and the absence of instruction pointers. It is complete enough for an agent to understand the tool's role without additional documentation.
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?
Parameter names (capture_id, thread_id, start_time, end_time, limit, cursor_position, timeout_seconds) are self-explanatory, and the description mentions time-range aggregation. However, it does not explicitly explain the cursor, timeout, or limit semantics, so the agent must infer their meaning from common API conventions.
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 clearly states the tool retrieves CPU samples for a specific thread, with one row per sample including timing and core information. It distinguishes this from related tools by explicitly noting it answers 'when' not 'where' (no instruction pointers), which separates it from analysis-focused 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?
The description explains the tool's output and its intended use case (measuring thread execution time and core distribution). It implies when to use it—when CPU sample data is needed—without explicitly naming alternative tools, but the context is sufficient for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One custom data lane's events and markers, in time order.
For a monitor lane this is the VSync train, and the gap between a present in pix_get_gpu_frames and the next VSync here is the wait a frame actually spent on the display - the part of latency that no GPU capture contains.
Omit data_type_id for the fullest lane; kind selects "event" or "marker". pix_list_custom_data_types lists what is available.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | ||
| limit | No | ||
| end_time | No | ||
| capture_id | Yes | ||
| start_time | No | ||
| data_type_id | No | ||
| cursor_position | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly, idempotent, non-destructive behavior. The description adds non-obvious behavior: results are time-ordered, kind filters event vs marker, and omitting data_type_id returns the fullest lane. This is useful beyond the structured hints.
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 cover definition, motivation, and usage without repeating schema or annotations. The VSync explanation is slightly elaborate but earns its place by clarifying the tool's latency-analysis purpose.
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?
The description provides strong purpose and domain context and points to the discovery sibling. However, for an 8-parameter tool with no schema descriptions, omitting pagination/timeout/filter semantics leaves a material gap even though parameter titles give some hints.
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 data_type_id and kind receive explanation; start_time, end_time, limit, cursor_position, and timeout_seconds are not described in the schema or the description. With 0% schema description coverage, the description needs to compensate for these parameters and does not.
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 first sentence states the exact deliverable: one custom data lane's events and markers in time order. It distinguishes the tool's scope from siblings like pix_list_custom_data_types, which enumerates available lanes/types rather than returning lane content.
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 monitor-lane/VSync example gives a concrete use case involving pix_get_gpu_frames, and the final sentence tells the agent to use pix_list_custom_data_types to discover available lanes. It lacks explicit when-not-to-use statements, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return one event by queue_id or global_id, with its parent chain.
| Name | Required | Description | Default |
|---|---|---|---|
| queue_id | No | ||
| global_id | No | ||
| capture_id | Yes | ||
| queue_name | No | ||
| timeout_seconds | No | ||
| include_children | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish that this is read-only, idempotent, and non-destructive, so the description does not need to cover those traits. It adds that the result includes the parent chain, which is useful behavioral context, but it does not explain precedence rules for queue_id vs global_id, the role of capture_id, or how include_children affects the result.
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 is a single concise sentence that front-loads the action and resource. Every word contributes to the core meaning, with no filler or redundant restating of the tool name.
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?
Despite having an output schema and safety annotations, the tool has six parameters with no schema descriptions, and the description does not adequately clarify the required capture_id or the interaction between identifiers. An agent would likely need additional external knowledge to call this tool 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 description coverage is 0%, so the description carries the burden of explaining parameters, but it only mentions queue_id and global_id as lookup keys. It does not explain the required capture_id, queue_name, timeout_seconds, or include_children, leaving significant gaps for an agent trying to invoke the tool correctly.
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: return one event by queue_id or global_id, and mentions the parent chain, which helps distinguish it from listing or searching tools. It does not explicitly mention the required capture_id or differentiate itself from pix_get_event_tree, so it is not fully distinguishing.
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 that this is a lookup tool for a single event, but it provides no explicit guidance on when to use it versus alternatives like pix_list_events, pix_search_events, or pix_get_event_tree. There are no usage conditions, exclusions, or references to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Per-event GPU timing from PIX's own timeline, with start and duration for each.
top=N ranks the whole queue by GPU duration, which is the cheapest way to find the expensive work in a frame: pix_get_counter_hotspots replays the capture once per counter, and this reads a timeline that already exists. The ranking is dominated by marker scopes - Frame, then Scene, then PostProcessing - which is the shape of the frame; leaves_only=true ranks the individual draws and dispatches inside instead. Without top, events come in queue order from cursor_position.
Windows starts replay if needed. Xbox requires pix_start_analysis first, with an explicit device_address; its returned time_unit is nanoseconds.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | ||
| limit | No | ||
| queue_id | No | ||
| capture_id | Yes | ||
| leaves_only | No | ||
| wait_seconds | No | ||
| name_contains | No | ||
| cursor_position | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavior beyond the annotations: it reads an existing timeline rather than replaying the capture, ranking is dominated by marker scopes, leaves_only changes the ranking granularity, and Windows may start replay automatically while Xbox requires pix_start_analysis with an explicit device_address. It also discloses the returned time_unit. No contradiction with annotations.
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 is dense but every sentence earns its place: core behavior, ranking semantics, the alternative tool, cursor behavior, and platform prerequisites are all covered with no filler. Information is front-loaded and logically grouped.
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 the output schema exists and the annotations already declare readability and idempotence, the description is complete enough for correct selection and invocation. It covers ranking modes, alternative tools, platform-specific setup, and scalar output units; the few unmentioned parameters are minor and self-explanatory.
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 0%, so the description carries the parameter-semantics burden. It does explain top, leaves_only, cursor_position, and queue-order behavior, but it leaves limit, name_contains, wait_seconds, and timeout_seconds undescribed. Some are self-explanatory from their names, but the description only partially compensates for the complete lack of schema documentation.
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 precise statement: 'Per-event GPU timing from PIX's own timeline, with start and duration for each.' This clearly names the operation, the resource, the source, and the data shape, and it explicitly contrasts with pix_get_counter_hotspots, making the tool easy to distinguish from its 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?
It gives explicit when-to-use guidance: top=N is called the 'cheapest way to find expensive work in a frame,' and pix_get_counter_hotspots is named as the replay-heavy alternative. It also explains mode differences (leaves_only vs queue order) and platform prerequisites (Windows vs Xbox), so an agent knows exactly when and how to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the marker hierarchy as a bounded tree.
| Name | Required | Description | Default |
|---|---|---|---|
| max_depth | No | ||
| max_nodes | No | ||
| capture_id | Yes | ||
| queue_name | No | ||
| root_queue_id | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, and non-destructive behavior, lowering the burden on the description. The word 'bounded' adds some behavioral context about tree limits, but the description does not explain pruning, missing nodes, timeout effects, or how queue/root parameters influence the returned tree.
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 is a single, front-loaded sentence with no filler. However, it is terse to the point of under-specification for a tool with six parameters and no schema-level descriptions.
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?
The description does not explain what a marker hierarchy contains, how bounds are applied, how queue/capture context matters, or how this differs from similar event tools. The output schema helps, but an agent still lacks enough context to confidently choose and invoke this tool 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 description coverage is 0%, so the description should compensate for the six parameters. 'Bounded tree' only weakly hints at max_depth and max_nodes; capture_id, queue_name, root_queue_id, and timeout_seconds remain semantically unexplained.
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 ('Return'), a clear resource ('marker hierarchy'), and a distinguishing result shape ('bounded tree'). This separates it from flat event-list tools like pix_list_events, though it does not explicitly name 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?
The description gives no direct guidance about when to use this tool instead of pix_get_event, pix_list_events, or other event-related siblings. No prerequisites, exclusions, or alternative conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every file operation on one device: what was touched, when, and for how long.
This is the lane that explains a hitch the CPU sampler cannot. A thread blocked in a synchronous read is off-core and looks idle; here the same stall is one row with a path, a start and an end. offset and size_bytes together are the access pattern, which is what separates a streaming system reading ahead from one seeking per request. status is the NTSTATUS: 0 succeeded, negative is the failure the caller saw.
Without device_id the device the captured title used most is chosen. Fails with no_devices when the capture recorded no file I/O at all - see pix_list_storage_devices for why that is the usual case.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| end_time | No | ||
| device_id | No | ||
| capture_id | Yes | ||
| start_time | No | ||
| cursor_position | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, the description discloses important behavioral details: the default device selection when device_id is omitted, the no_devices failure mode, and the semantics of returned rows including access pattern and NTSTATUS status. This goes well beyond what annotations alone convey and helps an agent predict both successful and failing behavior.
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 is well-structured: an opening summary, a diagnostic rationale, and a defaults/errors paragraph. It is somewhat dense and uses a few metaphorical phrases, but each sentence adds meaningful context. It is not bloated, though some output-field detail could be trimmed if the output schema already documents those fields.
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?
The description is strong on purpose, output row semantics, and one key default/error behavior, and an output schema exists to cover return structure. However, it is incomplete for a tool with seven parameters and zero schema descriptions: filtering bounds, pagination via cursor_position, limit behavior, and timeout_seconds are not explained. An agent could invoke the tool for the simple case but would lack guidance for controlled or paginated queries.
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 0%, so the description carries the full burden for parameter meaning. It only explains device_id's default behavior and implies capture_id via 'captured title.' It leaves limit, start_time, end_time, cursor_position, and timeout_seconds undocumented, and spends words on output fields like offset, size_bytes, and status that are not input parameters. This is a significant gap for a 7-parameter tool.
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 crisp, specific statement: 'Every file operation on one device: what was touched, when, and for how long.' It clearly identifies the resource (file I/O events), the verb (get/list), and the distinguishing value relative to the CPU sampler. This makes the tool's purpose unmistakable even among many sibling tools.
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 gives clear context for when to use this tool: when investigating a hitch or stall that the CPU sampler cannot explain, such as a thread blocked in a synchronous read. It also provides a path to an alternative tool (pix_list_storage_devices) for the no_devices case. It does not explicitly enumerate exclusions versus every sibling, but the main use case is well established.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The present timeline: one row per frame, from the Present call to the flip.
This is the frame-pacing view, and the reason to take a timing capture rather than a GPU one. Each frame carries the whole chain as separate timestamps - when Present was called, when it reached the queue, when the GPU finished writing, when the display scanned it out - so a stutter can be attributed to the part of the chain that grew rather than just to the frame that was late. block_on_fence and wait_on_swapchain are where a CPU thread sat waiting for the GPU or for a buffer to free up.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| end_time | No | ||
| capture_id | Yes | ||
| start_time | No | ||
| cursor_position | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only, idempotent, and non-destructive, so no side-effect disclosure is needed. The description adds valuable behavioral context about the row content and the meaning of timestamps and wait points, going beyond what the annotations provide. There is no contradiction with annotations.
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 is three sentences, front-loaded with the core definition, then expands on why the frame-pacing view is useful. The last sentence about block_on_fence and wait_on_swapchain is somewhat niche but contributes to interpreting the timeline.
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?
The description is strong for tool selection and output interpretation, but it omits how to constrain the query and what the six parameters mean. An output schema exists, which mitigates return-value uncertainty, but invocation guidance remains thin.
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 0%, and the description provides no parameter-level guidance. It does not explain capture_id, limit, start_time, end_time, cursor_position, or timeout_seconds, leaving an agent to infer all argument semantics from names alone.
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 clearly identifies the resource as 'The present timeline: one row per frame, from the Present call to the flip' and calls it 'the frame-pacing view', which distinguishes it from GPU-timeline tools. However, it does not use an explicit verb like 'returns' or 'gets', so the action is carried mostly by the tool name.
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 explains when this tool is the right choice: it is the frame-pacing view and the reason to take a timing capture rather than a GPU one, especially for attributing stutters to a stage in the present-to-flip chain. It does not explicitly name an alternative sibling tool or state 'use X instead', 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.
One GPU queue's named scopes, as the GPU actually ran them.
The same shape as pix_get_thread_timeline but indexed by queue rather than thread, and the times are when the GPU executed the work rather than when the CPU submitted it. Without queue_id the busiest queue is used.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| end_time | No | ||
| queue_id | No | ||
| capture_id | Yes | ||
| start_time | No | ||
| stack_level | No | ||
| cursor_position | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool read-only and idempotent, and the description adds useful behavioral context beyond them: times are when the GPU executed work, output shape mirrors the thread timeline, and omitting queue_id selects the busiest queue. These are meaningful runtime behaviors not inferable from the schema or annotations.
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, no repetition, with the core result stated first. Every sentence carries either definition or differentiation value.
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 a read-only annotation set, an output schema, and a well-scoped description, the tool is largely callable without further investigation. The only gaps are semantics for several pagination/filter parameters and how to discover a specific queue_id, but the optional-busiest-queue default reduces the impact.
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?
With 0% schema description coverage, the description needed to compensate. It explains queue_id's default and reframes start/end as GPU execution time, but it does not describe limit, cursor_position, stack_level, timeout_seconds, or end_time semantics beyond their names.
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 it returns one GPU queue's named scopes as actually executed, and explicitly contrasts it with pix_get_thread_timeline by queue indexing and GPU-execution timestamps. This clearly distinguishes it from the closest sibling without needing to inspect 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 names the alternative pix_get_thread_timeline and gives the deciding criteria: queue vs thread and GPU-executed vs CPU-submitted time. It also documents the no-queue_id fallback to the busiest queue, so an agent knows when to call this tool directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One metric sampled over time: a series rather than a list of events.
The lanes, and what each needs:
"pix_counter" (the default) - a counter reported while the capture ran, either by the title through PIXReportCounter or by the driver, such as the per-adapter video memory budget and usage. Takes metric_id from pix_list_timing_counters.
"cpu_usage" - one core's utilisation as a percentage, sampled every 100 ms. Takes core, plus either process_id or all_processes=true. Asking for the same core both ways is how to see whether a busy core was busy with the title or with something else.
"api_object_memory" - video memory held by one process's D3D12 objects, in bytes. Takes process_id.
"device_utilization" and "device_bandwidth" - per Win32 device. Take device_id from pix_list_storage_devices, and need a capture recorded with the ETW file provider.
in_page reports min, max, mean, first and last over the rows returned, which for a series is usually the whole question.
| Name | Required | Description | Default |
|---|---|---|---|
| core | No | ||
| limit | No | ||
| metric | No | ||
| end_time | No | ||
| device_id | No | ||
| metric_id | No | ||
| capture_id | Yes | ||
| process_id | No | ||
| start_time | No | ||
| all_processes | No | ||
| cursor_position | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only and idempotent behavior, and the description adds useful behavioral context: the 100 ms sampling interval for cpu_usage, the capture-relative nature of counters, the ETW requirement, and the in-page aggregate statistics. It does not explain pagination or timeout behavior, but these are minor in light of the annotation coverage.
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 is front-loaded with a clear one-sentence thesis, followed by a scannable bullet list organized by metric lane. Every bullet conveys necessary parameter or prerequisite information, with minimal fluff, though the final 'in_page' sentence is slightly ambiguous.
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 the five main metric lanes, the description is complete and actionable, including defaults, required parameters, and data sources. However, the generic control parameters for time range, pagination, and timeout are never explained, which leaves notable gaps for a complex tool even though an output schema exists.
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 0%, so the description must carry the parameter explanation burden. It does well for metric, metric_id, core, process_id, all_processes, and device_id, but leaves limit, cursor_position, start_time, end_time, and timeout_seconds semantically unexplained, which is a significant gap for a 12-parameter tool.
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 an explicit resource and verb: one metric sampled over time, as a series rather than a list of events. It further distinguishes five metric lanes and names the sibling tools that provide required IDs, so an agent can separate this from event-listing and counter-listing tools.
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?
Each lane comes with concrete usage requirements, such as taking metric_id from pix_list_timing_counters, device_id from pix_list_storage_devices, and the ETW file provider prerequisite. It explains the process_id vs all_processes comparison for cpu_usage, giving the agent actionable guidance, though it does not systematically compare against all sibling metric/timing tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One thread's page faults - the stalls that no CPU sample can show.
fault_type is what it cost. HardPageFault is the expensive one: the page was not in memory and the thread waited on the disk. DemandZero is a first touch of new memory, Transition a page reclaimed from the standby list, CopyOnWrite a private copy being made - all cheap, and worth having mainly to tell them apart from the hard kind.
A burst of hard faults on the game thread is a hitch caused by memory pressure rather than by work, and it appears in no other table here. thread_id comes from pix_list_timing_threads.
Like file I/O this needs a provider pix_capture_timing does not enable, so captures taken through this server return nothing; the query is correct and the table is empty.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| end_time | No | ||
| thread_id | Yes | ||
| capture_id | Yes | ||
| start_time | No | ||
| cursor_position | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, but the description adds crucial behavior beyond that: the meaning and relative cost of each fault type, the fact that hard faults indicate disk waits, and the important empty-result behavior when the underlying provider is not enabled. This is exactly the kind of contextual behavioral disclosure that helps an agent trust a query's empty result.
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 is longer than average, but nearly every sentence adds distinct value: fault-type taxonomy, diagnostic interpretation, thread_id provenance, and provider limitation. It is front-loaded with the core purpose and avoids redundant restatement of the tool name.
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?
The tool is complex enough to benefit from the provided behavior around fault types and empty captures, and the output schema covers return details. What is still missing is a bit more parameter context, especially how capture_id relates to open captures and what cursor_position means for pagination, but the core invocation path is sufficiently clear.
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 0%, so the description carries the burden for parameter meaning. It does provide useful guidance for thread_id by telling the agent to source it from pix_list_timing_threads, but capture_id, start_time, end_time, limit, cursor_position, and timeout_seconds are left undescribed. Most input parameters still lack semantic explanation beyond their names.
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 clearly states the resource: one thread's page faults, and explicitly frames them as 'the stalls that no CPU sample can show,' which differentiates this from sampling tools like pix_get_cpu_samples. It also explains what fault types mean, grounding the tool in a concrete diagnostic scenario.
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 gives strong context: page faults are for diagnosing memory-pressure hitches that appear in no other table, and thread_id must come from pix_list_timing_threads. It also warns that captures taken without the special provider return an empty table. It stops short of explicitly naming alternative tools to switch to, but the intended use case is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The pipeline state bound at one event: program type, root signature, and bound views.
This is PIX's Pipeline State view. event_index is the queue-relative index from pix_list_gpu_events, not the global id used by the pixtool-backed tools. Events that bind no pipeline - Signal, Present, ResourceBarrier - report no_pipeline_state.
| Name | Required | Description | Default |
|---|---|---|---|
| queue_id | No | ||
| capture_id | Yes | ||
| event_index | Yes | ||
| timeout_seconds | No | ||
| include_bindings | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context: the result is bound to a single event, uses queue-relative indexing, and returns no_pipeline_state for events that bind no pipeline. This goes beyond what annotations alone convey and helps the agent interpret atypical results.
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 is three sentences with no filler. It front-loads the core purpose, then immediately provides the critical indexing distinction and the no-pipeline edge case. Every sentence 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 the description does not need to enumerate return fields. It covers the most correctness-critical details: event_index provenance, the difference from pixtool-backed tools, and the no_pipeline_state case. Optional parameters are left unexplained, which is a minor gap given that the required parameters and key edge cases are addressed.
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 0%, so the description must compensate for the structured schema's lack of parameter information. However, it only explains event_index semantics; capture_id, queue_id, timeout_seconds, and include_bindings are not described at all. Even include_bindings, which relates to 'bound views' in the description, is not explicitly tied to a parameter, leaving meaningful gaps.
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 and action: it retrieves the pipeline state bound at a given event, covering program type, root signature, and bound views. It also differentiates itself as 'PIX's Pipeline State view' from related sibling tools like pix_get_root_signature and pix_get_resource_views. This is specific enough for an agent to understand what the tool returns and how it scopes to a single event.
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 gives concrete usage context: event_index is queue-relative and comes from pix_list_gpu_events, not the global id used by pixtool-backed tools. It also warns that events like Signal, Present, and ResourceBarrier will report no_pipeline_state. It doesn't explicitly name alternatives, but the indexing caveat and no-pipeline case provide practical guidance for when and how to call it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What the GPU made resident, evicted, or paged, and when.
Video memory is oversubscribed when the working set does not fit, and Windows resolves it by evicting an allocation and paging it back over PCIe when the GPU next needs it. The cost lands on a frame that otherwise looks ordinary - the same draws, the same state, several milliseconds longer - so it is invisible in the event list and in every GPU-capture tool here.
Each row names the object that moved, which is what makes it actionable: a texture atlas evicted every frame is a budget problem with an address. residency_count is the running number of resident objects after the operation.
operation filters to one of MakeResident, Evict, PageIn, PageOut; by default all four are queried and merged in time order. An empty result is the normal case for a title comfortably inside its video memory budget.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| end_time | No | ||
| operation | No | ||
| capture_id | Yes | ||
| start_time | No | ||
| cursor_position | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral detail beyond the readOnly/idempotent annotations: it explains what each row represents, that residency_count is the running count after the operation, that all four operation types are queried by default and merged in time order, and that an empty result is a meaningful outcome. This gives an agent a clear model of what the tool returns and how to interpret it.
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 is reasonably concise and well-structured, leading with the core purpose, then adding context, output semantics, and parameter behavior. It is a bit longer than strictly necessary, but each sentence earns its place by explaining why the tool is useful and how to interpret its results.
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 the domain complexity and the existence of an output schema, the description covers the essential context well: what the data means, why it is hard to find elsewhere, how to filter operations, and what an empty result indicates. The main shortfall is incomplete guidance on the time/cursor/limit parameters, but their names are reasonably self-explanatory.
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 0%, so the description must compensate. It only explains the operation parameter, listing its valid values and default behavior. It does not clarify start_time, end_time, limit, cursor_position, timeout_seconds, or even capture_id beyond what the schema's names imply. Since most parameters remain undocumented in both schema and description, this is a meaningful 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?
The description clearly identifies the resource ('residency operations' of GPU memory) and the specific information returned: objects that were made resident, evicted, or paged, along with timestamps. It is specific enough about the content and follows the get_* pattern of similar tools, though it does not explicitly contrast itself with related siblings such as pix_get_allocation_moves or pix_get_page_faults.
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 provides a clear use case: diagnosing video memory oversubscription that manifests as invisible frame hitches. It explains why this tool is needed and even sets expectations that an empty result is normal for a title within budget. It does not explicitly name alternatives or state when not to use it, but the context is strongly implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Describe one resource: full descriptor, heap, initial state, and view summary.
index comes from pix_list_resources.
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | ||
| capture_id | Yes | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds what the returned descriptor includes, which is useful but does not disclose deeper behavioral traits such as error conditions or output size. No contradiction 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 description is two sentences with no filler. The first sentence is information-dense and the second provides essential usage guidance. Every word 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?
The tool has an output schema, so return values are covered. However, the description leaves capture_id and timeout_seconds underspecified, which is a noticeable gap given zero schema descriptions. Overall, it is adequate but not fully 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 description coverage is 0%, so the description must compensate. It clarifies that 'index' comes from pix_list_resources, but it does not explain the role of capture_id or timeout_seconds. With three parameters and only one partially documented, the agent is left to infer the rest.
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 clearly states the action ('Describe one resource') and specifies the exact content of the descriptor: full descriptor, heap, initial state, and view summary. This distinguishes it from sibling tools like pix_get_resource_views, which presumably returns only views.
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 instruction 'index comes from pix_list_resources' explicitly tells the agent where to obtain the index parameter, establishing a clear usage flow. It does not explicitly name alternatives or state when not to use the tool, but the context is sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every view of one resource, and the events that bind it.
This answers "where is this texture actually used, and as what": each view carries its descriptor, and each binding names the event plus how it was reached - root parameter, bindless descriptor heap, or an API argument such as a copy source or a barrier transition.
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | ||
| limit | No | ||
| capture_id | Yes | ||
| cursor_position | No | ||
| timeout_seconds | No | ||
| include_bindings | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral detail about response contents: each view carries its descriptor, and each binding names the event and the reach path (root parameter, bindless heap, API argument). No contradiction with annotations.
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 text is compact and front-loaded, with the core concept in the first line and a clarifying explanation afterward. The first sentence is a fragment and some terminology is dense, but nothing is 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?
With annotations and an output schema, the safety profile and return values are largely covered. The main gap is invocation: 0% parameter documentation and no discussion of pagination or the include_bindings toggle, so an agent would have to guess at parameter semantics.
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 0%, so the description needed to map parameters like index, include_bindings, limit, and cursor_position to their roles. It does not. It provides domain context about views and bindings but never explains how the six input parameters control the query.
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 operation and object: retrieving every view of one resource plus the events that bind it. It goes beyond the tool name by explaining the practical question it answers ('where is this texture actually used, and as what') and by detailing descriptor and binding information.
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 'This answers...' line supplies a clear use case: choose this tool when you need to know where a resource is used and in what form. However, it does not explicitly contrast it with sibling tools such as pix_get_resource or pix_list_resources or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The root signature bound at one event, without the bound-view detail.
A narrower pix_get_pipeline_state for when only the binding layout matters.
| Name | Required | Description | Default |
|---|---|---|---|
| queue_id | No | ||
| capture_id | Yes | ||
| event_index | Yes | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds useful scope information about what is not included ('without the bound-view detail'), but it does not disclose other behavioral aspects such as failure modes, prerequisites, or queue/timeout behavior.
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 concise sentences with no filler. The core meaning is front-loaded, and the clarifying sibling comparison 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?
With an output schema and safety annotations present, the description is adequate for choosing the tool, but it is thin for invocation details. It does not explain how to determine the right capture, event, queue, or timeout, leaving the agent to infer parameter semantics from names alone.
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 0%, and the description provides no parameter-level guidance. The event-centric phrasing hints that event_index is central, but capture_id, queue_id, and timeout_seconds are left completely unexplained beyond their names.
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 exactly what the tool returns: the root signature bound at a given event, explicitly excluding bound-view detail. It also distinguishes itself from pix_get_pipeline_state, making the tool's scope clear relative to a closely named 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?
The description explicitly names pix_get_pipeline_state as the broader alternative and states this tool is the narrower choice 'for when only the binding layout matters.' This gives an agent a clear decision rule for selecting this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report PIX installs, pixtool health, limits, and open sessions.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral caveats beyond the report content, but it also does not contradict the annotations or introduce surprises for a stateless status query.
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 is a single front-loaded sentence with no filler. Every word contributes to defining what the status report includes.
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 zero-parameter, read-only status tool with an output schema and strong annotations, the description is complete: it names the resource and the four categories of status it reports. Nothing essential is missing for an agent to invoke it 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?
The tool has zero parameters, so there are no parameter semantics to document. The description appropriately spends its words on the output content instead of schema fields; the 100% schema coverage and empty properties make parameter explanation unnecessary.
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 ('Report') and resource ('PIX server status'), then enumerates concrete contents -- PIX installs, pixtool health, limits, and open sessions. These contents are specific enough to differentiate it from related siblings like pix_get_bridge_status or pix_list_open_captures.
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 guidance is given on when to choose this tool over alternatives, such as pix_get_bridge_status or pix_list_open_captures. The agent must infer from the name and listed contents when this status query is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One thread's named PIX scopes: what it was doing, and for how long.
This is the lane PIX draws for a thread. Each row is one PIXBeginEvent/End pair with its own name, span and nesting depth; without stack_level the whole tree comes back flattened, deepest scopes included. duration is wall clock and execution_time is the part of it the thread was actually on a core for - the gap between them is time spent descheduled, which is the difference between slow code and a thread that was waiting.
Empty means the process never called PIXBeginEvent. Check pix_get_timing_summary.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| end_time | No | ||
| thread_id | Yes | ||
| capture_id | Yes | ||
| start_time | No | ||
| stack_level | No | ||
| cursor_position | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses important behaviors: each row is one PIXBeginEvent/End pair with name, span, and nesting depth; omitting stack_level flattens the tree; and duration vs execution_time captures time spent descheduled. It also defines the empty-result case. This is rich, non-obvious behavioral detail that an agent would not get from the schema or annotations.
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 is well-structured: a one-line purpose, then a concise explanation of row semantics and the key stack_level/timing behaviors, then an actionable empty-case note. Every sentence adds value, and there is no repetition of schema or annotation content.
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 does not need to list return fields, and it covers the most important semantic nuances: flattening, timing interpretation, and empty results. The main gap is that several optional filtering/pagination parameters are left to name-based inference, but the tool is still usable by an agent given the clear overall framing.
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 0%, so the description must compensate for explaining the 8 parameters. It does explain stack_level behavior meaningfully and touches on duration/execution_time output semantics. However, it does not describe start_time, end_time, limit, cursor_position, timeout_seconds, or the required capture_id/thread_id beyond what their names imply. The compensation is only partial for a tool with this many parameters.
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 resource and intent: 'One thread's named PIX scopes: what it was doing, and for how long.' This is more than a restatement of the tool name; it identifies the exact scope of the tool and distinguishes it from broader GPU or event-level tools. The framing as 'the lane PIX draws for a thread' reinforces the unique positioning.
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 conveys a clear usage context: use this when you need a single thread's PIXBeginEvent/End scope timeline with nesting and timing information. It also provides a specific fallback for empty results ('Check pix_get_timing_summary'), which is actionable. It does not systematically contrast with all sibling tools, but the resource and output semantics make the primary usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What a timing capture covers: its window, the machine, and which tables have data.
Start here. The contains flags say which of the other tools will return anything - a capture of a program that never presented has no gpu_frames, and one taken of an uninstrumented process has no pix_events - so this is the difference between an empty answer that is a bug and one that is the truth.
| Name | Required | Description | Default |
|---|---|---|---|
| capture_id | Yes | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond that: it reveals that the result contains flags describing data availability, and warns that an empty result may be the correct truth rather than a bug.
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 is concise and well-structured, front-loading the core purpose before adding practical guidance. The illustrative examples about gpu_frames and pix_events are slightly verbose but earn their place by clarifying the contains-flags behavior.
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?
The presence of an output schema reduces the need to describe return values. The description provides the essential entry-point context and distinguishes meaningful empty results from bugs. The only notable gap is the unaddressed timeout_seconds parameter.
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?
With 0% schema description coverage and no parameter explanation in the description, the agent gets no help understanding 'timeout_seconds' or the expected format of 'capture_id'. The description focuses on output semantics rather than input semantics, so the parameters remain underdocumented.
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 clearly states what the tool covers: a timing capture's window, machine, and which tables have data. It distinguishes itself as the entry point among many siblings by explaining that its contains flags determine whether other tools will return anything.
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 explicitly says 'Start here' and explains why: the contains flags indicate which of the other tools will return data. This gives clear context for when to use this tool before consulting siblings, though it doesn't name specific sibling alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The input controllers the capture saw.
latency_instrumented says whether PIX's Dynamic Latency Instrumentation was running for that device, which is the difference between input timestamps anchored to the hardware and timestamps inferred from when the title read them.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| capture_id | Yes | ||
| cursor_position | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive behavior, so the description does not need to repeat that. The added latency_instrumented explanation provides some context about an output field, but it is confusingly worded ('which is the difference... when the title read them') and does not clarify pagination, ordering, or other behavioral details. It adds partial value but no contradiction with annotations.
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 is short and the core idea is placed first, which is good. However, the first sentence is grammatically incomplete and the second is a run-on with unclear referents for 'which' and 'the title.' It is compact but not cleanly structured.
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 and read-only annotations reduce the burden, but the description still leaves the operation implicit, provides no sibling differentiation, and leaves all parameter semantics undocumented. An agent could guess a basic capture_id call, but reliable use of limit, cursor_position, and timeout_seconds is not supported by this definition.
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 0%, and the description explains none of the four parameters: limit, capture_id, cursor_position, or timeout_seconds. The only weak connection is that 'capture' in the description implies capture_id, but limit, pagination cursor, and timeout behavior are completely undocumented. With zero schema descriptions and no compensatory explanation, this is a significant 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?
The description identifies the resource ('input controllers the capture saw') and implies a listing operation, so an agent can roughly infer what the tool returns. However, it is a sentence fragment rather than an explicit 'Lists...' statement, and it does not distinguish this tool from siblings like pix_get_controller_input. Overall purpose is clear in substance but not precisely or independently stated.
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 guidance about when to use pix_list_controllers versus alternatives, no mention of prerequisites, and no mention of when not to use it. The only implied context is that a capture is involved, which is insufficient for an agent choosing among many similar capture-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List GPU counters available for this capture, grouped and searchable.
| Name | Required | Description | Default |
|---|---|---|---|
| group | No | ||
| limit | No | ||
| cursor | No | ||
| pattern | No | ||
| refresh | No | ||
| capture_id | Yes | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds only minimal context about grouping and searchability, and does not disclose behavior around pagination (limit/cursor), refresh, or timeout. With annotations present, this meets but does not exceed the baseline.
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 is a single focused sentence with no filler. It front-loads the primary action and resource, then adds the key differentiating features. Every word 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?
Despite having an output schema, the tool has 7 parameters, several of which are non-obvious (cursor, limit, refresh, timeout_seconds), and the description provides no usage guidance or parameter details. For a tool with this parameter count and zero schema descriptions, the description is too sparse to fully guide 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 description coverage is 0%, so the description must compensate for explaining the 7 parameters. It only hints at 'grouped' (group) and 'searchable' (pattern), leaving limit, cursor, refresh, timeout_seconds, and capture_id semantics largely unexplained. This is inadequate for the number of parameters.
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 ('List'), a clear resource ('GPU counters'), and the scope ('available for this capture'). It also conveys the tool's functionality ('grouped and searchable'), which distinguishes it from counter-collection tools like pix_collect_counters, though it does not explicitly name sibling alternatives.
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 usage for browsing or searching counters within a capture, but gives no explicit guidance about when to use this tool versus closely related siblings such as pix_list_timing_counters, pix_suggest_counter_pattern, or pix_get_counter_hotspots. No exclusions or alternative routing are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The custom data lanes this capture carries, with how much is in each.
Two sources end up here. A title that calls PIX's custom data API declares its own lanes - a gameplay state, a streaming bucket, whatever it defines. PIX also records one per monitor, carrying that display's VSync signal, which is present on any capture and is the reference a present-to-display measurement needs.
event_count is spans, marker_count is instants. data_type_id is what pix_get_custom_data takes.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| capture_id | Yes | ||
| cursor_position | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only, idempotent, and non-destructive, so the description does not need to restate safety. It adds useful behavioral context beyond the annotations: two distinct sources contribute lanes, event_count represents spans while marker_count represents instants, and the returned data_type_id is what pix_get_custom_data consumes. No contradiction with annotations 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 main purpose is front-loaded in the first sentence, and the following paragraphs add relevant context about data sources and field semantics. The description is moderately detailed but every sentence contributes meaning; it is not bloated or repetitive, though it could be trimmed slightly without losing value.
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 listing tool with an output schema, the description covers the important conceptual ground: what is listed, where the data comes from, what the counts mean, and how the returned IDs are consumed by pix_get_custom_data. It does not address pagination or ordering behavior, but those are partially represented by the input schema and are not critical for a basic list call.
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 0%, so the description carries the full burden of explaining parameters, but it explains none of them. capture_id is only implicitly tied to 'capture', while limit, cursor_position, and timeout_seconds are left entirely to their schema names. The description's mentions of event_count, marker_count, and data_type_id refer to output concepts, not input parameters.
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 verb and resource: it lists the custom data lanes carried by a capture, with per-lane counts. It also clarifies the scope (per capture) and connects the output to a related sibling tool via 'data_type_id is what pix_get_custom_data takes,' which helps an agent understand this is the list operation paired with that getter.
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 does not explicitly say when to use this tool versus alternatives, but it implies usage by explaining that a per-monitor VSync lane is always present and is the reference a present-to-display measurement needs. It lacks direct exclusions or alternative-tool routing, but the context gives a reasonable hint about when this list matters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List capture events, optionally restricted to one parent marker or category.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| cursor | No | ||
| parent | No | ||
| refresh | No | ||
| category | No | ||
| capture_id | Yes | ||
| queue_name | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the behavioral detail that results can be restricted by parent marker or category. It does not disclose pagination, refresh behavior, queue handling, or timeout semantics, but given the annotations cover safety, the added context is adequate but not rich.
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 is a single sentence with no filler and front-loads the primary action, making it easy to parse. It is appropriately brief for a list operation, though it could have included a few more essential details without becoming verbose.
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 8 parameters, one required parameter, zero schema descriptions, and no explanation of pagination or refresh semantics, the one-sentence description is not complete enough for correct invocation. The existence of an output schema helps with return values, but the agent still lacks guidance on what capture_id refers to, how cursor/limit work, and what refresh or queue_name do.
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 0%, so the description carries the burden of explaining parameters. It only adds meaning for 'parent' and 'category' via the phrase 'restricted to one parent marker or category.' The required capture_id and important optional parameters like limit, cursor, refresh, queue_name, and timeout_seconds remain unexplained, leaving most of the 8-parameter surface 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?
The description clearly states a specific verb and resource: 'List capture events', with an optional restriction to 'one parent marker or category.' It is not a tautology and conveys the core function. However, it does not explicitly differentiate from related siblings like pix_search_events or pix_list_gpu_events, so it does not earn a 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?
There is no explicit guidance about when to use this tool versus alternatives. The optional parent/category restriction hints at one use case, but the description does not explain when to choose pix_list_events over pix_search_events, pix_get_event, or pix_list_timing_processes. The agent is left to infer usage from the tool name and sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List events from one queue, straight from PIX's engine.
Unlike pix_list_events this needs no CSV export, sees every queue, and can return the decoded D3D12 call with its arguments. Without queue_id the busiest GPU queue is used. Paging is by cursor_position; the response carries next_cursor.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| queue_id | No | ||
| capture_id | Yes | ||
| name_contains | No | ||
| cursor_position | No | ||
| timeout_seconds | No | ||
| include_api_call | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only and idempotent. The description goes further by disclosing engine-level access (no CSV export), the ability to see every queue, decoded D3D12 call return, default queue selection, and cursor-based paging with next_cursor responses. These are meaningful behavioral disclosures beyond the structured annotations.
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 with no wasted words. The core purpose is front-loaded, the sibling distinction is in the second sentence, and the needed usage details (queue default, paging) are in the third. Every sentence contributes unique value.
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 the output schema exists and annotations cover the read-only/idempotent safety profile, the description sufficiently covers the main behavioral contract: scope, default queue, paging, and optional D3D12 decoding. Minor gaps like exact name_contains matching semantics or timeout interpretation remain, but they are not critical 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 description coverage is 0%, so the description must compensate. It effectively clarifies queue_id (defaults to busiest queue), cursor_position (paging key, response has next_cursor), and include_api_call (can return decoded D3D12 call). The remaining parameters (limit, name_contains, timeout_seconds) are largely self-explanatory from their names and types, though not explicitly described.
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: 'List events from one queue, straight from PIX's engine.' It then explicitly distinguishes itself from the sibling pix_list_events by noting it needs no CSV export, sees every queue, and can return the decoded D3D12 call, so an agent can clearly tell which 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 description explicitly contrasts with pix_list_events, giving concrete criteria for choosing this tool over that alternative. It also provides default behavior ('Without queue_id the busiest GPU queue is used') and explains the pagination mechanism, giving clear operational context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The metric series this capture can plot, and what each one is keyed on.
These are the graph lanes above PIX's thread tracks: a value sampled repeatedly across the capture rather than a list of events. keys_available says how many keys exist for each lane - how many counters were reported, how many cores the machine had - which is a different question from whether the series has rows.
Feed a lane name to pix_get_metric_values.
| Name | Required | Description | Default |
|---|---|---|---|
| capture_id | Yes | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
It explains key behavioral semantics beyond the readOnly/idempotent annotations: these are continuous sampled series rather than event lists, and keys_available counts keys per lane, which is distinct from row presence. It does not describe output schema details, but an output schema exists to cover that.
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, with the core purpose first and no filler. The explanatory aside about keys_available is useful but slightly dense; overall it 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?
For a read-only listing tool with an output schema, the description adequately explains the conceptual model and next step (pix_get_metric_values). It leaves optional timeout_seconds undocumented and could be more explicit about capture_id, but the core calling context is 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 0%, so the description carries the burden, but it only refers obliquely to 'this capture' and never explains capture_id or timeout_seconds. The timeout parameter is entirely undocumented in both schema and description.
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 the tool returns 'the metric series this capture can plot' and explains these are sampled graph lanes, which identifies the resource and scope. It also distinguishes them from 'a list of events', though it does not explicitly contrast with sibling metrics/counters tools like pix_list_counters or pix_get_metric_values.
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 gives context that this lists available metric lanes and closes with 'Feed a lane name to pix_get_metric_values', which implies a follow-up workflow. It does not explicitly state when to choose this over related tools, nor does it offer exclusions or alternative conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List open capture sessions with their ids, paths, and cached artifacts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide the read-only, idempotent, and non-destructive safety profile. The description adds that only open sessions are returned and that cached artifacts are part of the result, which gives useful behavioral expectations beyond those hints.
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 is a single front-loaded sentence with no filler: it states the verb, resource, and output contents. Every word contributes.
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 zero-parameter, read-only listing tool with an output schema and comprehensive annotations, the description is complete. It tells the agent what the list contains without needing to replicate schema details.
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 input schema is empty and there are zero parameters, so the baseline is 4. The description does not introduce any parameter semantics, which is appropriate since there are none to document.
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 clearly identifies the operation ('List'), the resource ('open capture sessions'), and the relevant output fields (ids, paths, cached artifacts). This is specific enough to distinguish it from sibling open/close/get-overview capture tools.
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 'open capture sessions' phrasing gives clear context for when this tool should be used: enumerating current sessions and their cached artifacts. It does not explicitly name alternatives or exclusions, but the intended use is obvious from the scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every command queue in a capture, with its name, type, and event count.
This is the real queue table, not a guess. Use the id or name of the busiest graphics queue with pix_list_gpu_events or pix_get_pipeline_state; a capture whose default queue looks empty usually has its draws in a named one.
| Name | Required | Description | Default |
|---|---|---|---|
| capture_id | Yes | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it guarantees this is the authoritative queue table rather than a guess, and it explains a common capture behavior (draws appearing in a named queue when the default queue looks empty).
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 is concise and front-loaded with the core purpose. The second sentence is dense and adds operational value, though its grammar is slightly tangled ('Use the id or name... with pix_list_gpu_events or pix_get_pipeline_state') and could be clearer.
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 list operation with a read-only, idempotent annotation profile and an output schema, the description covers the main purpose, the kind of data returned, and practical downstream usage. The main gap is parameter documentation, especially timeout_seconds, but the tool is otherwise sufficiently specified for an agent to invoke it correctly with capture_id.
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 input schema has zero description coverage and the tool description does not explain capture_id or timeout_seconds. The phrase 'in a capture' weakly implies capture_id, but the semantics of the optional timeout_seconds parameter and any constraints on capture_id are left entirely to the schema's minimal titles.
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 ('List every command queue in a capture') and the exact returned fields ('name, type, and event count'), making the tool's purpose immediately clear. 'This is the real queue table, not a guess' further distinguishes it from discovery-like or estimated queue tools.
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 provides practical context: queue IDs/names from this tool should feed into pix_list_gpu_events or pix_get_pipeline_state, and it warns that the default queue may look empty while draws reside in a named queue. It does not explicitly state when to prefer this tool over siblings like pix_discover_queues, but the guidance is strong enough for an agent to choose it for authoritative queue enumeration.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the D3D12 resources in a capture with their dimensions and formats.
This is PIX's resource table: every texture and buffer the frame touched, with the debug name the application set. Filter with name_contains, then pass an entry's index to pix_get_resource or pix_get_resource_views.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| capture_id | Yes | ||
| name_contains | No | ||
| cursor_position | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, so the description does not need to restate safety. It adds useful behavioral context beyond annotations: the result covers 'every texture and buffer the frame touched,' includes 'the debug name the application set,' and produces indexes usable with specific sibling tools. This gives the agent a concrete model of what the call returns.
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 is compact and front-loaded: the first sentence states the action and outputs, the second adds the resource-table context and downstream workflow. Every sentence earns its place, with no filler or repetition of annotation fields.
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 is present, so not explaining the full return shape is acceptable. The description covers purpose, main filter, and next steps well. The only real gap is that optional pagination parameters such as limit and cursor_position are not connected to how the resource list is paged, which an autonomous agent might need for very large captures.
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 0%, so the description must compensate. It explains the capture context and explicitly calls out name_contains filtering, and it implies the output entries are indexable. However, limit, cursor_position, and timeout_seconds are left entirely to their parameter titles, with no guidance on pagination or timeout behavior.
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?
Description states a specific verb and resource: 'List the D3D12 resources in a capture with their dimensions and formats.' It goes further to describe the resource table and connects to downstream tools by telling the agent to pass an entry's index to pix_get_resource or pix_get_resource_views, which differentiates it from those sibling tools.
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 gives clear context: use this tool to see every texture and buffer in the capture, filter with name_contains, and then use the resulting index to fetch details from pix_get_resource or pix_get_resource_views. It does not explicitly state when not to use it or name exclusion conditions, but the workflow is clear enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The storage devices this capture watched, busiest first.
device_id from here goes to pix_get_file_io. Sorted by title_operation_count - the I/O done by the process PIX attached to - rather than by the machine-wide total, because the busiest disk overall is often some other program's.
Usually empty. PIX records file I/O only when the session enabled the ETW file provider, which pix_capture_timing has no switch for, so captures taken through this server have none. A capture recorded from the PIX UI with file I/O turned on will populate this and pix_get_file_io.
| Name | Required | Description | Default |
|---|---|---|---|
| capture_id | Yes | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnly/idempotent/destructive annotations by explaining the sorting key (title_operation_count), the scope of counted I/O (process-attached, not machine-wide), and the likely-empty condition caused by missing ETW file provider. This is exactly the non-obvious behavior an agent needs.
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 main purpose is front-loaded in the first sentence, and each subsequent paragraph adds necessary context: sorting rationale, data availability caveat, and source workflow. No filler or redundant restatement of the tool name.
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 list tool with an output schema, the description covers the non-obvious parts: when it is empty, how results are ordered, and how device_id connects to pix_get_file_io. An agent can decide whether to call it and interpret the result 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 has 0% description coverage, so the description partially carries the burden. 'This capture' clarifies that capture_id identifies the capture, but timeout_seconds is not addressed and no parameter-specific details or formats are given. The parameter names are self-explanatory enough to avoid confusion.
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 action and resource: it lists the storage devices watched by a capture, ordered busiest first. It also distinguishes its output from pix_get_file_io by pointing out that device_id from this tool feeds that 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?
Explains when results should exist (only captures with ETW file I/O enabled) and how server-side captures differ from PIX UI captures. It doesn't explicitly name alternatives to prefer, but the empty-result condition and linkage to pix_get_file_io give clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The counters a timing capture carries, grouped as PIX groups them.
These are not the same thing as pix_list_counters. Those are replay-time hardware metrics for a GPU capture, measured by re-running draws; these were reported live while the timing capture ran - what the title passed to PIXReportCounter, plus what the platform contributed, such as the video memory budget and usage that the driver publishes per adapter.
Each row names the process that reported it, so a machine-wide capture separates the title's counters from everything else's.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| capture_id | Yes | ||
| cursor_position | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable context beyond that: counters were reported live during timing capture, they are grouped by PIX, and each row names the reporting process. No contradiction 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?
Three sentences, each carrying meaningful differentiation or provenance information. The most important distinction appears early, and there is no 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?
The description gives strong context about what the data is, how it differs from replay-time counters, and how it is structured. However, the absence of any parameter guidance combined with 0% schema coverage leaves some invocation details to inference, though capture_id is self-evident and the output schema exists.
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 schema has 0% description coverage, and the description provides no guidance for capture_id, limit, cursor_position, or timeout_seconds. It explains the conceptual counters but does not compensate for the total lack of parameter-level semantics.
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 clearly identifies the resource as the counters carried by a timing capture and immediately contrasts it with pix_list_counters. There is no explicit verb like "list" or "return," but the tool name plus the contrast make the purpose unambiguous.
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 explicitly names pix_list_counters as the similar alternative and explains the live-vs-replay distinction that determines which one to use. It also adds a context cue about per-process rows for machine-wide captures, helping the agent select appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The GPU queues this capture saw, with the work counted on each.
queue_id from here goes to pix_get_gpu_timeline. A queue with event_count 0 was seen but never recorded doing anything, usually because the capture did not include the process that owns it.
| Name | Required | Description | Default |
|---|---|---|---|
| capture_id | Yes | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the operation as read-only, idempotent, and non-destructive, so the description does not need to restate that. The description adds valuable behavioral context: event_count 0 means the queue was seen but never recorded doing work, usually due to the owning process not being captured. This goes well beyond what the schema or annotations convey.
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 is two compact blocks with no filler. The first sentence states the core purpose, and the following sentences add the downstream integration and edge-case interpretation. Every sentence 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?
For a simple read-only listing tool with an output schema, the main behavior and the important event_count edge case are covered. The only meaningful gap is the unexplained timeout_seconds parameter and the lack of explicit guidance about when not to use this tool, but these are minor given the tool's simplicity.
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 0%, so the description must compensate, but it never mentions capture_id or timeout_seconds. The phrase 'this capture' implies capture_id, and timeout_seconds remains completely unexplained; an agent cannot tell what timeout applies to or how to set it correctly.
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 clearly states the tool lists GPU queues observed in a capture, with per-queue work counts, and explicitly ties queue_id to pix_get_gpu_timeline. This is specific and actionable, though it does not explicitly differentiate from similar siblings like pix_list_queues or pix_discover_queues.
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 provides clear context: queue_id from this tool feeds pix_get_gpu_timeline, and event_count 0 has a specific diagnostic meaning. It does not explicitly state when to prefer this over sibling tools, but the usage direction is strong enough for an agent to select it in a timing-capture workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every process alive during the capture, busiest first.
A timing capture is machine-wide: capturing one program still records the several hundred others that happened to be running. Only the one PIX attached to is sampled, so the first entry is almost always the one worth looking at and the rest are context for why it was slow. sampled=false means the process existed but did no measured work.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| capture_id | Yes | ||
| name_contains | No | ||
| cursor_position | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare read-only/idempotent/non-destructive behavior. The description adds substantial behavioral context beyond that: captures are machine-wide, only the attached PIX process is sampled, ordering is busiest-first, and sampled=false semantics are explained. This is exactly the kind of non-obvious runtime behavior an agent needs.
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 is compact, front-loads the core result, and each sentence adds meaningful context. The machine-wide caveat, the sampled-process explanation, and the sampled=false note all earn their place without unnecessary 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?
The description is strong on interpreting results and understanding the machine-wide capture behavior, and an output schema exists so return shape details are covered. However, with five input parameters and zero schema descriptions, the lack of any parameter usage guidance leaves an agent guessing about filtering, pagination, and timeout behavior.
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 0% and the description does not explain any of the five input parameters (limit, name_contains, cursor_position, timeout_seconds, capture_id). The description focuses on output semantics rather than parameter meaning, so it does not compensate for the lack of schema descriptions.
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 clearly identifies the tool as listing every process alive during a timing capture, ordered busiest first. It specifies the resource (processes) and distinguishes this from sibling thread/GPU/queue listing tools without needing 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?
The description provides helpful interpretation guidance (first entry is the attached PIX process, rest are context) but does not state when to use this tool versus alternatives such as pix_list_timing_threads or pix_list_timing_gpu_queues. There is no explicit when-to-use or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every thread of one process, with what PIX recorded for each, busiest first.
process_id comes from pix_list_timing_processes. The thread_id here is PIX's own, packing the process and thread together, and is what the per-thread tools take; os_thread_id is the one a debugger would show. stack_levels is how deep this thread's PIX event nesting goes.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| capture_id | Yes | ||
| process_id | Yes | ||
| cursor_position | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds meaningful context beyond that: busiest-first ordering, the distinction between PIX's packed thread_id and os_thread_id, and the meaning of stack_levels. It does not discuss pagination behavior, but the safety profile is already covered by annotations.
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 is three dense sentences with no filler. The core purpose is front-loaded, and the second sentence packs essential ID semantics into a compact contrast between PIX's thread_id and the debugger's os_thread_id. 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?
With an output schema present, the description does not need to enumerate return fields. It covers ordering, ID semantics, and the dependency on pix_list_timing_processes, which is enough for correct invocation. The only real omission is explicit pagination or limit behavior, but that is minor given the schema exposes limit and cursor_position.
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 0%, so the description carries the burden for parameter meaning. It explains process_id provenance and clarifies output-related identifiers such as thread_id, os_thread_id, and stack_levels, but it does not explain capture_id, limit, cursor_position, or timeout_seconds beyond their names. This is partial compensation with clear gaps.
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 clearly what the tool does: list every thread of one process with the data PIX recorded for each, ordered busiest first. It also distinguishes this tool from related siblings by tying process_id to pix_list_timing_processes and positioning it as the source of thread IDs for per-thread tools.
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 explicitly says process_id comes from pix_list_timing_processes and that the returned thread_id is what per-thread tools consume. This tells an agent when to call this tool: after choosing a process, before invoking per-thread analyses. It effectively routes away from alternatives by naming the dependency and downstream consumers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Register a capture and return a capture_id plus a compact overview.
| Name | Required | Description | Default |
|---|---|---|---|
| remote | No | ||
| prefetch | No | ||
| capture_path | Yes | ||
| timeout_seconds | No | ||
| disable_gpu_plugins | No | ||
| enable_recreate_at_gpuva | No | ||
| use_replay_time_executeindirect_buffers | No | ||
| enable_application_specific_driver_state | No | ||
| force_set_application_specific_driver_state | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint=true and readOnlyHint=false, and the description adds no further behavioral context such as whether the capture is loaded into memory, whether repeated calls return an existing capture_id, or whether remote paths trigger network activity. No contradiction with annotations, but no additional transparency either.
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; it efficiently conveys the core action and return value. The conciseness is fine, though it comes at the expense of substantive 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 9 parameters, zero schema coverage, and no usage context, this one-line description is far from complete. The output schema may cover the return value, but input semantics, prerequisites, and optional parameter triggers are entirely opaque. It provides only surface-level registration context.
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 0%, and the description names no parameters or constraints. It only mentions the output capture_id, leaving capture_path, remote, prefetch, timeout_seconds, and the GPU options entirely unexplained. The description does not compensate for the schema 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 action ('register a capture') and the return contract ('capture_id plus a compact overview'). This is distinguishable from close/list/get-overview siblings by the registration action, though 'register' is slightly ambiguous about whether it means opening an existing capture or creating a new 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?
No guidance on when to use this tool versus pix_capture_* for creating captures, pix_close_capture for closing, or pix_get_capture_overview for inspecting an open capture. The name implies opening an existing capture, but the description never states the prerequisite or names alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replay the capture once (or in a loop), optionally timing command-list recording.
| Name | Required | Description | Default |
|---|---|---|---|
| loop | No | ||
| time_cpu | No | ||
| capture_id | Yes | ||
| loop_count | No | ||
| measure_cycles | No | ||
| timeout_seconds | No | ||
| working_directory | No | ||
| do_not_expand_executeindirect | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotent and non-destructive hints, so the description does not need to repeat those. It adds some behavioral context by mentioning looping and optional timing of command-list recording, but it does not disclose side effects, prerequisites, or what happens during replay.
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 is a single, front-loaded sentence with no wasted words. However, it is so brief that it sacrifices necessary detail for an 8-parameter tool.
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 the large parameter set and the existence of similar playback-related siblings, the description is incomplete. It does not explain the required capture_id, the meaning of timing command-list recording, or how this relates to pix_recapture_playback, making correct invocation reliant on guesswork.
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 0% and there are 8 parameters, so the description must compensate but does not. It vaguely hints at loop behavior and timing options, but it never names parameters like capture_id, loop_count, timeout_seconds, or working_directory, leaving their semantics unexplained.
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 action ('Replay the capture') and mentions optional loop and timing behavior, making the core purpose clear. It does not distinguish this tool from the similarly named sibling pix_recapture_playback, so it lacks explicit 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?
There is no guidance about when to use this tool versus alternatives, no prerequisites, and no exclusions. The description only says what the tool does, leaving the agent to infer usage conditions such as requiring an already-open capture.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Capture a replay of the open capture (pixtool must itself be launched for capture).
| Name | Required | Description | Default |
|---|---|---|---|
| capture_id | Yes | ||
| expand_execute | No | ||
| timeout_seconds | No | ||
| include_recreation | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false, and the description adds context beyond them: the operation is scoped to the open capture and requires pixtool to be launched. However, readOnlyHint=false signals a mutating operation, and the description doesn't disclose what side effects 'capturing a replay' has (e.g., writing a file or changing the open capture).
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 is a single front-loaded sentence with no wasted words, stating the action before the prerequisite. The parenthetical compresses the pixtool prerequisite without explaining why it matters, but overall the structure is efficient.
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?
While the output schema covers return values and annotations cover the safety profile, the tool has 4 parameters at 0% schema description coverage and the description leaves most of them unexplained. It also doesn't clarify what a 'replay' is or what the tool concretely produces, which is a significant gap for a non-read-only operation.
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 0%, so the description carries the full burden of explaining the 4 parameters, but it only weakly hints that capture_id refers to an open capture. It says nothing about expand_execute, timeout_seconds, or include_recreation, leaving the agent to guess their meaning.
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 ('Capture') and resource ('a replay of the open capture'), which distinguishes it from siblings like pix_perform_playback (performing playback) and pix_recapture_region (recapturing a region). However, it doesn't explicitly contrast with those siblings, and 'capture a replay' remains somewhat ambiguous about what output is actually produced.
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 parenthetical 'pixtool must itself be launched for capture' provides a concrete prerequisite that helps the agent judge whether the tool can run in the current environment. But there is no guidance on when to choose this over pix_perform_playback or pix_recapture_region, and no exclusion criteria are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write a new .wpix containing only the events in [start_global_id, end_global_id].
| Name | Required | Description | Default |
|---|---|---|---|
| capture_id | Yes | ||
| output_file | Yes | ||
| end_global_id | Yes | ||
| start_global_id | Yes | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool idempotent and non-destructive; the description adds that it writes a new .wpix with a filtered subset, implying no mutation of the source capture. It does not, however, disclose overwrite behavior, whether the source capture must be open, or any other side effects beyond file creation.
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 is a single, front-loaded sentence with no filler. Every phrase contributes information about the operation, the output format, and the filtering scope.
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?
The output schema covers return-value expectations, and the description captures the core operation. However, with 0% schema description coverage, parameter semantics and prerequisites remain under-specified, so an agent must infer important details about the source capture, output path, and optional timeout behavior.
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 0%, so the description must compensate for insufficient parameter documentation. It only clarifies the role of start_global_id and end_global_id as range bounds; capture_id, output_file, and timeout_seconds are left entirely to inference from their property names.
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 ('Write'), a concrete deliverable ('a new .wpix'), and a precise scope ('only the events in [start_global_id, end_global_id]'). This clearly identifies what the tool does and distinguishes it from read-only listing/export siblings and from pix_recapture_playback.
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 intended use is implied: use it when you want to create a subset capture file containing a range of global event IDs. However, the description does not explicitly say when to prefer this over alternatives such as pix_export_event_list or pix_recapture_playback, nor does it mention any prerequisites like having a capture open.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replay the capture with the D3D12 debug layer on, to surface validation errors.
| Name | Required | Description | Default |
|---|---|---|---|
| capture_id | Yes | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as readOnly, idempotent, and non-destructive, and the description does not contradict them. The description adds behavioral context beyond annotations: it replays the capture and enables the D3D12 debug layer, which implies slower execution and explains why a timeout_seconds parameter may be needed.
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 is a single sentence, front-loaded with the action, with no filler or redundant detail. Every word contributes to understanding what the tool does.
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 two-parameter tool with an output schema and safety annotations, the description adequately explains what it does and why. A note about the optional timeout being useful because debug-layer replay can be slow would round it out, but nothing essential for invoking the tool 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 0%, so the description carries the full burden, but it names no parameters. capture_id and timeout_seconds are inferable from their names and the general description, yet their exact semantics, especially the meaning and default behavior of timeout_seconds, are not explained.
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, 'Replay', and names the exact resource: the capture, with the D3D12 debug layer enabled. It also states the outcome ('to surface validation errors'), which distinguishes it from ordinary playback tools like pix_perform_playback.
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 stated purpose, 'to surface validation errors', gives a clear context for when this tool is useful. However, it does not explicitly mention when not to use it or point to alternative replay/playback tools, so usage guidance remains implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run an arbitrary pixtool command pipeline.
This is the escape hatch for pixtool features without a dedicated tool. Pass
commands as a list of objects: {"name": "save-event-list", "positionals": ["out.csv"], "options": {"counters": "gpu__*"}}. Options with a
null value become bare flags. If capture_id is given, open-capture is prepended.
pixtool aborts the remaining commands once one fails. Values containing spaces are quoted automatically; a value containing a double quote cannot be expressed.
| Name | Required | Description | Default |
|---|---|---|---|
| commands | Yes | ||
| capture_id | No | ||
| output_level | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds important runtime behavior beyond the annotations: pixtool aborts remaining commands once one fails, null option values become bare flags, values with spaces are quoted automatically, and double quotes cannot be expressed. These are non-obvious and not covered by readOnlyHint or destructiveHint.
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 sentence earns its place: purpose, escape-hatch positioning, command object format, null-option handling, capture prefix, failure semantics, and quoting edge cases. It is dense but well-organized and front-loads the core description without 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?
The description is very complete for an open-world escape hatch: it covers command structure, failure behavior, quoting, capture prefix, and gives a concrete example. The only minor gap is the semantics of output_level and timeout_seconds, which are optional and not required for basic invocation. The presence of an output schema reduces the need to describe return values.
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?
For a tool with 0% schema description coverage, the description compensates well for 'commands' (list of objects with name, positionals, and options) and for 'capture_id' (prepends open-capture). However, it says nothing about 'output_level' or 'timeout_seconds', leaving those optional parameters without added meaning beyond their titles, which is a clear 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?
The first sentence states a specific action: 'Run an arbitrary pixtool command pipeline.' It also explicitly labels itself as the escape hatch for pixtool features without a dedicated tool, which distinguishes it from the many sibling pix_* tools and clarifies its unique role.
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 explicitly says this tool is for pixtool features 'without a dedicated tool', giving a when-to-use versus when-not-to-use rule. It also provides a concrete invocation structure with an example and explains the capture_id prefix behavior, so an agent knows exactly how to construct a call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Collect High Frequency Counters (a GPU-wide time series) and return sample rows.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| merge | No | ||
| cursor | No | ||
| refresh | No | ||
| counters | No | ||
| capture_id | Yes | ||
| destination | No | ||
| counter_regexes | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations mark readOnlyHint=false, so the description should disclose side effects, but it only says 'collect' and 'return sample rows' without explaining the save/ write behavior implied by the name and the destination parameter. The description adds the useful 'GPU-wide time series' context but omits what gets modified, written, or refreshed.
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 is a single short sentence and front-loads the core purpose, but it is under-specified for a tool with nine parameters and several sibling tools. It lacks parameter semantics, side effects, and usage context, making it concise at the expense of necessary substance.
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 detail is not strictly required, but the description still fails to provide enough context for correct invocation. It does not explain parameters, mention the save/destination behavior, or distinguish this tool from similar counter-related siblings, which is insufficient for a 9-parameter tool.
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 0% and none of the nine parameters (limit, merge, cursor, refresh, counters, capture_id, destination, counter_regexes, timeout_seconds) are explained in the description. The description only names the resource and result, leaving all parameter semantics to be guessed.
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 ('Collect') and a concrete resource ('High Frequency Counters' described as a GPU-wide time series), and it indicates the result ('return sample rows'). However, it does not explicitly differentiate this tool from sibling tools like pix_collect_counters or pix_list_counters, and the 'save' behavior implied by the tool name is not reflected in the description.
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 guidance is given about when to use this tool versus alternatives such as pix_collect_counters, pix_list_counters, or pix_list_timing_counters. Prerequisites like having an open capture or a valid capture_id are also not mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save a bound resource (render target or depth buffer) from a draw call.
The file format follows the destination extension. Without global_id or marker, pixtool uses the last event in the capture that has the resource bound.
| Name | Required | Description | Default |
|---|---|---|---|
| rtv | No | ||
| depth | No | ||
| marker | No | ||
| global_id | No | ||
| capture_id | Yes | ||
| destination | Yes | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the operation is non-read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond annotations: the output format is determined by the destination extension, and event selection falls back to the last bound event when global_id or marker is omitted. There is no contradiction with the annotations.
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 is concise and well-structured: the first sentence states the core purpose, and the second adds important file-format and selection fallback details. Every sentence earns its place with no filler or redundant restating of the tool name.
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?
The description covers the essential behavior and the non-obvious fallback selection logic, and an output schema exists to describe return values. However, with 7 parameters and no schema descriptions, more detail about required capture_id, destination semantics, and timeout_seconds would be needed for fully confident invocation. It is adequate but has clear 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 description coverage is 0%, so the description must compensate for the 7 undocumented parameters. It provides semantic hints for rtv, depth, global_id, marker, and destination, but it does not clarify capture_id, timeout_seconds, or the exact meaning/format of destination beyond extension-based format. The coverage is too partial for a schema with no property descriptions.
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 action ('Save') and a specific resource ('a bound resource (render target or depth buffer) from a draw call'), which clearly identifies the tool's purpose. It does not explicitly name sibling tools or how it differs from pix_save_screenshot or pix_get_resource, but the resource type and draw-call context make the purpose reasonably distinct.
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 the tool: when you need to save a bound render target or depth buffer from a draw call. It also gives a useful selection rule about global_id/marker and the fallback to the last bound event, but it does not explicitly state when to prefer this tool over alternatives like pix_save_screenshot or pix_get_resource.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save the capture's frame screenshot as a PNG.
| Name | Required | Description | Default |
|---|---|---|---|
| refresh | No | ||
| capture_id | Yes | ||
| destination | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal that this is not read-only, is idempotent, and is non-destructive. The description adds that it writes a PNG screenshot of a capture frame, but it does not disclose where the file is written, whether an existing file is overwritten, or whether the capture must be open.
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 is a single clear sentence with no filler and the core action is front-loaded. It could be more informative, but as a concise statement it is well structured.
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 tool with four parameters, no parameter descriptions in the schema, and a write side effect, this description is incomplete. The output schema removes the need to explain return values, but destination, refresh behavior, timeout, and any prerequisites 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?
With 0% schema description coverage, the description needed to explain the four parameters, but only 'capture's frame' hints at capture_id. refresh, destination, and timeout_seconds are left entirely unexplained, so the agent cannot know their semantics without external knowledge.
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 the exact operation ('Save'), the specific resource ('the capture's frame screenshot'), and the output format ('as a PNG'). This clearly distinguishes it from sibling save tools like pix_save_resource and pix_save_high_frequency_counters.
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 guidance on when to use this tool versus any alternative, and no mention of required capture state or typical scenarios. The single sentence describes what it does but not why or when an agent should call it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search events by name (substring, glob, or regex) with optional filters.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| cursor | No | ||
| refresh | No | ||
| category | No | ||
| use_regex | No | ||
| capture_id | Yes | ||
| queue_name | No | ||
| name_pattern | Yes | ||
| global_id_max | No | ||
| global_id_min | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already establish read-only, idempotent, non-destructive behavior, so the description's job is narrower. It adds useful matching behavior (substring, glob, or regex) and states that filters exist, but it leaves the meaning of refresh, timeout, cursor pagination, and global_id bounds undisclosed. This is modest extra context beyond the annotations.
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 concise, front-loaded sentence with no filler. The key search resource, matching modes, and filter existence are all present. It is appropriately brief, though the brevity contributes to the completeness gaps noted elsewhere.
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 11 parameters, zero schema descriptions, and a required capture_id that the description never mentions, this is under-specified. The existence of an output schema removes the need to describe return values, but input semantics, pagination, filter usage, and the required capture context are still missing. An agent would have to infer too much from parameter names to call it correctly in non-default cases.
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 0%, so the description must compensate, but it only clarifies name_pattern (substring/glob/regex) and vaguely references 'optional filters'. None of the other parameters (refresh, cursor, category, queue_name, global_id_min/max, timeout_seconds, capture_id) are explained, and there is no mapping of filter names to the parameters. This is a substantial gap for an 11-parameter tool.
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 action ('search') on a specific resource ('events') with explicit matching modes (substring, glob, regex) and optional filters. This distinguishes it from sibling tools like pix_list_events, which imply unfiltered listing, and pix_get_event, which implies single-event retrieval. The only minor weakness is not naming those siblings directly.
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 intended usage is implied by the phrase 'search events by name': an agent should use this when it needs to find events matching a name pattern. It does not explicitly compare against pix_list_events, pix_get_event, or other event tools, nor state when not to use it. This is adequate but leaves routing to the agent's inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replay a capture on a GPU so that PIX's timing data exists. Slow, and once only.
PIX gets per-event GPU timing by replaying the capture on a real D3D12 device; the 4.5 GB reference capture takes about twenty-five seconds. This blocks for up to wait_seconds (90 by default, enough for most captures) and reports where it got to. The replay keeps running between calls, so polling is free; pass wait_seconds=0 to start it and return at once. Once ready is true, pix_get_event_timing answers for every event in every queue at no further cost.
Windows defaults to this machine. Xbox requires an explicit device_address matching the GDK PIX analysis devkit and may interrupt its running title.
| Name | Required | Description | Default |
|---|---|---|---|
| capture_id | Yes | ||
| wait_seconds | No | ||
| device_address | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, it discloses blocking duration, that replay is once-only but continues between calls, free polling, default wait_seconds, and platform-specific behavior including Xbox device_address requirements and possible interruption of the running title. This greatly exceeds annotation coverage.
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 is multi-sentence but every sentence earns its place: purpose, performance, blocking/polling behavior, and platform notes. It is front-loaded with the core purpose and key constraints.
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 complex replay tool with no schema descriptions, the description covers nearly all operational context: blocking, waiting, platform differences, and downstream timing queries. It would be fully complete if timeout_seconds semantics were explained and the lifecycle relationship to open/close captures was made explicit.
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 0%, so the description must explain parameters. It gives rich semantics for wait_seconds and device_address, but never explains timeout_seconds and only implicitly references capture_id. This partial compensation earns a middle score.
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 states a specific action and resource: replay a capture on a GPU so PIX timing data exists. It also distinguishes itself from the dependent sibling pix_get_event_timing by noting that once ready, timing answers are available at no further cost.
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 clearly implies when to call it: before pix_get_event_timing, and explains polling behavior with wait_seconds=0. It does not explicitly list alternative tools or when not to use it, but the context is clear enough for an agent to route correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show the regexes that select a counter exactly, or its whole family.
| Name | Required | Description | Default |
|---|---|---|---|
| counter_name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish that the tool is read-only, idempotent, and non-destructive, so the description does not need to restate those traits. It adds a little behavioral context by promising regexes that match either exactly or by family, but it leaves unclear what 'whole family' means or what the returned regexes look like.
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 is only one sentence and has no filler or redundant phrases, making it efficient. It is slightly under-specified, but all words contribute to the core meaning, so conciseness itself is good.
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 single-parameter, read-only tool with an output schema and annotations, the description is minimally adequate. However, it lacks usage guidance and leaves the meaning of 'whole family' and the counter_name input under-specified, so an agent may not confidently choose and invoke it without extra inference.
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 schema has a single required counter_name string with 0% description coverage, so the description must compensate. It only refers indirectly to 'a counter' and never explains how counter_name should be formatted, whether it is an exact counter name, or how family selection is controlled. This is minimal added meaning beyond the parameter name.
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 uses a specific verb ('Show') and identifies the resource: regexes for selecting a counter, with the added scope of exact vs. family matches. This distinguishes it from counter-list or counter-collection siblings like pix_list_counters and pix_collect_counters, though the phrasing 'select a counter exactly' is somewhat terse.
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 guidance about when to use this tool instead of related counter tools, nor any mention of prerequisites or exclusions. The only signal is the implied use case: the agent should call this when it needs regex patterns to select counters. This falls short of clear routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upgrade a GPU capture file to the latest PIX format.
Without a destination the source file is overwritten in place.
| Name | Required | Description | Default |
|---|---|---|---|
| destination | No | ||
| timeout_seconds | No | ||
| source_capture_path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds a key behavioral detail beyond those annotations: without a destination, the source file is overwritten in place. This warns the agent about the destructive default and clarifies the destination parameter's role. It does not further explain idempotency or side effects, but the most critical trait is disclosed.
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 with no fluff. The primary action is first, and the critical overwrite behavior is front-loaded in the second sentence. Every word 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?
The tool is relatively simple with one required parameter and an output schema, so return values are already handled. However, the optional timeout_seconds parameter is unexplained, and the description does not clarify whether destination is a file path, directory, or how the upgrade process reports progress/errors. It is adequate for basic usage but incomplete for fully informed 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 description coverage is 0%, so the description must compensate. It indirectly explains the destination parameter ('Without a destination') and the source by name in the tool title, but timeout_seconds is entirely undocumented and no parameter is described with enough detail for an agent to know expected formats, constraints, or behavior. This is a significant gap at zero schema coverage.
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 ('Upgrade'), a specific resource ('GPU capture file'), and the target format ('latest PIX format'). This is unique among the large sibling list—no other tool performs file upgrading—so an agent can clearly distinguish it from the other operations.
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 gives no explicit guidance on when to use this tool versus alternatives, and no sibling performs a similar upgrade operation. The overwrite-in-place behavior implies a choice between destination and in-place, but there is no direct statement about prerequisites, when upgrading is needed, or when to avoid it.
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.1.0pix_build_bridgepix_capture_apppix_capture_attached_processpix_capture_programmaticpix_capture_timingpix_capture_uwp_apppix_clear_capture_cachepix_close_capturepix_collect_counterspix_collect_occupancypix_discover_queuespix_export_event_listpix_export_to_cpppix_get_allocation_movespix_get_api_objectspix_get_bridge_statuspix_get_capture_overviewpix_get_command_listspix_get_context_switchespix_get_controller_inputpix_get_core_activitypix_get_counter_hotspotspix_get_cpu_samplespix_get_custom_datapix_get_eventpix_get_event_timingpix_get_event_treepix_get_file_iopix_get_gpu_framespix_get_gpu_timelinepix_get_metric_valuespix_get_page_faultspix_get_pipeline_statepix_get_residency_operationspix_get_resourcepix_get_resource_viewspix_get_root_signaturepix_get_server_statuspix_get_thread_timelinepix_get_timing_summarypix_list_controllerspix_list_counterspix_list_custom_data_typespix_list_eventspix_list_gpu_eventspix_list_metricspix_list_open_capturespix_list_queuespix_list_resourcespix_list_storage_devicespix_list_timing_counterspix_list_timing_gpu_queuespix_list_timing_processespix_list_timing_threadspix_open_capturepix_perform_playbackpix_recapture_playbackpix_recapture_regionpix_run_debug_layerpix_run_pixtoolpix_save_high_frequency_counterspix_save_resourcepix_save_screenshotpix_search_eventspix_start_analysispix_suggest_counter_patternpix_upgrade_captureScored across 67 tools
Most tools have distinct purposes, but a few pairs overlap, such as pix_list_queues vs pix_discover_queues and pix_list_events vs pix_list_gpu_events. The detailed descriptions help, but the large number of tools makes misselection more likely.
All tools follow a consistent snake_case verb_noun pattern with the pix_ prefix, such as list_resources, get_pipeline_state, and capture_timing. This consistency makes the tool's action and target predictable across the entire set.
With 67 tools, this far exceeds the typical well-scoped MCP server range. While the PIX domain is broad, the count is unwieldy and could benefit from being split into focused servers by area such as capture, timing, or GPU analysis.
The tool set covers the full capture-analysis lifecycle: capture from various targets, open/close/upgrade captures, inspect GPU/CPU timing, events, resources, pipeline state, counters, occupancy, memory, input, and export. No obvious dead ends or missing core operations are apparent.
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
Analytics and debugging for your MCP server — explore usage and sessions, then root-cause errors.
Remote MCP for C2PA intake verifier MCP, structured receipts, audit logs, and reviewer-ready evidenc
OCR, transcription, file extraction, and image generation for AI agents via MCP.
