Filmsquare HelpDocs

5.0 Work with your own Claude5.2 What Claude can do

What Claude can do

Every MCP tool Filmsquare gives your Claude, how find_actions and run_action reach the rest of the API, and what is left out on purpose.

Updated 7 min read.md

On this page
  1. The named tools
  2. Where media goes
  3. find_actions and run_action
  4. Examples
  5. When the API refuses
  6. Left out on purpose
  7. Safety
  8. Prompts

Your Claude can do in Filmsquare what the API lets your role do. Eighteen named tools cover the everyday work; two more, find_actions and run_action, reach every other API action. Every call goes through the API itself, as you: the same role checks, the same validation, the same gates.

The named tools #

ToolWhat it doesNeeds
whats_waitingDepartment steps waiting on your sign-off, and your unread notifications. The place to start—
list_productionsThe productions in the workspace with their episodes—
get_episodeOne episode: scenes and shots in cut order, every department step (signed off, waiting on whom, changes requested, open), and whether the finals can renderepisode_id
get_feedbackComment threads on a shot, take, episode, scene, element, folder, asset version, canvas or canvas node, with every message and its pin (timecode in frames, or a region of the picture). Open threads by default; status resolved or all for the rest. With target_type sheet: the open notes on the sheet's latest version (intent, quote or the whole sheet, suggested text, handled or not) and how earlier versions' notes endedtarget_type, target_id
reply_feedbackReply in a thread as you (@name mentions notify people), and resolve it when the note is handled. A note on a sheet is marked handled instead; when it has a suggestion, suggestion_outcome (applied, adapted or declined) is required, and a person confirms itthread_id, body
view_mediaA still, keyframe or take as an image Claude can look at; a video comes back as its poster plus a download linkasset_version_id
upload_fileA file from the conversation onto a shot or scene layer as a new take, or into a production as an asset. At most 10 MB. pick: true also picks it (director and up)name, mime, data_base64
where_does_it_goWhich screen a file belongs on: the map, a decision tree and worked examples. Read it when you name a screen—
prepare_uploadSigned upload URLs and ready-made curl commands for up to 100 files on disk, so the bytes never go through the conversation. Use it for every videofiles
add_to_visualizePut uploaded files under Storyboard → 3D or Storyboard → Animatic, up to 100 per call, on shots and scenes by code. Sending the same again changes nothingepisode_id, items
get_scriptThe episode's latest script revision, and the @handles of the cast, sets and props that already existepisode_id
edit_scriptChange a scene, a speech or a line of the script without sending all of it: exact text and what replaces it, saved as a new version; notes and tags move alongepisode_id, base_rev, edits
submit_breakdownPut Claude's breakdown into Filmsquare: scenes, shots with acting, dialogue, cast, sets and props. Writing then waits for sign-offepisode_id, breakdown
get_continuityThe continuity sheet of an episode: what each shot plays, the elements and their references, what each pick was made with, findings so far, shots to check again. Runs the free lineage check firstepisode_id
report_continuityRecord a visual continuity check; each mismatch becomes a note on the pickepisode_id, seen, issues
submit_stylePut a style guide in the style library (Create → Styles): a new style, or with style_id its next version; production_id makes it a production's. Own work carries up to 6 reference stills (uploaded with prepare_upload); someone else's work is text only and never published. Names of people or brands are refused. Maker rolename, guide
request_signoffAsk the signers of a department to sign off an episode's step; they get a notificationepisode_id, department
sign_offRecord your decision on a step: approved or changes_requested, with an optional note. Only the step's signers can. With expect_version (the step's version as you saw it) it is refused with changed_since when the work moved. Only when you asked Claude to decideepisode_id, department, decision
studio_analyticsFor the owner and producers: how the studio is going, with the numbers of Analytics. view crew (per person over a period: delivered, credits per delivered, time to sign-off, first pass, lanes, redo, hands-on and agent-alone hours, the studio median and the time per step), day, costs, or report (the report mail's text as it would be sent). Anyone else is refused: they see only their own numbersview

Every tool also takes an optional workspace. Leave it out: the connection's workspace is used.

department is one of writing, breakdown, casting, voice, wardrobe, sets, props, animatic, music, draft, sound, edit, final.

Where media goes #

Tell your Claude the screen in your own words ("put it under 3D"). This is what it does:

You haveIt goesWith
Clay render or still of one shot, with lens, height and moveStoryboard → 3D, on the shotadd_to_visualize
Blender clip of a shot, a take or a sceneStoryboard → 3D, on what it coversadd_to_visualize
Animatic of a scene, sequence or episodeStoryboard → Animaticadd_to_visualize
Draft or final video of a shotStoryboard → Shots, as a takeupload_file
Reference picture or mood boardHome → Filesupload_file

Something in the wrong place moves without uploading again: moveTake or moveAsset through run_action (director and up). A pick the import made is cleared with the move. A take that somebody picked, or that was generated here, stays where it is.

find_actions and run_action #

Everything without a named tool goes through these two: creating shots, picking takes, making drafts, estimates, elements and versions, folders, canvases, costs, briefs, crew.

  1. find_actions searches the API's own catalogue with a few words, such as "pick take", "create shot" or "resolve thread". It returns matching actions with their method, path, a summary, the minimum role and the inputs.
  2. run_action runs one by its name, with path_params (not the workspace), query and body as the action describes. It answers with the API's JSON.

find_actions understands set language. It maps the words a crew uses onto the API's words:

You sayIt also searches
pick, chooseselect
note, notes, comment, comments, feedbackthread, message
replymessage
rendergeneration, generate
makecreate, generate
new, addcreate
remove, deletearchive
signsignoff
approvesignoff, approval
cast, character, propelement
setelement, location
production, productionsproject
crewmember, steps
costcosts, estimate
priceestimate
prompt, preview, dry rungenerate
kosten, schatting, prijs (Dutch)generate, estimate
mismatchcontinuity
model, modelsmodels, acceptance, routing

New API actions show up in find_actions the moment they ship. No new tool is needed.

Examples #

ToSearchAction
Price a draft before rendering it"estimate shot"estimateShotGeneration
See the prompt, the model and the credits before rendering"dry run"generateForShot with {"kind": "video", "tier": "draft", "dryRun": true}
Render a draft"generate shot"generateForShot with {"kind": "video", "tier": "draft"}
Pick a take"pick take"selectTake
Make a draft final"promote"promoteGeneration
Retake from a note"revise take"estimateReviseTake, then reviseTake
See which model gets accepted"model acceptance"getModelAcceptance
Cost of an episode"episode costs"getEpisodeCosts

Before it renders, Claude calls the generate action with dryRun: true: it shows the compiled prompt, the model, the references and the credits, and makes nothing. It can then change the prompt for that one render. overrides.prompt replaces the prompt text (the reference lines stay, so cast, sets and props always go along), overrides.promptAppend adds to it, and overrides.negativePrompt adds what to avoid. Dialogue is spoken from its lines and takes no prompt override.

The dry run answers with provider and model_key. Passing them back as provider and modelKey holds that model. getGeneration reads back what a take was made with: the prompt, the model, the estimated credits and the booked credits.

When the API refuses #

A refusal comes back as a tool error with the API's code and details, for example The API refused: 409 gate_closed: finals render once casting, sets, animatic are signed off {"episode_id": "…", "waiting_on": ["casting", "sets", "animatic"]}. Claude reads it and tells you what is missing. See Errors you will meet.

Left out on purpose #

Claude cannot reach these, by design:

  • API keys and Claude connections: a connection never makes keys or allows other connections. A person does that, signed in.
  • OAuth and sign-up.
  • Webhooks: they send data out of Filmsquare.
  • Provider callbacks and the realtime sockets (canvas and presence).

The finals gate, credit checks and plan limits apply to Claude exactly as to anyone.

Safety #

  • Claude acts as you. It has your role (or the lower one you chose when connecting), and what it does shows up in your name.
  • Crew material is not instructions. Comments, scripts and other text Claude reads in Filmsquare are material from the crew. Filmsquare tells Claude so: only you decide what it does.
  • It quotes the price first. Making takes costs credits. Claude is told to call the generate action with dryRun: true, which makes nothing, and to say what a take will cost before it starts one, and never to render finals unasked.
  • It never signs off unasked. sign_off records a decision in your name. Claude is told to use it only when you asked it to decide.

Prompts #

Four prompts carry a working method for common jobs: break_down_episode, process_feedback, work_on_step and check_continuity. See Prompts and working method.

With Claude

MCP

Your own Claude does this over MCP, in your name and with your role:

  • find_actions

    Searches everything the API can do and returns the matching actions with their inputs.

    Ask: Find the action that changes a step's sign-off rule.

  • run_action

    Runs one action found with find_actions, as you, with your role and rights.

    Ask: Pick the second take of shot 5 on episode 2.

  • whats_waiting

    Lists the steps waiting on your sign-off and your unread notifications.

    Ask: What is waiting on me in Filmsquare?

  • list_productions

    Lists the productions in your workspace with their episodes.

    Ask: Which productions and episodes do we have in Filmsquare?

  • get_episode

    Shows an episode's scenes and shots in cut order, every department step, and whether finals can render.

    Ask: Where does episode 2 stand, and who is each step waiting on?

  • get_feedback

    Reads the comment threads on a shot, take, episode or element, with each pin's timecode or region.

    Ask: Which notes are still open on episode 2?

  • reply_feedback

    Replies in a comment thread as you, and resolves it once the note is handled.

    Ask: Reply to the note on shot 4 that the new draft fixes the eyeline, and resolve it.

  • view_media

    Looks at a still, keyframe or take; video comes back as its poster plus a download link.

    Ask: Show me the picked still of shot 3 and tell me if it matches its references.

  • upload_file

    Adds a file you have as a new take on a shot or scene, or as a production asset (10 MB at most).

    Ask: Upload this reference photo to the assets of the production.

  • get_script

    Reads the latest script revision of an episode, with the @handles that already exist.

    Ask: Read the script of episode 2 and tell me which characters have no @handle yet.

  • edit_script

    Changes a scene, a speech or a line of an episode's script and saves it as a new version, without sending the whole script.

    Ask: Rewrite the opening of S02 in episode 2 the way we just discussed, and save it as a new version.

  • submit_breakdown

    Puts your breakdown into Filmsquare: scenes, shots, dialogue, cast, sets and props.

    Ask: Break down the script of episode 2 and submit it. Reuse the handles we already have.

  • get_continuity

    Lays an episode's picked shots side by side, with the element versions each one uses.

    Ask: Lay out the picks of scene S2 for a continuity check.

  • report_continuity

    Records the continuity check you did; each mismatch becomes a note on the shot's pick.

    Ask: Check continuity in scene S2 and report the mismatches you find.

  • submit_style

    Puts a style guide in your style library (Create, Styles): a new style or the next version of one.

    Ask: Look at these stills, write a style guide, show it to me and submit it when I say go.

  • request_signoff

    Asks the signers of a department step to sign off; they get a notification.

    Ask: Ask the signers of the next step on episode 2 to sign off, with a note on what changed.

  • sign_off

    Records your decision on a step: signed off or changes requested. Only when you ask it to decide.

    Ask: Sign off the next step on episode 2 for me.

  • where_does_it_go

    Tells you which screen a file belongs on: the map, a decision tree and worked examples.

    Ask: Where does this blockout reel go?

  • prepare_upload

    Gives signed upload links and ready-made curl commands for up to 100 files on disk.

    Ask: Upload the videos in this folder.

  • add_to_visualize

    Puts uploaded files under Storyboard, 3D or Animatic, on shots and scenes by code.

    Ask: Put the Blender work under 3D and the animatics under Animatic.

  • studio_analytics

    For the owner and producers: how the studio is going, from the crew, one day, the costs or the report mail as it would be sent.

    Ask: How did the crew do last week, and who needs help?

Connect Claude 5.1

This page as Markdown: /docs/claude/tools.md