twitter_article_publish

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

While annotations already mark the operation as non-read-only, the description goes far beyond by disclosing that the announcement tweet is REAL and PUBLIC, that the action is hard to fully undo, and that even after deletion the content was already public. It also describes authentication prerequisites and provides high-value context about the exact reversal behaviors of sibling tools, with no contradiction to the annotations.

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 front-loaded with the core action and then builds out critical warning and side-effect context. Every sentence serves a distinct purpose: warning about irreversibility, naming alternatives, giving confirmation guidance, and covering defaults and prerequisites. The length is justified given the consequential nature of the operation.

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 tool has 8 parameters, complex state transitions, and no output schema, yet the description succeeds in covering what matters: the outcome, the order of operations, side effects, undo semantics, defaults, return value, and authentication needs. The agent is equipped to decide, confirm, and invoke safely.

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 input schema already covers 100% of parameters with detailed descriptions, so the baseline is 3. The description repeats a few key facts (id must be a draft, audience and reply_control default to 'Everyone', caption max 256 characters) but does not add new parameter semantics beyond what the schema already provides.

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 tool's core action—publish a DRAFT article as the authenticated account—and specifies the resulting state change: transitioning to Published and posting a REAL, PUBLIC announcement tweet. It distinguishes itself from sibling tools by explicitly naming twitter_article_unpublish and twitter_article_delete and their different reversal behaviors.

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 explicit when-to-use guidance: publishing a draft article with a public announcement tweet. It also gives exclusionary context by explaining that unpublish only reverts the article but leaves the tweet, and that only delete on a published article removes both. Additionally, it instructs the agent to confirm with the caller unless explicitly authorized, which is clear and actionable usage guidance.

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