perf_report

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

No annotations are provided, so the description carries the full burden. It discloses output format ('table with columns like % overhead | command | DSO | symbol'), prerequisites for special modes ('needs perf record -d', '-b', '--latency'), and important caveats like 'Works on any perf.data.' It does not explicitly address whether the command modifies state, but as an analysis/report tool this is not a major gap.

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 long, but it is front-loaded with the core purpose and organized into a 'Key parameters' list. Every line conveys useful information for a complex tool with 72 parameters. It is not as tight as a two-sentence description, but it earns its length by preventing common misuse.

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 tool's high complexity (72 parameters) and no annotations, the description provides a solid orientation: it explains what the tool does, what output to expect, which parameters matter most, and what data prerequisites exist for special modes. It could be more complete by naming sibling alternatives for non-CPU analyses, but it is more than sufficient for common use 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?

Although the schema already covers 100% of parameters, the description adds substantial value by explaining key parameters with practical examples: sort default and useful alternatives, call_graph syntax ('graph,0.5,caller,function,percent'), percent_limit semantics, and mode switches (mem_mode, branch_stack, latency). This goes well beyond the schema's one-line definitions and makes the tool significantly more usable.

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?

Opens with a specific verb and resource: 'Histogram profiling: shows which functions consumed the most CPU time... as a ranked overhead table.' It explicitly positions itself as 'the primary analysis tool' for answering 'where is time spent?', which distinguishes it from sibling perf tools like perf_annotate or perf_mem_report.

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?

Clearly identifies the primary use case: answering 'where is time spent?' and states it works on any perf.data from perf record. It does not explicitly name alternatives or exclusion criteria, but the 'primary analysis tool' framing gives clear context compared to sibling tools. Lacks explicit 'use X instead when' guidance, so not a 5.

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