Create draft post

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It clearly states the draft is not published until approved and explicitly published, and it details the non-obvious link-handling rule, including the opt-out flag. It does not mention authentication or rate limits, but the key safe behavior (no immediate publishing) and the link constraint are well disclosed.

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 description is a single, well-organized paragraph that front-loads the purpose in the first sentence, then lists supported features, states the critical rule, and explains the safety behavior. Every sentence provides necessary information without redundancy. The use of 'RULE' in caps draws attention to the most important constraint.

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 tool with 10 parameters and a nested poll object, the description gives sufficient context for correct invocation by explaining the workflow (draft, approve, publish) and the key behavioral rules. It does not describe return values, but no output schema exists, and the main purpose is to guide selection and invocation, which it does well. It could mention what the response contains (e.g., draft ID), but the description is otherwise complete.

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 adds value beyond the schema by emphasizing the critical rule that URLs must go in parts[1+] and that allowLinksInMainPost should only be true on explicit user request. It also summarizes the supported features and notes the 'text must equal parts[0]' constraint, reinforcing relationships already present in the schema.

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 clearly states the verb and resource: "Create a draft social post for a channel (currently only "x")". It distinguishes from sibling tools by framing the action as creating a draft, which is later approved and published by other tools. The scope (channel 'x') and feature list (text, threads, polls, etc.) are explicit.

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?

The description provides strong contextual guidance by noting that drafts are "saved locally and NOT published until approved and then explicitly published", which clarifies the tool's role in the workflow. It also includes the rule about avoiding links in the main post. However, it does not explicitly name alternatives like update_draft or publish_draft, but the workflow description implies when this tool is appropriate.

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