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

readOnlyHint=true already declares this as a safe read, so the description's burden is low. It adds the useful note that health information is included in the response, but says nothing about error behavior for missing apps or the richness of the status payload.

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?

A single efficient sentence with the core purpose front-loaded. No padding, though it could have used its brevity budget to add one routing hint instead.

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?

An output schema exists so return values need no explanation, and the single required parameter is fully documented. The definition is nearly complete for a simple one-param read tool; only sibling differentiation is absent.

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 a single 'name' parameter already described as 'Application name'. The description adds no naming conventions, namespace/context qualifiers, or format hints beyond the schema 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?

States a specific verb ('Get') and resource ('detailed status for a single ArgoCD application') plus the scope of content ('including resource health'). This distinguishes it from the list-oriented sibling argo_apps, though the overlap with argo_app_health_summary is not addressed.

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

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

Usage is only implied: 'for a single application' suggests it is the per-app detail fetch. No explicit when-to-use, when-not, or routing to argo_apps / argo_app_health_summary / argo_app_diff is given.

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 readOnlyHint annotation already establishes the safe read-only nature. The description reinforces that this is a read operation but adds no behavioral context such as how the diff is computed, whether it contacts the cluster, 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 a single front-loaded sentence with no wasted words. It efficiently communicates the core action.

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 one-parameter read-only tool with an output schema and annotations, this is largely complete. The main gap is the absence of sibling differentiation, but the core operation is clear.

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 single `name` parameter is documented in the schema. The description adds no parameter meaning beyond the schema, so the baseline 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 states a specific verb and resource: showing what is out of sync for an ArgoCD application. This distinguishes it from a general app detail or health summary, though it does not explicitly name the sibling tools it differs from.

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 implies the tool is used for sync drift inspection, but gives no explicit when-to-use guidance, prerequisites, or alternatives. Sibling tools like argo_app_detail and argo_app_health_summary are not mentioned, leaving the agent to infer 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?

Annotations already declare readOnlyHint=true, so safety is covered. The description adds real value beyond that by disclosing what the diagnosis produces (causes, suggested next commands, evidence resources/conditions), giving the agent a mental model of the output. It omits auth/permission context, but with an output schema present that gap is minor.

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?

A single front-loaded sentence with the verb and resource first, followed by the concrete payload. No filler; every clause earns its place.

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?

With output schema present, annotations covering safety, and the one parameter documented, the description is nearly complete: it conveys purpose and output shape. Slightly more on when to prefer it over argo_app_detail would round it out.

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?

There is a single parameter 'name' with 100% schema description coverage, so the schema fully documents it. The description adds no format/lookup hints beyond the schema, which is the expected baseline when schema coverage is complete.

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?

States a specific verb (Diagnose) and resource (ArgoCD application) plus the concrete outputs: sync/health, likely causes, suggested commands, and unhealthy resources as evidence. This clearly distinguishes it from plain detail/diff siblings conceptually, though it doesn't name a sibling explicitly to anchor that contrast.

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?

'in one call' hints that this consolidates what would otherwise require multiple calls, implying a diagnostic use case. However, it never explicitly states when to choose this over argo_app_detail or argo_app_diff, nor any preconditions, so usage 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds that results come back as a structured summary rather than a table, which is useful shaping context, but it says nothing about pagination, cluster/context requirements, or what happens if no project is given.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with the purpose front-loaded and no filler. The second sentence is marginally redundant given the output schema but still contributes signal about result shape.

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?

An output schema exists, so return values need no explanation, and annotations cover safety. The remaining gaps are the unmentioned filter capabilities and the lack of routing guidance among three closely related argo_* siblings, which an agent would need to choose 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 both 'project' and 'selector' are already documented in the schema. The description never mentions that filtering by project or label selector is possible, so it adds nothing beyond the schema and cannot lift the baseline.

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

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

States a specific verb and resource ('List ArgoCD applications') plus the content scope ('sync/health status'), so an agent knows exactly what it returns. It does not explicitly differentiate itself from siblings like argo_app_health_summary or argo_app_detail, which keeps it 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?

There is no statement of when to use this versus argo_app_detail, argo_app_diff, or argo_app_health_summary, which cover overlapping territory. The only contrast offered ('structured summary instead of table output') describes output format, not 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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds that output is structured and compact, but says nothing about prerequisites (shellcheck must be installed), behavior on unparseable/missing files, or whether exit status reflects findings.

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 with the capability and output shape front-loaded and no filler. The final sentence largely repeats the schema's minSeverity description, a minor 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?

With an output schema present and full parameter documentation, the description covers what it needs to. The remaining gap is operational context (tool dependency, failure behavior) rather than anything required to select or 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?

Schema description coverage is 100%, so all four parameters including the two enums are documented in the schema. The description only restates minSeverity's filtering effect, adding nothing beyond what the schema already says, so baseline 3 is correct.

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?

States a specific verb and resource ('Run shellcheck') and describes the return shape (file, line, column, message, SC rule code), which an agent can use to decide relevance. It does not, however, differentiate itself from the nearby bash_syntax_check or bash_test 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?

