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

It explicitly reassures that nothing at path is modified, discloses one-time bundle extraction into the server's data folder, and notes that registration persists between sessions. This goes well beyond the sparse annotations and gives an agent a clear safety picture.

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, then uses short labeled Args and Returns sections to organize details. Every sentence carries needed information, including the important 'nothing modified' guarantee.

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 registration tool with three parameters and nontrivial path handling, the description covers all required inputs, edge-case input types, side effects, and what the call returns. The presence of an output schema means the return-value 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?

The input schema contains no descriptions, yet the description fully documents all three parameters: name format, accepted path types with realistic examples, and deployment allowed values. An agent can construct correct arguments without opening anything else.

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 line 'Register TPM logs to analyse; remembered between sessions' states a specific action, resource, and persistence behavior. This clearly separates it from siblings like remove_log_source, check_log_sources, and list_log_files.

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

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

The description gives clear, concrete guidance on what inputs are valid: folder, single file, or archive bundle, with examples and a deployment value of 'saas', 'onprem', or 'auto'. It does not explicitly contrast this tool with siblings such as check_log_sources or list_log_files, so it stops short of full when-to-use-versus-alternatives 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses important behavior: duplicate removal, consecutive repeat collapsing, and the overflow policy where WARN and above are kept while the rest are sampled. It also documents the return row structure, giving the agent a clear model of what the tool does.

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 front-loaded purpose, behavior notes, a compact Args list, and a short Returns section. Every sentence earns its place; despite covering 14 parameters, it remains readable and free of 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?

For a 14-parameter tool with zero schema descriptions, the description covers purpose, filtering options, defaults, behavioral edge cases (limit overflow), and return fields. Nothing essential for correctly invoking the tool appears to be missing.

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

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

Schema description coverage is 0%, so the description carries full responsibility for parameter meaning. The 'Args' section explains all 14 parameters, including defaults for minutes_before, minutes_after, min_severity, collapse_repeats, and the limit range, making every parameter actionable without 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 opens with a specific action and resource: 'Merge all logs into one chronological sequence - what happened before and after.' It also ties the tool to a concrete use case ('what led up to this failure') and distinguishes it from sibling log tools by emphasizing interleaving server/client logs by timestamp.

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 when the tool is useful: reconstructing what led up to a failure by merging and time-ordering logs. It does not explicitly name alternatives or state when not to use it, but the scenario is concrete enough for an agent to select it appropriately.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context by explaining that the tool scans log sources, reports parseability and format issues, and provides guidance for missing logs, all consistent with a non-mutating diagnostic step.

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 'Run this first' and organized into a clear overview followed by output details. It is a bit longer than strictly necessary, and the 'Returns' section may duplicate what the output schema already conveys, but nearly every sentence adds useful context.

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 zero-parameter discovery tool, the description is complete: it states what it checks, what it reports, where missing logs can be found, and what the return structure looks like. Combined with rich annotations and an output schema, an agent has everything needed to call it 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 tool takes zero parameters, so there are no parameter semantics for the description to clarify. Baseline for 0-parameter tools is 4, and the description does not need to compensate for any schema gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Show which TPM logs are available, and whether they can be read and parsed.' It then enumerates concrete outputs such as devices found, time spans, SaaS/on-prem determination, and TPM versions, which clearly distinguishes it from sibling tools like list_log_files or search_logs.

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 'Run this first,' giving a clear directive on when to invoke this tool. It does not explicitly enumerate when-not-to-use or alternatives, but the sequencing guidance is unambiguous and actionable.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and side-effect profile. The description adds value by explaining the comparison logic (only issues not present on healthy device) and the return format (lists with counts). It does not contradict annotations and provides context beyond what the structured fields carry.

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 a one-sentence summary, followed by a clean Args list and a Returns note. There is no wasted text; each sentence earns its place. The structure makes it easy for an agent to parse quickly.

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 8 parameters and an output schema (not shown), the description covers all parameters, explains the comparison semantics, and describes the return keys. It is complete for an agent to invoke the tool correctly without external documentation. The only minor gap is that device identifiers are not specified as names or IDs, but this is likely context-dependent and not critical.

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

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

Schema description coverage is 0%, so the description fully compensates by explaining every parameter in the Args block: healthy_device, problem_device, since, until, source, min_severity, include_noise, and top. Each gets a concise, meaningful definition (e.g., 'A device that patches correctly', 'WARN (default) or ERROR'). This is essential for an agent to populate parameters correctly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('Show warnings and errors on a problem device that a healthy device does not have') with a clear resource and comparison logic. It is distinct from siblings like diagnose or summarize_errors, though it does not explicitly name alternatives. The verb 'Show' and the two-device comparison make the purpose unambiguous.

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 when to use this tool (when you have a healthy and problem device to compare) but does not explicitly state when not to use it or mention alternative tools. There is no guidance on choosing between this and diagnose or summarize_errors. The context is clear enough for an agent to infer, but explicit routing would be better.

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?

