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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), the description discloses meaningful behaviors: the offer's 'reasons' are closed and no run reads them again (a terminal side effect), the write goes through the same writer as the tommo's page, and it requires a signed-in person rather than a key. These add context the annotations cannot express, though the phrasing is murky.

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?

Two long sentences that are reasonably front-loaded on the primary action. But the em-dash-laden, whimsical wording ('the offer's after, whole') is dense and hard to parse, so length is not the issue — clarity of expression is.

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?

For a mutation tool with no output schema, the description does cover the precondition, auth requirement, and a terminal side effect, which is more than most. Still, the obscured language leaves the exact result state of the accepted change ambiguous for an agent that needs to call it confidently.

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 100%, so the two parameters are already documented in the schema and the baseline is 3. The description adds only a soft gloss on the optional 'text' parameter ('with text, the person's own whole text in its place') without adding format, constraints, or interaction with offer_id.

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 core action is decipherable as accepting a text change that Tommo offered, and the title reinforces it. But the description is written in heavily obfuscated prose ('the text becomes the offer's after, whole'), which forces the agent to work to confirm it is not, say, refusing or listing a change. It never names the closely related siblings refuse_a_text_change or list_text_changes_offered to differentiate itself.

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 two real usage constraints: the text must still be 'the offer's before' (a precondition) and only a signed-in person may take one, not a key (auth requirement). However, it never explicitly routes to the alternative action (refusing a text change) despite that being the natural sibling choice, so the when/when-not framing is only implied.

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