The mention that it is 'much more compact than raw shellcheck output' implies you should prefer it over raw shellcheck, and 'Use minSeverity to filter' hints at a workflow. There is no explicit when-to-use/when-not or routing to bash_syntax_check or bash_test, so usage 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?

Beyond the `readOnlyHint` annotation, the description explains that it uses `bash -n`, does not execute code, is safe on untrusted scripts, and reports `valid:true` when clean. It adds meaningful safety and output behavior context, though it does not describe edge cases such as unreadable or missing files.

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 with no filler. The core action, safety property, and success signal are front-loaded and easy to scan.

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 is simple, annotations already indicate read-only behavior, the output schema exists, and parameter documentation is complete in the schema. The description is largely sufficient, though it could mention when this syntax-only check is preferable to `bash_lint` or `bash_test`.

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 schema already documents `files`, `maxItems`, and `detailLevel`. The description adds no parameter-level guidance beyond what is already structured, which is the baseline 3 case.

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 gives a specific verb and resource: checking shell scripts for syntax errors with `bash -n`, plus the shape of the diagnostics. It is clear what the tool does, but it does not explicitly differentiate itself from siblings such as `bash_lint` or `bash_test`.

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 by noting that it parses without executing and is safe on untrusted scripts. However, it does not explicitly state when to choose this over `bash_lint`, `bash_test`, or `run`, nor does it give exclusion 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?

With no annotations, the description carries the full burden and does substantial work: it discloses that the script is actually executed (arbitrary side effects), that a permission gate (BASH_MCP_MODE) applies, and how results degrade to exit-code-only for unrecognized output formats. It omits what the gate failure looks like and how timeout kills the process.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the action, then the return contract, then the gating caveat. Every clause carries information; nothing is repeated from the schema or title.

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?

An output schema exists, yet the description still summarizes the return shape and the parsing fallback, which is helpful rather than redundant. Gaps remain around timeout semantics and what the BASH_MCP_MODE gate returns when it blocks execution.

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 3 is the baseline, but the description adds real meaning: passing a .bats file triggers an implicit --tap invocation, and the expected harness output formats are described. cwd and timeout are left entirely to the schema, so it does not fully compensate beyond the baseline.

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

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

Names a specific verb+resource ('Run a shell test script') and immediately scopes the accepted inputs (.bats via --tap, or a plain .sh harness), which cleanly separates it from siblings like bash_lint, bash_syntax_check, npm_test and python_test. An agent can pick this tool without opening the schema.

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 two accepted script types are spelled out, which tells the agent what inputs qualify, and the closing clause signals that execution is mode-gated. It stops short of naming an alternative tool or stating when not to use it (e.g. use bash_lint for static checks), so it is clear context without 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 carries the burden and does well: it discloses that commands execute without a shell and gives the concrete workaround (command='sh', args=['-c', '...']) for pipelines. It leaves gaps on failure semantics (what happens if one command in the batch fails) and concurrency limits, which matters for a batch executor.

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 sentences, zero waste, with the core behavior front-loaded before the shell caveat and the usage guidance. Every sentence earns its place.

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?

An output schema exists, so return values need no explanation, and the execution model is well covered. What's missing is partial-failure behavior and the default/max timeout implications for a 30s default batch, which an agent would want before batching long-running commands.

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% and the schema itself documents command, label, args, cwd and timeout. The description reinforces the shell semantics but largely restates the schema's command field note rather than adding new meaning. Baseline 3 applies when the schema does the heavy lifting.

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?

States a specific verb and resource ('run multiple commands in parallel and return all results') and immediately scopes the tool against the sequential-call alternative. An agent can distinguish it from run/run_seq without opening the schema.

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 gives the trigger condition: gather independent pieces of information in one call instead of multiple sequential calls. It implies the boundary with sequential execution tools (run_seq) but never names them, so the routing is clear rather than airtight.

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?

Adds substantial context beyond the readOnlyHint annotation: default truncation at 200 lines, batched return shape { files, count }, per-file error isolation that does not abort the batch, git-backed reads via `ref`, and the non-obvious interaction with the Edit/Write 'must read first' guard.

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?

Front-loaded with the core action, then batched reads, then range limiting, then git ref, then the editing caveat — ordered by likely agent need. Every sentence carries distinct information; nothing is padding.

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 7-parameter read tool with an output schema and readOnlyHint, the description covers batching, truncation defaults, git sourcing, error behavior, and the edit-guard caveat. Nothing an agent needs to 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?

Schema coverage is 100%, so baseline is 3, but the description adds real value: it explains the path/paths dichotomy and the { files, count } result, gives a concrete ref example ('main'), and frames startLine/endLine/maxLines as the large-file strategy rather than just restating field names.

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?

States a specific verb and resource ('Read one or more files') and immediately names distinguishing features: line numbers, smart truncation, structured metadata. This clearly separates it from sibling directory/listing tools like ls, tree, and find_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?

