Siren

list_films

Read-onlyIdempotent

The film library, one ranked page at a time. Films sit on job shelves; pass job and the human's goal and hire from the top of the page. Each film says what it is, when to hire it, its length and shapes, fits_this_brand (with what is missing) and made_recently (this brand already got it: prefer another film on the shelf unless the human asked for that one). Page on with next_page. Want it all at once? all=true, or fetch the catalog file (https://api.mysiren.ai/api/v1/films.md, every film by shelf, also .txt/.json) and read it in steps. search= finds films by word. Then describe_film for the body. Videos are on every plan; credits are the only limit. Every film here is 25 credits. Platinum films (50 credits) are not in these pages: the answer's platinum section flags them, and list_platinum_films has the shelf.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`all`	No	true = every film that passes the filters on one page (about 10k tokens for the whole library). Prefer job + page, or the catalog.md file.
`job`	No	The shelf: launch, feature (one feature or update), explain (what the product does), brand (story, manifesto, mood), ai (AI or agent product), proof (a number, testimonials), app (mobile app), shop (products, food, property), people (team or mascot). Omit to rank the whole library.
`goal`	No	The human's own words for the outcome, e.g. "launch video for our new AI agent" or "show our 10k users". Ranks the films by fit.
`page`	No	Page number, from 1. Each page is page_size films; next_page in the answer says what to call next.
`aspect`	No	Only films that render this shape: wide-desktop, square-ig, story-reel, vertical-ig-feed.
`detail`	No	"short" (default) or "full" to add the long description per film.	short
`search`	No	Find films by word across ids, names and descriptions, e.g. "phone", "chat", "mascot", "halftone". Every word must match.
`narrated`	No	true = only films with a voice-over part; false = only music-and-motion films.
`for_brand`	No	The brand name you will pass in create_campaign brand_override, when the video is for a brand other than this workspace. fits_this_brand then judges that brand (no mascot, people or screens of this workspace).
`page_size`	No	Films per page, 1 to 25.
`max_seconds`	No	Only films this long or shorter, e.g. 15 for a short feed post.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 13, 2026

addedInput schema / properties / for_brand

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "The brand name you will pass in create_campaign brand_override, when the video is for a brand other than this workspace. fits_this_brand then judges that brand (no mascot, people or screens of this workspace)."
+}

Changed10 schema fields changedSep 24, 2026

addedInput schema / properties / all

Added value: +{
+  "default": false,
+  "description": "true = every film that passes the filters on one page (about 10k tokens for the whole library). Prefer job + page, or the catalog.md file.",
+  "type": "boolean"
+}

addedInput schema / properties / aspect

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Only films that render this shape: wide-desktop, square-ig, story-reel, vertical-ig-feed."
+}

addedInput schema / properties / detail

Added value: +{
+  "default": "short",
+  "description": "\"short\" (default) or \"full\" to add the long description per film.",
+  "type": "string"
+}

changedInput schema / properties / goal / description

Previous value: -"Optional: the human's own words for the outcome, e.g. \"tell our story\" or \"launch a feature\". Reorders the catalog by fit."New value: +"The human's own words for the outcome, e.g. \"launch video for our new AI agent\" or \"show our 10k users\". Ranks the films by fit."

addedInput schema / properties / job

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "The shelf: launch, feature (one feature or update), explain (what the product does), brand (story, manifesto, mood), ai (AI or agent product), proof (a number, testimonials), app (mobile app), shop (products, food, property), people (team or mascot). Omit to rank the whole library."
+}

addedInput schema / properties / max_seconds

Added value: +{
+  "anyOf": [
+    {
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Only films this long or shorter, e.g. 15 for a short feed post."
+}

addedInput schema / properties / narrated

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "true = only films with a voice-over part; false = only music-and-motion films."
+}

addedInput schema / properties / page

Added value: +{
+  "default": 1,
+  "description": "Page number, from 1. Each page is page_size films; next_page in the answer says what to call next.",
+  "type": "integer"
+}

addedInput schema / properties / page_size

Added value: +{
+  "default": 8,
+  "description": "Films per page, 1 to 25.",
+  "type": "integer"
+}

addedInput schema / properties / search

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Find films by word across ids, names and descriptions, e.g. \"phone\", \"chat\", \"mascot\", \"halftone\". Every word must match."
+}

AddedSep 17, 2026

TDQS

A3.8/5.0

Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description nonetheless adds substantive context beyond them — credit economics ('Every film here is 25 credits', platinum at 50), that videos are on every plan with credits as the only limit, and the semantics of fits_this_brand and made_recently. This is useful operational context an agent could not infer from the annotations.

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

Conciseness3/5

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

The content is dense and mostly earns its place, but it is written in a chatty, metaphor-heavy register ('hire from the top of the page', 'Films sit on job shelves') and front-loads a poetic fragment rather than the action. The catalog URL and file-format details add length that could be trimmed without losing essential guidance.

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

Completeness4/5

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

With an output schema present, return values need not be explained, and the description focuses correctly on ranking, filtering, paging, cost, and sibling routing. For an 11-parameter read tool this is largely complete, though a couple of filters (narrated, aspect, for_brand) are left entirely to the schema.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents all 11 parameters, establishing a baseline of 3. The description adds some framing (job + goal ranking, search by word, paging via next_page) but does not extend meaning for parameters like aspect, detail, narrated, for_brand, or max_seconds beyond what the schema states.

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

Purpose4/5

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

The description establishes that this returns the film library as a ranked, paginated list and explicitly carves out platinum films ('Platinum films (50 credits) are not in these pages... list_platinum_films has the shelf'), which differentiates it from the closest sibling. The verb is implied rather than stated ('The film library, one ranked page at a time'), so it is clear but stylistically indirect.

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

Usage Guidelines4/5

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

It gives concrete usage: pass job and the human's goal, hire from the top of the page, page with next_page, use search= for keyword lookup, and fetch the catalog file or all=true for the full set. It routes to describe_film for the body and to list_platinum_films for platinum content. It lacks an explicit 'when not to use' framing, but the alternatives are named.

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

All Siren tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.