pix_get_pipeline_state

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.