lint_diagnose

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

Annotations state readOnlyHint=false and idempotentHint=false, which flags mutation, but say nothing about scope. The description adds real behavioral context: it executes an arbitrary argv command, captures non-zero outputs, and produces a diagnosis prompt, which is more than the annotations convey. It still omits important traits for an arbitrary-command executor — sandboxing, command allow-listing or policy enforcement, whether the command's side effects actually occur, and the HTTP authorization requirement hinted at only by the authority_file parameter.

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 filler or repetition. It is efficiently written, though its brevity means there is no structure for the reader to navigate; the compression comes at the cost of coverage elsewhere rather than from trimming 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?

This tool executes arbitrary commands and has five parameters with no output schema, so the description carries the burden of explaining what comes back. It says only 'render a host-agent diagnosis prompt' without indicating whether the result is text, structured fields, or both, nor how failures are reported. The authorization path (authority_file for HTTP transport) and any safety constraints on the command are also 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 80%, so parameters are largely self-documenting and a baseline of 3 applies. The description contributes nothing parameter-specific: it does not clarify how cwd and workspace_root interact, that repo defaults to the current directory, or that authority_file is HTTP-only (that detail lives only in the schema). It neither adds nor conflicts with 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 three-part action: run a command, capture failure outputs, render a host-agent diagnosis prompt. The verb chain is concrete and goes beyond restating the name 'lint_diagnose'. However, it never distinguishes itself from near-neighbors such as command_fake_run, command_policy_check, gates_lint, or self_verify, so an agent cannot route between them on the strength of this sentence alone.

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 when-to-use or when-not-to-use guidance, no prerequisites, and no named alternative. The description implies the tool is for diagnosing failing commands, but nothing tells an agent whether to prefer it over gates_lint or command_fake_run, or what conditions make it appropriate.

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