Narracore Screenplay Formatter

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

Goes well beyond the annotations by disclosing the cost model (1 credit per story project per 24h), that validation failures are never charged, that repeats of an absorbed window are free no-ops, and that the client is responsible for hash-verifying the patch. It does not describe what canon state is actually mutated (supersede/archive effects live only in the schema). The 'repeats are free no-ops' phrasing sits in mild tension with idempotentHint=false, but this reads as a specific carve-out rather than a direct contradiction.

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

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

The English text is front-loaded with the charging rule and then moves to mechanics and responsibility, which is sensible ordering. But it is a dense run-on with stacked parentheticals, and the full Chinese restatement duplicates the same content rather than adding information, so not every clause earns its place.

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

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

For a charged, deeply nested mutation tool with an output schema, the description supplies the crucial pieces an agent needs: cost/retry semantics, the anchoring contract, and the client-side verification obligation. Missing only the explicit upstream dependency (prepared window) and a hint of what state transitions the call performs.

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

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

With only 40% schema description coverage, the description carries real weight: it explains that quote/anchor selectors must be verbatim unit text (the schema only says quote is a non-empty string) and that client canon_text is rejected, which governs canon_segments and bible_ops.sources. It leaves state, units, window_fp, base_state_hash and story_merge unexplained, so compensation is partial rather than complete.

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

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

States a specific verb+resource: merging the caller's own extraction of a prepared window into canonical state, with a clear division of labor ("YOU decide what the story means; the server only verifies anchors and patch safety"). It distinguishes itself from the prepare step implicitly via "a prepared window" but never names prepare_story_window or render_story_handoff, so differentiation relies on inference.

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

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

Gives concrete operating context: selectors must quote/anchor exact unit text, client-supplied canon_text is rejected, and the returned canon_patch must be tail-hash-verified before applying. However, it never states the prerequisite (a window prepared by prepare_story_window) or when to prefer a sibling, so the routing guidance stays implicit.

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

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

Adds substantial context beyond annotations: analyzer/version determinism tied to a specific rule set, a credit model (one credit covers one screenplay for 24h across five tools), no charge on failed calls, and request_id-based idempotent billing. This resolves the apparent tension with idempotentHint=false by clarifying that only billing is idempotent, not output state.

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

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

The capability statement is front-loaded and the billing/chaining rules are packed into dense but useful sentences. It runs long and the trailing Chinese sentence largely restates the English content, which adds length without new information for a single-language reader.

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

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

Output schema exists, so return values need no prose explanation, and the description still names the main result sections. Combined with billing, determinism, and chaining guidance, an agent has everything needed to call this correctly alongside format_screenplay.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds meaning on top by explaining that input_format='blocks' is meant to receive blocks returned by a sibling tool and that plain formatted text should not be re-fed during chaining. It does not elaborate on text vs blocks parsing tradeoffs or the license_key/request_id parameters, which the schema already documents.

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

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

States a specific verb+resource (deterministic screenplay statistics) and enumerates concrete outputs: scene list with parsed headings, per-scene word count, dialogue ratio, action density, character table, genko_yoshi counts. It also names a sibling (format_screenplay) whose inputs it shares, so an agent can place it in the tool family without opening the schema.

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

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

Gives clear operating context: pass the same screenplay used with format_screenplay, and when chaining, pass back blocks (structured) rather than formatted text. It does not, however, specify when to prefer this over diagnose_scenes or compile_film_breakdown, and gives no explicit exclusions, so it stops short of full alternative routing.

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

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

Annotations are minimal (readOnly=false, idempotent=false), so the description carries most of the burden and delivers: determinism, server-side no-LLM behavior, verbatim dialogue preservation, bidirectionality of CUT-OUT/CUT-IN, and a full billing model (one credit/24h, failures not charged, request_id idempotency). It stops short of describing output shape or any rate limits, keeping it out of the top band.

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

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

Purpose and deterministic caveat lead cleanly, but the body is one very long compound sentence packed with parenthetical asides and a bilingual trailer. It is thorough rather than tight; a reader must parse several clauses before reaching the key billing and workflow guidance.

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

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

Given 9 parameters, no required fields, complex two-layer output, and an output schema present, the description covers the workflow end-to-end: input modes, entity registration, shot proposal heuristics, style handling, billing, and the next tool to call. Nothing an agent needs in order to invoke it correctly is absent.

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

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

