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

With no annotations, the description carries the full burden. It discloses the output format (source/assembly listing with % annotations), the key requirement (debuginfo for source interleaving), and compatibility (works on any perf.data). It doesn't explicitly state it's read-only, but the verbs 'shows' and 'annotation' strongly imply a non-mutating analytical operation. The provided behavioral details (output, requirements) go beyond the bare minimum.

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 front-loaded with the purpose, then provides usage context, key parameters, output, and requirements. It is organized with a 'Key parameters:' section and uses concise bullet-like formatting. While it lists seven parameters, each earns its place by clarifying important defaults or options. It remains reasonably compact for a tool with 33 parameters.

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 complexity (33 params), the description covers the essential workflow, key parameters, output, and dependency (debuginfo). The output schema exists, so return values are already specified. The only minor gaps are not discussing every parameter or potential limitations (e.g., permission requirements), but the schema covers parameter details. Overall it provides enough context for an agent to invoke the tool correctly.

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 baseline is 3. The description adds meaningful semantic context for several key parameters: symbol (default: hottest), dsos (restrict to binary/library), source (interleave source), disassembler_style (Intel vs AT&T), percent_type (enumerating options), data_type, and code_with_type. These enrich the terse schema descriptions, especially for percent_type where the schema only says 'Percent type.'

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 opens with 'Source/assembly annotation: shows per-line or per-instruction sample percentages inside a specific function.' This clearly states the verb (shows), the resource (source/assembly annotation with percentages), and the specific scope (inside a specific function). It also differentiates from siblings by positioning it as a follow-up to perf_report for drilling into hot functions.

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?

Explicitly says 'Use this after perf_report to drill into a hot function,' giving clear workflow context. It doesn't explicitly list alternatives or exclusion cases, but the 'after perf_report' instruction implies its role relative to sibling tools. The description also notes requirements (debuginfo packages) which further guides when to use.

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

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

With no annotations provided, the description takes on the burden of disclosing behavior. It explains the output format, notes that it 'Works on any perf.data,' and clarifies the effects of the kernel and kernel_maps flags. It does not, however, describe error behavior or permissions needed, but for a read-only listing tool this is sufficient.

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 compact, front-loaded with the main purpose, and uses a clear structure: purpose, use case, key parameters, and output format. Every sentence contributes meaningful information without unnecessary elaboration.

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 and the input schema covers all parameters, the description adds necessary extra context about the tool's purpose and usage scenario. It also covers the output format and typical use case, making it complete for a straightforward listing tool. It omits only minor details like interaction with force/verbose, which are already in the 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?

The schema already provides 100% coverage of parameter descriptions. The description's parameter notes restate or slightly reword the schema (e.g., with_hits 'only show DSOs that have actual samples' vs schema 'Show only DSOs with hits'), adding little new information. It does not explain 'force' or 'verbose' beyond their schema descriptions, so the value added is marginal.

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 opens with a precise verb and resource: 'List the ELF build-id hashes for binaries referenced in perf.data.' This clearly distinguishes the tool from sibling perf tools, which are about reports, timecharts, or sched operations, and not about build-id verification.

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 explicitly states a use case: 'Use this to verify symbol resolution will work: compare build IDs against installed debuginfo packages.' This gives a clear context and intent. While it doesn't explicitly mention when not to use it, the guidance is strong enough for selection.

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

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

No annotations exist, so the description carries the full burden. It discloses what the tool does (HITM analysis), key parameter behaviors, output structure, and a prerequisite ('perf record -d -a'). It does not describe error handling or exit codes, but for a read-only analysis tool, this is sufficient.

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 well-structured and concise, starting with a clear definition, then usage guidance, key parameters in a bulleted list, output summary, and a prerequisite. Every sentence contributes information without 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 the tool's complexity (21 parameters, output schema), the description provides essential context: purpose, usage scenario, key parameters, output format, and prerequisite. It does not explain every parameter, but the schema already covers those. The description adds context that is not available elsewhere, making it complete enough for an AI agent to select and invoke the tool correctly.

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 already describes all 21 parameters, achieving 100% coverage. The description adds extra meaning for key parameters like display (explaining 'tot', 'lcl', 'rmt' values), coalesce (example grouping), stats, and call_graph, going beyond the schema's minimal descriptions. This added value justifies a score above 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 clearly identifies the tool as a cache-to-cache false sharing analysis, specifically detecting cache lines with the most HITM events. This distinguishes it from sibling perf tools like perf_mem_report or perf_report, which focus on different aspects of memory and performance analysis.

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?

