Generate post drafts

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

Annotations cover the safety profile (readOnly false, destructive false, closed-world, non-idempotent), and the description adds real context beyond them: no publish/queue side effect, the 8,000-character context ceiling, quality tiers, and that the result surfaces rule_violations against account content_rules. It stops short of saying where drafts are persisted or whether premium quality has latency/cost implications for a non-idempotent call.

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?

Three dense sentences, front-loaded with what is generated and how much, then constraints, then the use-case trigger. Every clause carries information; no restatement of the title.

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?

Six parameters with no output schema, and the description does cover the return-side hint (rule_violations). The remaining gap is where drafts land and whether they must be added to the library or queued separately — a material detail given the surrounding add_library and bulk_queue_library siblings.

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 baseline is 3; the description earns above it by binding formula to a discovery tool ('auto, or an id from list_formulas') and restating quality tiers and the context limit in prose. It adds no enum constraint the schema lacks, but the cross-tool linkage for formula is genuinely useful.

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?

Specific verb (generates) plus resource (post drafts) with an explicit 1-5 count range and the exact inputs that shape the output. It also carves out the negative space — 'Nothing is published or queued' — which separates it from publish, schedule_text and bulk_queue_library in the sibling list.

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 a clear triggering condition: 'Applies when the user wants drafts to read, edit or choose from,' and routes the formula id lookup to list_formulas. It does not name the write-path alternatives (publish, schedule_text) explicitly, so the exclusion is inferred rather than stated.

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