Schema coverage is 100% and every parameter carries a description, so the baseline is 3. The description adds meaning beyond the schema for style (editable starting point, never a lock), style_note (verbatim, unvalidated), and segment_seconds (estimates to adjust), but these are restatements of schema intent rather than new syntax this contract provides.

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

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

States a specific verb (turn a screenplay into video-generation prompt scaffolds) and a specific resource, and explicitly distinguishes itself from siblings by describing the two-layer segment/shot output that no sibling (analyze_screenplay, compile_film_breakdown, check_video_prompts) produces. The deterministic/no-LLM clause makes the value proposition unmistakable.

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

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

Explicitly routes the agent forward: 'After filling, call check_video_prompts (free) for drift findings,' and gives the when-to-use condition for style presets vs. the default checklist. It does not, however, state when to choose build_video_prompts over analyze_screenplay or compile_film_breakdown, so the upstream selection is left to inference.

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

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

Annotations already establish readOnly/idempotent/non-destructive, so the bar is lower; the description adds genuinely useful behavior — what a credit actually buys (one screenplay for 24 hours across screenplay tools, one film analysis, or one story project for 24 hours) and that the call is free.

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

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

Front-loaded and the credit-cost explanation is valuable, but the full Chinese sentence restates the English credit definition verbatim for the same reader, which is duplication rather than added information.

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

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

An output schema exists so return values need no explanation, and the description covers the credit model, the free-call fact, and the auth preference. Complete enough for a zero-required-parameter read tool.

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

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

Schema description coverage is 100% and the schema already documents the NRC pattern and the 'optional if configured in client auth header' note, so the description largely repeats it. Baseline 3 applies since the schema carries the parameter semantics.

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

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

States a specific verb and resource ('Check the remaining credits for a Narracore license key') and enumerates the secondary returns (recent usage, purchase link). No sibling tool does anything comparable, so the agent can distinguish it instantly.

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

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

Gives clear invocation context: 'Costs nothing' and the preferred auth method ('set the key in your MCP client auth instead of passing it in chat'). It does not discuss when to call it versus alternatives, but no sibling overlaps, so the guidance that matters is present.

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

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

Annotations already cover safety (readOnly/idempotent/non-destructive), yet the description adds significant behavior: no LLM on the server, pure pattern matching and set comparison, findings are reported and nothing is blocked, free with no key required, and the exact violation vs advisory taxonomy with the escape hatch (advisories=false). That is well beyond what annotations provide.

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

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

The load-bearing sentence (free, deterministic, screenplay-vs-prompts comparison, report-only) is front-loaded, and every sentence carries gate semantics. The violation/advisory enumeration is dense and reads as a wall of text, but given the number of distinct gates it is mostly justified.

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

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

An output schema exists, so return-value detail is not required. Combined with 100% schema coverage and explicit annotations, the description leaves no gap an agent needs in order to call this tool correctly, including the free-form vs scaffolded branch.

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

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

Schema description coverage is 100%, so the baseline is 3; the description still adds meaning by clarifying that up to 10 prompt texts at <=20k chars each are accepted, that style enables preset-specific banned-vocabulary/limit advisories, and that char_limit defaults to the style preset recommendation.

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

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

States a specific verb+resource: 'deterministic quality gates for video-generation prompts written against a screenplay'. It also names the sibling workflow it consumes ('build_video_prompts scaffolds') and distinguishes itself from siblings that analyze/validate the screenplay rather than the prompts.

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

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

Gives clear operational context: submit the SAME screenplay plus 1-10 prompt texts, free-form prompts without [SHOT] markers skip structure gates, advisories can be disabled. It does not explicitly say when to prefer this over siblings like analyze_screenplay or validate_film_breakdown, so it falls short of a full 5.

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

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

Annotations only declare the generic write/idempotency stance, and the description adds substantial behavioral context beyond them: the 1-credit charge model, 24h analysis_id de-duplication, no charge on failed validation, the 24h expiring signed PDF link, and the explicit warning that input records are never echoed back. It also discloses that the server cannot verify media_id and that media_id exists only to protect the caller from double-charging.

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

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

The charge rule and pipeline order are front-loaded, which is good, but the paragraph is extremely dense (nested parentheticals, long arrow chains) and then repeats the entire content in Chinese, roughly doubling length without adding new information for a single-language agent.

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

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

For a high-complexity tool with nested payloads and an output schema, the description covers charging, dedup, validation failure behavior, output artifacts and the PDF link, which is most of what an agent needs. The remaining gap is the semantics of the nested shot/scene layer objects, which are handled only by the schema.

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

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

