Suggest changes to some writing

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

Annotations only supply the safety profile (not read-only, not destructive, not idempotent); the description supplies the behavior that actually matters — edits are proposed and gated on human accept/decline on the record's page, so nothing is applied on this call. It also discloses the cap of 15 edits and the dependency on a prior get_record read ('Copy each passage exactly from get_record, long enough to occur once'), which is a real prerequisite an agent must satisfy. No contradiction with the annotations.

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?

Front-loaded with the core behavior and kept to four dense sentences with no filler; the routing rule, constraints, and prerequisite all appear. Phrasing is telegraphic in places ('Feedback on structure is said in words, not suggested'), which costs a little clarity but not much space.

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?

There is no output schema, but the description explains the return mechanism — each suggestion surfaces on the page for accept/decline — so an agent understands what happens after the call. Combined with the prerequisite read and the 15-edit cap, the definition is complete enough to invoke correctly; only failure behavior when a passage does not match is left unstated.

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?

With 75% schema coverage the baseline is 3, but the description adds meaning the schema lacks: passages must be copied verbatim from get_record and be long enough to be unique, and the structure kind is constrained by the rule that structural feedback is given in prose rather than as a suggestion. It does not explain the meaning of the 'meaning' boolean or the field default 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?

States a specific verb+resource with its defining constraint: it proposes edits to writing rather than applying them, and the person accepts or declines each. It explicitly distinguishes itself from the sibling update_record, which handles plain commands, so an agent can route correctly without opening either 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?

Gives an explicit decision rule ('a plain command (fix the spelling) you just do with update_record; suggest when the changes are judgement calls on their words') naming both the alternative and the selecting condition. It adds exclusions and scope limits ('Do only the help asked for, keep their voice, small changes, at most 15') and rules out one category entirely ('Feedback on structure is said in words, not suggested').

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