Annotations already cover readOnly, idempotent, non-destructive. The description adds key behavioral details: confidence levels, baseline coverage, threshold crossing, and return criteria. It does not mention pagination or rate limits, but that's minor here.

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?

Well-structured: high-level purpose first, then anomaly types, then explicit Args and Returns sections. Every sentence adds value; 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?

Complex tool with 6 params, but annotations cover safety and output schema exists. The description explains return structure, parameter semantics and confidence. Effectively complete for an agent.

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 0%, so the description must explain parameters. It provides useful detail for since, until, baseline_days, and mentions source, device, role. However, it omits the 'role' parameter's default and doesn't elaborate on 'until' accepted formats beyond ISO/relative. Also, it doesn't explain the effect of omitting source/device. Lacks completeness despite some effort.

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?

Clear verb+resource (detect anomalies in logs), describes specific anomaly types, and implicitly distinguishes from related tools like check_log_sources (checks sources) and summarize_errors (summarizes errors).

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?

States how to use (compare recent window with baseline), but does not explicitly say when not to use or name alternatives. However, the context is clear enough to route an agent.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: it discloses that the tool reads logs, returns a structured verdict with findings/remediation, and includes a missing_logs field that tells the agent how to obtain absent data. It also implies a time-window default (7d) and per-device/source scoping. This goes beyond the annotations without contradicting them.

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 longer than average, but every section earns its place: the one-sentence summary is front-loaded, the symptom list is a compact reference table, the Args block is a clear parameter guide, and the Returns block lists the output fields. It uses bullet-like formatting and avoids redundancy. The length is proportional to the tool's complexity, and the structure makes it 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 tool with five parameters and ten symptom variants, the description covers all necessary aspects: what it does, which symptoms it handles, how to set time windows and filters, and what it returns (verdict, findings, details, missing_logs, advice). An output schema exists, so the description needn't detail every return field, but it names them all. Nothing an agent needs to select or invoke it correctly is missing.

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 provides zero documentation for parameters (coverage 0%), so the description carries the full burden. It does this thoroughly: 'symptom' is explained with a list of ten valid ids and what each checks; 'since' and 'until' specify ISO or relative formats with a default; 'source' and 'device' clarify scope and that 'omit for all sources'. This is exactly the semantic enrichment an agent needs and goes well beyond the bare 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 opens with a specific verb ('Run a symptom playbook') and a clear resource ('logs'), and states the output ('verdict with evidence'). It also enumerates ten distinct symptom playbooks, which sharply distinguishes it from sibling tools like search_logs or summarize_errors by establishing it as a high-level diagnostic orchestration rather than a low-level log query. The purpose is unambiguous and fully covers the tool's role.

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 symptom list itself is a strong implicit usage guide: it tells an agent exactly which symptom ids map to which diagnostic scenarios, and the description notes it 'read[s] the right logs' per symptom. However, it never explicitly says when NOT to use this tool or points to an alternative (e.g., 'for raw log inspection use search_logs'). The context is clear enough for most cases, but explicit exclusions are missing, 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?

Annotations already establish that the tool is read-only, idempotent, and non-destructive. The description adds meaningful behavioral detail beyond that: it defines the acceptable input formats, the edge-case behavior when topic is omitted (returning the index), and the shape of the response (what the topic is, where it comes from, related symptoms/fixes).

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, with an opening purpose sentence followed by Args and Returns sections. Every sentence contributes useful information, and the concrete examples are high-signal without being 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?

For a single-parameter, read-only tool with an output schema, the description covers everything an agent needs: what inputs are valid, what happens without an argument, and what the response contains. No critical gaps are apparent.

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?

Even though schema description coverage is 0%, the description fully compensates for the single optional topic parameter. It lists concrete examples of each accepted topic type and explicitly states the default behavior when omitted, which is richer guidance than the bare schema 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 opens with a specific verb and resource: explaining a TPM log file, error code, symptom, or known issue. It enumerates the accepted topic types clearly, which helps differentiate it from siblings like search_logs and summarize_errors, though it does not explicitly name those alternatives.

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 accepted topic categories and the 'Omit for the index' note clearly imply when to use this tool: any time an agent needs an explanation of a log, error, symptom, or known issue. However, it does not explicitly state when not to use it or mention a sibling alternative, so the routing signal is implied rather than direct.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it discloses that rotated files (e.g., adaptiva.2.log) match their base name, and it outlines the return structure (one row per file plus counts). These details help the agent anticipate results without overstepping.

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 purpose line, a parameter list, and a return note. It is longer than minimal but every sentence adds value; the rotated-file behavior and return-count detail are not filler. The front-loading of the purpose is effective, and the docstring-style formatting improves scannability.

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 list-metadata tool with an existing output schema (though not shown), the description is complete. It covers all parameters, gives matching semantics, and describes the return structure including aggregate counts. An agent can call this tool correctly without additional external knowledge, and the tool's simplicity (no nested objects, all optional params) aligns with this level of detail.

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 0% description coverage, so the description carries the full burden. It explains every parameter with type hints and concrete examples: source (omit for all), device (with sample names), role (enumeration), name (exact or glob, rotated matching), and limit (range 1-1000). This far exceeds minimal schema information and fully compensates for missing 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 begins with a specific verb ('List') and resource ('log files') and enumerates the attributes returned (device, role, purpose, size, time span). It clearly distinguishes this from content-searching siblings like search_logs by focusing on file metadata, and the parameter examples (e.g., 'content*.log') reinforce the listing scope.

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 for retrieving log file metadata but does not explicitly state when to prefer this over siblings like search_logs or summarize_errors. It does provide practical parameter guidance (e.g., 'omit for all sources') and explains how rotated files match base names, which helps correct invocation, but it lacks explicit when-to-use or when-not-to-use conditions.

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?

