Skip to main content
Glama

Heista

by co.heista

Generate Ad Script

generate_adscript

Generate direct-response video ad scripts by fusing a proven structural source (decoded ad or formula) with a brand's PowerSource. Output is feed-native ad copy for paid social (Meta, TikTok, Reels) in the brand's voice — hook, beat-by-beat body, CTA close, plus visual direction per beat. Takes source_id (from adformula_intelligence, decoder_intelligence, or decode_ad), source_type ("formula" or "decode"), powersource_id (from any create_powersource_*), and tunable params: count (1-5 variants, tensions and selling points auto-rotated across variants), script_mode ("blueprint" preserves source structure exactly, "remix" preserves psychology but writes original copy), duration (target seconds), audience, tension override, selling_points override, voice_mode ("creator" for UGC default, "brand" for owned channels), and idempotency_key.

Use this when the user says "write me a script", "I need a TikTok script", "write an ad based on this", or wants shell-faithful replication of a proven winner in their own brand voice. REQUIRES both a structural source AND a powersource — guide the user through creating either if missing.

Metered pricing — typically 2-5 credits per script (~2 credits for 15s, ~5 credits for 60s). Pre-flight reserves a 17-credit ceiling and refunds the difference after measurement.

Do NOT use to discover sources — use decoder_intelligence or adformula_intelligence first. Do NOT use to extract brand intel — use create_powersource_url first.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
countNoNumber of scripts to generate (1-5, default 1). Each script uses a different tension and selling point combination for variety.
tensionNoLock to a specific behavioral tension from the PowerSource (e.g., "Frustration → Relief"). Omit to let the system select the best match.
audienceNoAudience segment from the PowerSource. "buyer_profile" (default) uses the composite buyer. "audience_0", "audience_1", etc. target specific segments.
durationNoTarget duration in seconds (remix mode only, 10-120). Blueprint mode locks to the source duration.
source_idYesThe ID of the structural source to write from. For source_type="decode": either a job_id from your own decode_ad call OR an id from decoder_intelligence (corpus ad). For source_type="formula": a formula id from adformula_intelligence.
voice_modeNoVoice register for the script. "creator" (default) = authentic creator voice for UGC, PowerSource locks facts/tensions/selling points but NOT voice register. "brand" = full PowerSource brand voice for brand-owned content (website, OOH, brand films). Most ad scripts should use "creator".
script_modeNoScript mode. "blueprint" (default) follows the source formula exactly — same beat structure, same timing. "remix" uses the psychological architecture but writes original copy.
source_typeYesType of structural source. "decode" = a single decoded ad (your own or from the corpus). "formula" = a clustered blueprint built from multiple winning ads.
powersource_idYesIdentifier for the brand PowerSource that supplies voice, selling points, tensions, and audience. Accepts either a job_id from create_powersource_* or a brief_id from get_powersource — both work.
selling_pointsNoLock to specific selling points from the PowerSource (max 5). Omit to let the system select the best match for each beat.
idempotency_keyNoOptional unique key to make this call safely retryable. If the same key + org repeats, the original result is returned without re-charging.

TDQS

A4.9/5.0
Behavior5/5

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

Discloses metered pricing (2-5 credits), pre-flight reservation of 17 credits with refund, and behavior details like auto-rotation of tensions and selling points across variants, and script modes affecting copy generation. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with main action first, then parameters, usage context, and exclusions. Every sentence adds value, though longer than minimal. Could be slightly more concise but comprehensive for complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers output format, behavior in different modes, pricing, prerequisites, and explicitly warns against using for source discovery or intel extraction. No output schema, but description compensates fully. Complete for a complex tool with 11 parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage, description adds significant meaning beyond schema: explains count auto-rotation, script_mode effects, voice_mode context, duration constraints in blueprint mode, source_id types, and powersource_id accepting job_id or brief_id. Provides implicit defaults.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it generates direct-response video ad scripts by fusing a structural source with a brand's PowerSource, and specifies the output format (hook, body, CTA, visual direction). It distinguishes itself from sibling tools like decode_ad (decodes ads) and create_powersource_* (extracts intel) by focusing on script generation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit usage scenarios ('write me a script', 'I need a TikTok script') and when not to use it (discover sources or extract intel, redirecting to decoder_intelligence or adformula_intelligence). Also explains prerequisites and guides user to create missing inputs.

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

All Heista toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A3.7/5.0
Disambiguation4/5

Despite the high tool count, most tools have distinct purposes with thorough descriptions that specify when to use each. Some overlap exists among creative direction tools (call_creative_worlds vs chat_with_creative_worlds), but the descriptions clarify usage patterns.

Naming Consistency3/5

Naming conventions are inconsistent overall: some follow verb_noun (create_powersource_url, decode_ad), others use noun_verb or compound names (adformula_intelligence, fleet_analytics_overview). However, subgroups like dispatch_* and list_*_presets maintain internal consistency.

Tool Count2/5

112 tools is far beyond the typical 3-15 range for well-scoped servers. While the server covers a broad domain, the sheer number likely overwhelms agents and suggests insufficient consolidation of related operations.

Completeness4/5

The tool set covers core creative intelligence workflows: brand analysis, ad decoding, script generation, creative direction, and research. Minor gaps exist (e.g., no social media publishing tools), but the main use cases are well-supported.

Resources