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

Annotations declare readOnlyHint=false and destructiveHint=false, and the description adds substantial context beyond them: the call is a dry run producing a preview plus proposal id, the mutation is deferred to apply_proposal, there is a needsApproval branch with an approve link, and the operation can trigger notifications to people in the system. It does not address non-idempotency (repeated proposals creating duplicates) or limits/rate behavior, which are the remaining relevant traits.

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?

Information density is high and the workflow order is front-loaded, but the prose is congested and partly malformed – the colon after 'change records' introduces a noun-phrase fragment, and the confirmation sequence is one long run-on. Restructuring into imperative steps would convey the same content with less parsing effort.

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?

An output schema exists, so return values need not be explained, and the description still tells the agent what the answer contains (current state, proposed state, proposal id, needsApproval). Combined with the confirmation workflow and the notification warning, an agent has enough to call and follow up correctly; only idempotency/repeat-proposal behavior is unaddressed.

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% and the schema already spells out system resolution via get_ai_agent_options, the id/type/users shape, and the 25-item cap; the description only restates 'Give one item per record, at most 25'. It adds no meaning about the users array, the type enum, or how nested ids are obtained beyond what the schema already says.

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 states the action (propose adding users as followers of records) and, crucially, that 'Nothing is written yet' and the result is a preview of before/after state plus a proposal id. It also names what the tool is not for ('Not for reading (use search_records or get_record)'), which separates it from the read siblings. The one weak spot is the fragment 'Users who follow a record and hear of what happens on it', which is jammed in mid-sentence rather than stating the resource cleanly.

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?

It gives a precise trigger ('Use when the person asks for this in a system whose AI agent may change records'), an explicit exclusion ('Not for reading – use search_records or get_record'), and the full follow-up protocol: show the preview, disclose any notification to users in the system, ask for confirmation, then call apply_proposal, or hand over the approve link when needsApproval is true. Nothing about when or how to proceed is left to inference.

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