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

Annotations declare destructiveHint and openWorldHint true, and the description adds genuinely new behavioral detail beyond them: the owner_approval_url → ALLOW flow, enumerated pairing.status values with the caveat that only 'paired' confirms pairing, 'a request is not proof the person saw it', 'a comparison leaves source unchanged', and 'later human navigation wins'. Together these set realistic expectations about a human-in-the-loop, non-idempotent operation.

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?

It is front-loaded with the core action and the sentences are information-dense with little filler. However, telegraphic fragments like 'Present work or ask the person.' restate the title, and the pairing paragraph is packed into one run-on construction that is hard to parse.

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 24 parameters, no output schema, and destructive/open-world annotations, the definition covers the tricky pairing and approval flow well but is silent on what most targets actually do and what happens on a destructive path. An agent would still be guessing for most of the target enum values.

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 description coverage is only 29% across 24 parameters, so the description carries a heavy compensation burden it does not meet. It explains target inference, the code/pair link, that text holds the whole alternative document for comparison, and the meaning of pairing.status, but leaves act, note, view, wait, agent, block, close, value, words, heading, lifetime, question, revision, compare_id, preference, timeout_ms, operation_id, and after_return_id without added meaning.

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 names concrete actions: pointing the person to a place in a Rapier document, asking them something there, and pairing a browser with a 4-letter code. It clarifies that the tool presents work to a human, distinguishing it from sibling operations like edit/read/export. It loses a point because the 16-value target enum (read_aloud, playback, comparison, view, preferences, plugin, file, record, attachment, return, note) is mostly unexplained, so the full breadth of 'show' is opaque.

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?

There is implied guidance — 'An omitted target is inferred from its fields', pairing requires a code and owner approval, and the note that a request is not proof the person saw it. But there is no explicit statement of when to prefer this over siblings such as open or edit, and no guidance on which target to pick for a given intent.

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