List GPU Trace shader objects

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. Beyond that, the description adds valuable caveats: 'A blob reference does not imply complete source/call-stack debug information' and 'Sample counts cover Entire Trace.' These clarify data semantics and scope, providing extra behavioral context not present in 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. The first sentence is dense but efficiently lists all key output fields. The second and third sentences each add a critical caveat without fluff. Every word serves a purpose, and the structure is front-loaded with the main action and resource.

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 7 parameters and no output schema, and schema descriptions cover only 29% of them. The description explains output contents and a couple of relevant caveats, but it fails to clarify the behavior of shader_regex and include_inactive, or how pagination (limit/offset) works. This incompleteness is significant for an agent to select and invoke the tool correctly, especially given the absence 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 only 29%, so the description must compensate. It does add meaning for stage and debug_blob parameters by mentioning 'exact shader stage/name/hash' and 'debug-blob reference state,' but it omits explanations for shader_regex, include_inactive, limit, and offset. These parameters remain undocumented in both schema and description, leaving significant ambiguity 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 clearly states 'Return the Shader Pipelines table grouped by Shader Object' with a precise list of output fields (shader stage/name/hash, sample counts, DXIL/SPIR-V correlation, debug-blob state, referencing pipelines). It distinguishes from siblings by the explicit grouping and the detailed output, especially versus list_gpu_trace_shader_pipelines, which likely provides a different view.

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 use when needing shader-object-level detail, but it does not explicitly state when to prefer this tool over alternatives like list_gpu_trace_shader_pipelines or list_gpu_trace_shader_occupancy. No exclusions or alternative references are provided, so usage context is 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.