case_close

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

Annotations already indicate readOnlyHint=false and idempotentHint=false. The description goes beyond by disclosing that the grade is computed from the ledger rather than accepted, that the return includes open_gaps, and that a closed case cannot be closed again and its record is never rewritten. This adds meaningful behavioral context about irreversibility and the computation logic, without contradicting the annotations.

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 organized into concise, clearly labeled sections (purpose, WHEN, RETURNS, GOTCHAS), front-loaded with the core purpose. Every sentence provides useful information without redundancy. The format makes it easy for an agent to quickly grasp the tool's behavior and consequences.

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 description covers the tool's purpose, trigger condition, output shape, and important gotchas (irreversibility, refusal of already-closed cases, and the alternative for reopening). For a simple single-parameter tool, this is comprehensive and leaves no critical gaps for an agent to make a correct call.

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 input schema for case_id already provides a full description, including that there is no grade parameter and that closing recomputes the grade. The tool description repeats this ('no grade parameter — closing recomputes the grade from the ledger') but does not add new meaning. With 100% schema description coverage, the baseline of 3 is appropriate; the description adds no additional semantic insight.

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 opening line 'Record the final grade and archive the case — step 08' clearly states the action (record + archive), the target resource (case), and its position in the workflow. It distinguishes itself from siblings like case_grade (which computes grade without closing) and case_open by its finalizing, archiving role.

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 'WHEN' section explicitly states to use this tool when the investigation is finished or handed over. It also provides an alternative for reopening ('open a new case that cites this one'), clarifying that closing is a terminal action and not for ongoing work. This is clear usage guidance with both a positive trigger and an exclusion.

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