code_check

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds real behavioral context beyond them: per-site classifications (exists | absent | unknown | not_installed | guarded), exit-code semantics (4 = not checked, 3 = absent or version mismatch against the lock), the guarantee that nothing the repository supplies is started when env points outside the project, and the standard-library-only 'none' mode. This is unusually rich disclosure for a read-only tool.

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

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

Front-loaded with language coverage and result semantics, and every clause carries information (no padding). It is telegraphic and semicolon-dense, with heavy abbreviation ('arity', 'exit 4'), which costs some parseability, but nothing is wasted.

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 no output schema, the description correctly carries the return burden by enumerating site statuses and exit codes, and it covers all three invocation modes plus environment resolution. It is thin only on what TS/JS checking actually verifies and on any prerequisite (e.g. an index), which keeps it short of 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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: the 'nothing given = changes against HEAD' default for diff, the resolution semantics of as_path for snippet, and the resolution rule for env (auto vs external venv vs none). These clarify interaction between parameters rather than restating them.

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 (check) and a precise resource: whether Python imports/names/attributes/kwargs and JVM classes/methods/fields/Mixin targets resolve against the project environment, classpath and JDK. The language scope and the notion of a 'site' result are unambiguous. It does not, however, differentiate itself from siblings such as analyze, project_query or node_inspect, so an agent gets no routing signal.

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 clear context for each of the three input modes (paths, diff against a revision with nothing-given meaning changes vs HEAD, snippet + as_path) and states the language fallback (other languages -> not_checked, exit 4). What is missing is explicit when-not or an alternative tool: nothing tells the agent when to prefer this over node_inspect or relation_trace.

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