get_stutters

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

Beyond the read-only and non-destructive annotations, it discloses that the tool may first watch for watch_seconds when a trace is not already running and that no game is opened. It does not further explain trace startup behavior, privilege requirements, or how inactivity affects the usefulness of the measurements.

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 compact sentences front-load the measurements and then cover timing and the absence of game-launching side effects. The opening fragment and long first sentence are somewhat dense, while phrases such as "every program that draws (games)" could be expressed more clearly.

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 one optional parameter, the definition supplies enough information to invoke it with defaults, anticipate a possible wait, and understand the broad result categories despite the absence of an output schema. It remains less complete about stutter thresholds, trace prerequisites, and data-quality expectations when little rendering or interrupt activity occurs.

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 already fully documents watch_seconds, including its range, default, and sampling rationale. The description adds useful semantics beyond that schema by explaining that the watch period applies conditionally when the trace was not already running.

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 diagnostic data: frame rate, 1% lows, frame times and stutter counts for rendering programs, recent stutters, and per-driver DPC/ISR spikes. This scope implicitly distinguishes it from generic CPU, GPU, and process tools, but it lacks an explicit collection verb or direct sibling comparison.

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 focus on games and LatencyMon-style driver timing provides clear context for diagnosing rendering stutters and driver-latency spikes. It does not explicitly state when to prefer it over tools such as get_history, record_activity, get_cpu, or get_gpus, or mention that representative workload activity may be needed.

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