Script tools

Everything that produces or changes a script. In practice you call generate_script and then edit_script until the words are right; the other three are for reading state and for the cases where you want to be explicit.

Generation is asynchronous

generate_script returns a script_id immediately and the text arrives later. Poll with get_script, or get_generation_status if you’re tracking several things at once. Don’t call generate_script again while you wait — it’s idempotent per story and you’ll just get the same id back.

generate_script

Start generating a social-video script — either from existing reporting (an article URL, pasted text, or an uploaded document) or, with `brief`, from a story the user describes and wants written for them. Call this ONCE per story: it runs in the background and returns a script_id immediately — poll with get_generation_status and revise with edit_script. Calling it again for a story you already started returns the SAME script rather than writing a second one. Style settings omitted here fall back to the user's saved defaults. Documents uploaded in this conversation are attached automatically — you do not need to pass their URLs.

Parameter	Type	Description
source	string	Article URL or the full article text. Optional when the user uploaded a document to work from, or when you're passing a brief instead.
brief	string	Use when there is NO article and the user wants the story written for them (e.g. announcing a partnership, a product, an event). Write the brief yourself from what the user told you: what the story is, who/what it names, the angle, the audience, and anything they want it to end on. Everything factual in it must come from the user — confirm the scope with them first and never invent facts, figures, or quotes. Ignored if `source` is provided.
title	string	Optional headline for the script.
force_new	boolean	Write a second, separate script for a story this conversation already covered. Only when the user explicitly wants a fresh take from scratch — to change an existing script, use edit_script.
article_file_url	string	URL of an uploaded document (PDF/DOCX/TXT) to use as the article itself. Chat uploads are attached automatically; pass this only over MCP, or to override which upload is the primary source.
evidence_file_urls	string[]	URLs of supporting documents the writer should reference alongside the article.
duration_seconds	number	Target video length in seconds (10–600). Omit to use the user's defaults.
tone	string	Overall tone, e.g. professional, conversational, dramatic, playful.
speaking_styles	string[]	Speaking styles, e.g. unbiased, professional, educational, conversational, serious, playful, casual, dramatic.
style_description	string	Freeform description of the desired style/voice.
story_focus	string	Story focus: retelling, strengthen, or summary.
cta	string	Call to action to end the script with.
custom_instructions	string	High-priority freeform instructions injected into the script prompt.

Writing without an article

generate_script takes either a source (a URL, or pasted text) or a brief describing the story you want. With a brief there is no article at all: you supply the facts and the angle, and Editory drafts from them.

{
  "brief": "Announce our partnership with Northwind. Mention that it starts in March, and point viewers at their Instagram @northwind.",
  "duration_seconds": 45,
  "tone": "upbeat"
}

Everything in the brief is treated as fact, and the model is instructed not to invent specifics beyond it — no statistics, quotes, dates or outcomes you didn’t give it. If you want those in the script, put them in the brief.

edit_script

Ask the script-editing agent to revise a script conversationally (tone, length, structure, hook, CTA). Returns the updated script and persists it. Use for edits described in natural language; use update_script for verbatim replacement text you already have.

Parameter	Type	Description
script_id required	string
instruction required	string	The edit request, e.g. "make the hook punchier and cut it to 45 seconds".

Revisions are conversational and cumulative. Each one is kept, so a later instruction can refer back to an earlier state.

{ "script_id": "…", "instruction": "Cut the third paragraph and make the ending land harder." }

get_script

Fetch a script's status, text, and the photos scraped from its source article. Use after generate_script completes, or to review/edit an existing script.

Parameter	Type	Description
script_id required	string

update_script

Replace a script's text verbatim. Use when you (or the user) already have the exact final text; use edit_script for natural-language revisions.

Parameter	Type	Description
script_id required	string
script_text required	string

update_script replaces, edit_script revises

update_script writes exactly the text you give it, with no model in the loop. Use it when you have the final words already. For anything you’d phrase as an instruction, edit_script produces better results and leaves a history.

scrape_article

Fetch and extract an article from a URL (title, text, authors, and the photos published with it). Use to preview/confirm an article before generating a script, or to show the user what images the story comes with. generate_script scrapes internally — it keeps the same photos — so you do NOT need to call this first unless you want to show the user what was found or answer questions about the article.

Parameter	Type	Description
url required	string	The article URL to scrape.

You rarely need this — generate_script scrapes a URL itself. It’s useful when you want to read the article first and decide whether it’s worth a script, or to pull the headline and photos out for something else.