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

Beyond the annotations (readOnly=false, destructive=false, openWorld=true) it discloses the crucial staging behavior: nothing is written yet, the response returns per-record before/after state plus a proposal id, and apply_proposal is the only commit path. It also surfaces the open-world consequence (something may be sent to people in their system) and the needsApproval/approve-link branch, which the annotations cannot express.

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 content is high-value but the delivery is a run-on chain of semicolons and clauses, and the first clause ('AI Agents (inside one system): Use when the person asks for this in a system whose AI agent may change records') buries the purpose behind a meta-condition. The purpose statement and the commit/approval workflow are both present but interleaved, so nothing is skimmable.

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, yet the description still usefully characterizes the response (current vs. proposed state, proposal id) and covers the full human-in-the-loop workflow for a non-destructive propose step. The one gap for a two-param, 25-item batch tool is that relationship direction and duplicate/link-exists handling are implied rather than stated.

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 the schema already defines system, items, id/type pairs and other_parent. The description only adds the batch cap ('one item per record, at most 25'), which merely restates maxItems, and says nothing extra about how to choose the system value or how to order the two records. Baseline 3 applies.

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 concrete effect — two records linked, e.g. a contact to a deal or an existing note/task to another record — plus the no-op case when they are already linked. It is written as a noun phrase fragment rather than a verb+resource sentence, so the actual action ('propose linking') has to be inferred from the title, but the resource and outcome are unambiguous.

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 clear gating condition ('in a system whose AI agent may change records'), an explicit exclusion with alternatives ('Not for reading (use search_records or get_record)'), and a next-step rule ('only then call apply_proposal'). What it lacks is any differentiation from propose_unlink_records or the other propose_* mutation siblings, which an agent choosing among a catalog of 32 propose_* tools would want.

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