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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds substantial behavioral detail: 'Sending leaf_code:null permanently removes that account saved reporting line,' 'Omitted accounts stay unchanged,' and the warning to never claim completion without checking the response fields. This goes well beyond the annotations and discloses important side effects.

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 five sentences and every sentence carries essential information—purpose, preconditions, null semantics, no apply-all, and response interpretation. It is front-loaded with the core action, but the density of warnings makes it longer than absolutely minimal, which is appropriate for a destructive 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?

Given the tool's complexity—four parameters, a nested decisions array, destructive behavior, and no output schema—the description is remarkably complete. It covers prerequisites, user approval steps, edge cases, response fields to check, and the caution not to assume completion. This fully compensates for the missing output schema.

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 75%, and the description enriches the most critical parameter: leaf_code:null is explicitly linked to permanent removal, and the decisions array is clarified by noting omitted accounts stay unchanged and there is no auto-confirm flag. It does not explain removal_token, but the schema already describes its purpose adequately.

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 opens with 'Persist only the explicit reporting-line decisions the user approved'—a specific verb (persist) and resource (reporting-line decisions). It clearly distinguishes from sibling confirm tools like confirm_centre_mappings and confirm_column_mapping by narrowing scope to reporting-line mappings.

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 explicit when-to-use guidance: 'Before calling, show the proposal grouped by confidence tier... and get clear approval.' It also gives when-not-to-use cautions, such as sending leaf_code:null only when the user explicitly asked to clear the row, and notes there is no apply-all flag. However, it does not explicitly name alternative tools, so it falls short of a perfect score.

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