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

Beyond the annotations it discloses the key side effect — "The source is marked written, so it is never offered again" — plus the re-save-revises-draft rule, the fact that "Nothing is posted", the target destinations, and that the call is free. With destructiveHint/readOnlyHint already set, this adds exactly the state-change context an agent needs before calling.

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?

Almost every clause carries spec detail, so there is little dead weight, but the content is delivered as one dense run-on paragraph with parenthetical pile-ups, making it hard to scan. Front-loading is acceptable (purpose first), yet a bulleted variant list would have been far more usable.

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 high-complexity tool (6 params, nested objects, no output schema) it covers the variant semantics, the state mutation, and roughly what is returned ("X's composer, the Articles tab, or Reddit's submit page"). Remaining gaps are minor: it does not pin down the exact return payload or how conflicts between supplying x/reddit/article/thread are resolved.

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 only 67% and the schema carries almost no prose (just min/maxLength), so the description does the heavy lifting: 280 characters "as X counts them", links counting 23, reddit needs subreddit+title+body, image is a local path, article title under 100 chars with a 600+ char Markdown body using , 5:2 cover, thread of 2–12 posts. This is meaning well beyond the structured fields.

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+resource ("Save one note's drafts") and enumerates the concrete output variants (x, reddit, article, thread), so an agent can tell what the tool produces apart from siblings like notes_context or notes_voice. It never explicitly contrasts itself with those siblings, and the phrase "Assisted posts in the results app" is vague, which keeps it short of a 5.

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 real selection conditions: "on its own, the long form: article ... or thread", thread is "for an account without X Premium", and premium "is what you saw on X's Articles tab just now". It also explains the revise-on-re-save behavior. It stops short of 5 because it never states when NOT to use this tool or how it relates to the other notes_* siblings.

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