perf_kwork_latency

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the output ('per-handler latency table') and the prerequisite, but does not mention whether the tool modifies anything, what input files it reads, or other potential side effects. This is moderate transparency; the core behavior is clear enough but lacks depth.

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 very concise and front-loaded: the first sentence states the core purpose, followed by a short list of key parameters, output, and requirement. Every sentence earns its place with no fluff or redundancy.

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 that an output schema exists, the description does not need to explain return values. It covers the essential context: what the tool does, key parameters, output format, and a prerequisite. It is adequate for an AI agent to understand when to invoke it, though it could optionally mention that the 'input' parameter is a perf.data file.

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 input schema has 100% coverage with descriptions for all 14 parameters, so the baseline is 3. The description restates a few parameters (sort, name, kwork) with slightly different wording but does not add significant new meaning beyond the schema. No additional semantics are provided for the remaining parameters.

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 tool as a 'Kernel work item latency breakdown showing scheduling delay for each handler,' which distinguishes it from sibling tools like perf_kwork_top or perf_kwork_report by focusing specifically on latency and scheduling delay. The purpose is immediately understandable and specific.

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 provides clear context for use—latency breakdown of kernel work items—and explicitly mentions a prerequisite ('Requires: perf kwork record'). However, it does not explicitly compare against alternatives or state when not to use this tool, so it stops short of a 5.

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