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

Goes well past the annotations by disclosing that acceptance lives beside the model and is untouched by undo/restore_revision, that it is invalidated by placement, shape, openings or type-geometry changes, and that check_contacts reports accepted_body_changed or accepted_kind_changed. These are the non-obvious semantics an agent needs and annotations cannot carry; nothing contradicts idempotentHint or destructiveHint=false.

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 lead sentence correctly front-loads accept-versus-unaccept, but the rest is a run-on tangle of parentheticals ('(was rebound)', 'now: holds, body_changed, element_gone or body_unread') mixed into one block. The information is valuable; the packaging costs readability.

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 supplies the read-mode return shape (stored pairs, max 20, n_stored, per-pair now statuses) and the durable-state semantics, which is a lot. It leaves unanswered what accept/unaccept themselves return on success, which is the main remaining gap for a mutation tool.

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 already 100%, so the baseline is 3, but the description adds the consequence of kind and re-accept ('bind it to the bodies as they are then (was rebound)') and the not_stored outcome for unaccept. It stops short of explaining field-level syntax, which the schema already covers.

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+resource ('Marks contacts ... as accepted, or takes that back') and anchors it to the sibling that produces the pairs (check_contacts). An agent can tell it apart from check_contacts, undo, and restore_revision 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?

Implies the workflow clearly: pairs come from check_contacts, accept binds them to current bodies, unaccept reverses, and a re-accept is required after a body or kind change. It never states an explicit exclusion or a competing tool to prefer, so it falls one step short of full when/when-not guidance.

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