Narracore Screenplay Formatter

Analysis topology from cuts

plan_film_analysis

Read-onlyIdempotent

FREE deterministic. Turn shot-cut timestamps into the analysis topology every Film Protocol agent shares: numbered base shots (shot-000001), long-take windowing (shot-000017-w01of03 when a shot exceeds the profile cap), and greedy analysis units (≤20s / ≤8 shots per unit by default). Pass duration_sec + the cut timestamps you detected locally (e.g. ffmpeg scene filter, threshold 0.30 — see get_film_contract section="media_recipe"); you get back windows and units carrying both source-relative and clip-relative times to cut your analysis clips and label your observations with. No ffmpeg commands are returned (execution is your platform's business). 免费：切镜时间点 → 统一分析拓扑（长镜开窗 + ≤20s/≤8 镜单元）。

Input Schema

TableJSON Schema

Name	Required	Description	Default
`duration_sec`	Yes	Total duration of the film/video in seconds
`cut_timestamps`	Yes	Shot-cut timestamps in seconds (ascending; 0 and duration are implied)

Output Schema

TableJSON Schema

Name	Required	Description	Default
`ok`	Yes
`tool`	No
`state`	No
`reason`	No
`message`	No
`recovery`	No
`topology`	No
`conflicts`	No
`windowing`	No
`request_id`	No
`diagnostics`	No
`contract_version`	No
`analysis_profile_version`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 5, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "analysis_profile_version": {
+      "type": "string"
+    },
+    "conflicts": {},
+    "contract_version": {
+      "type": "string"
+    },
+    "diagnostics": {
+      "items": {
+        "additionalProperties": {},
+        "properties": {
+          "block_id": {
+            "type": "string"
+          },
+          "code": {
+            "type": "string"
+          },
+          "line": {
+            "type": "number"
+          },
+          "message": {
+            "type": "string"
+          },
+          "severity": {
+            "type": "string"
+          },
+          "suggested_action": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "code",
+          "severity",
+          "message"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "message": {
+      "type": "string"
+    },
+    "ok": {
+      "type": "boolean"
+    },
+    "reason": {
+      "type": "string"
+    },
+    "recovery": {
+      "additionalProperties": false,
+      "properties": {
+        "action": {
+          "type": "string"
+        },
+        "field_path": {
+          "type": "string"
+        },
+        "keep_request_id": {
+          "type": "boolean"
+        },
+        "note": {
+          "type": "string"
+        },
+        "resets_at_utc": {
+          "type": "string"
+        },
+        "retry_after_ms": {
+          "type": "number"
+        },
+        "retryable": {
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "action",
+        "retryable",
+        "keep_request_id"
+      ],
+      "type": "object"
+    },
+    "request_id": {
+      "type": "string"
+    },
+    "state": {},
+    "tool": {
+      "const": "plan_film_analysis",
+      "type": "string"
+    },
+    "topology": {},
+    "windowing": {}
+  },
+  "required": [
+    "ok"
+  ],
+  "type": "object"
+}

AddedSep 17, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already cover readOnly/idempotent/non-destructive, and the description adds genuinely new context: FREE, deterministic, no execution returned, and that outputs carry both source-relative and clip-relative times. The windowing rule for over-cap shots (shot-000017-w01of03) is disclosed rather than hidden. Missing only error/limit behavior for the 4000-item cap.

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?

Front-loaded with the core transformation, then inputs, then outputs, in a logical order with no filler. The appended Chinese restatement duplicates content already stated and is the only notable waste.

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?

With an output schema present, return values need not be explained, yet the description still summarizes them. Inputs, defaults, derivation guidance, and the cross-reference to get_film_contract are all covered, so an agent can invoke this correctly without further exploration.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value: how to obtain cut timestamps (ffmpeg scene filter, threshold 0.30), the implied 0/duration endpoints, and the default unit caps (≤20s / ≤8 shots) that govern how the two inputs are interpreted.

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?

States a precise verb+resource: transform cut timestamps into a shared 'analysis topology' of numbered base shots, long-take windows, and greedy analysis units. The scope (no ffmpeg execution, deterministic) and the sibling-adjacent contract pointer make it distinguishable from tools like analyze_screenplay or compile_film_breakdown.

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?

Explicitly says what to pass (duration_sec + locally detected cut timestamps) and where to find the detection recipe (get_film_contract section="media_recipe"). It also clarifies what it is not (no ffmpeg commands returned). No explicit 'do not use when' exclusion, so it stops short of a 5.

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

All Narracore Screenplay Formatter 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.