It explicitly states when to use the tool: to diagnose multi-threaded performance issues from false sharing. However, it does not mention when NOT to use it or point to alternatives. This is clear usage context but lacks explicit exclusions or alternative recommendations.

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

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

No annotations are provided, so the description must disclose behavior. It explains the mutual exclusivity of output formats and the output path return. However, it doesn't mention that the tool writes output files, whether it overwrites existing files, or any side effects, which are relevant for a conversion tool.

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 concise and well-structured, with a clear opening sentence, a use-case line, and bullet points for key parameters. Every sentence adds value, and the output line is informative.

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 complexity (8 params) and presence of an output schema, the description covers the essential context: its purpose, the key parameters, the constraint, and the return value. It is complete for an AI agent to select and invoke the tool correctly.

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 baseline is 3. The description adds meaning by highlighting key parameters (to_json, to_ctf, all, tod) and providing an example path. It also introduces the exactly-one rule, which is not encoded in the schema.

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?

Description clearly states the tool converts perf.data to JSON or CTF, with a specific verb and target formats. This distinguishes it from sibling tools like perf_report or perf_annotate, which analyze rather than export data.

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?

Explicitly states the use case: 'Use this to export data for processing in external tools.' It also provides a constraint (exactly one of to_json or to_ctf). It doesn't mention when-not-to-use or alternative tools, but the context is clear.

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

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

No annotations are provided, so the description must handle behavioral transparency. It does disclose that both files must be from perf record with compatible events and describes the output format. However, it does not explicitly state whether the operation is read-only or has any side effects, which is a gap without 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 concise and well-organized: it starts with the core purpose, follows with a usage sentence, a recognizable list of key parameters, the output format, and then a constraint. Every sentence adds information and there is no 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?

The description covers the essential output (differential table with columns) and the prerequisite (compatible events), which is important given the large schema and no provided output schema. It doesn't explain every parameter, but it highlights the key ones and gives enough context to successfully invoke the tool.

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 schema has 100% description coverage, giving a baseline of 3. The description adds value by clearly identifying old_input as baseline and new_input as comparison, and by expanding the compute parameter with valid methods ('delta', 'delta-abs', 'ratio', 'wdiff', 'cycles'), which goes beyond the schema's generic 'Comparison method' label.

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 that the tool compares two perf.data profiles side by side and shows per-symbol overhead changes between baseline and new measurement. It also mentions concrete use cases (optimization validation, regression detection, A/B testing), which distinctly positions it against siblings like perf_report or perf_annotate.

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 explicitly instructs when to use the tool: 'Use this for before/after comparisons — optimization validation, regression detection, or A/B testing.' This gives clear context, though it does not explicitly mention when not to use it or name alternative tools, so a score of 4 is appropriate.

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

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

With no annotations, the description carries the behavioral burden. It discloses the output format ('one event per line'), the data shown (name, type, config, sampling settings), and states there are no prerequisites. While it doesn't explicitly say 'read-only,' the verb 'List' and absence of mutation language make the behavior clear.

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?

Every sentence earns its place: purpose, usage, parameter notes, output format, and prerequisites are covered in a short, front-loaded structure with no fluff.

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?

For a simple list tool with six parameters, an output schema, and no annotations, the description covers purpose, usage, key parameters, output, and prerequisites. It is complete enough for an agent to invoke correctly without additional context.

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?

All six parameters have schema descriptions (100% coverage), and the description adds extra guidance for freq, group, and verbose by explaining what each flag enables (e.g., 'verbose=1 for full perf_event_attr details'). This exceeds the baseline for a fully-schema-covered tool, though force and trace_fields aren't mentioned.

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?

Description opens with a specific verb-resource pair: 'List events in a perf.data file.' It also differentiates itself from sibling perf tools by stating 'Always call this first to understand what was recorded before using other tools,' making its role in the workflow explicit.

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?

Provides clear context: 'Always call this first' and 'No prerequisites — works on any perf.data.' It does not name an alternative tool for specific scenarios, but the 'first before other tools' instruction gives unambiguous usage timing.

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

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

