add_brand_asset
ChatGPTAttach an image to a brand kit so designs can use it. The role is the contract: a LOGO and a PRODUCT_SHOT are placed in a design as the file itself, never drawn; KEY_VISUAL and BANNER are a look to match. A logo saved as a key visual is not offered as the logo. Pass url for an image, or svg for SVG markup the human pasted into the conversation: pass it exactly as pasted, never retyped, shortened or recoloured. For a variant they asked for (a white logo for dark grounds), ask them to paste that version rather than editing the markup yourself.
add_design_image
ChatGPTPut a picture into a concept's design as a new layer, fitted whole inside box (or cropped to fill it with cover): a product shot, the logo, a brand asset, a part generated earlier, or one you send. Costs nothing. Product shots and logos are placed with this, never drawn: their files are in list_design_requests brand and get_generation_context productShots.
add_font
ChatGPTDownload a Google Fonts family (any in the catalogue; list_fonts search finds one) and install it, every weight it has from 400 to 900. Free. Only for a font the human chose or agreed to: fonts are the brand's look.
add_grain
ChatGPTFree. A fine film grain on top of every layer, in overlay. Separately generated parts and a studio pack shot carry different noise or none; one shared grain makes a composite read as one photograph. Add it last, after everything else is placed (layers added later land above it), and preview. amount 0.02-0.25, default 0.08. Not for flat graphic designs, where grain only dirties the colour.
add_inspo
ChatGPTSave a reference. Two kinds, and they are used for opposite purposes: VISUAL_TEMPLATE — a layout we may reproduce for a different product. 'This vs that', a closing-down notice, a big-type poster. Category is irrelevant; the form is the point. REQUIRES an image and honest shape and layoutNotes, because a template nobody has seen cannot be borrowed. In practice these come from screenshots pasted onto the canvas, where the vision pass classifies them automatically — use this tool for one you have genuinely looked at. COMPETITOR — what a rival is actually claiming, as positioning input. Read to find what is already said in this market so we can say something else. NOT material to borrow: copying a competitor's claim is how you write the category average. Needs no image, which is what makes ads_library_search suitable for it. DO NOT add a VISUAL_TEMPLATE from ads_library_search. That tool returns metadata only — no creative, no body text — so anything you wrote about the layout would be invented. The snapshot URL renders a page, not an image. FILTER BEFORE CALLING. Ad Library keyword matching is loose — it matches ad body text, not the product, so a search for 'Wise' returns care homes and trucking ads. Check the page name and link title before adding.
add_site_voice_samples
ChatGPTStores the words of the chosen pages, exactly as read_site_content read them, as voice samples: what the brand wrote to its readers. Pass pages, not text — the words are taken from the reading, so nothing is retyped. Only pages on the project's own website (its landing page's site) are kept. Choose pages where the brand talks in sentences (about, story, the home page, a programme or product description); never a listing, a FAQ of policies or legal text. Set audienceSegment to who the page addresses. Tell the human which pages were kept; they can mute one on the board.
add_voice_samples
ChatGPTSave the brand's own writing — an email to participants, a message to parents, a newsletter — as evidence of how it actually talks. Generation reads these grouped by who they were written to, so set audienceSegment honestly: PRIMARY for the core audience, GATEKEEPER for whoever permits or pays (parents), ADVOCATE for whoever recommends (teachers). Store only what the brand wrote. Strip the quoted thread underneath a reply, and never store anyone's email address or phone number. One message per item: a thread mixes our words with the replies. Usually the human pastes these onto the canvas; use this when they paste them into the conversation instead.
build_scene
ChatGPTPAID, from the design's budget: about 21 credits for method 'around', 5 credits for 'settle', 26 credits for 'around' with settle. The way to make a product look photographed in a place instead of pasted onto it. Place the real product first (a cut-out, straight, at the size and spot you want), then call this: - method 'around': an image model builds the whole scene around the product, so the floor, camera height, perspective and light agree with the product photo. It replaces every picture and shape under the product (returned in undo). Pass prompt: the place, the surface it stands on, what else is there (food, props), the light. Set the words first (the headline, the second level): their places are told to the model as zones to keep calm, so the scene is built with room for them. Add settle: true for the scene's light on the product (a hard sun, a dappled shadow). - method 'settle': the scene is already in the design (a generated backdrop, a photo) and the product stands on it; a model adds its contact shadow, cast shadow, reflection and light. Place it where the surface really is first. Either way the model moves and resizes the product and garbles its label, so its version is found and thrown away: the real layers are moved to where it stood and take its light. Expect the product to come back up to a quarter smaller or larger than you placed it; place it a little large. Anything stuck to the product (a blank note, a tag) goes in layerIds after it and moves with it; words stay text layers and do not move, so put them back on it after. Text layers under the product stay where they are (a headline behind it keeps its depth). Preview after, at full size.
classify_inspo
ChatGPTFill in a reference's structured fields after reading its image: a VISUAL_TEMPLATE, or a COMPETITOR whose picture a person added from the Ad Library (its hook is then the headline in the frame). The vision-pass equivalent of store_specs: pasting a screenshot saves the file and creates the row, and this is how the row gets its shape, tension and layout notes when no ANTHROPIC_API_KEY is configured and you are the model. READ THE IMAGE FIRST. Call view_image with the row's imageUrl. Everything here is a claim about a picture, and a claim about a picture you have not seen is worse than a blank row — generation reads references flat, so an invented layout note competes on equal terms with one that is true. shape and layoutNotes are the fields that matter. A concept borrows the structure, and layoutNotes is read later by someone reusing it for a different product who cannot see the image. Be concrete: 'two columns, red cross chip left, green tick right, heavy condensed caps on white' rather than 'a clean comparison'. Lead with the structure, the device the eye follows, in words any category could use (three items on one scale where the last one breaks it); then the arrangement around it (its headline box, field colour, decorations), named as that ad's own and not for borrowing. Never end with 'reproducible for any category: same chart': that line is what gets an ad cloned.
complete_imported_ad
ChatGPTYour reading of one imported ad, after looking at it: every word in the image, what it is, and the copy Meta shows around it. texts is EVERY word drawn in the image, top to bottom, exactly as drawn — headline, lines, badges, the small print, the CTA on a button — except the brand's name inside its logo. Exactly one is HEADLINE: the line the ad leads with, which becomes the hook the results are credited to. Transcribe; do not correct or translate. Your reading is saved, and its picture then waits in list_text_reads for a blind read-back (record_text_read) that code compares with these words: a human cannot approve the ad until that read is in, and a mismatch sends the ad back to waiting for copy. (Where the install has its own reader, the comparison is made at once and a mismatch saves nothing.) A video is transcribed from its frames (framesPath): every word shown on screen across them — titles, captions, subtitles — each once. A video that shows no words passes texts: [] and hook: the line it opens on, as said; the read-back then only checks that the frames really carry no words. Classify the ad as it IS, not as you would have written it: angle, hookType, tension, shape, adFormat, productMode and audience are what the rollup learns from. scene is what the picture shows, in words with no quotation marks. primaryText, headline and description are yours to write, in the brand's voice, and they must not repeat the image's words: they are read beside it. The concept then waits for a human decision like any other.
create_brand_kit
ChatGPTOnly for a project that has no brand kit: every project made here starts with an empty one, so this is refused when a kit exists (list_brands) — use update_brand_kit on it. Sets the name, tone and visual notes and attaches assets. Colours are save_palette's, fonts set_brand_fonts', and a logo is an asset with role LOGO.
create_brief
ChatGPTDefine what a batch of ads should achieve: what get_generation_context reads back and both ways of writing concepts work from. Constraints are followed literally, so put real limits here — policy restrictions, claims you cannot make, mandatory product visibility.
create_project
ChatGPTCreate a project in this workspace: one brand's board at /canvas/<slug>, with an empty brand kit. Only when the human asks for a new project. website becomes its landing page, which read_site_brand and read_site_content read by default. Then read the site and propose what to keep (see the operator's onboarding steps); nothing about the brand's look is written here. Refused when a project with the same name or website exists. Its Facebook Page, Instagram account and ad account are set by the human in the project's settings.
cut_out_image
ChatGPTCuts the subject out of a picture this workspace has — a product photographed on a table, a part generated without cutout — keeping the subject exactly as it is. This is how a real product stands in a generated scene without an image model ever redrawing it. About 1 credit, from the design's budget; a picture that is already a cut-out comes back as it is, free. Open the returned file with view_image to check the edges. placeError means it is stored and was not placed.
derive_story_version
ChatGPTReplaces the Stories and Reels version (9:16) with the feed version (4:5) as it stands now. A photograph that fills the feed frame covers this one, and what stands in it (the product, hands, their shadows) goes along at its place and size in it, so the scene needs no second build or backdrop. Words and the logo go into the safe band, about a quarter smaller. Free. Do it once the feed ad is finished, then rework the words with edit_design (size '9:16'). Anything done only at 9:16 before this is replaced.
draw_screen
ChatGPTPAID, about 5 credits, three a request at most. NATIVE_SCREEN, feed only (9:16 carries it): a real phone alone, the chat written big on its screen and read back, cut out and stood in at. Then build_scene around, settle: true, [phone, product]. Replaces fit_screen/set_chat.
dress_product
ChatGPTPAID, from the design's budget (one image-model edit). Snow settled on a shoe's toe, drops on a cold can, sand on a sandal: what makes a product look shot where it stands. The model is shown the ad (no words) and asked for that one addition; its picture is compared with the design, and only what it added on or just beside the product is kept, as a new layer over the product. The product's own layer is never touched, so deleting the new layer undoes it. Nothing is kept when the model moved, recoloured or buried the product (the answer says why; the call is still paid). Use it after build_scene, on a product already standing in its scene, and only when the scene calls for it: snow in snow, rain in rain. Ask for a little, and where: 'a light dusting of fresh snow on the toe and along the top of the laces, a few flakes on the sole'. Never words, a logo, or something that hides the product.
edit_design
ChatGPTApply a batch of operations to a concept's design, all or nothing: every operation is applied, the result is validated whole, and only then saved. A mistake comes back with every problem named, and nothing half-applied. The concept's words and hook follow the design, and a decision is withdrawn when a word changes; any other change leaves the picture out of date until finish_design. Operations: {op:'set', layerId, patch} changes a layer's fields (a property that kind of layer does not have is refused); {op:'add', layer, index?} adds a whole layer (on top unless index says where; the id is made for you if absent); {op:'remove', layerId}; {op:'move', layerId, to:'front'|'back'|index}; {op:'background', color}; {op:'rename', name}. A picture is never stretched: set to a box of another shape, it keeps its proportions and covers the box, centred, and the frame crops the rest. On an image layer, patch {recolour:'#hex'} puts a one-colour mark (the logo, an icon) in that colour: place the logo in the colour the brand's notes and the ground under it ask for, never as uploaded when that clashes. A picture of several colours is refused. Two sizes share their words: retyping a text layer, adding one or removing one in either size does the same in the other; positions, sizes and every non-text layer are each size's own. Pass size '9:16' to change the Stories and Reels version. Costs nothing. preview_design to look at the result. A design is a frame — 1080x1350 for the feed, 1080x1920 for Stories and Reels — and layers drawn bottom first. Every layer has {id, name, type, x, y} (the top-left corner of its unturned box, in frame pixels) and may have opacity (0-1), rotation (degrees, about its centre), skewX (-45 to 45, a slant about the centre, for type on a leaning surface), shadow {color, opacity, blur, x, y} (x=y=0 is a glow) and blend (normal, multiply, screen, overlay, darken, lighten, color-dodge, color-burn, hard-light, soft-light, difference, luminosity). - text: text, width (wrap width; text grows downward), fontFamily, fontWeight, fontSize, lineHeight (a multiple), charSpacing (thousandths of an em), fill '#RRGGBB', align, role, stroke + strokeWidth (an outline under the letters), marks [{text, fill?, fontWeight?, highlight?}] (words inside the line set apart: another colour or weight, or a marker colour behind them; each applies to the first place its text appears). Exactly one text layer has role HEADLINE: it is the hook. - image: src, width, height, radius (rounded corners), flipX. A src must be one a tool returned (generate_design_part, cut_out_image, add_design_image) — never invent one. - rect: width, height, fill, radius, stroke + strokeWidth, gradient. - ellipse: width, height, fill, stroke + strokeWidth, gradient. - icon: icon (tick, cross, arrow-curved, arrow-loop, arrow-straight, circle-hand, underline-hand, star, starburst, sparkle, heart), width, height, color, weight (line weight of the hand-drawn marks, 1-20, default 7). The graphic devices: ticks and crosses for a comparison, hand-drawn arrows, rings and underlines for callouts, a starburst sticker under a short word, stars for a rating. Arrows keep their own proportions in any box (drawn at the box's shorter side, centred): size an arrow with a square box and aim it with rotation, never by stretching the box. Each arrow points right in its unrotated drawing. gradient = {type:'linear'|'radial', angle (linear: 0 left-to-right, 90 top-to-bottom), stops: [{at 0-1, color, opacity}]} — a scrim under type is a rect with a linear gradient from the background colour at opacity 0 to opacity 0.8. In set, null removes an optional property (shadow: null). A text layer may use only an installed family at a weight it has (get_design fonts; the brand's faces are brandFonts).
estimate_audience
ChatGPTMeta's estimate of the monthly people an audience and goal reach, and whether Meta accepts it. Read-only, creates nothing, costs nothing. Run it on the audience you are about to propose and give the human the number with the places and ages: 'Pazardzhik, 13 to 30, about 13,000 people' is a decision they can make; a key and an age range is not. The same checks as launch_specs run first, including the special ad category of the concepts.
find_ad_locations
ChatGPTLook up the cities, regions and countries an ad can target, by name. Meta addresses a place by its key; pass the key and name to launch_specs. Search in the local spelling or in English ('Pazardzhik'), and check the region and country of what comes back: several towns share names.
finish_design
ChatGPTExports both sizes as the concept's render, which is what a human approves and launch uploads, and takes the concept off the design queue. Free. Only after you have looked at both previews and would put your name to them. Comes back with findings for both sizes (null if the checks could not run); the export is made either way. Tell the human what you built and what it cost; approving it is theirs.
fit_screen
ChatGPTFree. Fits a placed phone's, laptop's or monitor's pure #00FF00 screen (build_scene does it by itself): paints it, adds a screen layer. Then set_chat or set_terminal.
generate_design_part
ChatGPTDraws ONE picture to build a design from — a backdrop, a scene, a hand, an object, a texture, an illustration — from your own prompt, by the model you choose. It never draws the finished ad: no words, no logo and no product pack go in a part (the product is placed from its real photo, the words are text layers). cutout takes the background off, so the part can stand anywhere on the design. An ad is usually built from several: the hero scene, the carrier its words sit on, foreground pieces for depth, a backdrop. Paid out of the design's budget, which the human set: code refuses a call that would pass it, priced by the model and the size asked for, and every result says what is left. Prices, roughly: Nano Banana Pro 14 credits, GPT Image 2 31 credits, Recraft V4.1 21 credits (at 2K; Recraft at 1K is 4 credits), a cut-out 1 credit. Recraft V4.1 suits illustrations and backdrops from a plain prompt. Nano Banana Pro and GPT Image 2 read references (a style to match, or a part to change) and suit photographs of people and hands. A logo or a product shot passed as a reference is refused: those are placed, never shown to a model. Words are never wanted in a part: open it and look for stray letters yourself (textCheck PENDING means no reader ran). If you see any, regenerate with the same prompt. Open the returned file with view_image and look at it before using it. When the cut-out or the placing fails after the picture was paid for, the picture still comes back, with cutoutError or placeError saying what to do: never generate it again for that.
get_attribute_rollup
ChatGPTTHE core query: performance grouped by angle x hookType, joined from live ad metrics back through to the CreativeSpec that produced them. Cost per result (cpaUsd) is per conversion: the event each campaign optimises for, a purchase only where that is the goal. Groups below the spend and impression thresholds are excluded, because results on tiny spend are noise, and a group of fewer than three ads is never CLEAR. byBet sets experiments against core concepts, unfloored, with spend shown so thin data reads as thin. byLead sets what the ads sold on against each other (an offer, a feeling, proof…). byBet, byFormat and byLead carry no intervals or evidence level and cover every account of the project, whatever adAccountId says: read them as direction, never as a winner. Always scoped to one project (one brand): blending brands is evidence for neither.
get_batch_lift
ChatGPTOne row per brief, oldest first: spend, link CTR and CPA (per conversion) with 95% intervals, the change against the previous batch with enough data, and whether that change is distinguishable from noise. Each batch is summed over its whole life. This is the loop's own report card: later batches built on the rollup should beat earlier ones.
get_calendar
ChatGPTWhat happened on each day of a project and what is planned for it, in the project's timezone (its ad account's). Read it at the start of a session to see what is due or missed. days lists only days where something happened. Each is read from rows that already exist, nothing stored separately: spend, impressions, link clicks, purchases and conversions (the event the campaigns optimise for) from the synced Meta metrics; concepts launched, approved and rejected (with the reason); renders and their cost; concepts made; briefs, references and organic posts added; organic posts published. entries are the plans overlapping the range, each with a progress state measured against what happened. Organic: planned, scheduled, publishing, published, late (with lateByDays), failed, missed, cancelled. Flight: upcoming, due (start passed, nothing launched), partial, live, ended, missed, overran (spend after the end date), cancelled. Event: upcoming or past. A PAID_FLIGHT launches nothing by itself: the date passing does nothing, and a flight that is due needs launch_specs, with the human's yes, like any launch. Organic posts are scheduled and published only by a human on the board; one is scheduled or published only when its status here says so. Defaults to a week back and three weeks ahead; at most 62 days.
get_competitor_claims
ChatGPTEvery COMPETITOR reference: who is saying what in this market. CALL THIS AFTER DRAFTING, NEVER BEFORE. These are not material to write from — they are material to check against. Read before drafting, a competitor's claim gets absorbed exactly like a layout does, and a batch comes back sounding like the category. That is why they were removed from get_generation_context. The question to ask of them is not 'what are they saying that we could say too' but 'what is already owned, and are we accidentally standing on it'. A hook that could run under a competitor's logo has failed the substitution test, and a claim a bigger advertiser already owns is one you will lose.
get_design
ChatGPTA concept's design: every layer with its id and values, the visual idea it is built from, the budget and what has been spent, and the last export. Two sizes: layers is the 4:5 feed version (1080x1350) and story the 9:16 Stories and Reels version (1080x1920). They share their text layers and words; every other layer, and every position, is each size's own. At 9:16 words and the logo stay inside story.safeBand (y 270-1250). A design is a frame — 1080x1350 for the feed, 1080x1920 for Stories and Reels — and layers drawn bottom first. Every layer has {id, name, type, x, y} (the top-left corner of its unturned box, in frame pixels) and may have opacity (0-1), rotation (degrees, about its centre), skewX (-45 to 45, a slant about the centre, for type on a leaning surface), shadow {color, opacity, blur, x, y} (x=y=0 is a glow) and blend (normal, multiply, screen, overlay, darken, lighten, color-dodge, color-burn, hard-light, soft-light, difference, luminosity). - text: text, width (wrap width; text grows downward), fontFamily, fontWeight, fontSize, lineHeight (a multiple), charSpacing (thousandths of an em), fill '#RRGGBB', align, role, stroke + strokeWidth (an outline under the letters), marks [{text, fill?, fontWeight?, highlight?}] (words inside the line set apart: another colour or weight, or a marker colour behind them; each applies to the first place its text appears). Exactly one text layer has role HEADLINE: it is the hook. - image: src, width, height, radius (rounded corners), flipX. A src must be one a tool returned (generate_design_part, cut_out_image, add_design_image) — never invent one. - rect: width, height, fill, radius, stroke + strokeWidth, gradient. - ellipse: width, height, fill, stroke + strokeWidth, gradient. - icon: icon (tick, cross, arrow-curved, arrow-loop, arrow-straight, circle-hand, underline-hand, star, starburst, sparkle, heart), width, height, color, weight (line weight of the hand-drawn marks, 1-20, default 7). The graphic devices: ticks and crosses for a comparison, hand-drawn arrows, rings and underlines for callouts, a starburst sticker under a short word, stars for a rating. Arrows keep their own proportions in any box (drawn at the box's shorter side, centred): size an arrow with a square box and aim it with rotation, never by stretching the box. Each arrow points right in its unrotated drawing. gradient = {type:'linear'|'radial', angle (linear: 0 left-to-right, 90 top-to-bottom), stops: [{at 0-1, color, opacity}]} — a scrim under type is a rect with a linear gradient from the background colour at opacity 0 to opacity 0.8. In set, null removes an optional property (shadow: null). A text layer may use only an installed family at a weight it has (get_design fonts; the brand's faces are brandFonts).
get_generation_context
ChatGPTFetch the brief, brand kit, product shots, visual templates, organic winners, board notes, the brand's voice, the concepts a human rejected and why, the concepts already on the brief, and the attribute groups that cost less per conversion than the blend of the groups with enough data. Call this before writing a batch, write the concepts yourself, then pass them to store_specs: you can open the reference images, which generate_specs cannot.
get_playbook
ChatGPTHow to do this work well: the playbook Puncho's own operator follows, by topic. Call it with no topic before your first action in a conversation: it returns the rules (what a person decides, what costs money, how to report) and the list of topics. Then read a stage's topic before working on it: concepts and ad-copy before writing any ad, designs and ad-design before building one, launch before launching, results before reading performance. Read-only and free.
get_project_status
ChatGPTEverything set up on a project, in one reading: its landing page, what it sells, whether its Page, Instagram and ad account are set, and whether the workspace reaches Meta at all (settings.meta); the look (palettes, fonts, logo, and look.missing); brand assets by role; voice samples and the voice setup's progress; references and organic posts; concepts by status and designs waiting. Read-only and needs no brief. Use it when the human asks whether everything is in place, and report what is missing with whose job it is.
get_spec_lineage
ChatGPTFollow a CreativeSpec's parent chain and its descendants, and list the references it borrowed from: which inspo item or organic post, which project it is on, and what was taken (SHAPE, MECHANISM, VOICE, SUBJECT). Answers 'what was this a variant of', 'what came out of this concept' and 'where did its layout come from'.
get_test_verdict
ChatGPTFor a brief with a testVariable: each tested value's results, the leader, whether it is a clear winner yet, and roughly how much more spend per arm a verdict needs. Judged on cost per conversion (the event the campaign optimises for) when there are conversions, on link CTR otherwise, and never CLEAR with fewer than three ads in an arm. Null when the brief plans no test.
integrate_image
ChatGPTFree, in code, and the picture's content is never redrawn. Tones a placed picture toward the colour and brightness of the scene around it (tone 0-1, default 0.35), and gives a cut-out a contact shadow where it touches the surface plus a cast shadow falling away from light. A turned or slanted cut-out gets the cast shadow only. Do this to every product and every cut-out part you place on a scene, then preview: a product with no shadow on the table looks pasted. Re-running starts again from the original picture, so tune freely. The shadow layers (<id>-contact, <id>-ambient) can be moved or resized with edit_design when the surface is elsewhere.
lint_specs
ChatGPTCheck every string a reader would see, across specs. Catches banned terms, copy over Meta's limits, a headline block that has drifted from the hook the rollup credits, and on-image copy hiding inside a prose imagePrompt where the approval gate never sees it. Not a quality judgement — no model runs here, and a clean result does not mean the copy is good. Run it after storing a batch, with that batch's briefId, and read the findings rather than summarising them away. Same checks as pnpm specs:lint.
list_ad_accounts
ChatGPTThis workspace's ad accounts, with which is the default and which are inactive. Inactive accounts cannot deliver ads and launches into them are refused. Accounts come from the workspace's own Meta connection (an owner or admin connects it under Settings, Meta), or a platform admin assigns them.
list_brands
ChatGPTA project's brand kit with its id, palettes, fonts, assets (label and role) and briefs with their ids. Read this before create_brief, and to find a brief or an asset again. A project is one brand with one kit (the newest, if an older duplicate survives): canvas pastes, fonts and palette all use it.
list_campaign_presets
ChatGPTNamed campaign settings the human keeps on the board: places, ages, objective, goal, pixel and event, daily budget. Launch with one by passing its name as launch_specs' preset instead of asking for targeting again. eventFiredRecently: false means the pixel has not fired the conversion event lately: raise it before launching. dailyBudgetUsd is in currency, the ad account's own. Each project keeps its own.
list_campaigns
ChatGPTThe campaigns holding this project's ads, newest first: each one's id (what set_daily_budget takes), name, status, daily budget and the currency it is in (the ad account's), and its ad sets with their ids and how many ads each holds. Status and budget are as last recorded here: run sync_insights first when they may have changed in Ads Manager.
list_design_requests
ChatGPTThe design queue: concepts a human pressed "Design this" on, oldest first, each with what you need to build it — the hook and every word planned for the image, the visual idea, the human's note, the budget, the brand's palette, fonts, logo and product shots as files, and the design as it stands (a blank canvas in the brand's paper colour, holding the concept's words as text layers stacked top-left), and references: the pictures of the ads and posts the concept borrowed from, each with what was borrowed (SHAPE, MECHANISM, VOICE, SUBJECT), to open with view_image. HOW TO BUILD ONE, the way an agency does: 1. Read the visual idea and plan the composition: what goes where, what the eye hits first. A reference borrowed for its SHAPE is the layout to start from. 2. Place what is real as it is: the product shot (add_design_image; cut_out_image when it has a background and must stand in a scene), the logo (add_design_image). 3. Generate the parts that do not exist yet, one at a time, with no words in them (generate_design_part): a backdrop, a hand, a splash, a texture, an object cut out. Write each prompt like a photographer's or illustrator's brief. 4. Settle every placed product and cut-out into the scene with integrate_image (free): tone and shadows. If the preview still looks pasted, decide whether relight_product (paid) is worth it for this ad. 5. Make the type belong to the picture, never a band of text pasted on top: set words on objects generated for them with no writing (a note, a tag, a sticker, a label, a receipt, a chalkboard, a phone notification, a ribbon), turned and slanted to match the object; tuck the headline behind the product (the cut-out above the letters); point at things with generated hand-drawn marks (arrows, circles, underlines); set one word apart with marks. Never put a word in a generated picture: set it as a text layer on the object. 6. LOOK: preview_design, open each file with view_image, fix every finding, and answer every critique question honestly against the picture. Fix what fails and look again. 7. derive_story_version once the feed ad is done, then adjust the 9:16 and look again. 8. finish_design when you would put your name to it. No two ads in a batch share a layout. No headline band across the top and no product line at the foot unless the idea needs them: those are habits, not design. It exports both sizes for the human to approve. Spend only inside the budget; code refuses past it. When it runs out, finish with what you have or tell the human what more would buy.
list_finished_campaigns
ChatGPTThe campaigns a person marked finished on this project's board, newest first: the campaign's numbers (spend, link CTR and cost per result, with 95% intervals, and thin when it is below the floor where a difference says anything), each ad's numbers with its concept's typed attributes, and the debrief if one is written. One with debrief: null is waiting for one: write it with record_debrief. Money is in the ad account's currency (currency).
list_fonts
ChatGPTThe installed typefaces with their weights, the brand's heading and body choice (a new design sets its headline in the heading face and its other words in the body face), and the Google Fonts families that can be added (canAdd): with no search, the suggested ones with a note on each; with one, up to 30 families of the whole catalogue whose name matches, most used first. cyrillic: false marks a face with no Cyrillic: Cyrillic words cannot be set in it (a save is refused). Free. The installed fonts are this workspace's (shared library faces plus its own uploads) and every project in it can use them; the heading and body choice is the project's.
list_imported_ads
ChatGPTAds a human imported finished (a Figma export) that nobody has read yet. Each is a concept whose image is its render, with placeholder attributes and no copy; it cannot be approved or launched until complete_imported_ad records what it says. Open every imagePath with view_image and look at it before writing anything: the words are in the pixels and nowhere else. A video (kind 'video') is read from framesPath: nine frames across its whole length, in reading order left to right, top to bottom. You cannot hear it.
list_inspo
ChatGPTA project's references for generation: by default its VISUAL_TEMPLATE rows (layouts to borrow) and the brand's organic posts. Filter by angle or hook type to find references matching a strategy. kind: COMPETITOR lists rivals' claims instead, which are read after drafting and never before (get_competitor_claims). Muted references are excluded unless includeMuted is set — they are on the board but withheld from generation, and the count of them tells you how thin the board really is. unclassifiedTemplates is the whole worklist for classify_inspo, whatever the limit. competitorPictures says which competitor ads from the Ad Library still need a person to add their picture (waiting: name the few worth it and give their links) and which have one nobody read yet (toRead: view_image, then classify_inspo).
list_projects
ChatGPTEvery project in this workspace: one brand's board; board is its link, to give the person as it is. References, voice, notes, briefs, concepts, campaign settings and the rollup all belong to one project and are never read across projects. When there is more than one, pass project (id or slug) to the tools that list or create a brand's material, and ask the human which project they mean if they have not said.
list_revision_requests
ChatGPTSpecs a human sent to you with a change to make. Each comes with the request in their words, the current image's path (open it with view_image before deciding anything), the spec's visual, its logo placement and whether it is still shown its borrowed layout reference. A concept with a design (hasDesign) is changed as layers: get_design, edit_design, preview_design, then finish_design, which makes the new picture for free. For the others: decide whether the request changes the SPEC (a word in the image, the scene, the logo, the layout reference) or only the PICTURE. Change the spec with revise_spec first — a note that contradicts the spec loses to it. Then tell the human what changed and propose the render (EDIT with a short note for a change to the current picture, FRESH when the layout itself changes, with its price) and wait for their yes. A revision request is not consent to pay for a picture. The request clears when the new render lands.
list_specs
ChatGPTA project's concepts, newest first, one short row each: id, hook, status, brief, the typed attributes, and whether it has a design, a picture, a design request waiting and ads on Meta. Filter by brief or status: APPROVED is what launch_specs takes, LAUNCHED what is running. total counts every match, so narrow the filter or raise limit when fewer came back. The copy is not here: lint_specs returns the strings, get_design the layers.
list_text_reads
ChatGPTEvery render whose words matter is read back after it is made, because image models misdraw letters (a Latin letter in a Cyrillic word, a dropped syllable). You are the reader. Each item gives the image file and nothing about what it should say — on purpose: a reader shown the intended line reads the intended line. Look at each with view_image, transcribe it with record_text_read, and code compares your transcription with the approved copy. Check this queue after any render, at the start of a session, and before telling a human a batch is ready.
list_unlinked_meta_ads
ChatGPTAds in the ad account that were made in Ads Manager, not launched from here. Their spend is real but their results are invisible to the board and the rollup until each is linked to a concept (link_meta_ad). Read-only. The account is the one named, else the project's.
plan_calendar_entry
ChatGPTAdds a PLANNED entry. Use it to put an event or a deadline on the calendar, to plan a flight of approved concepts around one, or to plan an organic post: one concept and its caption, for a human to schedule. Planning only. It cannot schedule, publish or launch anything: a human schedules an organic post on the board, and a flight runs only once its concepts are launched with launch_specs. The caption is every word of the post outside the image, and the human scheduling it reads exactly that. It is held to the same bar as ad copy (.agents/skills/ad-copy) and written in the brand's voice (get_generation_context): no filler, no banned register.
preview_design
ChatGPTDraws the design exactly as the export will and writes it to a PNG. Free, and records nothing: it is stepping back from the screen. Comes back with findings (what code can measure: text that will not read against what is behind it, text too small, text outside the 9:16 safe band, cut-outs standing on nothing, words that collide or almost touch, uneven spacing in a stack, loose leading, a stranded last word, sizes too close to lead, pictures shown bigger than their pixels, colours from neither the pack nor the brand, a layout the batch already has, a habit the whole batch shares, a second ad with arrows or rings) and critique (what only your eye can answer). Open each file with view_image, fix every finding, answer every critique question honestly against the picture, change what fails, and look again. Both sizes unless one is asked for.
product_colours
ChatGPTThe main colours of a pack or product photo, with their share, and a suggested signature (the field it reads best on), ink (its darkest) and paper (its lightest). Free. Build the ad's ground and type from these: the strongest food ads extend the pack into the frame, so the product cannot look pasted on it. Previews flag flat colours that come from neither the pack nor the brand palette.
read_site_brand
ChatGPTReads a website and proposes a colour scheme (accent, ink, paper, optional secondary), heading and body fonts matched to the Google Fonts catalogue, and logo candidates. WRITES NOTHING. Defaults to the project's landing page. Show the human what it found — the site's title and address first, so they can say whether it is the brand's site at all (mentionsProject false is a reason to ask) — then ask which colours, fonts and logo to keep. Never apply without that answer.
read_site_content
ChatGPTReads the home page and a few of the site's key pages (about, shop, product pages) and returns: images, key-visual candidates with their size; products from the store's structured data, with name, price, page, description and photo; and copy, each page's own words (an excerpt; the full text is kept for add_site_voice_samples). WRITES NOTHING. Defaults to the project's landing page. Look at every candidate you might propose with view_site_image first: drop stock-looking filler, people's faces the brand may not have rights to use in ads, sponsors' material and duplicates. Then propose, with read_site_brand's result, in one message, and apply only what the human keeps.
record_debrief
ChatGPTWhat a finished campaign came to: a verdict, a summary of what happened and why, and its lessons. Read list_finished_campaigns first and work from its numbers; a person marks a campaign finished, and an unfinished one is refused. Lessons reach every later batch at once through get_generation_context lessons, labelled as yours, and a person can edit or mute them on the board. So each lesson is one specific thing the numbers show, with the number: 'SOCIAL_PROOF hooks cost 40% less per sign-up than CURIOSITY_GAP ones (31 vs 52 results)', not 'proof works'. Tag what it is about (angle, hookType, shape, tension, audienceSegment, adFormat, productMode, lead, or the specId of one ad) so it joins to the concepts it speaks of. Say TOO_LITTLE_DATA when the numbers are thin, and make its lessons TRY, not KEEP or STOP: a thin campaign proves nothing. Calling again replaces the verdict and summary and adds lessons; it never removes one, so what a person wrote or muted stays, and one a person deleted is not added back. A lesson already there word for word is skipped.
record_decision
ChatGPTWhen the human states something that should hold for every future batch, in conversation — a word that is allowed or banned, a kind of line they never want, a fact they confirmed — record it here at once, in their own words, and tell them. It becomes a note in the project's Voice frame, marked as from chat, which every batch reads in get_generation_context notes and which outranks the brief and the copy rules. Before this, a decision lived only in the conversation that heard it and the next session made the same mistake. Only decisions the human actually made. Never your own conclusions, never a one-off choice for this batch (which ideas to build). The human can edit or mute the note on the board.
record_text_read
ChatGPTYour blind transcription of one render from list_text_reads. How to read: Transcribe every piece of text visible in this image, exactly as it is drawn, letter by letter. Do not correct spelling. Do not guess what a word was meant to be. Do not translate. If a letter is malformed, write the letter it most looks like — including a Latin letter in a Cyrillic word, if that is what is drawn. Include text in logos, badges, captions and interface elements. Output one text block per line, in reading order, and nothing else. If there is no text, output nothing. For a video (a contact sheet of nine frames), write each distinct line once, however many frames show it. Transcribe what is DRAWN, not what you know the ad says: if a word is misspelled in the picture, write the misspelling. The comparison with the copy is made in code and returned: MATCH, or MISMATCH with each line that differs. UNCHECKED means nothing was compared: the concept has a newer picture (read that one), or no copy yet.
relight_product
ChatGPTPAID, from the design's budget (about 14 credits with Nano Banana Pro). An image model is shown the picture (no words) and makes the product belong: its shadow on the surface, the scene's light falling on it, reflections. Everything it painted around the product is kept; inside the product's outline its version is thrown away and the real pixels go back, colour-matched to the new light. So the label and pack are always the real ones. YOU DECIDE when it is worth it. Use integrate_image first, always. Reach for this only when the preview still looks pasted: a strong directional light the product does not share, a glossy or wet surface that should reflect it, the product held or half-hidden by something, or a hero shot where realism carries the ad. Not for a flat graphic layout, a product on a plain field, or one already convincing. Say in your report which you relit and why. Needs a straight (unrotated) cut-out. Refused, before anything is paid, when words, the logo or another product shot lie under the product inside the area the model repaints: move them out first. The product layer becomes the relit area; undo returns the layers it replaced, to put back with edit_design if the result is worse. placeError means the relit picture is stored and was not put into the design.
revise_spec
ChatGPTChange what a spec says the image should be: the scene, the words in the image, the attached assets, the colours, where the real logo is stamped, and whether fresh renders are shown the reference the layout was borrowed from. Use it whenever a human asks for a change the spec contradicts. A render note alone loses: 'remove the course line' cannot win while that line is in texts, 'remove the logo' cannot win while logoPlacement puts it there, and 'no arrows' cannot win while the reference with five callouts is attached — set useLayoutReference false for that. A concept with a design is changed as layers: words, layout and pictures with edit_design and generate_design_part. Here it takes only request and visualIdea; anything else is refused and says where it goes. An idea not yet designed takes texts and visualIdea. texts replaces the whole list; send every line that should remain. The HEADLINE stays the hook: a new hook is a new concept (store_specs with parentId). Changing texts puts the current picture back in list_text_reads, and it is refused for an imported ad, whose words are its pixels (complete_imported_ad). Withdraws any approval, since the current picture no longer matches. Returns copy-lint findings.
set_brief_leads
ChatGPTRecords what a brief's campaign sells on, one or more leads, after the person chose them: OFFER (a real deal or the price as the argument), FEELING (a moment, a mood, who you are with it), PROOF (reviews, numbers, press), PRODUCT (how it is made, what it does), PROBLEM (the pain it removes), NEW (a launch, a season). Concepts then each lead with one of them, and only OFFER puts a price on the image. Replaces what the brief had. Ask the person first and suggest from the goal: what a campaign sells on is their call.
set_chat
ChatGPTFree. Lays a messenger out on the fitted phone screen in code, both sizes. Never build a chat by hand.
set_reference_active
ChatGPTStop a reference reaching generation, or bring it back. Muting keeps the row — deleting it would lose the record that we looked at it and decided against it, which is how the same weak reference gets pasted back in three months later. Mute a reference that is off-category, weak, or whose format we cannot actually execute. References are offered to generation flat and equally weighted, so a dead one competes with the good ones and skews the batch. Muting is curation, not a verdict on the ad — always give a reason, because the next person to see the row needs to know whether to trust the decision. VOICE mutes a sample of the brand's writing — a real email that is still the wrong register for ads, like a formal one to a sponsor.
set_spec_attributes
ChatGPTFix the dimensions the rollup groups by on an existing spec — tension, angle, hookType, audience, special ad category. For correcting an honest mislabel, or backfilling a dimension added after the spec was written. This edits the record of what a concept IS, so only ever move a value toward what the copy actually does. A label chosen to make a result look better is not a correction, and the rollup has no way to tell the difference. Copy is NOT editable here. Rewriting a hook is a new concept — use store_specs with parentId so the lineage survives. The audience segment and the special ad category are what a human approved the concept under: changing either on an approved concept sends it back for their decision, and on a concept with ads on Meta it is refused.
set_terminal
ChatGPTFree. Lays a terminal out on the fitted screen of a laptop or monitor, both sizes. Any developer's screen; never draw screen text or set it by hand. Short lines (~30 characters); the ad's point in one accent line.
set_type
ChatGPTThe last step before previewing: lays out every word and the logo in a layout (the ad-design skill's Type layouts), at both sizes. accent: headline words set apart (face: the brand's accent face). The headline follows the brand's type style. labels: words over things in the picture. GIANT_WORD cuts the product out (about 2 credits) to stand in front of the word. Refused when it does not fit.
store_specs
ChatGPTPersist CreativeSpecs you wrote yourself (after get_generation_context) as DRAFT. Identical rows to what generate_specs produces, so rendering, approval, launch and the attribute rollup all work the same. Set parentId when a concept is a variant of an existing spec — lineage is what makes 'more like the winners' meaningful later. Two fields carry the audit trail: sources says which references the concept borrowed from and what it took, and rationale says what it is betting on. A concept citing nothing is one written from the category average. The returned warnings read every live concept on the brief, not this call alone. These are ideas, not ads yet: nothing is drawn. Each carries its art direction in visualIdea and EVERY WORD THAT WILL APPEAR ON THE IMAGE in texts — headline, captions, badges, small print — with exactly one HEADLINE, which is the hook. A human picks the ideas worth designing on the board (Design this, with a budget), and they arrive in list_design_requests to be assembled from parts. The look need not be set to store ideas.
suggest_product_draw
ChatGPTWhen the idea wants the product worn, held or in use, which a photo of the empty product cannot show, suggest that the model draw it from the product's photos (build_scene method worn). It decides nothing: the board shows your reason beside an Allow button on the concept, and only a person's Allow lets it be drawn. Say why the idea needs it and how many photos of the product there are (its file and angles in list_design_requests); fewer angles may differ more at the toe or the back, so say so, and suggest it anyway when the idea needs it. Free.
sync_ad_accounts
ChatGPTRefresh ad accounts from Meta and list the ones this workspace has. Run it after a new account was assigned in Business Settings. When the workspace has its own Meta connection (Settings, Meta), an account that connection reaches and this install has never seen becomes the workspace's, and the first becomes its default. From a chat app connected by sign-in it adds nothing and only reports them in notAdded: a person adds them with "List accounts and Pages again" under Settings, Meta. needsPlatformAdmin names accounts it reaches that are already known here and assigned to nobody: a platform admin assigns those. alreadyInUse counts the ones another workspace here already has, which are left where they are. Tell the human about all three. Without its own connection it assigns nothing: a newly reachable account waits, unassigned, until a platform admin gives it to a workspace, and waitingForAssignment says how many are waiting. Safe to re-run.
sync_insights
ChatGPTFetch per-ad daily metrics and store them against our ads. Re-syncs a trailing window because Meta's numbers keep moving for ~72h as conversions attribute. accounts has one entry each with the days it was asked for (since, until, in its own timezone); statusError on one means its metrics were written and its statuses could not be read.
sync_pixels
ChatGPTRead the ad account's Meta pixels and what each fired in the last seven days, and store them. Read-only on Meta. Run it before choosing a conversion goal: a pixel that has not fired the event gives Meta nothing to optimise on — say so, and suggest OUTCOME_TRAFFIC with LANDING_PAGE_VIEWS instead. The human never needs to paste a pixel id.
update_brand_kit
ChatGPTChange the name, tone notes or visual notes of an existing kit. Every field is optional; omitted fields are left alone. The look has its own tools: colours are save_palette (or apply_site_brand from the brand's website), fonts set_brand_fonts, and the logo add_brand_asset with role LOGO.
update_calendar_entry
ChatGPTEdits a calendar entry: pass only the fields to change. specIds replaces the whole list. cancel marks it CANCELLED and keeps it on the calendar as a record. Refused for an organic post a human has scheduled, or one going out or gone out: a human approved that exact post. Ask them to unschedule it on the board first. The caption is held to the ad-copy bar and the brand's voice, as in plan_calendar_entry.
view_image
ChatGPTReturns the picture behind a path or URL another tool gave you: an inspo imageUrl, an organic mediaUrl, a render's imageUrl or currentImage, a design picture's file, an export, an imported ad's imagePath, storyImagePath or framesPath (a video's contact sheet). Pass the value exactly as returned. Only images this server stored can be opened. Large images are scaled down; raise maxSide to read small text.
view_site_image
ChatGPTReturns the picture at a ref from read_site_content (an image or a product's photo) or a logo candidate's address from read_site_brand, scaled down. Public addresses only. Nothing is stored: the image becomes a Brand asset only through apply_site_brand.