Explicit routing guidance: use `path` for one file vs `paths` for batching, use startLine/endLine/maxLines for large files, and use `ref` to read from git instead of disk. It also gives a critical precondition — the built-in Read must be run before Edit/Write because cat does not satisfy that guard.

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 it readOnlyHint=true, but the description adds genuinely useful context beyond that: probes are 'client-only and non-blocking — no server/auth calls', which tells the agent it is cheap and safe to call speculatively. It doesn't detail latency or output shape, but the output schema covers the latter.

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 capability and followed by the usage rationale and behavioral guarantee. Every sentence carries distinct information with no waste.

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, read-only probe with a full output schema, the description covers what is probed, why, and how invasive it is. Nothing an agent needs in order to call 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 tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate, and it correctly implies no inputs are needed.

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?

States a concrete verb and resource: reports which CLIs are installed and their versions, plus kubectl context. This clearly separates it from probing siblings like kube_contexts or git_status, which return data for a specific tool rather than a capability inventory.

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 says to use it 'before calling' a CLI 'so you can pick the right tool', which gives a clear trigger point. It stops short of naming explicit alternatives or when-not-to-use conditions, so it falls just under the top score.

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 the full behavioral burden. It usefully discloses that warnings are omitted by default and how to include them, and that output is structured and compact. It does not mention side effects (build artifacts, execution time), failure behavior, or permissions—gaps for a build command.

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 front-loaded sentences with zero filler. Each sentence earns its place: purpose/output, compactness benefit, and the warning default with the override.

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?

An output schema exists, so return values need not be explained. The description covers the purpose and the main behavioral toggle (warnings). For a no-annotation build tool it could say more about failure semantics, but given the rich schema and output schema it is largely 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?

Schema description coverage is 100%, so all six parameters are already documented by the schema. The description reinforces the includeWarnings/detailLevel interaction, but adds little beyond the schema text; for example, detailLevel:'full' skipping the response budget is only in the schema. The baseline of 3 is appropriate when the schema does the heavy lifting.

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 and resource ('Run dotnet build') and lists the structured diagnostic fields returned, making the operation unambiguous. It distinguishes itself from raw MSBuild output by promising compact structured diagnostics. However, it does not explicitly contrast itself with any sibling tool, so it stops 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?

There is no explicit when-to-use / when-not guidance relative to alternatives. The only guidance is parameter-level: warnings are omitted by default, and includeWarnings:true or detailLevel:'full' includes them. Usage is implied by the tool name and dotnet context, but alternatives like dotnet_test are not addressed.

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 behavioral burden. It discloses output filtering ('Only failures are listed') and compactness, but omits execution traits such as timeouts, required SDK/build state, and possible side effects like build artifacts.

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 action and return shape, and each sentence adds distinct value without repetition.

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?

An output schema exists, so return values need not be explained, but the description still summarizes them. It covers purpose and output filtering; only execution prerequisites and runtime characteristics are missing for an annotation-free runner.

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 schema already documents cwd, filter, and project. The description adds no parameter-level meaning beyond that; baseline 3 applies.

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?

States a specific action ('Run dotnet test') and the exact return shape (pass/fail/skip counts, failure messages), while contrasting it with raw test output. This clearly distinguishes it from generic test runners and sibling tools.

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?

Implies it should be used for .NET test runs and that it is preferable to raw output, but gives no explicit when-to-use/when-not guidance relative to siblings like dotnet_build or npm_test, nor prerequisites such as build state.

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, so safety is covered. The description adds useful return-format context ([path, sizeBytes] pairs and du emission order), but does not disclose practical traits such as performance, permissions, symlink handling, or large-output 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?

Three short sentences, front-loaded with the core action and return format. No wasted text.

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 is simple, parameters are fully documented, annotations cover safety, and an output schema exists. The description is largely complete, though it omits usage boundaries against siblings and operational caveats.

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 both parameters are already documented. The description only lightly restates maxDepth's effect and does not add significant semantics 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?

States a specific verb and resource: show disk usage for paths. It clearly distinguishes disk-usage measurement from listing/inspection siblings, but does not explicitly name when to use it over ls or tree.

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?

Mentions that maxDepth controls summary depth, which gives some usage context. It does not say when to choose du over alternatives like ls, tree, or find_files, nor does it state 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?

readOnlyHint=true already establishes this is a safe non-mutating search, so the description's burden is lower. It adds the return shape ('structured list of paths') and the OR semantics, but says nothing about recursion depth behavior, symlink handling, result volume/limits, or ordering — the traits an agent would actually want before running a broad search.

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 tight sentences with the core purpose front-loaded and no filler. The 'Returns structured list of paths' clause is mildly redundant given an output schema exists, which keeps it just short of 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?

Structural burden is low: all 8 parameters are optional, the schema is fully documented, and an output schema covers return values. The only real gap is the unexplained name/pattern alias overlap, which an agent could stumble on; otherwise the definition is sufficient 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 baseline is 3. The description merely restates what the schema already says ('names' OR logic appears verbatim in the schema description), and it does not resolve the genuinely ambiguous case of three overlapping filters — name, names, and pattern (an alias) — leaving the agent without guidance on which to use.

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?