With no annotations, the description carries the full burden. It discloses that the tool writes a new perf.data file and returns path and size, and it explains the semantics of the itrace values. However, it does not mention side effects like overwriting existing output or the meaning of the force flag, though these are present in the schema.

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 efficient and well-structured: it leads with the core purpose, then a usage note, then a key-parameter list, and finally the output. Each sentence contributes, with no wasted words.

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 complexity (20 params) and the presence of a full output schema, the description covers the essential context: what it does, when to use it, and what it returns. It does not enumerate every parameter, but the schema fills that gap, and the description provides enough for selection and invocation.

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 baseline is 3. The description adds significant value by detailing itrace option values ('i0ns', 'b', 'c', 'e') with their meanings, and by summarizing the roles of build_ids, jit, and sched_stat parameters more succinctly than the schema.

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 transformer of perf.data files with a specific verb ('Transform') and resource ('perf.data file'), listing concrete operations like injecting build IDs and decoding hardware traces. It also distinguishes itself from sibling tools by positioning it as a preprocessing step before perf_report or perf_script.

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?

It explicitly states when to use the tool: 'Use this as a preprocessing step before perf_report or perf_script.' This provides clear context and implies that other perf tools are for downstream analysis, not for this injection/transformation step.

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

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

No annotations are provided, so the description must disclose behavior. It clearly states the tool reads the running kernel's symbol table, requires no perf.data, and returns a specific output format. This is sufficient for a read-only lookup, though it doesn't mention permissions or edge cases.

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 efficient: one sentence for purpose, one for the perf.data caveat, then a compact parameter list and output format. Every sentence adds value with no wasted words.

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 simple 2-parameter tool, the description fully covers what the tool does, its prerequisites, and its return format. The schema covers parameters, and the description provides an output format example, making it complete.

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 already provides descriptions for both parameters (100% coverage). The description repeats this information and adds the output format, but does not need to compensate for missing schema details.

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 uses a specific verb and resource: 'Look up a kernel symbol by name' and lists the return fields (address, type, module). This clearly distinguishes it from sibling perf tools, none of which perform symbol lookup.

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?

Explicitly states that it does not require a perf.data file and reads the running kernel's symbol table directly, giving clear context for when to use it. However, it does not explicitly name alternatives or exclusion criteria.

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

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

With no annotations, the description carries the burden of disclosure. It adds valuable context: the requirement of a prior 'perf kmem record', the output format (allocation statistics table), and the meaning of key parameters like 'live' for leak detection. It implies a read-only analysis, which is consistent with the tool's nature.

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 tightly structured: purpose statement, use case, key parameters, output, and prerequisite. Every sentence adds value, and it is succinct enough to parse quickly without missing important details.

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?

For a stats tool with an output schema and 12 parameters, the description covers the main behaviors, parameter semantics, output format, and a prerequisite. It is sufficiently complete for an agent to decide when to use it and how to invoke it.

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 schema coverage is 100%, the description enriches key parameters: it explains slab as kmalloc/kmem_cache, page as page allocator, caller as per-callsite, live as not-yet-freed allocations, and lists sort keys. This goes beyond the raw schema descriptions.

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 the tool provides kernel memory allocation statistics with slab and page allocator activity and per-callsite breakdown. This is a specific verb+resource that distinguishes it from sibling perf commands.

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?

It explicitly tells when to use the tool: 'Use this to find excessive allocators, fragmentation, or leaks.' It also notes a prerequisite ('Requires: perf kmem record'), giving context for invocation, though it does not explicitly name alternative tools or when not to use it.

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

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

With no annotations, the description carries the burden and does provide useful behavioral context: it states the required prerequisite ('Requires: perf kvm stat record'), the output shape (exit reason table with count, time, percentage), and interpretive behaviors. It does not explicitly mention permissions or side effects, but as a read-only analysis tool this is a reasonable disclosure.

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 compact and well-structured: it leads with purpose, then use case, then key parameters, then output and requirements. Every sentence contributes value; there is no redundancy or filler.

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 complexity (21 parameters) and the presence of a complete input schema and output schema, the description adequately covers the core purpose, diagnostic use cases, key parameter meanings, output, and prerequisite. It could be slightly more complete by mentioning side-effect/permission details, but overall it provides enough context for correct selection and invocation.

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 100%, so the baseline is 3. The description goes beyond the schema by detailing sort key values ('sample', 'time', 'max', 'min'), giving an example exit type ('HLT'), and explaining the guest/host filter semantics. Not all 21 params are covered, but the most decision-relevant ones are enriched.

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 opens with a specific verb+resource pairing: 'KVM virtual machine exit analysis: shows VM exit reasons, counts, and time per exit type.' This clearly distinguishes the tool from the many perf sibling tools by stating exactly what it analyzes and what it reports.

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?