With schema coverage at only 43%, the description compensates by explaining media_id = sha256(video bytes) computed locally, the analysis_id derivation, and the idempotency semantics of request_id. It adds real meaning beyond the schema, though the structure and meaning of the shots/scenes/relations layer fields remain schema-only.

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

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

States a specific verb (compile) and resource (film breakdown) and then enumerates the exact pipeline stages, from authoritative validation through window/canonical shot merge, aggregates, heuristic reconstructions and a print-ready PDF with a 24h signed link. This scope (charged compilation producing a PDF report) is unmistakably distinct from siblings like validate_film_breakdown or plan_film_analysis without opening any schema.

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

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

Gives explicit conditions for recompiling (new model, same analysis_id, no re-charge) vs starting a new analysis (different cuts or protocol), plus the free re-call rules and the detail=summary option. It implies the input must already be validated but never names the sibling tool that performs validation, so routing to alternatives is left to inference.

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

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

Goes well beyond the annotations by disclosing transformation side effects (Latin upper-casing, CJK preserved verbatim, notes as [[…]]), lossy/ignored input (boneyard stripped and reported, title-page keys and # headers skipped with warnings), a Chinese-content parser fallback, and the unusual billing model (one credit per screenplay per 24h, failed calls never charged). This is exactly the kind of behavior an agent cannot infer from readOnlyHint/destructiveHint.

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

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

Dense but front-loaded, with purpose stated first and per-direction behavior clustered afterward. The trailing Chinese restatement duplicates the English content, costing a little space without adding information.

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

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; the description covers direction semantics, parsing caveats, fallbacks, and billing, leaving no obvious gap for correct invocation.

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

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 coupling semantics the schema does not convey — that direction determines which of text/blocks/fountain is meaningful and what each direction emits. Useful marginal value over the structured fields.

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

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

States a specific bidirectional transformation between Narracore screenplay blocks and Fountain text, naming both the resource and both directions. An agent can distinguish it immediately from siblings like format_screenplay or analyze_screenplay.

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

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

Explicitly defines the two direction values and the condition that selects each, and points to the downstream consumer (pass blocks straight to format_screenplay with input_format="blocks"). There is no explicit when-not-to-use or sibling comparison, 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.

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

Goes well beyond the annotations by disclosing the core behavioral contract: no server-side LLM, the server maps ordinals to blocks, drops findings whose verbatim evidence cannot be verified (scene then scores null, never faked), and computes a severity-weighted 0-100 score plus a reference-only baseline. It also covers billing behavior (1 credit/24h, failures not charged), which annotations cannot express.

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

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

Front-loaded with the key contract (AI cites, server scores) and structured as a numbered two-step flow, so it reads efficiently despite its length. The trailing Chinese sentence restates the same content already given in English, which is mild redundancy.

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

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

For a complex two-mode, credit-metered tool, it covers the workflow, the evidence-verification contract, failure handling, billing, and the free tier. An output schema exists, so return-value detail is correctly left to it, and nothing an agent needs to invoke either mode is missing.

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

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

Schema coverage is 75%, and the description adds real meaning: it explains the material/score mode split, the shape of findings=[{scene, summary, problems:[...]}], the six problem types, that evidence must be a verbatim quote, that blocks are ordinals, and that severity is low|medium|high. This meaningfully supplements the schema, though some field detail remains schema-only.

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

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

States a specific verb and resource — scene-level 'shootability' diagnosis for a screenplay — and names the exact rule set (ai-2.0 / narracore.cn). It is clearly distinguishable from siblings like analyze_screenplay or format_screenplay because it defines a precise two-mode diagnostic job.

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

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

The description gives explicit sequencing: call mode="material" first (free, returns material + schema), analyze yourself, then call mode="score" with findings. It also states credit scope (one screenplay for 24h across screenplay tools) and that failed calls are never charged. It does not, however, position itself against the other screenplay-analysis siblings, so 4 rather than 5.

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

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

Annotations only declare the safety profile (readOnly=false, destructive=false, idempotent=false); the description adds a large amount beyond that: 24h-per-screenplay billing across the tool family, no charge on failure, request_id never double-charging, free tier behavior, quota-exhaustion handling instructions, the UNRESOLVED_STRUCTURE flag on wall-of-text input, and the meaning of the confidence field. Nothing here contradicts 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.

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

Purpose is front-loaded and the mode/billing sections are cleanly bulleted. The billing paragraph is dense and somewhat sprawling for a tool description, but every block carries operational information an agent needs (modes, chaining, diagnostics, quota).

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

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

For a 14-parameter tool with nested objects and an output schema, the description covers the decision-relevant gaps: mode selection, chaining, diagnostics interpretation, confidence semantics, and billing/failure behavior. Return-value shape is delegated to the output schema, which is the correct division of labor.

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

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 earns more: it explains the two input_format modes conceptually (line-per-element parsing rules vs. blocks rendered exactly as submitted, never re-classified), warns that blocks and text parse differently when chaining, and covers style/dialogue_breaks/cover.anonymous as free rendering options within the bundle.

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

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

The first sentence names a specific verb (Convert) and precise resource (raw/loosely formatted screenplay text → structured blocks + print-ready PDF on a fixed typewriter grid). It scopes the input domain (Chinese/English/mixed, Japanese broadcast format, colon-style dialogue) and explicitly excludes general prose rewriting, so an agent can distinguish it from siblings like analyze_screenplay or convert_fountain.

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

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

It states when to use it (formatting, import, shareable PDF) and when not to (general prose rewriting or story editing), plus a concrete free diagnostic path via output="validate_only" and the correct chaining pattern (pass back blocks, not text). It stops short of naming the sibling tools whose boundaries matter most (convert_fountain, render_bilingual_pdf, analyze_screenplay), leaving that routing to the agent.

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

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

Annotations already declare readOnly/idempotent/non-destructive/non-openWorld, so the safety profile is covered. The description adds genuinely useful context beyond that: it is free, the video never leaves the caller's machine, and the toolchain is deterministic (normalization is exact→alias→reject, no fuzzy guessing). It does not discuss rate limits or response shape, but the output schema exists to cover the latter.

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

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

Front-loaded well with 'FREE' and the core action, and the per-section breakdown is informative. However it is dense and the trailing Chinese sentence largely duplicates the preceding English content without adding new information, which weakens conciseness.

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

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

With annotations, a full input schema, and an output schema present, the description supplies everything else an agent needs: the purpose of the contract, the meaning of every section, and a first-contact recommendation. Nothing required to call it correctly is missing.

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

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 goes further by enumerating and explaining each enum value's content (core contents, vocabulary alias table, guidance prompts, media_recipe caveat). The film_schema_version parameter is left to the schema, which is adequate.

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

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

States a specific verb and resource — 'Return the Narracore Film Contract by section' — and immediately defines what that contract is (the protocol that produces a validated Film IR). An agent can distinguish this documentation/contract tool from siblings like compile_film_breakdown or validate_film_breakdown without opening the schema.

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

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

Gives clear per-section routing (what each section contains) and an explicit recommendation — section="all" on first contact. It does not state when to prefer this over sibling tools or what to do after retrieving the contract, so it stops short of full when/when-not guidance.

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

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.

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.

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.

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.

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.

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.

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower, yet the description adds real context beyond them: it is FREE, failed calls are never charged, the server stores nothing, and the caller must retain the full text and returned StoryState. It also draws an important epistemic boundary ('a source is traceable, not proof your interpretation is true'). No annotation contradictions.

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

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

The core purpose, cost, and statelessness are front-loaded ('FREE. Split a story conversation...'), and each sentence carries operational meaning. The full bilingual duplication effectively doubles the length, though the lang enum suggests bilingual support is intentional rather than padding.

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

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

For a tool with a deeply nested state object and an existing output schema, the description covers the non-obvious essentials: no server-side persistence, cost/idempotency behavior, and the provenance-vs-truth caveat. It omits explicit routing versus the sibling absorb_story_window and any guidance on the state/language parameters, leaving modest gaps.

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

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

Schema description coverage is only 25% (essentially just request_id), so the schema does not carry the load. The description helps partially by framing that StoryState is returned and must be kept client-side, which clarifies the state round-trip, but it says nothing about the lang enum, the state sub-structure, or the conversation item shape.

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

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

The description names a specific verb and resource: 'Split a story conversation (verbatim user/assistant turns) into stable, hash-anchored units.' It clarifies its role relative to the caller ('YOU judge the story; the server only slices and anchors provenance'), which distinguishes it conceptually from the sibling absorb_story_window, but it never names that sibling explicitly.

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

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

Usage is implied through the workflow context ('for the Narracore Story Continuity Protocol') and the caller/server division of labor, and the idempotency note tells the agent how repeated calls behave. However, there is no explicit statement of when to use this tool versus the sibling absorb_story_window or when to skip it entirely.

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

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

The description adds substantial behavioral context beyond the annotations: fixed typewriter grids, A3 landscape layout, scene-by-scene alignment, required matching scene-heading counts, mismatch-return behavior, credit cost, and free re-rendering within 24 hours. These details help an agent understand both output behavior and billing-related consequences.

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

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

The description is front-loaded with the tool's purpose and then adds only relevant details about layout, alignment constraints, mismatch behavior, and credits. Despite its length, every sentence provides useful information for correct invocation.

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

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

Given the presence of an output schema and annotations, the description is complete enough for an agent to call the tool correctly. It covers inputs, the non-translation behavior, scene-alignment constraints, failure behavior, and credit implications.

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

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 six parameters, including input_format and translation requirements. The description reinforces that the original uses format_screenplay-style inputs and that translation must match scene headings, but most parameter-level meaning is already carried by the schema.

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

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

The description opens with a specific verb and resource: it renders a bilingual side-by-side screenplay PDF. It distinguishes this from related tools by explaining that it takes the original screenplay plus a user-provided translation and typesets them together, rather than translating or formatting a single-language screenplay.

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

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

It clearly states the input pattern: submit the original screenplay using the same inputs as format_screenplay plus a translation. It also says the translation is user-provided and the tool never translates, which implicitly rules out using it as a translation tool. However, it does not explicitly name the alternative to use for monolingual formatting.

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

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

Annotations already cover readOnly, idempotent and non-destructive behavior, yet the description adds genuinely new operational facts: the call is FREE, failed calls are never charged, and project_token proves identity only — not the authenticity or freshness of the supplied state. The warning to keep full text client-side is also useful. It stops short of describing output structure or limits, so a 4.

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

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

Front-loads the most important qualifier ('FREE') and then the purpose, with the authenticity caveat following. The bilingual restatement roughly doubles the length, which is defensible for a zh/en-targeted tool but does introduce redundancy. Every sentence otherwise carries weight.

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

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

An output schema exists, so return-format explanation is rightly omitted, and annotations cover the safety profile. The description supplies the non-obvious trust and billing context an agent needs. It is slightly thin on the tuning parameters (recent_chars, direction), which is the only material gap.

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

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

Schema coverage is only 20% across 5 parameters. The description adds real meaning for project_token (identity-only, not content validation) and implicitly covers lang (zh/en) and the state payload. However, recent_chars (window size), direction, and the idempotency behavior of request_id are left to the schema, so it does not fully compensate for the coverage gap.

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

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

States a specific verb and resource: 'Render a StoryState into a zh/en handoff document (recent-canon window + bible) for a successor writer/AI.' The purpose and output artifact are unambiguous. It does not explicitly name or contrast with siblings such as prepare_story_window or absorb_story_window, so it earns a 4 rather than a 5.

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

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

The intended consumer (a successor writer/AI) implies the usage context, but there is no explicit when-to-use versus alternatives like prepare_story_window, nor any stated prerequisites or when-not-to-use conditions. Guidance is inferable but not spelled out.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, and the description adds substantive behavior beyond them: it never watches video or judges observation truth, only fixes the representation layer, separates lossless fixes (normalized_patch) from semantic errors, and is advisory rather than authoritative. That is rich context an agent needs to interpret results correctly.

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

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

Front-loaded with the key qualifier (FREE preflight) and dense with signal, but the fully duplicated Chinese sentence adds length without adding information for a single-language reader. Structure is otherwise tight with no filler sentences.

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

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

For a 4-param nested validation tool with an output schema, the description is close to complete: it scopes what is and isn't validated and explains the advisory relationship to compile_film_breakdown. Return-value details are correctly delegated to the output schema, so no gap there; only the nested field-level semantics are left to the schema.

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

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

Schema description coverage is 0%, so the description must compensate; it names all four top-level parameters and assigns each a validation role (cross-referencing shot ids, scene membership, relation endpoints, window completeness for long takes). It does not enumerate the many nested layer/provenance fields, but it covers the parameters that matter for invocation.

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

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

States a specific verb (validate) and resource (a film breakdown payload of film_manifest + shots + scenes + relations), then enumerates the exact checks: schema shape, closed vocabularies, cross-references, window topology, provenance, observability metadata. It explicitly distinguishes itself from compile_film_breakdown as the non-authoritative preflight.

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

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

Gives explicit when-to-use guidance ('compile_film_breakdown re-validates authoritatively' and the Chinese line advising to run it before compiling to save a failed round trip), plus what to do with results (normalized_patch vs errors, retry_feedback to feed back to the model). Nothing is left to inference.

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