Create or schedule a post

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

Beyond the annotations, the description discloses meaningful behavioral context: text is validated against network limits before sending, posts appear publicly under the brand, and the agent must show the user the content and obtain confirmation before publishing. This is exactly the kind of non-obvious behavior an agent needs to know.

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 four sentences with no filler. It front-loads the main purpose, then efficiently covers scheduling, drafts, media prerequisites, validation, and the mandatory user confirmation. Every sentence contributes essential operational information.

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 9 parameters, the description covers the critical workflow: media upload prerequisite, state semantics, scheduling behavior, validation, and the public-facing nature of the action. The output schema exists, so the lack of return-value detail is not a gap. The annotation set plus description is sufficient for safe and correct invocation.

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 high (89%), so the baseline is a 3. The description adds semantic value by explaining that files must contain upload_media ids, that publish_date should be left empty for immediate publishing, and that state 'ready' means publish/schedule while 'draft' means save for human review.

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 action — publish now, schedule, or save as draft — on a single connected account, which distinguishes it from sibling tools like update_publication and upload_media. It clearly names the resource (a post) and the key constraint (ONE connected account).

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 gives concrete usage guidance: use state 'ready' with a future publish_date to schedule, use 'draft' to leave for review, and upload media first with upload_media. It does not explicitly name update_publication as the alternative for editing existing posts, but the guidance is clear enough for correct invocation.

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