It gives explicit use guidance: 'Use this to diagnose virtualization overhead' and provides concrete diagnostic examples (HLT exits, I/O exits, EPT violations). It does not name alternative tools or state when not to use it, so it falls just 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.

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.

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

With no annotations, the description carries the burden. It discloses the output (per-handler statistics table) and the prerequisite (perf kwork record), but does not discuss read-only nature, error behavior, or any edge cases. It is not misleading, but not rich either.

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 well-structured: a bold summary, a use-case line, key parameters in bullet-like lines, output line, and requirement line. Every sentence adds value, and there is no redundancy or fluff.

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 complexity (14 params, output schema), the description provides a concise overview covering purpose, typical use, key filters, output, and prerequisite. It leaves parameter details to the schema, which is acceptable. It could include an example invocation, but the summary is sufficient.

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% with adequate descriptions for all 14 parameters. The description highlights three key parameters (sort, name, kwork) and repeats their allowed values, but adds no new information beyond what the schema already provides. Baseline 3 is appropriate.

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 the tool provides kernel work item statistics (IRQ, softIRQ, workqueue) with count, total runtime, and max latency. It further clarifies the use case: 'Use this to find the most expensive interrupt handlers or work items.' The sibling differentiation is implicit by focusing on report-style post-processing (Requires: perf kwork record) versus live tools like perf_kwork_top.

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 explicitly says when to use it ('Use this to find the most expensive interrupt handlers or work items') and notes the prerequisite 'Requires: perf kwork record.' It does not explicitly name alternatives or state when not to use, but the context is clear enough for an agent to choose between report and other kwork tools.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool consumes a perf kwork record (rather than doing recording itself) and that it outputs a per-event timeline. However, it does not reveal whether the operation is read-only, whether it writes files, requires special privileges, or how the BPF option behaves. This is moderate transparency—better than nothing but incomplete for a tool with 16 parameters.

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 exceptionally concise: a one-sentence purpose, a two-bullet key-parameter list, and one-line output and requirement. Every sentence contributes unique information. It is front-loaded with the core purpose and structured with clear labels, making it easy to scan. No wasted words or repetition of schema fields.

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 complexity (16 params), no annotations, and an output schema (which the description partially covers with 'per-event timeline'), the description gives the essential context: what it does, its input prerequisite, and its output. However, it lacks differentiation from sibling commands (e.g., kwork_latency, kwork_report) and does not explain the overall perf kwork workflow. It is adequate but leaves the agent to infer the tool's position relative to others.

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 baseline is 3. The description adds meaningful detail for two parameters: call_graph ('fp' or 'dwarf' for callchain) and name (filter to handler). These go slightly beyond the schema descriptions, but the many other parameters (sort, time, force, etc.) receive no extra explanation. The addition is marginal, keeping the score at 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 clearly specifies the tool's purpose: 'Timestamped kernel work item events showing when each handler ran and for how long.' This is a specific verb-resource pair (showing events) and is distinct from the 'top', 'latency', and 'report' sibling tools by focusing on per-event timelines. It stops short of a 5 because it doesn't explicitly differentiate from siblings, but the 'per-event timeline' wording strongly implies the unique angle.

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 a key prerequisite ('Requires: perf kwork record') and lists two key parameters, but does not offer explicit guidance on when to prefer this tool over alternatives. The intended use case (analyzing timing of handlers) is implied but not stated directly, and no alternatives are mentioned. This is sufficient context to guess usage, but not clear, exclusionary guidance.

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

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

With no annotations provided, the description carries the full burden. It discloses the input requirement (perf kwork record), the ranking metric, and that the output is a ranked list. It does not describe any side effects, permission needs, or nuances like how BPF mode affects behavior, but for a read-only reporting tool this is acceptable.

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 well-structured: a clear first sentence, a brief purpose statement, a bullet for key parameters, then output and requirements. Every sentence earns its place and the content is immediately scannable.

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 14-parameter schema is fully covered and an output schema exists, the description need not explain return values in depth. It supplies the essential prerequisite, the core metric, and the intended use case. It could have added a note on how this relates to sibling kwork tools, but the overall context is sufficient.

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?

