variant_build

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

With no annotations, the description carries the full burden and does meaningful work: it discloses that nothing is posted, that caption links are not clickable and the working path is profile link / Story sticker, and that output includes a classified diff vs canonical plus a hash. It does not say whether the variant is persisted under account_id, whether the call is idempotent, or what happens on an unsupported surface.

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?

Front-loaded with the verb and resource, then the surface taxonomy, then the output inventory — a sensible order. It is a single very dense sentence, and clauses like 'the variant's hash' are slightly surplus given no output schema consumers, but nothing is genuinely wasted.

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?

No annotations and no output schema, so the description's output inventory is valuable and covers return values well. The critical gap is the required nested 'package' object, whose expected contents are left entirely undefined despite being the only required parameter.

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 coverage is 0%, so the description must compensate and it partly does: the surface list (feed 4:5, carousel narrative order, reel 9:16, story 9:16) effectively documents the allowed values of 'surface'. But 'account_id' is never mentioned and the required nested 'package' object's structure is only gestured at with 'canonical content package'.

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?

States a specific verb and resource ('Build one native Instagram variant') and enumerates the four supported surfaces inline, so an agent can tell what artifact is produced. It does not name or distinguish itself from the sibling preview_pack, which is the most likely source of confusion.

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?

'Formalization only — nothing is posted' usefully bounds the operation, and the implied prerequisite 'from a canonical content package' hints at required input. However, there is no explicit when-to-use guidance, no mention of whether preview_pack should be run first, and no stated exclusions.

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