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

Annotations declare the mutation profile (readOnlyHint=false, destructiveHint=false), and the description adds value beyond them: it discloses the effect ('status and category recorded on every row accepted') and the human-confirmation requirement. It does not address what happens on a repeat call (no waiting rows? error?) despite idempotentHint=false, which is the one meaningful gap.

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 operation and constraint are front-loaded, and the 'Effects:' line is efficient, but the prose is padded with stylistic framing ('in one reasoned act', 'This is a review act') that costs tokens without adding decision-relevant information.

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 3-parameter mutation with no output schema, the description covers the prerequisite, the human-confirmation rule, the field-selection behavior, and the resulting side effects on the records. It lacks only return/response expectations and repeat-call behavior.

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 baseline is 3, but the description genuinely adds meaning: 'minus any the person says are not part of it' explains the role of `except` as a subtractive filter, 'every waiting row, or one rule's rows' explains `rule_id` scoping, and 'The reason is their confirmation' tells the agent what `reason` should contain.

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 (confirm/accept) and resource (rows suggested by standing rules), and scopes it as 'every waiting row, or one rule's rows'. The phrasing 'what standing rules suggest' is indirect rather than saying 'pending rule suggestions', but an agent can still distinguish it from purch_rules (which lists suggestions) without opening the schema.

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 a clear precondition — 'Show them the rows first (purch_rules lists each rule with the rows it is suggesting for)' — routing the agent to the sibling that surfaces what would be accepted, plus a hard usage constraint: 'never the rule alone', i.e. only after human confirmation. No explicit when-not-to-use case or named alternative action (e.g. for rejecting rows) is given, so it falls short of 5.

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