Since the input schema's description coverage is 100%, the description doesn't need to restate all parameters. It adds value by highlighting the 'sort' parameter and clarifying its default ('runtime'), which is not in the schema. Minor discrepancy: it omits 'avg' which the schema lists as a sort key, but the description says 'key parameters' and not exhaustive.

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 this tool ranks kernel work items by total runtime and identifies them as interrupt/softirq/workqueue handlers. It uses a specific verb ('Top...ranked by total runtime') and describes the resource, though it doesn't explicitly differentiate itself from sibling kwork tools like perf_kwork_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?

The description implies usage as a 'quick view' of busiest handlers and states the prerequisite 'Requires: perf kwork record.' However, it does not explicitly state when to use this tool over alternatives like perf_kwork_report or perf_kwork_latency, nor does it mention any exclusions.

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

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 explains the output ('contention table with wait times and optional stacks') and the prerequisites, and notes that BPF-based tracking is optional. This is useful context beyond the schema, though it does not cover potential failure modes or privilege requirements for BPF, so it is not a 5.

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 relatively concise and front-loaded with the main purpose. The key parameters list is somewhat redundant given the schema, but it helps prioritize important options for a 29-parameter tool. The structure is clear and readable, earning a 4 rather than a 5 due to the redundant parameter list.

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 complexity (29 parameters, output schema present, no annotations), the description provides a solid overview: purpose, output format, prerequisites, and optional modes. It does not explain every parameter (the schema handles that) and lacks sibling differentiation, but it is sufficiently complete for an agent to understand what the tool does and when it can be invoked.

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 baseline is 3. The description lists key parameters with explanations that largely mirror the schema descriptions (e.g., 'lock_addr: show lock addresses' vs. schema 'Show lock addresses'). There is minimal added semantic value, though minor nuances like 'live' in 'use_bpf: use BPF for live contention tracing' provide a slight enhancement. Overall, the description does not meaningfully add beyond what the schema already provides.

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 'Detailed lock contention analysis showing where threads wait for locks' with a specific verb and resource. It distinguishes itself as a detailed analysis tool, but does not explicitly differentiate from sibling tools like perf_lock_report or perf_lock_info, so it falls short of a 5.

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 a prerequisite ('Requires: perf lock record or lock tracepoints') which gives some context on when the tool can be used. However, it does not explicitly state when to use this tool versus alternatives, or provide when-not-to-use guidance. The 'detailed' emphasis implies usage for deeper analysis, but it is not explicit, so the guidance is only implied.

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

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

With no annotations, the description carries the full transparency burden. It does disclose a behavioral requirement ('Requires: perf lock record') and the output format, which adds context beyond the schema. However, it does not state safety characteristics (e.g., read-only nature) or potential side effects, though the verb 'Display' implicitly suggests a read operation.

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 concise (four short sentences) and front-loaded with the primary purpose. The 'Output:' and 'Requires:' sections are clearly structured. However, the first two sentences ('Display general information...' and 'Shows lock types...') are somewhat redundant, which prevents a 5.

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 has 10 parameters, no annotations, and an output schema, the description provides essential context: the prerequisite file and the output type. The schema covers parameter details, and the output schema covers return values. However, it lacks explicit differentiation from sibling lock tools, which would make it more complete.

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?