The description discloses that only the extracted copy is deleted, never the original, which adds valuable nuance beyond the annotations (all false, so they offer no safety signal). It also notes the inability to remove externally configured sources. However, it does not mention idempotency or other behavioral details that the annotations leave unaddressed, so it is not fully 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 concise, front-loaded with purpose, and structured with clear Args and Returns sections. Every sentence contributes value: the core action, the safety guarantee, the exclusion, and the parameter/return notes. 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?

For a single-parameter tool with an output schema, the description covers purpose, side effects, exclusions, and the return value. It is complete enough for an agent to invoke it 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?

With 0% schema description coverage, the description must compensate for the single 'name' parameter. It merely restates 'The source name,' which adds no meaning beyond the schema's type and title. It does not clarify format, source, or validation requirements, leaving the agent with minimal guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Unregister') and resource ('a source added with add_log_source'), clearly distinguishing it from sibling tools like add_log_source and check_log_sources. It also clarifies the side effect, leaving no ambiguity about what the tool does.

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 that sources from TPM_LOG_SOURCES or auto-discovery cannot be removed here, giving a clear when-not-to-use condition. It also implies the primary use case (sources added via add_log_source) but does not name alternative tools for those cases, so it stops short of full routing 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?

Annotations already mark the operation as read-only, idempotent, and non-destructive. The description adds meaningful behavior beyond that: matches are whole entries, de-duplicated across logs, sorted by time, and redacted, with paging behavior disclosed. There is no contradiction with the 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 front-loaded with a one-line purpose, followed by a compact behavioral note, a well-organized Args list, and a Returns line. Every section contributes useful information and there is no 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?

For a read-only search tool with an output schema, the description covers the use case, all filter parameters, behavioral quirks, and paging/return shape. An agent has enough context to select and invoke the tool correctly without additional inference.

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

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

Schema description coverage is 0%, so the description carries the full parameter-documentation burden. It documents every parameter with defaults, constraints, and examples, including regex, since, source, role, files, component, min_severity, context, limit, offset, and order.

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 'Search every log', a specific verb plus resource, and adds 'including multi-line messages and stack traces' to define the scope precisely. It is clearly distinguishable from sibling analysis tools like summarize_errors or diagnose even without naming them.

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 makes the intended use clear: search raw log entries by pattern over all logs, with rich filtering options. It does not explicitly mention alternatives or exclusion conditions, but the search semantics and filter list provide strong contextual 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?

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds rich behavioral detail beyond that: repeat collapsing via normalized signatures, cross-log duplicate counting, INFO lines with stack traces elevated to ERROR, known platform noise separated into `noise`, and per-issue metadata like counts, first/last seen, devices, root causes, and fixes.

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, then provides dense but scannable behavioral details and an Args/Returns structure. Every sentence earns its place; the length is justified by the complexity of a 9-parameter diagnostic tool.

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 complexity and the 0% schema description coverage, the description is complete: it explains filtering, deduplication, severity elevation, noise handling, known-fix metadata, and return sections. An output schema exists to handle detailed return structure, so no essential guidance is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden for all 9 parameters. The Args section documents every parameter with formats, defaults, allowed values, examples, and semantics, e.g. `since` supports ISO or relative times, `role` accepts server/client/setup, `files` accepts globs, and `top` is bounded to 1-100.

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: 'Group every warning and error into distinct issues, ranked, with known fixes.' It also positions itself as 'The best first call for "what is wrong?"', which clearly distinguishes it from sibling tools like search_logs, diagnose, and detect_log_anomalies.

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

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

The description gives clear situational advice: use this as the first call when diagnosing what is wrong. It does not, however, explicitly name siblings as alternatives or state cases where another tool such as search_logs or diagnose should be preferred instead, so it stops just short of full exclusion guidance.

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