create_social_svg

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds substantial behavioral detail beyond those: copy is corrected and spelling issues visibly reported, output uses packaged fonts with native unscaled headline glyphs, inline vector logos, xlink:href for rasters, and PNG previews must never use system-font fallback. No statement contradicts the read-only/idempotent 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 long but appropriate for a 16-parameter, no-output-schema tool. It is organized: purpose, exclusivity, output construction details, preview rule, and quote-specific usage. Each section adds information, though the first sentence is slightly overloaded by combining the spell-check behavior with the generation purpose.

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 complexity and missing output schema, the description covers the essential workflow well: output format, rendering constraints, tool exclusivity, and quote-specific parameter relationships. It does not explain several high-level fields like mode, cta, body, and kicker, but an agent can still correctly invoke the core social-post workflow.

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 only 56%, so the description must compensate for under-documented parameters. It does add useful cross-parameter meaning for quote templates: person is required, the quote belongs in headline, and emphasis is violet. However, several parameters lacking schema descriptions (cta, body, kicker, mode, assetBasePath, includeLogoPlaceholder) remain unexplained by both the schema and the description.

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 ('generate') and resource ('Illustrator-safe SVG 1.1 SAMPLE artwork from reference-locked social templates'), and also names the spell-check/report behavior. It explicitly positions itself as 'the only supported social-post renderer' and contrasts with legacy/freeform generators, making it distinguishable from siblings such as create_one_pager or create_quote_post.

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 states an explicit exclusivity rule: 'never recreate its SVG through a legacy or freeform generator.' It also gives concrete conditional guidance for template=quote ('provide person and put the quote in headline') and mandates the violet emphasis. This is strong usage direction, including a prohibition against alternatives.

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