All 10 parameters have schema descriptions (100% coverage), so the baseline is 3. The tool description adds no parameter-specific meaning beyond what the schema already provides, but it doesn't need to since the schema is comprehensive.

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 the tool displays general information about locks in perf.data, specifically lock types and configurations. This distinguishes it from sibling tools like perf_lock_contention and perf_lock_report, which focus on contention and detailed reports respectively.

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 a clear prerequisite (requires perf lock record) that establishes when the tool is usable. However, it does not explicitly mention alternatives or when not to use this tool versus other lock-related tools, so it misses the 'when-not/alternatives' aspect for a 5.

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

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

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It does mention the output ('per-lock statistics table') and a prerequisite (needs prior lock recording), but it does not explicitly state that the operation is read-only, what happens on missing input, or whether any files are written. This is adequate but leaves some ambiguity.

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 compact and well-structured: it front-loads the primary function, then gives the use case, a few key parameters in bullet-like format, the output shape, and the prerequisite. Each line adds necessary information without unnecessary prose.

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 complexity (19 parameters, output schema present), the description covers the essential context: what the tool reports, typical use, key parameter options, output format, and required preparatory steps. With an output schema already available, the description need not explain return values, and it provides enough for an agent to select and invoke the tool appropriately.

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 schema already documents all 19 parameters (100% coverage), so the baseline is 3. The description adds value by highlighting key parameters and giving concrete allowed values for 'sort' (e.g., 'acquired', 'contended', 'avg_wait') and 'type_filter' (e.g., 'spinlock', 'mutex'), plus defining the behavior of 'threads' and 'combine_locks' in plain terms. This goes beyond what the schema states.

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 opens with 'Lock statistics: acquired count, contended count, and wait times per lock,' which clearly names the resource and the metrics reported. The added context 'Use this to find the most contended locks in the system' gives a specific use case that distinguishes it from sibling tools like perf_lock_info or perf_lock_contention.

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 explicitly states when to use the tool ('Use this to find the most contended locks in the system') and provides a prerequisite ('Requires: perf lock record or lock tracepoints'). However, it does not explicitly discuss when not to use it or mention alternative tools, so it gets a 4 rather than a 5.

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

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

No annotations are provided, so the description must carry behavioral context. It discloses the output ('memory access histogram'), the prerequisite ('perf mem record or perf record -d'), and clarifies key behaviors like DWARF-based type profiling. It does not explicitly state read-only or side-effect-free behavior, but the 'report' framing implies non-mutating operation.

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 tight and well-structured: intro sentence, use-case sentence, key parameters, output, and requirement. Every sentence contributes value and nothing is extraneous.

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?

For a 17-parameter tool with output schema and no annotations, the description covers the essential context: purpose, key parameters, output shape, and recording prerequisite. It doesn't explain all parameters, but the schema and output schema fill those gaps. Slight lack of interpretive guidance on reading the histogram.

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?

All 17 parameters have schema descriptions (100% coverage), so baseline is 3. The description adds extra meaning by explaining 'type' values ('load'/'store'), 'ldlat' threshold units, 'type_profile' is DWARF-based, and 'phys_data' refers to physical memory addresses, going beyond the schema.

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?

Description clearly states the tool performs memory access profiling with data source (L1/L2/L3/DRAM), latency, and load/store breakdown. It positions it for cache-miss and NUMA analysis, which distinguishes it from sibling perf tools like perf_c2c_report or perf_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?

Explicitly says 'Use this to find cache-miss-heavy code or NUMA-unfriendly access patterns,' giving clear when-to-use guidance. However, it does not mention when not to use it or name specific alternative tools.

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

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.

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

With no annotations, the description carries the transparency burden. It discloses the output table fields, the sort default, and the prerequisite command. It implies a read-only analytical behavior, though it does not explicitly state non-mutating or permission requirements.

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 compact and well-structured: an intro sentence, a use-case sentence, bulleted key parameters, an output line, and a prerequisite line. Every sentence adds value and is front-loaded with purpose.

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 output schema and full parameter schema coverage, the description covers the essential context: what it does, when to use it, key parameters, output shape, and prerequisite. It could be more complete by distinguishing from perf_sched_timehist, but overall it is sufficient for a 14-parameter tool.

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 baseline is 3. The description adds value by specifying the default for 'sort' ('max') and highlighting 'pid' as a filter. These details go beyond the schema descriptions without repeating all 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 reporting per-task scheduling latency statistics, showing max, average, and total delay. This is a specific verb+resource, but it does not explicitly distinguish itself from the closely related sibling perf_sched_timehist.

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?

It explicitly states when to use the tool: 'Use this to identify tasks that are being starved or experiencing long scheduling delays.' It also mentions the prerequisite 'Requires: perf sched record.' However, it does not provide exclusions or mention alternative siblings.

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

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

