Publish an X/Twitter thread

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

Beyond the annotations (readOnly=false, openWorld, idempotent false), the description adds critical behavioral context: 'CAPABILITY: publish — this can reach a LIVE AUDIENCE,' the token restriction ('A draft-scoped token gets a 403 here; a human must approve at timetopost.co instead'), and the scheduling behavior ('omit to go out on the next scheduler tick (~1 min)'). This significantly enhances what the agent knows about the tool's side effects and limitations.

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 long but densely packed with necessary operational details. It is front-loaded with the core purpose and segment structure, then includes behavioral, permission, and style guidance. The writing-style rules are verbose but relevant for an agent that may draft content; still, they could be moved to a linked reference to tighten the tool description.

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?

The description covers purpose, scheduling, permissions, and follow-up verification via get_post. However, it does not describe the return value/response shape of publish_thread itself, and with no output schema, this leaves an important gap. Agents must assume what the tool returns and rely on get_post to confirm the actual post IDs, which is a notable omission.

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?

The schema already covers brand and schedule_at descriptions, and the description adds meaning for segments by clarifying that 'segments[0] is the anchor tweet; segments 2..N ... publish as chained replies' and expands schedule_at with 'future ISO datetime; omit to go out on the next scheduler tick.' This fills the gap for the undocumented segments parameter and enhances the schedule_at semantics.

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 opens with a specific verb and resource: 'Publish or schedule an X/Twitter thread in one call.' It further distinguishes itself from siblings by noting it's a 'Convenience wrapper over schedule_post + thread,' and explains the segment structure, leaving no ambiguity about the tool's function.

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?

Provides clear usage context: it positions itself as a wrapper over schedule_post + thread, advises following up with get_post to confirm platform post ids, and instructs reading account recent posts with list_posts before drafting. It does not explicitly contrast with publish_post for single posts, but the wrapper phrasing and thread-specific purpose give adequate guidance.

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