decision_check

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

The description goes well beyond the annotations. Annotations provide no hints (readOnlyHint=false, etc.), but the description discloses that the tool 'Never edits code or records', that it 'Refreshes a stale index first when a guard needs the graph', and explains exit codes (exit 1 for new findings, exit 3 for unknown). It also clarifies that exit 3 means something was not checked and is 'never ok'. This is rich behavioral context that an agent needs to interpret results correctly, and it does not contradict any annotation.

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 information-dense but not bloated. It front-loads the purpose and then covers parameters, exit codes, and a promise about side effects. Every sentence contributes value. It could be slightly better structured with line breaks or bullet points, but it's efficient given the complexity of 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?

For a tool with 3 parameters and no output schema, the description is fairly complete. It describes the outcome categories (violations, possible, etc.), exit codes, the index refresh side effect, and the guarantee about not editing code/records. It does not detail the exact return format, but with no output schema and moderate complexity, this is acceptable. The description carries the full burden since annotations are sparse, and it largely succeeds.

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 three parameters (base, refresh, changed_only). The description adds significant meaning beyond the schema: it explains that changed_only=true or base=REV counts only new findings and yields exit 1, and it ties the refresh parameter to the index refresh behavior. It also clarifies the meaning of exit 3 in relation to unknown findings. This goes beyond a baseline of 3 by providing actionable semantics for parameter combinations.

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 clearly states a specific action: checking the working tree against every accepted guard of accepted decision records, and enumerates the outcome categories (violations, possible, reviews, triggers, ok, waived, unknown). It uses a specific verb and resource, so it's not a tautology. However, it does not differentiate itself from sibling tools like code_check or change_review by naming alternatives, so it doesn't fully achieve sibling distinction.

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 its siblings. It explains parameter effects (changed_only, base) and exit codes, but never states a condition like 'use this when you need to check decision guards' or 'use code_check instead for X'. There is no when/when-not guidance, so an agent would have to infer from the tool name and description that this is for decision guard checks, which is not explicit.

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