With no annotations provided, the description takes on the full burden of behavioral disclosure. It discloses the output format ('ASCII grid with CPUs as rows and time as columns'), a key prerequisite ('Requires: perf sched record'), and parameter effects (compact, cpus, pids, coloring). While it does not mention failure modes or side effects, the read-only nature is implied by the map output, making it reasonably transparent.

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 front-loaded with the core purpose, followed by usage guidance, key parameters, output format, and prerequisite. It is slightly longer than necessary due to repeating parameter names that already exist in the schema, but each sentence serves a purpose and the structure is logical and scannable.

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 complexity (15 parameters) and the presence of an output schema (so return values need not be explained), the description covers the essential aspects: purpose, usage, output, and prerequisite. It does not explain all parameters, but the schema covers those. The description is complete enough for an agent to decide whether to use it and to understand its core behavior.

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 already has 100% description coverage for all 15 parameters. The description adds modest value by explaining 'compact: one-character-per-task view' and grouping related parameters (color_pids/color_cpus), but most of the parameter semantics are already present in the schema. It does not meaningfully deepen understanding of parameters like symfs, vmlinux, or verbose beyond the schema descriptions.

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 opening sentence 'ASCII CPU activity map showing which task ran on which CPU at each time slice' names the specific verb (map), resource (CPU activity), and output format, clearly distinguishing it from sibling tools like perf_sched_latency or perf_sched_timehist. It explains the visual output and use case for scheduling patterns, CPU affinity, and load imbalance.

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 explicitly states 'Use this for a visual overview of scheduling patterns, CPU affinity issues, and load imbalance,' giving a clear when-to-use context. It does not explicitly mention when not to use it or name alternative tools, but the visual-overview framing strongly implies differentiation from statistical or script-based siblings.

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

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

