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

Beyond the read-only and non-destructive annotations, it discloses important workflow behavior: the plan should be assembled once and sent to review without preliminary confirmation; corrections replace the pending plan via replaces_receipt; matched_entities data should be reused without re-fetching; junk should be ignored and ids never invented. It also explains source_touch_id pinning, that pinned links outrank heuristic matches, and that candidate_names are match candidates rather than authoritative identities.

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 core action is front-loaded, and nearly every sentence contains operational guidance, but the description is a dense run-on paragraph mixing workflow rules, ID conventions, matching heuristics, and usage triggers. It would be more effective if the 'When to use' guidance were moved forward and the technical instructions were separated into clearer clauses.

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 the complex planning workflow, the 100% schema coverage, the annotations, and the output schema, the description is largely complete: it covers the review handoff, pending-plan replacement, id reuse, ambiguity resolution, and source-touch pinning. It leaves some gaps around the exact boundary with commit_reviewed_updates and around what happens when there is nothing to propose.

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 meaningful usage guidance for parameters: pass source text in `text`, use source_touch_id for stored work, and pass candidate_names for lowercase or uncased names. It does not describe the deprecated `transcript` alias, but the schema covers that detail.

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 a specific verb and resource: read matched records/schema/history, assemble one complete plan of records, people, links, activity, and requested tasks, then hand off to review_proposed_updates. It clearly distinguishes this from directly calling write tools and from the subsequent review step, so an agent can tell what this tool is for 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?

It gives an explicit trigger ('After any meaningful conversation, email, or note about a relationship') and instructs the agent to pass text in `text`, plus says to call review_proposed_updates without preliminary confirmation. It also says to propose only new changes after saving and not to call write tools directly, but it never explicitly contrasts this with update_record or commit_reviewed_updates, leaving part of the routing to inference.

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