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?

Goes well beyond the annotations by disclosing the billing model (one credit covers one screenplay for 24 hours across the screenplay tool family), failure/retry semantics (failed calls never charged; same request_id never double-charges), and determinism guarantees (analyzer_version 1.0, same rules as narracore.cn). None of this is recoverable from the structured fields.

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 purpose before usage and billing, and each sentence carries information. It runs long and the trailing Chinese restatement duplicates the preceding content, which slightly dilutes density but serves a bilingual audience.

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 not be enumerated, yet the description still previews the payload (scene headings fields, character metrics) and fully covers input coupling, billing, and retry behavior. Nothing an agent needs to invoke this 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 description coverage is 100%, so the baseline is 3, but the description adds real meaning on top: input_format="text" vs "blocks" and, critically, that chained calls should pass back the structured blocks rather than the formatted text. That is actionable guidance the schema does not supply.

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 (deterministic statistics) on a specific resource (screenplay) and enumerates the exact outputs: scene list with parsed headings, per-scene word count/dialogue ratio/action density, and a character table. It also anchors the tool against siblings by naming format_screenplay and the shared analyzer rules, so an agent can distinguish it 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 concrete usage context: accepts the same inputs as format_screenplay, pass the SAME screenplay to both tools, and when chaining, pass back the structured blocks rather than formatted plain text. It does not explicitly say when to prefer this over diagnose_scenes or compile_film_breakdown, so the when-not guidance is partial.

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 the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial context: no LLM on the server, pattern-matching only, findings reported and nothing blocked, free with no key required. It also enumerates every violation and advisory category with their triggering conditions, which is far beyond annotation coverage.

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 key framing (free, deterministic, report-only) and the gate taxonomy is dense but each item is specific and useful. It is long and the trailing Chinese sentence duplicates the English summary, which is minor waste rather than a structural flaw.

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 an 8-parameter tool with a rich output schema, the description covers the gate semantics, scope limits (up to 10 prompts, ≤20k chars each), advisory opt-out, and free-form vs scaffold behavior. Nothing an agent needs 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 description coverage is 100%, so the baseline is 3, but the description adds real meaning: it clarifies that prompts are finished texts of ≤20k chars, that style presets drive banned-vocabulary and recommended-limit advisories, and that char_limit defaults to the preset recommendation. It does not add much on input_format or request_id beyond 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?

States a specific verb+resource: deterministic quality gates for video-generation prompts written against a screenplay, and explicitly contrasts with the sibling that builds prompts (build_video_prompts scaffolds). An agent can distinguish this as the check/validate step versus the generate step 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 invocation context: submit the SAME screenplay plus up to 10 finished prompt texts, advisories can be disabled, and free-form prompts without [SHOT] markers skip structure gates. It does not explicitly name alternatives or when-not-to-use conditions, 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 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?

Annotations only declare safety flags (readOnly=false, idempotent=false, destructive=false), so the description carries the burden and does so richly: Latin upper-casing, CJK preservation, [[…]] notes, boneyard stripping with reporting, skipped title-page/section headers with warnings, and the Chinese-parser fallback. It also discloses the credit model (one credit per screenplay/24h, failed calls never charged), which is genuine behavior beyond the schema.

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?

It is a single dense paragraph rather than a structured layout, but it is front-loaded with the core purpose and nearly every sentence carries distinct information about casing, parsing, fallbacks, or billing. Only the trailing billing clause is slightly redundant against the shorter Chinese restatement.

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 7-param, bidirectional converter with an output schema, the description covers both directions, edge cases (boneyard, title page, CJK fallback), idempotency/request_id usage, and billing. Nothing an agent needs to invoke it correctly is missing, and return values are left to the output 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 coverage is 100%, so the baseline is 3. The description goes beyond it by clarifying direction semantics (to_fountain vs from_fountain), which inputs (text/blocks vs fountain) belong to which direction, and what input_format selects, adding meaningful constraint context.

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 states a specific bidirectional verb+resource: converting between Narracore screenplay blocks and Fountain plain-text. Both directions are named and the relationship to the sibling format_screenplay is made explicit, so an agent can distinguish it 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?

It explains when each direction applies and that from_fountain output can be passed straight to format_screenplay (input_format="blocks"), which is real routing guidance. It does not, however, explicitly say when not to use this tool versus other screenplay siblings like analyze_screenplay.

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: no LLM on the server, findings whose evidence cannot be verified are dropped, the scene then 'scores null — never faked', severity-weighted exact arithmetic, and 'Failed calls are never charged'. This is rich operational context an agent needs to trust the results.

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 mechanism and two-step flow before detail, and the opening sentence carries the core distinction. It is dense and the trailing Chinese restatement is redundant, but nearly every sentence 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?

An output schema exists so return values needn't be explained, yet the description still covers verification, null-scoring, credit model, and the material→score workflow. For an 8-parameter tool this is fully adequate.

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 75% schema coverage the baseline is 3, but the description adds real meaning: the exact findings object shape ({scene, summary, problems:[{type, severity, evidence, blocks, suggestion]}), that evidence must be a verbatim quote, and that blocks are ordinals mapped back to numbered material. It also enumerates the 6 problem types.

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 (diagnose) and resource (scenes), plus the exact mechanism: 'YOU (the calling AI) cite the evidence, the server validates it and computes the score'. The two-step flow and the 'shootability' intent clearly separate it from sibling tools like analyze_screenplay or validate_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?

Gives explicit sequencing: call mode='material' first, then 'after analyzing the material yourself, call mode='score''. It states material is FREE and score costs a credit, plus the 24-hour coverage window. It does not, however, state when to prefer this over analyze_screenplay or other siblings.

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 readOnlyHint=false, destructiveHint=false, openWorldHint=false, and idempotentHint=false, so the description usefully adds billing rules (one credit per screenplay per 24h, failed calls never charged, request_id never double-charges), the free-tier behavior, and the diagnostics/confidence semantics. However, the material billing and quota disclosure is largely a policy/UX layer rather than operational behavior of the formatting itself, and the idempotency claim is only implicitly reconciled with idempotentHint=false.

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?

It is long but front-loaded: the opening sentence carries purpose, scope, and exclusions, then it is chunked into INPUT, chaining, pre-delivery, and billing sections. Some lines (credit/pricing detail) approach promotional copy, but each block still serves a decision the caller must make.

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 an 11-parameter, nested-object tool with an output schema, the definition covers both input modes, chaining, free paths, and pre-delivery diagnostics, and it delegates full parameter detail to the llms.txt manual. That is close to complete; the small remaining gap is that the header/footer/cover parameters are only pointed at rather than summarized, which is acceptable with 100% schema coverage.

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 meaning beyond the schema: it explains that blocks are 'validated and rendered EXACTLY as submitted, never re-classified', describes the line grammar for text mode, and notes UNRESOLVED_STRUCTURE for unbroken text. That clarifies when each mode should be chosen and what the parser expects.

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 ('Convert ... screenplay text ... into ... serializer blocks and a print-ready PDF') with the target grid and languages spelled out, and it explicitly excludes adjacent work ('NOT for general prose rewriting or story editing'). An agent can distinguish it from analyze_screenplay, diagnose_scenes, and convert_fountain without opening schemas.

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 (screenplay formatting, import, PDF production), mode selection (text vs blocks vs validate_only), and routing guidance to siblings ('to run other tools on this screenplay, pass back the BLOCKS you received — not the plain text'). It also states validate_only is free and check_video_prompts is free, so the agent knows the cost-free paths.

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?

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.