generate_post_carousel

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

With no annotations provided, the description carries the transparency burden. It discloses the core behavior (generates a PDF), the returned values (asset ID and download URL), and a prerequisite. However, it does not mention side effects (e.g., whether the generated asset is persisted, whether it consumes credits, or whether it overwrites previous versions), which is a notable gap for a generative action.

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 two sentences, front-loaded with the primary action, followed by the output and the key prerequisite. Every word adds value; no redundancy or irrelevant detail.

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?

Given the moderate complexity (4 params, no output schema), the description covers the essential aspects: purpose, output format, and a critical prerequisite. It could be more complete by noting default behavior for optional parameters, but overall it provides sufficient operational context for an agent to invoke the tool 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?

The input schema has 100% description coverage for all parameters. The description adds context by linking postId to the post's cards, but it does little to explain style, title, or variant beyond what the schema already states. Baseline 3 is appropriate since the schema handles param documentation adequately.

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 ('Generate a carousel PDF'), identifies the source ('from the post's cards'), and mentions the output (asset ID and download URL). This clearly distinguishes it from sibling tools like generate_post_visual_options or regenerate_post_visual, which focus on visual options rather than a PDF artifact.

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 a clear precondition ('Requires cards to be set first via set_post_cards or edit_post_card'), which tells the agent when this tool is appropriate. It does not explicitly list exclusions or alternatives, but the prerequisite provides sufficient contextual guidance for tool selection.

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