States a specific verb and resource (find files) plus the three filtering axes (name pattern, type, modification time) and the return shape (list of paths). It does not differentiate from overlapping siblings such as glob, ls, or tree, so an agent can't tell on purpose alone which one to prefer.

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 second sentence gives real selection guidance between parameters ('names' for multiple globs with OR logic, 'modifiedWithin' for recent files), which is useful. But there is no when-to-use-this-vs-alternatives guidance, and the sibling set contains glob and ls that an agent would reasonably confuse with this tool.

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, so the safety profile is covered; the description adds the non-obvious output policy that passing checks are counted rather than listed by default. It does not cover error behavior for a missing/unresolvable PR, but that is a minor gap against the annotation baseline.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two dense sentences: what it returns first, default targeting and the listing exception second. No filler, and the most decision-relevant fact is front-loaded.

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?

An output schema exists and annotations cover the read-only profile, so the description need only frame intent and the default scoping rule — both are present. Nothing needed to call this three-optional-param tool 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?

Schema coverage is 100% and all three parameters carry descriptions, so the schema does the heavy lifting. The description restates the two most important defaults (`pr` and `all=true`) but adds no syntax or format detail 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?

States a specific verb and resource ('Report a pull request's CI checks') and even characterizes the payload ('counts per state plus the failing and pending checks'). It is clearly distinct from unrelated siblings, though it never names the nearest analog (glab_ci_status) for contrast.

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?

Gives the default target ('Defaults to the current branch's PR') and states the condition that changes behavior ('unless all=true'), so an agent knows how to invoke it with no arguments. No explicit when-not or sibling-alternative guidance is given.

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 readOnlyHint annotation already establishes that this is a safe read operation. The description adds useful operational context: it summarizes status, failed jobs/steps, and error evidence, and defaults to the latest run on the current branch. It does not mention authentication or rate limits, but those are secondary 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?

The description is two compact sentences, front-loads the primary action, and then adds the key output/default details. Every phrase contributes to understanding the 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?

With an output schema, readOnlyHint, and full parameter descriptions, the definition is largely self-contained. The description covers the purpose and default behavior, though it could mention prerequisites such as an authenticated GitHub CLI for full operational completeness.

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 schema already documents cwd, run, and branch. The description only restates the run/branch default behavior in combined form and does not add syntax or precedence details beyond the schema, so 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 uses a specific verb ("Diagnose") and resource ("GitHub Actions run") and enumerates what the summary contains: status, failed jobs and steps, and ##[error] lines. It distinguishes itself from non-GitHub diagnostics by platform, but does not explicitly name sibling alternatives such as gh_pr_checks or glab_pipeline_failure_summary.

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 diagnosing a failed Actions run and explains the default target (latest run on current branch), but gives no explicit when-to-use/when-not guidance or alternatives. An agent can infer the context but must still decide on its own when this tool is preferable to 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered structurally. The description adds the return shape (current branch plus [name, lastCommit] pairs) and the remotes/ naming convention, which are useful behavioral details. It does not go further into pagination or repository-state requirements, so a middling score is appropriate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the core action and followed by the return shape. There is no wasted text.

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?

An output schema exists, so the description does not need to enumerate return values, yet it helpfully summarizes the key ones. The main remaining gap is the lack of guidance on when to prefer this tool over related git tools.

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 both cwd and remote documented in the schema, so the baseline is 3. The description's note that remote branch names start with remotes/ is helpful context for the 'remote' flag but does not explicitly explain the parameter's behavior.

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 ('List git branches'), which is unambiguous and does not overlap with any sibling tool (git_status, git_log, or git_diff cover other concerns). It stops short of explicitly contrasting itself with those siblings, so it falls just below 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 contains no guidance about when to call this tool versus alternatives such as git_status, git_log, or git_diff. An agent must infer the appropriate context on its own.

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, so safety is covered; the description adds that output is per-file change counts rather than patch bodies. It says nothing about defaults when no ref/base are given, untracked or binary files, rename detection, or how staged combines with other params.

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, purpose first, then the two non-obvious parameters. No filler and nothing repeated needlessly.

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?

Output schema exists, so return values need no explanation, and all five parameters are documented. The remaining gap is behavioral: what the tool does by default with no ref (working tree vs index) and whether staged combines with base/ref, which an agent would need to reason out.

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 explains base/ref combination ('git diff <base> <ref>') and path scoping. The description only restates those with a slightly friendlier example, so the baseline of 3 applies.

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?

States a specific verb and resource plus the shape of the result: 'Structured git diff: files changed with insertions/deletions counts.' That implicitly separates it from git_diff_content (patch text), but the sibling is never named, so an agent must infer the split.

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?

Gives concrete invocation guidance: base+ref for two-ref comparison with a worked example (base='main', ref='feature'), and path for scoping to files or directories. It stops short of saying when to prefer git_diff_content or how staged interacts with base/ref.

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 readOnlyHint annotation already establishes that this is a safe read operation, and the description adds useful behavioral context by explaining that output is parsed into structured hunks per file instead of raw unified diff text. It does not discuss limits on large diffs or pagination, but with annotations and an output schema present, that omission is minor.

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 and output shape, then moves efficiently through selection guidance and key parameter usage. Each sentence contributes useful information with 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?

With an output schema, full parameter schema coverage, and readOnlyHint annotations, the description provides enough context to call the tool correctly. It could mention staged/context behavior for completeness, but those are already handled by the schema and are not essential to the description's role.

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 all six parameters are already documented in the schema. The description reinforces the important usage of base+ref and path, but it does not add syntax or semantics beyond what the schema already states, so the baseline 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 states a specific verb and resource ('Show git diff') and immediately distinguishes the tool's output as 'structured patch content' with 'parsed hunks per file' rather than raw unified diff text. It also contrasts the tool with file-level diff/stat approaches, so an agent can identify its role among siblings like git_diff and git_status.

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 says to use this when actual code changes are needed rather than file-level stats, which provides a clear selection rule against sibling diff/status tools. It also explains how to use base+ref for two-ref comparison and path for scoping, leaving little ambiguity about invocation.

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?

readOnlyHint=true already tells the agent this is a safe read, and the output schema exists, so the description doesn't need to enumerate return values. It adds some value by noting output is 'compact and parseable' and by disclosing that exclude uses --invert-grep semantics, but says nothing about default result limits (count defaults to 20), ordering, or what happens with large histories.

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?

Four short sentences, front-loaded with the output contract before the parameter hints. Every sentence carries distinct information with no repetition of the tool name or padding.

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?

With eight optional parameters, full schema coverage, an output schema, and a readOnly annotation, the description covers the non-obvious surface adequately. It stops short of explaining how the filters combine or what the default 20-commit cap means for callers expecting a full history.

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 schema already documents all eight parameters including the range and exclude examples. The description restates the range ('main..feature') and exclude ('ci:') examples rather than adding new semantics such as precedence between since/range/author or how path filtering interacts with range.

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?

States a concrete resource and return shape ('Structured git log: commit hash, author, date, message. Compact and parseable'), so an agent knows exactly what it gets back. It does not differentiate itself from adjacent siblings like git_diff or git_status, which 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 guidance ('Use range for ref comparisons', 'Use exclude to filter out commits matching a pattern') is really per-parameter usage instruction rather than when-to-use-this-tool-vs-alternatives guidance. There is no statement about when to reach for git_log instead of git_diff, git_status or rg, so the choice among siblings is left implicit.

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?

readOnlyHint=true already declares the safety profile, and the description usefully specifies that the output is an aggregate of three artifacts (commits, file statuses, diffstat) rather than a raw diff. It doesn't mention size/truncation behavior for large branches, which is the main remaining 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?

A single front-loaded sentence that puts the resource and range before the use case. Minor deduction for the trailing ellipsis, which leaves the enumeration looking truncated rather than finished.

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?

Read-only, fully documented parameters with sensible defaults, and an output schema that carries return-value detail. The description is close to complete for this complexity; only edge-case behavior on very large comparisons is unaddressed.

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 base, head, and cwd are already documented with defaults. The description's 'base...head' phrasing reinforces the range semantics but adds no format details beyond the schema, so the baseline 3 applies.

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?

States a specific verb ('Collect') and concrete resources (commit list, changed files with status, diffstat) over a base...head range, plus the intent ('for writing a PR description'). It implicitly separates itself from single-purpose siblings like git_log and git_diff by being an aggregate, but never names them explicitly.

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 parenthetical 'for writing a PR description' gives a use context, which is useful. However there is no explicit guidance on when to prefer this over git_log, git_diff, or git_status, nor any stated exclusions or prerequisites.

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 readOnlyHint annotation already declares the safety profile, so the description only needs added context. "Structured ... replaces parsing raw output" usefully flags that the result is machine-readable rather than porcelain text, but it says nothing about cost, scope limits, or what happens with a dirty multi-repo tree.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, zero filler, with the payload contents front-loaded before the rationale. Nothing could be removed without losing information.

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?

With an output schema covering the returned fields and a single optional parameter, the description is close to sufficient. The one meaningful gap is default behavior when cwd is not supplied, which an agent would need to know before calling.

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% for the single cwd parameter, so baseline 3 applies. The description adds no semantics beyond the schema — notably it never states what happens when cwd is omitted and the optional default path is used.

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?

States the resource (git status) and enumerates exactly what it returns: branch, staged/unstaged/untracked files. This separates it from git_diff, git_log and git_branches, though those siblings are never named, so the differentiation is inferential rather than 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?

"Replaces parsing raw git status output" implies when to reach for it (instead of shelling out to git status), but there is no explicit when-to-use/when-not and no alternative tool named. The agent must infer that git_diff or git_branches cover the narrower questions.

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, so the safety profile is covered. The description adds the non-obvious aggregation trait: passing, skipped and manual jobs are counted, not listed, unless all=true. That's real behavior an agent couldn't infer from structured fields, though auth/rate-limit context is absent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero waste. The default behavior is front-loaded, then the mr override, then the output-shape caveat — a sensible priority order for an agent deciding how to call it.

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?

With a readOnly annotation, an output schema and full schema coverage, the description supplies what remains: scope selection and the counted-vs-listed distinction. Only slightly incomplete in not addressing the interaction between an explicit pipeline ID and branch.

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 every parameter including all defaults (cwd, repo, branch, pipeline, mr, all) is already documented in the schema. The description restates the branch/mr/all semantics rather than adding new constraints such as ID formats or precedence between branch and pipeline. 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 opens with a specific verb and resource: report a GitLab pipeline's jobs as counts per status, plus the failed, running and pending jobs. That is concretely distinguishable from non-filtering list tools. It stops short of naming how it differs from the sibling glab_pipeline_failure_summary, so it lands just below top marks.

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 states the default selection (current branch's latest pipeline), the alternate selection (pass mr for a merge request's head pipeline), and the condition that changes output shape (all=true). Clear context with no exclusions, but no guidance on when to prefer this over glab_pipeline_failure_summary.

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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description still adds real behavior beyond that: allowed-to-fail jobs are surfaced but excluded from the failure count, and traces are truncated to the last script lines — an agent knows to expect evidence rather than full logs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two dense sentences with zero filler. The one-call diagnostic promise and the returned evidence are front-loaded, and the scoping notes (allowed-to-fail, default branch) follow logically.

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 an output schema exists, the description need not document return shape, yet it still characterizes the payload precisely. With all five parameters documented in-schema and the read-only annotation carrying the safety profile, nothing an agent needs to call this 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?

Schema description coverage is 100%, so every parameter including mr, branch, pipeline, repo, and cwd already carries an explanation. The description reinforces only the default behavior (current branch's latest pipeline), adding marginal semantics beyond the schema. Baseline 3 applies.

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?

States a specific verb (diagnose) and resource (GitLab pipeline), then enumerates exactly what the diagnosis contains: status, failed jobs with GitLab's stated reasons, and the trailing script lines of each failed job's trace. This is clearly distinguishable from glab_ci_status, which the description implies is the shallower status-only view.

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?

"Diagnose a GitLab pipeline in one call" plus the default-to-current-branch behavior gives a clear context for invocation. However, no sibling is named as an explicit alternative (glab_ci_status exists and is the obvious shallow counterpart), so the guidance is strong but not fully prescriptive.

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 readOnlyHint annotation already establishes that this is a safe read operation. The description adds that results are a compact list of paths, but it does not mention recursion behavior, hidden-file handling, or cwd defaults.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with zero waste, and the primary action is front-loaded before the return-value note.

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?

Because an output schema exists, the description need not explain return values. However, with many search-related siblings, it should do more to clarify when glob is the right choice.

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 pattern and cwd parameters are already documented in the schema. The description adds no syntax or behavioral detail beyond what the 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?

States a specific verb and resource: find files matching a glob pattern. It is clear what the tool does, but it does not distinguish itself from siblings such as find_files, ls, or rg.

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?

There is no guidance on when to use glob instead of find_files, ls, tree, or rg. The only implied usage is from the word 'glob,' and no exclusions or alternative selection criteria are provided.

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?

readOnlyHint=true already declares this a safe read, so the description doesn't need to establish safety. It adds that status, chart, and app version are surfaced, which is modest extra value, but 'Structured output' is redundant given a real output schema exists and nothing is said about scope defaults or empty-result 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?

Two short sentences, front-loaded with the action and the key returned fields. The trailing 'Structured output' is close to wasted space since an output schema is declared, but the overall brevity is good.

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?

With an output schema present, the description needn't explain return shape, and the read-only annotation covers safety. What's missing is sibling differentiation in a crowded helm/kube/argo toolset, which keeps it just under a 5.

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 filter (regex), context, namespace (omit for all), and allNamespaces override. The description adds nothing beyond that, which is acceptable at full coverage.

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?

'List Helm releases' gives a specific verb and resource, and it names the fields surfaced (status, chart, app version). However, it does not distinguish itself from close siblings such as helm_status, helm_values, or helm_release_triage, so an agent must infer the boundary.

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?

No statement of when to use this versus helm_status or helm_release_triage, no prerequisites (kube context/cluster access), and no exclusions. The agent gets no routing guidance at all.

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, so the safety profile is covered; the description adds real value by disclosing aggregation behavior and the shape of the synthesis (likely causes, suggested next commands, recent-revision evidence). It omits what happens on a missing/unhealthy release or whether diagnosis is bounded in scope.

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?

A single dense sentence with no filler, leading with the core capability and then enumerating exactly what comes back. Nothing to trim.

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?

An output schema exists so return values need no explanation, and the inputs are fully documented. The remaining gap is behavioral edge cases: what the agent gets if the release doesn't exist or if helm isn't reachable, which for a diagnostic tool would matter.

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 all three parameters (context, release, namespace) are documented in the schema, including the namespace default. The description adds no semantics beyond that, which is the baseline case when structured fields do the work.

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?

Specific verb ('Diagnose') plus resource ('a Helm release's health') and an explicit statement that it fuses helm status + helm history into one composite result. That implicitly separates it from the sibling helm_status, though no sibling is named outright.

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?

'in one call' hints that this replaces manually running helm_status and helm_history, but the description never states when to prefer it over helm_status or helm_list, nor any preconditions (e.g. release must exist, namespace must be in context). Usage is inferable rather than stated.

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?

readOnlyHint=true already declares the safety profile, and an output schema exists to explain the return shape. The description adds no behavioral context beyond the title restatement – 'detailed status' is not expanded into what states, history, or failure modes are reported.

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?

A single front-loaded sentence with no waste. It is efficient, though the brevity leaves no room for routing or behavioral detail.

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?

Output schema and full parameter descriptions are supplied, so the call mechanics are covered. However, against a crowded sibling set containing helm_release_triage and helm_values, the description does not say enough to disambiguate the tool's role.

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 release, namespace, and context are already documented in the schema. The description adds no meaning beyond that, which is the baseline expectation when the schema does the work.

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?

States a specific verb and resource: 'Get detailed status of a Helm release.' An agent can tell it is a read-only introspection call on a named release. It stops short of differentiating against nearby siblings like helm_release_triage or helm_values, which also surface release information.

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?

No guidance on when to use this versus helm_release_triage, helm_values, or helm_list, all of which appear in the sibling set. Nothing tells the agent which situation selects this tool over those.

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 readOnlyHint annotation already communicates that this is a safe read operation. The description adds that values are 'computed' and returned 'as structured data,' which is useful context beyond the annotation, but it does not disclose failure behavior, Kubernetes context requirements, or other operational traits.

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 a single front-loaded sentence with no wasted language. It states the verb, resource, and output shape immediately.

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 read-only Helm values lookup, the description is largely sufficient: annotations cover safety, the schema documents all parameters, and an output schema exists for return values. The only meaningful gap is the absence of guidance on when to choose this tool over related Helm tools.

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 all four parameters are already documented in the schema, including release, namespace, context, and allValues. The description adds no parameter-specific meaning beyond what the schema provides, so the baseline 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 states a specific verb and resource: 'Get the computed values for a Helm release.' It clearly distinguishes the operation from list/status-style tools by focusing on computed values, though it does not explicitly name or differentiate against siblings such as helm_status or helm_release_triage.

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 no explicit guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. The purpose is inferable from the wording, but an agent receives no 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 establish a read-only safety profile, and the description adds genuinely non-obvious behavior: the filter is passed directly to jq with no shell, so backslash escaping is neither needed nor supported, plus a note on output form. Error behavior on malformed filters is not covered, keeping it at 4.

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?

Four short sentences, front-loaded with purpose then input forms then the escaping caveat. No filler; every sentence carries actionable information.

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?

Six parameters are fully documented in the schema and an output schema exists, so return values need no prose. The description fills the remaining gap an agent would actually stumble on: filter escaping.

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 goes beyond it by explaining the file-vs-raw-JSON input choice and how the filter string must be written literally (no shell escaping). Flags like slurp/compact/rawOutput are left entirely to 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?

States a specific verb and resource ('Query and transform JSON using jq expressions') and clarifies accepted input forms. It does not explicitly name siblings like yq (YAML) or cat, so differentiation is implied rather than stated.

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 for when to reach for it: 'far more compact than reading a full JSON file', which implicitly steers the agent away from cat/ls-style reads. No explicit exclusions or named alternatives are given.

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 readOnlyHint annotation already communicates that this is a safe read operation. The description adds the useful behavioral detail that the current context is marked in the result, but does not discuss permissions, output format, or any other runtime 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?

A single, front-loaded sentence with no wasted words. It communicates the resource and the key distinguishing output detail immediately.

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 low complexity, zero parameters, and the presence of an output schema, the description is largely complete. An agent can understand what the tool returns, though it does not mention that the operation is read-only beyond the annotation.

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 has zero parameters, so there are no parameter semantics to document. The description does not need to compensate for any schema gaps, making the baseline score 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?

States a specific verb and resource ('List available kubectl contexts') and adds that the current context is marked. It is clearly distinct in practice from siblings like kube_get, but it does not explicitly differentiate itself from 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?

Usage is implied by the simple list operation: an agent would call this when it needs available kubectl contexts. However, the description gives no explicit when-to-use guidance or comparison to kubectl-related siblings such as kube_get.

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, so the safety profile is covered. The description adds that the output is a 'structured diagnosis' with replica counts and conditions, which is useful context, but doesn't mention scoping, permissions, or what a degraded result looks like.

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?

A single, front-loaded sentence that packs verb, resource, output fields, and output shape with zero 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?

The tool is simple (one required param), annotations cover read-only safety, and an output schema exists, so the description needn't explain return values. It is essentially complete, with only the sibling-differentiation gap remaining.

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%, with name, context, and namespace all documented in the schema. The description adds no parameter-level detail beyond what the schema provides, so the baseline 3 applies.

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?

States a specific verb and resource ('Report a deployment's rollout health') and even names the fields surfaced (ready/desired replicas, conditions). However, it does not distinguish this from sibling tools like kube_get or kube_diagnose_pod, leaving the agent to infer the difference.

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?

No guidance on when to use this versus kube_get, kube_diagnose_pod, or kube_events_summary, and no stated prerequisites. The agent must guess based on the name alone.

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 only declare readOnlyHint=true; the description adds substantive behavior by disclosing that it aggregates multiple signals into one call and enumerating what evidence categories it surfaces (CrashLoopBackOff, ImagePullBackOff, OOMKilled, Unschedulable, restarts). It stops short of stating limits, such as what it does with a healthy pod or whether the pod must already exist in the given context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler, and the value proposition ('in one call') is front-loaded before the return contents. The parenthetical evidence list is dense rather than padded.

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?

With an output schema present, return values need no prose explanation, and annotations cover safety; the description still adds the failure-mode scope an agent needs to judge applicability. All three parameters are fully documented in the schema, so nothing required to 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?

Schema coverage is 100% with all three fields documented, including the namespace default, so the schema already carries semantics. The description adds nothing about how pod name relates to namespace or context, which is the correct baseline-3 position when the schema does the heavy lifting.

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?

States a specific verb and resource plus the condition it targets ('Diagnose why a pod is unhealthy'), which is clearly distinct from raw retrieval tools like kube_get or kube_logs. It does not, however, differentiate itself from the nearby kube_pod_failure_summary sibling, leaving an agent to guess which diagnostic entry point to pick.

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 phrase 'in one call' implies this should be preferred over manually chaining get/logs/events, which is useful implied guidance. But there is no explicit when-to-use or when-not statement and no sibling is named as an alternative or complement.

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?

readOnlyHint=true already covers the safety profile, and the schema covers detailLevel/maxItems caps. The description adds real behavior (Warning-only filter, grouping by reason, count ordering) but says nothing about the response budget interaction, truncation behavior, or that results are aggregated rather than complete.

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?

A single sentence that front-loads the scope, the aggregation behavior, and the contrast with the naive alternative. 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?

With an output schema present and full parameter documentation, the description only needs to convey scope and aggregation semantics, which it does. Minor gap: it doesn't clarify how allNamespaces interacts with the summary grouping when no namespace is given.

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 every parameter is already documented, including the detailLevel presets and maxItems override. The description adds no syntax or defaulting information beyond what the schema states, so baseline 3 applies.

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?

States a specific verb (Summarize) and resource (Warning events) plus the output shape: grouped by reason, ordered by count. It implicitly separates itself from raw event listing ('instead of scrolling raw kubectl get events') but never names the actual sibling (e.g. kube_get) that does the raw read.

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 clause 'instead of scrolling raw kubectl get events' gives a clear selection rule against the raw-listing approach. It stops short of naming the sibling tool or stating when NOT to use it (e.g. when you need event timestamps or raw messages, use another tool).

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 only declare readOnlyHint, so the description does real work: it discloses that output is a compact summary by default, that jq skips the summary and returns raw results, and that kubectl JSON underlies it. It doesn't cover auth/context requirements or failure behavior, keeping it below 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?

Three sentences, front-loaded with the core capability, followed by output-shaping behavior and the single most important routing tip. 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 an 11-parameter read-only query tool with no output schema, the description covers purpose, default output shape, and the jq escape hatch, which are the essentials. Interaction between detailLevel, maxItems, and includeRaw is left entirely to the schema, but that is acceptable given full coverage there.

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 all 11 parameters are already documented in structured fields, including the jq example. The description's jq explanation largely restates the schema, establishing the baseline 3 rather than adding new 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?

States a specific verb and resource ('Get Kubernetes resources') and clarifies the mechanism ('Wraps kubectl get -o json'). It does not differentiate itself from specialized siblings like kube_deployment_status or kube_pod_failure_summary, which an agent must infer from the generic naming.

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 one clear routing rule: use the jq param instead of the summary when extracting specific fields. However, it never says when to prefer the generic kube_get over the many specialized kube_* siblings, nor when the standalone jq sibling would be more 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?

Annotations already declare readOnlyHint=true, so the description is not required to explain the safety profile. It adds meaningful behavioral detail beyond the annotations: the exact line format, oldest-first ordering, the merging of consecutive repeats into one line marked ' [×N]', and the rule that when the response budget truncates output, the newest lines are kept. This is genuinely useful context for interpreting results.

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 two sentences and front-loads the core behavior before the grep advice. The second sentence is dense but contains no filler, though the formatting details could be separated for easier reading.

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?

With 11 parameters, a full schema and a complete output schema, the description still says enough. It covers how log lines are formatted and what happens when the output budget truncates results. The schema covers everything else. Still, the interaction among detailLevel, maxItems, and the budget is only described 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?

Schema description coverage is 100%, so the schema already documents all 11 parameters. The description adds only the operational hint that grep should be used instead of shell piping; it gives no additional syntax or format details for tail, since, detailLevel, maxItems, or the budget interaction. This matches the baseline of 3 when the schema itself describes the 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 first sentence, 'Get pod logs,' gives a specific verb and resource and is immediately actionable. However, it doesn't differentiate this tool from sibling tools such as kube_get or kube_events_summary; for example, it could explain why logs come from this tool rather than from a general kubectl wrapper.

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 'Use grep ... instead of piping through shell commands' sentence explains how to use the grep parameter, not when to prefer this tool over alternatives. No explicit guidance about when this tool should be used instead of its siblings is present, so the agent can only infer usage.

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