Post to Bluesky

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

The description adds valuable behavioral context beyond the annotations: automatic linkification, immediate public visibility, irreversible publication, the confirm requirement, and the video transcoder delay. These details explain the real-world side effects of invoking the tool, which is especially important given the destructiveHint annotation.

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 tight sentences with no filler. The primary action is front-loaded, capabilities are summarized compactly, and the most critical operational constraint (300 chars, use create_thread) and safety requirement (confirm: true) are stated directly.

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?

Despite having 13 parameters and no output schema, the description covers the full scope of the tool's behavior well: what content it supports, the length limit, the automatic link handling, the video processing behavior, and the irreversible public nature. The rich parameter schema fills in the remaining details, so an agent has everything needed to invoke this correctly.

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 100%, so the schema already documents every parameter thoroughly. The description still adds useful cross-cutting semantics such as 'you do not need to format' links, the Bluesky-specific character counting, and the confirm-guardrail requirement, which helps an agent understand how parameters behave together.

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 clear verb and resource ('Publish a post') and explicitly enumerates the supported content types: text, images with alt text, video, link cards, quotes, and replies. It also distinguishes itself from create_thread by stating the 300-character boundary, so an agent can select this tool without ambiguity.

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?

Usage guidance is explicit: it states the tool should be used for posts up to 300 characters and directs longer content to create_thread. It also tells agents that URLs, hashtags, and mentions will be linkified automatically, so no manual formatting is needed, and that confirm=true is mandatory because the post is public immediately.

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