code_check

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

With no annotations, the description carries the full burden and does meaningful work: it discloses the evidence side effect (commands + results recorded against a task), the preview-first safety behavior implying execution requires an explicit opt-in, and that async mode must be polled via code_control. It stops short of failure/exit semantics and any permission or rate considerations.

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 compact clauses pack purpose, evidence recording, the shell alternative, preview behavior, and the async escape hatch with zero filler, and the core action is front-loaded. The telegraphic phrasing ('async:true for long suites') is efficient but slightly at the cost of readability.

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 10-parameter execution tool with no annotations and no output schema, the description covers intent, safety preview, and async handling but leaves the response shape, failure semantics, and the verifier modes entirely unexplained. Enough to call it correctly in the common case, not enough to call it confidently in edge cases.

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

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

Schema coverage is 100%, so the schema already documents all ten parameters, making 3 the baseline. The description adds only scattered meaning (async ties to code_control, checks defaulting) and says nothing about verifier, timeout, workdir, or expected_state_revision, all of which are terse one-word schema descriptions.

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

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

States a concrete verb+resource: run test/typecheck/lint, scoped to 'after editing', plus two differentiators (records evidence, precedes execution with a preview). It positions itself against raw shell and points to code_control for background results, but never names the read/audit siblings it might be confused with.

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?

'Run ... after editing' gives a clear trigger, and 'async:true for long suites' gives an explicit conditional for switching modes. It also advises preferring this over raw shell. Missing is any explicit when-not guidance (e.g., when to use code_audit or code_query instead of re-running checks).

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