No annotations are provided, so the description carries the transparency burden. It explicitly says the tool 'simulate[s] the original scheduling' and 'reports statistics,' making its non-destructive simulation nature clear. It also notes the required prior recording step. It could add more detail about potential side effects, but the simulation wording effectively conveys the behavior.

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 short but contains redundancy: the first sentence ('Replay recorded scheduler events to simulate the original scheduling') and the second ('Replays the workload's scheduling decisions...') say essentially the same thing. The 'Output' and 'Requires' lines are useful and well-structured, but the duplicate opening could be condensed.

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 presence of a full input schema and an output schema, the description provides sufficient context: it states the output (throughput, latency) and the prerequisite (perf sched record). This is adequate for a specialized replay tool, though it could optionally describe how statistics are computed or what 'simulate' means operationally.

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 100%, and the schema already documents all 8 parameters with concise explanations. The description does not add extra meaning to the parameters (e.g., how 'cpu' filtering interacts with replay), so the baseline score of 3 is appropriate.

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 uses a specific verb+resource ('Replay recorded scheduler events') and clearly states what the tool does: simulates original scheduling and reports statistics. It distinguishes itself from sibling tools like perf_sched_map and perf_sched_latency by focusing on replay behavior and statistical output.

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 clearly states 'Requires: perf sched record,' giving an explicit prerequisite and implying when to use the tool (after recording events). However, it does not mention alternatives or explicitly when not to use this tool compared to other sched subcommands.

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

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

With no annotations, the description must carry transparency. It discloses the raw output format and requirement, but does not mention potential side effects, output size, or behavior nuances like whether it reads from stdin or modifies files. Basic but not fully comprehensive.

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?

Three short sentences, front-loaded with the core function, followed by use-case guidance and output/requirement notes. Every sentence earns its place with zero redundancy or fluff.

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 8 parameters (1 required) and an output schema. The description covers purpose, usage context, output format, and prerequisite. It doesn't explain parameter details, but the schema covers that, making the overall context sufficiently complete for a dump-style tool.

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 100% (all 8 parameters have descriptions), so baseline is 3. The description itself does not add parameter-level detail beyond stating input path and dump purpose; it relies on the schema for parameter semantics.

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 the tool's verb+resource ('Dump raw scheduler tracepoint events from perf.data') and explicitly differentiates it from sibling structured-view tools by naming latency, timehist, and map. This provides a specific, unambiguous purpose.

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?

It gives explicit when-to-use guidance ('for custom analysis or when the structured views... don't show what you need'), names alternative tools, and states a prerequisite ('Requires: perf sched record'). This is strong contextual direction for selection.

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

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 explains the output format ('per-event table with timestamp, task, runtime, wait-time, scheduling delay') and the prerequisite recording command. It also adds nuance to key parameters, such as 'summary: true to show only summary stats (no per-event detail)' and 'call_graph: 'fp' or 'dwarf' for callchain,' providing meaningful behavior beyond what a generic description would offer.

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 well-structured: a single-sentence definition, a usage context sentence, a focused bullet list of key parameters, and two short lines for output and requirements. It is front-loaded and avoids redundancy with the schema, making every sentence earn its place without being overly verbose.

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 complexity (25 parameters) and that the schema fully covers parameter descriptions and an output schema exists, the description provides sufficient context: it identifies the tool's purpose, usage context, key behavioral parameters, output format, and the required perf sched record prerequisite. It could have mentioned direct alternatives, but the 'detailed scheduling analysis' guidance is enough for a capable agent to select this tool appropriately.

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 100%, so the baseline is 3. However, the description enriches several parameters: summary, wakeups, migrations, idle_hist, state, call_graph, with_summary, comms, and time are each given practical meaning (e.g., 'state: show task state (R/S/D/T) at each switch'). This adds value beyond the schema's brief field descriptions, so a 4 is warranted.

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 opening sentence clearly states the tool produces 'Timestamped scheduler timeline showing every context switch with runtime and scheduling delay,' specifying the resource (context switch timeline) and actions (showing). This distinguishes it from sibling tools like perf_sched_map, perf_sched_latency, and perf_sched_replay, which serve different analysis purposes.

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 explicitly says 'Use this for detailed scheduling analysis -- find when and why tasks were descheduled,' providing clear context for when to invoke this tool. It also notes the prerequisite 'Requires: perf sched record,' which helps the agent know the required input state, though it does not explicitly call out alternatives or exclusions.

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

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

With no annotations, the description fully discloses behavior: one line per sample, configurable fields, works on any perf.data from perf record, and special trace modes. It also mentions output format and key filtering options, giving the agent a clear picture of side effects (none destructive).

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 structured with a clear opening, use-case paragraph, and key-parameter list; every sentence adds operational value. It is longer than the calibration high example but justified by the tool's complexity (57 parameters), and it remains scannable.

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?

For a 57-parameter tool, the description covers the core behavior, output format, and the most impactful parameter groups. Since an output schema exists, the description doesn't need to explain return values, and it provides enough context for correct invocation alongside the fully documented 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 coverage is 100%, but the description adds substantial value by listing common field sets for 'fields' and summarizing filter parameters (symbols, dsos, comms, pid/tid, time, max_events) beyond their schema definitions. This helps the agent choose parameter values.

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 starts with a specific verb ('Dump raw per-sample events from perf.data') and clearly distinguishes from aggregated histogram tools like perf_report by emphasizing raw per-sample output. The use cases (flamegraph input, custom filtering, inspecting individual events) further differentiate it from siblings.

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?

It explicitly states when to use: 'when you need the raw data rather than aggregated histograms' and names concrete scenarios. It doesn't name sibling tools directly but clearly contrasts with the histogram-based alternative, which is sufficient for tool selection.

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

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

With no annotations available, the description carries the full burden. It discloses the output ('returns the SVG file path and size') and the prerequisite ('Requires: perf timechart record'), but it does not mention limitations, error handling, or side effects beyond creating an SVG file. This partial transparency leaves gaps.

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 well-structured with a clear opening purpose, a 'Key parameters' summary, and separate lines for 'Output' and 'Requires.' It avoids unnecessary detail and stays within a compact size, though the parameter list is somewhat redundant with the schema.

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 complexity (17 parameters) and the existence of an output schema, the description provides adequate context about the tool's purpose and key options. However, it lacks guidance on when to use specific filters, how they interact, or typical workflows, leaving some gaps for a heavy parameterized tool.

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 100%, and the description only highlights a subset of parameters in a 'Key parameters' list without adding new semantic meaning. The baseline of 3 applies because the schema already documents parameters well; the description adds marginal value by emphasizing common filters.

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 the tool's primary function: 'Generate a timechart SVG showing CPU activity and task scheduling over time as a visual timeline.' This specific verb-resource pairing distinguishes it from sibling tools like perf_sched_map or perf_report, which focus on other forms of analysis or output.

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 on when to use the tool by explaining 'Requires: perf timechart record' and listing key filters such as process, power_only, and tasks_only. However, it does not explicitly exclude alternatives or describe trade-offs compared to other perf visualization tools.

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