rolldev_inspector_trace

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

With no annotations, the description carries the burden and does much of it: it declares 'Read-only: never changes the environment', states the output shape ('compact text plus JSON'), and discloses the 200-span cap tied to include_spans. It omits error behavior, auth/env prerequisites, and whether the analysis is sampled or truncated beyond the span cap.

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, both dense and front-loaded: the analytical output comes first, then the conditional span payload and the safety guarantee. No filler and no repetition 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?

There is no output schema, so the description must characterize the return value, and it does — cost per category, hot spans, N+1 calls, slowest calls, text plus JSON. Combined with 100% parameter coverage this is nearly complete; a short note on what 'cost' means (tokens/money/time) would close the gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all four parameters including the 200-span cap on include_spans. The description only restates the include_spans behavior and adds nothing about save_output_to_file or about how project_path affects the analysis, so it stays at the baseline.

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+resource ('Bottleneck analysis of one trace') and enumerates exactly what is produced: cost per category, hot spans, N+1 calls, slowest calls. It is clearly distinguishable from a sibling like rolldev_inspector_traces (listing traces) by the 'one trace' scope, but it never explicitly names the alternatives it contrasts with.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Usage is implied rather than stated: you call this to diagnose a single trace whose id you already have. The schema field note ('Trace id from rolldev_inspector_traces') supplies the discovery path, but the description itself gives no when-to-use/when-not guidance versus rolldev_inspector_hotspots, rolldev_inspector_request or rolldev_inspector_service.

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