story-architect-mcp

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

With no annotations, the description carries the full burden: it implies a read-only measurement operation but never states that it is non-mutating, nor whether it requires the arc to be previously set (story_set_project) or how costly the scan is. It does usefully disclose the computed artifacts, which is the main behavioral fact an agent needs, but omits output shape and any prerequisites.

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?

A single front-loaded sentence that enumerates the three analyses with no filler. It is efficiently sized for the tool's scope, though it spends no words on guidance or output context.

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 two-parameter, no-output-schema tool, the description lists all three returned artifacts, which partially substitutes for an output schema. However, it never describes the result structure (per-chapter? per-scene? numeric ranges?), and with no annotations an agent gets no safety or precondition context, leaving a meaningful 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 description coverage is 100% and both parameters (arc, chapter) are documented in-schema, including the 'omit chapter to analyze the whole arc' rule, so the baseline of 3 applies. The description adds no syntax, format, or defaulting information 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?

The description names a specific analysis operation and enumerates the three concrete outputs (Action/Dialogue/Description ratio, Tension curve, Scene beats), so an agent knows exactly what is computed. It does not explicitly differentiate itself from near-neighbors such as story_analyze_sentiment or story_analyze_voice, which also read chapters and produce derived metrics.

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?

There is no statement of when to invoke this versus alternatives; the only scoping hint ('bỏ qua để phân tích toàn bộ Arc') lives in the schema, not the description. An agent must infer the trigger condition and cannot learn from the text why it would pick this over the other analysis 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?

No annotations are provided, so the description carries the full disclosure burden. It never states that this is a read-only analysis (likely LLM-backed, potentially slow or costly), whether compareToStyleGuide causes file reads with side effects, or what happens on a missing arc/chapter. For a tool with zero annotation coverage, this is a significant gap.

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?

Two short sentences with no filler, and the core capability is front-loaded. It is arguably over-terse for an analysis tool, but nothing is wasted.

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?

There is no output schema and no annotations, yet the description says nothing about what the analysis returns (sentiment scores, tone labels, drift report, emotional arc series) or where results land. For a four-parameter analysis tool, an agent cannot predict the response shape or cost from this definition alone.

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 all four parameters are already documented in the schema. The description only reinforces scope (chapter vs. whole arc), adding marginal meaning beyond the schema's own 'bỏ qua để phân tích toàn bộ Arc' note. Baseline 3 is appropriate when the schema does the heavy lifting.

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 (analyze) and three concrete resources (sentiment, tone, emotional arc), plus a secondary capability (tone drift detection across chapters), and clarifies the scope is a chapter or an arc. It does not differentiate itself from close siblings like story_analyze_voice, story_analyze_pacing, or story_track_emotion, which an agent could easily confuse with this tool.

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 only implied: mentioning 'chương/arc' suggests choosing chapter-level versus arc-level analysis, and 'tone drift giữa các chương' hints at multi-chapter comparisons. There is no explicit when-to-use, when-not-to-use, or named alternative among the many analysis siblings (voice, pacing, emotion tracking).

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?

No annotations are provided, so the description carries the burden. It discloses that the tool reads a style_guide.json baseline and performs drift comparison, which is useful context, but it does not say what happens if no style guide exists, whether the operation is read-only, or what the result contains.

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?

A single dense sentence with the analyzed dimensions front-loaded before the drift check; no filler. Slightly over-packed as a parenthetical list, but efficient.

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 two simple, fully documented parameters and no output schema, the description is enough to invoke the tool, but it never describes the return shape (drift score? per-metric verdicts?) or the dependency on style_guide.json, which an agent needs to interpret results.

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 both parameters are documented in the schema, so baseline is 3. The description adds no meaning beyond the schema — it does not clarify whether omitting 'chapter' analyzes the whole arc or what 'chapter' accepts (number vs path).

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 (phân tích / analyze) plus the exact facets measured (sentence length, vocabulary, POV, tense, dominant emotion) and a second function: detecting voice drift against style_guide.json. That distinguishes it from siblings like story_analyze_pacing and story_analyze_sentiment, though the emotion overlap is not resolved.

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 tells what is compared (style_guide.json) but never states when to use this tool versus story_analyze_sentiment, story_analyze_pacing, or story_query_context, nor any preconditions such as requiring an existing style guide. Usage must be inferred.

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?

With no annotations provided, the description carries the full behavioral burden. It does disclose a meaningful trait: appending to the end without losing previous content, which is useful for a mutation tool. It does not cover permissions, missing-chapter behavior, response format, or other side effects, so it remains incomplete.

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 a single, front-loaded sentence with no wasted words. It immediately communicates the append action and the non-destructive guarantee.

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 simple four-parameter append tool with full schema coverage and no output schema, the description is adequate but not complete. It does not explain edge cases such as a missing chapter or what the tool returns, which would help an agent invoke it confidently.

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 all four parameters are already documented in the input schema. The description does not add syntax, format, or usage details beyond what the schema provides, making the baseline score of 3 appropriate.

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 verb (nối thêm), resource (phân cảnh), and target location (cuối chương truyện hiện có), with the added constraint that prior content is preserved. It is clear what the tool does, but it does not explicitly differentiate itself from sibling story_write_chapter.

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 phrase 'vào cuối chương truyện hiện có' implies the tool is for appending to an existing chapter without replacing it, which hints at when to use it. However, it gives no explicit alternatives, exclusions, or prerequisites such as what happens if the chapter does not exist.

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?

With no annotations, the description carries the full disclosure burden and does so well: it lists concrete validation rules (paths must stay inside the project, destinations are limited to manuscript/bible/outline/drafts_raw, chapter lines must exist) and states the persistence target .story/layout-verdict.json. It does not say what happens on validation failure (error shape, whether an existing verdict file is overwritten), which is the remaining gap.

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 that leads with the action and the upstream tool, then the validation rules, then the consumers and the revert path. Nothing is wasted, though the validation clause is packed tightly enough to require careful reading.

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 2-parameter write tool with no output schema and no annotations, the description covers the critical facts an agent needs: input provenance, enforced constraints, storage location, downstream effects, and rollback. Only the failure/error behavior is left unstated.

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 the nested verdict object is well typed (kind enum, confidence 0-1, required reasoning, arcs/chapters/files arrays), so the schema does most of the work. The description adds real semantic context by explaining that the verdict is the AI's output from reading story_export_layout_brief and listing the constraints the server enforces on paths and destinations.

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 verb (nộp/save) and resource (layout verdict JSON), and ties it to its upstream producer story_export_layout_brief. An agent can immediately tell this apart from analysis tools such as story_scan_messy_project because it writes a persisted verdict rather than computing one.

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 names the downstream consumers (story_auto_refactor_structure, story_scan_messy_project) that will prioritize this verdict, and it explicitly states how to undo it: delete the file to return to the heuristic. That covers when to use it, what it affects, and how to opt 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?

With no annotations, the description carries the burden of disclosing behavior. It does explain the dry-run safety path, which is valuable, but for a file-moving mutation it omits whether the operation is reversible, that a snapshot happens (that detail lives only in the schema), and what the result looks like. It signals the operation but not its 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?

Two tight sentences with the core purpose front-loaded and the safety mode immediately following. Nothing is wasted, though the dry-run sentence could have carried more behavioral detail given the space available.

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 mutation tool with no annotations and no output schema, the description is minimal: it lacks any mention of what is returned, whether snapshot/rollback protects the user, or how it relates to the scan/verdict tools. The dry-run hint helps but does not fully cover the complexity of a directory-restructuring operation.

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%, with the strategy enum fully documented in-schema. The description's mention of confirm=false as dry-run duplicates what the schema already states, adding no new semantics. Baseline 3 is appropriate given the schema does the heavy lifting.

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 verb+resource: it classifies and normalizes the directory structure of a novel project into a standard layout. This clearly distinguishes it from read-only siblings like story_scan_messy_project, though it does not explicitly name the related story_apply_layout_verdict. An agent can identify the operation without reading 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 gives useful procedural guidance: use dry-run mode (confirm=false) to preview before committing. However, it never states when this tool should be chosen over closely related siblings such as story_scan_messy_project or story_apply_layout_verdict, nor does it state prerequisites. Usage is implied rather than fully directed.

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?

No annotations are supplied, so the description carries the full burden. It frames the tool as a read/analysis operation ('phân tích ... để phát hiện mâu thuẫn') yet the schema exposes an addEvent capability, meaning the tool can mutate timeline state — and the description never says so, nor whether conflicts are persisted, what permissions are needed, or how results are returned beyond 'exports a Mermaid chart'.

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?

Two dense sentences with the detection purpose front-loaded followed by the parallel-thread/Mermaid output capability. No filler, though the visual-output claim sits in the same breath as analysis without separating the two modes of operation.

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 no annotations and no output schema, the description covers the analysis purpose and the Mermaid return artifact reasonably well. But it omits the event-insertion behavior implied by addEvent and says nothing about what the conflict report itself contains, leaving a mutation-capable tool under-described.

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 every sub-field (label, thread, chapter, location, characters, absoluteDate, relativeOrder) is already documented in the schema; baseline 3 applies. The description adds only the thematic link to 'Threads/Subplots' for the thread field and never mentions the single top-level addEvent parameter, so it contributes little beyond structured data.

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: analyze absolute/relative time markers, events, locations and characters to detect timeline contradictions, with concrete examples (a character in two places at once, reversed event order) plus Mermaid diagram output. The scope is unmistakable and no sibling tool overlaps with conflict detection, though it does not explicitly name non-overlap.

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 only implied: an agent can infer this is for consistency-checking a story's chronology, but the description gives no trigger conditions, no prerequisites, and no when-not-to-use guidance versus other analysis siblings such as story_log_plot_hole or story_analyze_pacing.

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?

With no annotations provided, the description must carry the behavioral burden. It usefully discloses that the export includes a table of contents and author information and that output is a file in one of several formats, but it does not mention overwrite behavior, required project context, or what happens with the unsupported PDF option.

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?

A single, front-loaded sentence that states the action, target, formats, and bundled output contents. It contains no filler and is appropriately sized for a tool with full schema coverage.

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 file-export mutation tool with no annotations and no output schema, the description is adequate but incomplete. It identifies the output formats and included sections, but leaves gaps around overwrite behavior, project context, and error/format limitations such as the PDF enum value.

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 explains format, outputPath, and includeOutline. The description adds only a high-level list of formats and mentions TOC/author info, which is not parameter-specific. Baseline 3 is appropriate because the schema does the heavy lifting.

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 gives a specific verb-resource pair: "Đóng gói và xuất bản toàn bộ tác phẩm" into named file formats. It is clear what the tool produces, though it does not explicitly differentiate itself from the similarly named story_export_layout_brief sibling.

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 by "toàn bộ tác phẩm" — export the whole manuscript — but the description does not state when to prefer it over alternatives or when not to use it. It also gives no guidance on choosing among the supported formats.

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?

No annotations exist, so the description carries the full behavioral burden. It does disclose what the payload contains and its role in a larger pipeline, but never states that the operation is read-only/non-destructive, whether anything is written to disk, or how large the brief may get for a big project (no truncation or size caveat). Those are meaningful gaps for a tool whose output is meant to be read wholesale into an agent's context.

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?

Three sentences, front-loaded with what the tool produces before the pipeline steps. Every sentence contributes, though the inline enumeration of the three downstream/upstream steps is slightly dense and could be tightened.

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 no output schema, the description usefully compensates by enumerating the brief's contents (file tree, content excerpts, heuristic profile) and its position in the workflow. It stops short of clarifying output format (single text blob vs. file reference) and any size limits, which matters for an evidence-export 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?

Only one parameter (projectPath), and schema description coverage is 100%, so the schema already defines it as the project path. The description adds no further semantics such as whether a relative or absolute path is expected, or what happens with an invalid path. Baseline 3 applies when the schema does the work.

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 concrete verb+resource: it packages a project's raw evidence (file tree + content excerpts + heuristic profile) into a layout brief for AI inference. It clearly differentiates from regex-based analysis and names the downstream tools it feeds (story_apply_layout_verdict, story_auto_refactor_structure). It does not disambiguate against the sibling story_export, which an agent might reasonably confuse with this.

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 gives an explicit three-step workflow: call this tool, read the brief and infer, then submit the verdict via story_apply_layout_verdict, after which story_auto_refactor_structure with strategy auto_profile consumes the result. The condition selecting this tool over rule-based analysis is stated directly ('thay vì quy tắc regex cứng').

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?

With no annotations provided, the description carries the full burden. It discloses the key behavioral trait: it can either propose entities or automatically create files in the bible/ folder, depending on the confirm flag. It also specifies the output format (Markdown with YAML frontmatter), which is valuable. It does not mention potential overwrites or file system prerequisites, but the primary behavior is transparent.

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 a single concise sentence that front-loads the primary action ('Analyze chapter text') and packs in all essential details (entities detected, two modes, output location, format). There is no redundant or extraneous 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?

The tool has no output schema, so the description should explain what the agent can expect as a result. It says 'create suggestions' but does not specify the return format (e.g., a list, a status, or file paths). It also omits any prerequisites like the existence of the bible/ folder. For a moderate-complexity tool, this is a noticeable 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?

The schema already documents all three parameters (arc, chapter, confirm) with descriptions, including the purpose of confirm (false=preview, true=write). The tool description adds overall workflow context but does not add per-parameter meaning beyond the schema. With 100% schema coverage, the baseline of 3 is appropriate.

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 clearly specifies the tool's function: analyzing chapter text to detect characters and places, then creating suggestions or Markdown files in bible/ with YAML frontmatter. This distinct action differentiates it from sibling tools like story_map_relationships or story_auto_refactor_structure.

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 provides clear context: it is used for analyzing chapter text and extracting entities. It also indicates two modes (preview vs. auto-create) via the confirm parameter, giving clear guidance on when to use each. It does not explicitly mention alternatives or exclusions, but the context is sufficient.

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?

Since no annotations are provided, the description carries a high burden of disclosure. It clearly states the output format (HTML), the location of the file, and the specific metrics compiled, which is valuable behavioral context for a generative tool.

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 delivered in a single, powerful sentence that efficiently communicates the function, the output format, the default location, and the core content of the visualization with zero fluff.

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 that the tool is a high-level synthesis and reporting tool, the description provides all necessary context for an agent to decide if the requested action (e.g., 'show me my story progress') aligns with this specific 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?

The input schema coverage is 100%, providing a baseline score of 3. The description adds clarity by specifying the default file path for the `outputPath` parameter, which is a useful behavioral detail for this optional parameter.

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 is highly specific, clearly stating the tool generates an HTML dashboard. It defines exactly what the dashboard includes (word count, progress, plot holes, Chekhov guns, characters), distinguishing its function as an aggregator from the low-level tools in the sibling list.

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?

While it does not explicitly list alternatives, the description clearly defines its role as a synthesis/reporting tool, implying its usage when a holistic project overview is needed. The context suggests it is used when the goal is review, not data manipulation.

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?

With no annotations, the description must carry the behavioral load. It usefully discloses the input sources it reads (previous chapter, outline, lore, style guide, Chekhov guns), which is real context beyond the schema, but it is silent on whether it mutates state, whether it persists the generated prompt, how large or structured the output is, and what happens if those sources are missing.

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?

A single compact sentence using an arrow to front-load inputs and the result; zero filler. It would be stronger if the disambiguating use case came before the input list. Note the description is in Vietnamese while the tool name, title, and schema wording are mixed, which slightly hurts scanability for an agent working in English.

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 3-parameter, 100%-documented tool with no output schema and no annotations, the description covers the 'what goes in → what comes out' contract but leaves the output shape, whether it is returned or stored, and failure modes unspecified. Adequate but with clear gaps for a tool whose whole value is the generated artifact.

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 arc, chapter, and the strategy enum in full, making 3 the baseline. The description adds nothing about parameters — notably the strategy enum is never referenced, so the agent gets no narrative hint that 'rewrite' vs 'expand' changes what context is gathered.

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 concrete verb ('Tạo' / create) and a concrete artifact ('System Prompt') from a named set of inputs, so the agent knows this aggregates story context rather than writing prose itself. It does not name or contrast with the closest sibling (story_write_chapter), which would be the natural alternative an agent might confuse it with.

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 phrase 'cho lượt viết tiếp theo' (for the next writing turn) implies when to use it, but there is no explicit when-not, no mention of why one would choose this over story_write_chapter or story_query_context, and no stated prerequisites such as an existing arc/chapter.

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?

No annotations are provided, so the description carries the burden. The verb 'view' implies a read-only operation, which is a helpful clue, but it doesn't disclose preconditions (e.g., whether a project must be pointed to) or error behavior. This is minimal but adequate for a simple getter.

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 a single short sentence with no extraneous words. It is front-loaded with the action verb and directly states the resource. Perfectly concise.

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?

There is no output schema, so the description should give some indication of the return value. It only says 'information', which is vague and leaves the agent unsure of the exact fields or structure. For a simple tool this is a minor gap but still incomplete.

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?

The tool has zero parameters, so the schema already fully covers parameter semantics. The baseline for 0 parameters is 4, and the description doesn't need to add parameter details.

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 verb ('view') and resource ('current novel project information'), clearly distinguishing it from sibling tools like story_set_project or story_init. However, it doesn't specify exactly what project information is included, so it falls short of 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 description implies usage when one needs to see the active project's details, but it does not explicitly state when to use this tool vs alternatives or mention any exclusions. This is implied usage, not explicit 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?

With no annotations, the description carries the full burden, and it does disclose the key side effect (creating a standard directory tree plus initial metadata). It does not disclose permission requirements, failure behavior on name collisions, or whether existing directories are overwritten — significant gaps for a mutation tool with zero 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?

A single front-loaded sentence that names the operation and its concrete outputs with no filler. The directory list is high-value detail 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 7-parameter creation tool with no output schema and no annotations, the description should say what is returned and how errors (e.g., existing project) are handled. It covers the write effects but leaves the response contract and failure modes unspecified.

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 includes enum values and a documented default (80000) for targetWordCount, so the schema does the heavy lifting. The description adds nothing about individual parameters beyond what the schema already states; baseline 3 applies.

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 (khởi tạo/tạo) and resource (dự án tiểu thuyết), and enumerates concrete artifacts created (.story/, bible/, manuscript/, outline/). This clearly separates it from retrieval siblings like story_list_projects and story_get_project_info, though it does not name those siblings 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?

The phrase 'dự án tiểu thuyết mới' implies first-time setup, which is useful context for choosing this over story_set_project. However, there is no explicit when-not guidance, no mention of prerequisites, and no statement about what happens if the project already exists.

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?

With no annotations provided, the description carries the burden and does disclose key behavior: results are scoped to the current server session, and entries carry initialization state plus an active project marker. It doesn't state whether an empty list is possible or whether the call has any side effects, which keeps it from a 5.

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?

Two short sentences, zero filler, with the scope-and-contents statement front-loaded and the alternative tool named second. 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 simple no-arg read tool with no output schema, the description conveys enough: what is listed, what metadata comes back, and where to go next. Only the empty-result behavior is left implicit.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly signals that no arguments are needed by describing a plain session-scoped listing.

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?

Specific verb (Liệt kê/list) plus a precise resource and scope: novel projects opened in the server session, with initialization status and the active project called out. This cleanly separates it from story_get_project_info and story_set_project.

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 explicitly routes the agent to story_set_project for switching projects, which establishes the natural pairing. It stops short of stating when-not-to-use or prerequisites, but the context for invocation is clear for a zero-parameter listing tool.

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?

With no annotations provided, the description carries the full transparency burden. It adds useful conceptual context by defining 'unfired' as planted but unresolved, but does not disclose any other behavioral traits such as output format, ordering, or side effects (likely none). This is adequate for a simple listing but not rich.

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 a single concise sentence in the title and one explanatory phrase in the description. It is front-loaded with the action 'Liệt kê tất cả' and contains no redundant or filler text.

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?

The tool has no output schema, so the description should compensate by explaining the return structure. It explains the semantic filter but does not mention what fields or format the list will contain. Given the simplicity of the tool, this is a moderate 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?

The tool has zero parameters, so the baseline is 4. The description adds semantic value by clarifying what 'unfired' means, which helps the agent understand the scope of the listing despite no schema fields to explain.

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 uses the verb 'liệt kê' (list) with a specific resource ('unfired Chekhov guns') and defines the key term as 'details planted but not yet resolved,' clearly distinguishing it from analysis siblings like story_stats or story_query_context.

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 implies the tool lists unfired Chekhov guns but provides no explicit guidance on when to prefer it over similar analysis tools such as story_query_context or story_stats. No alternatives are mentioned, so the usage context is only partially clear.

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?

With no annotations provided, the description must disclose behavioral traits on its own. It only says 'mark' and gives the Chekhov's gun metaphor, but does not explain what happens if the id is invalid, whether it verifies the detail was previously planted, or what the return/response is. This is a significant gap for a write operation.

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 a single, concise sentence that front-loads the core purpose with a memorable metaphor. Every word contributes to understanding, and there is no redundancy or filler.

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?

The description combined with the schema is adequate for a simple logging action, but it lacks guidance on how this tool relates to story_log_setup or story_list_unfired, and does not mention failure modes or postconditions. For a tool with no output schema and simple parameters, this is acceptable but not complete.

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?

The input schema already provides 100% coverage with detailed descriptions for all three parameters (id, payoff, payoffChapter). The tool description itself adds no additional parameter meaning, so the baseline score of 3 applies.

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 clearly states the tool's function: marking a planted detail (Chekhov's gun) as resolved (payoff). It uses a specific verb ('mark' / 'Đánh dấu') and resource (a planted detail), and the metaphor distinguishes it from sibling tools like story_log_setup (which plants details) and story_list_unfired (which lists unresolved ones).

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 implies when to use the tool (when a setup has paid off) but provides no explicit when-to-use guidance or alternatives. It does not mention story_log_setup for planting or story_list_unfired for checking outstanding setups, relying on the name and metaphorical phrasing to convey context.

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?

No annotations are provided, so the description carries the full burden. It conveys that this is a write into a persistent tracking system, but says nothing about required preconditions (active project via story_set_project, story_init), duplicate handling, whether the entry is immutable or later resolved via story_resolve_plot_hole, or what the caller gets back.

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?

A single front-loaded sentence with no filler; every clause (record, new, contradiction/hole, tracking system) contributes to identification of the action.

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?

The schema fully documents the inputs and there is no output schema to explain, so the description only needs to cover behavior and routing. It remains silent on the lifecycle relationship to story_resolve_plot_hole and on project/init prerequisites, which matters for a mutation tool with zero annotation 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 description coverage is 100%, with every one of the four parameters documented in the schema, including an example format for chapters and a default for severity. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.

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 ('Ghi nhận' = record/log) and a specific resource ('điểm mâu thuẫn hoặc lỗ hổng cốt truyện' = plot contradiction/hole), plus the target ('hệ thống theo dõi' = tracking system). The word 'mới' (new) implicitly separates it from the sibling story_resolve_plot_hole, though the sibling is never named 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 only implied: 'mới' signals this creates a new entry rather than resolving an existing one, which contrasts loosely with story_resolve_plot_hole. There is no explicit statement of when to use this versus story_log_payoff or story_detect_timeline_conflicts (which might surface holes automatically), and no prerequisites such as an active project.

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?

Since no annotations are provided, the description carries the full burden. However, it only describes the conceptual action. It offers zero technical behavioral details (e.g., idempotency, how the setup is indexed, what occurs if the chapter doesn't exist). This is a significant gap for a logging/tracking tool.

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 extremely concise and directly addresses the core concept of the tool in a single, highly focused statement. It avoids jargon not related to the specific 'setup' concept.

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?

As a specialized plot tracking tool without any annotations or defined output, the definition is insufficiently complete. It explains *what* it does but fails to provide the necessary context for an agent to handle edge cases or integrate this step reliably into a larger narrative workflow.

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?

The schema description coverage is 100%, meaning the description is redundant in detailing the parameters. While the description reinforces the conceptual nature of the inputs (setup detail, chapter location), it adds little semantic value beyond what the schema already dictates.

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 title and description clearly define the tool's purpose as logging a specific narrative element ('Chekhov's Gun'/'setup'). It successfully differentiates itself from `story_log_payoff` by focusing on the initial setup rather than the subsequent resolution.

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 implies the appropriate time to use the tool (when a setup requires future payoff), which provides moderate guidance. However, it offers no explicit exclusions or comparison to other methods of logging plot ideas.

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?

With no annotations, the description carries the full burden, and it discloses the key trait that this tool writes/updates a persistent file (.story/relationships.json), plus the auto-scan trigger and the EXTRACTED/INFERRED provenance labeling. It leaves out whether existing relationships are overwritten or merged, permission needs, and reversibility, keeping it from a 5.

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?

Three compact sentences, front-loaded with the core action and destination file, then mode behavior, then the provenance vocabulary. No filler, though the provenance-label sentence is somewhat tangential to 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?

For a 6-parameter, no-required, mutation-style tool with no annotations and no output schema, the description covers modes and labeling but omits what the tool returns and whether an existing relationships.json is replaced or merged—material gaps an agent would want before calling it.

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 every parameter including the blank-source/target auto-scan behavior and minChapters. The description largely restates those points and adds little new syntax or format meaning, so the baseline 3 applies.

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: analyzes the manuscript and auto-updates a character-relationship graph persisted to .story/relationships.json. This clearly distinguishes it from most siblings, though it does not explicitly differentiate from the related story_track_character_state or story_extract_entities_to_bible tools.

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?

Explains the two operating modes (targeted pair when source/target are supplied vs. full-manuscript auto-scan when they are blank) and the minChapters threshold, which is real mode-selection guidance. However, it gives no when-not-to-use guidance and never routes the agent to or away from sibling tools like story_track_character_state.

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?

With no annotations at all, the description carries the full burden and does a good job: it discloses that this is a destructive delete of on-disk snapshots, that confirm=false means preview-only, and that the newest snapshot plus recent pre-rollback backups are protected unless thresholds are exceeded. It stops short of stating irreversibility or what exactly the preview reports.

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?

Three tight sentences with the resource/risk front-loaded and the safety guarantee last; nearly every clause earns its place, though the disk-bloat rationale could be trimmed.

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 destructive, zero-annotation tool with no output schema, the description covers purpose, default-safe behavior, and retention guarantees. It leaves minor gaps around what the dry-run preview returns and whether deletion is reversible.

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 each parameter is already documented, so the schema does the heavy lifting. The description paraphrases keepLast and the confirm/dry-run behavior, adding minimal information beyond 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?

Names a specific verb+resource (prune old snapshots in .story/snapshots/) and explains the reason (full-copy snapshots bloat disk). It does not explicitly name story_snapshot or story_rollback as the create/restore counterparts, so sibling differentiation is implied via the pre-rollback backup mention rather than stated.

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?

Clearly frames the workflow: default dry-run preview, then confirm=true to actually delete, and retain the N most recent. It gives safe-usage context but no explicit 'do not use when' exclusions or pointers to alternatives.

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?

No annotations exist, so the description carries the full burden and it falls short. It never states that the tool is a read operation, that rebuildIndex writes/replaces the .cbm/index.json file on disk, or how truncation behaves when the token budget is exhausted (which content gets dropped). The phrase 'tối ưu nhất' asserts quality without explaining the selection or ranking behavior.

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?

Two sentences, the core capability front-loaded, and the mode switch placed second. Nothing is padding, though 'tối ưu nhất' is unverifiable marketing rather than information, which keeps it from a 5.

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 six-parameter tool with no annotations and no output schema, the description leaves too much unsaid: it does not describe what the returned 'Context Budget' looks like (synthesized prose, entity list, graph slice?), how query and from/to modes interact, or the cost/impact of rebuildIndex. The agent must open the schema and guess the rest.

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 all six parameters (query, from, to, maxDepth, budgetTokens, rebuildIndex) are already documented in the schema, establishing the baseline of 3. The description's mention of from+to merely restates what the schema already says and adds no format, interaction (from+to vs query precedence), or unit detail beyond it.

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 action (extract and synthesize an optimal Context Budget) and the sources it draws from (Bible + Relationships + Timeline in a Knowledge Graph), which is far more informative than the bare name 'story_query_context'. The second sentence carves out a distinct second mode (from+to shortest relationship path). It stops short of explicitly contrasting itself with siblings like story_map_relationships or story_generate_writing_prompt, so differentiation is only partial.

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 sentence 'Truyền from+to để hỏi đường liên hệ ngắn nhất giữa hai nhân vật' does give a concrete condition for the path-query mode, so usage is more than bare implication. However, it never says when to prefer this tool over story_generate_writing_prompt, story_map_relationships, or story_extract_entities_to_bible, nor when not to use it. The rival-sibling exclusions an agent would need are absent.

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?

With no annotations, the description must carry the behavioral burden. It usefully discloses that the response includes derived data (word count, scene title list) beyond raw content, but says nothing about the response format, what happens when the arc/chapter doesn't exist, or whether an active project is required.

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?

A single well-formed sentence that front-loads the primary action and then lists the secondary return data. No filler, though the brevity borders on under-specification rather than tightness.

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 two-parameter read tool with a fully documented schema, no annotations and no output schema, the description covers the core action and hints at the return payload. The remaining gaps (error cases, project context) are minor for this level of complexity.

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 both parameters (arc, chapter) have examples in the schema, so the description correctly does not need to restate them. It adds no additional semantics such as whether names are paths, case-sensitive, or matched against the current project.

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 ('Đọc toàn bộ nội dung') and resource (a story chapter), plus what comes bundled with it: word count statistics and a list of scene titles. That makes it easily distinguishable from the write-side sibling story_write_chapter, though it never names an alternative.

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?

There is no guidance on when to call this versus story_query_context, story_stats or story_get_project_info, and no stated prerequisites (e.g. whether a project must first be selected via story_set_project). The only cue is the implicit read semantics of the verb.

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?

No annotations are provided, so the description must carry the full burden. It only states the action without disclosing side effects, reversibility, required permissions, or return behavior. For a mutation tool, this is a significant gap.

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 a single, concise sentence with no unnecessary wording. It front-loads the core action and leaves nothing ambiguous in terms of length.

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 no annotations and no output schema, the description is too terse. It does not explain what the tool returns, when it should be used relative to sibling tools, or any behavioral nuances. The schema documents parameters but not the broader operational context.

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%, meaning all parameters are documented in the schema. The description adds no additional meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

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 uses a specific verb ('resolve') and resource ('plot hole') and specifies the two possible states ('resolved or won't-fix'). This clearly distinguishes it from the sibling tool story_log_plot_hole, which likely handles creating/logging plot holes.

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 usage context is implied by the verb 'resolve' and the presence of sibling tools, but the description does not explicitly state when to use this tool versus alternatives like story_log_plot_hole, nor does it mention any prerequisites or exclusions.

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?

With no annotations, the description carries the full burden. It states the action but does not disclose that rollback is destructive, irreversible, or that a confirmation/preview step exists. The confirm parameter's semantics are only in the schema, leaving a significant transparency gap for a mutation tool.

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 a single efficient sentence with no redundant wording, clearly naming the action and source. It could include a safety note without sacrificing brevity, but it is appropriately concise for the information it conveys.

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?

The tool's two-phase confirm flow (preview vs execute) and potential destructiveness are absent from the description. Given the absence of annotations and output schema, the description is under-specified for a rollback operation of this complexity.

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%, with both parameters clearly described. The tool description adds no additional parameter meaning beyond what the schema provides, so baseline 3 is appropriate.

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 clearly states the tool restores a project to a prior snapshot, identifying the storage location. It is distinct from sibling story_snapshot (which creates snapshots), though it does not explicitly name the alternative. The phrase 'previous snapshot' slightly undersells that any snapshot can be selected via snapshotId.

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?

No guidance is given on when to use rollback versus sibling tools like story_snapshot. There is no mention of scenarios, prerequisites, or exclusions. The only usage hint (preview vs execute) comes from the schema, not the description.

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?

With no annotations, the description carries the full behavioral burden. It usefully discloses that the scan detects duplicates, recognizes encoding, and classifies files with confidence scores, but it does not state whether files are modified, moved, or merely reported on, nor does it mention permissions or safety characteristics.

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 a single efficient sentence with the core action and outputs front-loaded. Every listed item earns its place by describing a concrete scan capability.

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?

There is no output schema, so the description should explain what a scan returns. It names the classification groups and confidence scores, which is helpful, but it does not describe the response structure, whether results are persisted, or how duplicate/encoding findings are reported.

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 both path and detectDuplicates are already documented in the input schema. The description implies that path is the project directory to scan and that duplicate detection is part of the operation, but it adds no syntax or behavioral detail 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?

The description states a specific verb (scan) and resource (messy novel project), then lists concrete operations: duplicate detection, encoding recognition, and classification into four file groups with confidence scores. It is clear what the tool does, though it does not explicitly differentiate itself from sibling tools such as story_list_projects or story_get_project_info.

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 only contextual cue is that the project is 'messy', but there is no explicit guidance on when to use this scan versus alternatives like story_list_projects, story_get_project_info, or story_init. No exclusions, prerequisites, or alternative-routing instructions are provided.

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?

With no annotations, the description usefully discloses a non-obvious behavior: automatic detection and rejection of code projects (Node.js, Python, Rust) to avoid wasted resources, plus the force escape hatch. It omits what the failure response looks like and whether the setting persists to config, so the mutation's side effects remain partially undisclosed.

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?

Three short sentences, front-loaded with the core action before the validation caveat. The force sentence slightly duplicates the schema field description, keeping it just short of a 5.

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 simple two-parameter tool with full schema coverage and no output schema, the description covers purpose, the validation trap, and the override. Only the return/error semantics on rejection are missing, which is a minor 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 description coverage is 100%, so both parameters are already documented, including force's meaning ('Bỏ qua kiểm tra loại dự án'). The description essentially restates the schema's force semantics rather than adding new detail, so the baseline 3 applies.

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 verb and resource ('Thiết lập hoặc chuyển đổi dự án tiểu thuyết đích' – set/switch the target novel project), which is concrete. It does not explicitly name the contrasting siblings (story_init, story_list_projects, story_get_project_info), so differentiation is implied rather than stated.

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 gives one actionable condition ('Dùng force=true để bỏ qua kiểm tra' – use force to skip the check), which tells the agent when to override validation. However, it never says when to use this tool versus story_init or story_list_projects, leaving the primary routing decision 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?

With no annotations provided, the description carries the behavioral burden. It discloses the write action to a specific directory and the non-destructive intent (creating a snapshot for rollback). It does not mention file naming or overwrite behavior, but the core behavior is adequately transparent.

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 a single, front-loaded sentence that directly states the action, target, and purpose. No wasted words or redundant 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?

For a simple tool with two optional parameters and no output schema, the description covers the essential context: what it does, where it writes, and why. It could mention that `story_rollback` consumes these snapshots, but the sibling list and 'rollback' mention make this reasonably discoverable.

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%, with both `label` and `description` already documented in the input schema. The tool description adds no additional parameter semantics, so the baseline score of 3 is appropriate.

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 clearly states the action ('save snapshot') and the resource ('current project state') with a specific destination (`.story/snapshots/`). It distinguishes the tool from siblings by tying it to rollback functionality, which is not claimed by any other tool.

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 phrase 'so can rollback when needed' indicates when this tool is appropriate (before changes that may need to be undone). It lacks explicit exclusions or alternative suggestions, but the context is clear enough for a simple snapshot creation tool.

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?

No annotations are provided, so the description must carry full weight. It discloses the tool's output metrics but does not mention whether it performs a read-only operation, requires a prior story_init, or interacts with project state. This leaves some behavioral ambiguity.

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 a single sentence that front-loads the primary action (statistics) followed by concrete metrics. Every element adds value—total words, velocity, goal completion, and arc/chapter breakdowns—with no redundant or filler language.

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 zero parameters and no output schema, the description carries the responsibility of explaining return content. It lists the main statistic categories and per-arc/chapter detail, but does not specify the exact structure (e.g., relative vs absolute percentages, formatting, or whether aggregates and details are combined). This is a minor gap for an otherwise straightforward 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?

The tool has zero parameters and the schema's property list is empty, so there are no parameter meanings to add. Per the baseline rule for 0-parameter tools, a score of 4 is appropriate—the description correctly focuses on what the tool returns rather than inputs.

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 uses a specific verb 'Thống kê' (statistics) and clearly identifies the resource and scope: total word count, writing velocity, goal completion percentage, and per-arc/chapter details. This distinguishes it from sibling analysis tools like story_analyze_pacing and story_analyze_voice, which focus on qualitative or different quantitative metrics.

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 implies usage when narrative statistics are needed but does not explicitly state when to use this tool over alternatives or mention prerequisites like an initialized project. There are no exclusions or alternative tool references, leaving the agent to infer context from the metric list.

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?

No annotations exist, so the description carries the full behavioral burden, and it does not say whether a 'log' replaces or appends to prior chapter state, whether history is retained or mutable, or what the call returns. The phrase 'theo từng mốc chương' hints at per-chapter versioning but never confirms write semantics for a mutation tool.

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?

A single front-loaded sentence with the verb pair first and the tracked facets in a parenthetical, so nothing must be read twice. The parenthetical partially restates schema field descriptions, which is the only mild 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?

For a 4-parameter tool with a nested state object, no output schema, and no annotations, the description covers what is tracked but not the consequences of logging, the shape of the query/history response, or how state interacts with chapter. Adequate to select the tool, insufficient to call it confidently.

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 character, chapter, action, and every state sub-field. The description's parenthetical field list mirrors those schema descriptions without adding syntax, format, or interaction rules (e.g., whether state is required for action=log). Baseline 3 applies.

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 pair (ghi nhận / truy vấn) and resource (trạng thái nhân vật) plus the grain (theo từng mốc chương), and enumerates the tracked facets (location, inventory, injury, known secrets). An agent can distinguish it from story_track_emotion or story_query_context by those facets, though no sibling is named 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?

The record-or-query duality is stated, but the actual choice is delegated to the action enum rather than to guidance about when to log vs. query vs. history. The trailing 'để đảm bảo tính liên tục (continuity)' gives motivation but no exclusion against sibling tools like story_track_emotion or story_query_context.

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?

No annotations, so the description must carry the behavioral burden. It signals that the tool is stateless and context-free ('quick', 'no project context needed'), which usefully tells the agent it can be called without setting up a project. It says nothing about whether results are persisted, cost, or output shape.

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?

Two short sentences, no filler, with the key constraint (no project context needed) stated up front. Slightly under-specified rather than verbose, but structurally sound.

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 single-parameter, no-output-schema tool this is nearly adequate, but with two near-identical siblings and no annotations the description should explain what makes this analyzer different and what a caller gets back. Those gaps matter for correct selection.

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?

Only one parameter and schema description coverage is 100%, so the schema already documents 'text' fully. The description adds nothing beyond it, which is the expected baseline for full schema coverage.

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: analyze emotion and tone of a text passage. But it does not distinguish itself from the very close siblings story_analyze_sentiment and story_analyze_voice, leaving the agent unable to tell which analyzer to pick. 'Quick' and 'no project context' hint at scope but never establish the boundary.

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?

'Không cần context dự án — chỉ cần đưa vào đoạn văn' gives an implied usage condition (use when you have a standalone snippet and no project state). No explicit exclusion against story_analyze_sentiment or story_analyze_voice, so the sibling decision 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?

No annotations are provided, so the description carries the full burden. It does disclose two meaningful behaviors beyond the schema: an automatic safe snapshot backup before overwriting an existing chapter, and progress recording ('ghi nhận tiến độ viết'). It does not state what the tool returns (file path, snapshot id, progress delta), whether overwrites are irreversible, or any failure modes.

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?

Two short sentences, zero filler, with the destination path stated first and the side effects (snapshot, progress) following. Nothing can be removed without losing 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?

For a 5-parameter mutation tool with no annotations and no output schema, the description covers destination and side effects but omits the return value and any overwrite/error semantics. Those gaps matter more here precisely because structured fields supply no safety or return information.

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 would be 3. The description adds meaning by showing how arc and chapter compose into the output path template, and it explains autoSnapshot's real effect (backup before overwrite) rather than just restating the flag. The remaining 'title' parameter and the shape of 'content' gain nothing extra.

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 verb pair (lưu/cập nhật = save/update) and a concrete resource (chapter content written to manuscript/<arc>/<chapter>.md), so the agent knows exactly what the tool produces. It does not explicitly distinguish itself from the sibling story_append_scene, which also mutates chapter text, so it stops short of 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 phrase 'nếu sửa chương cũ' (if editing an existing chapter) implies the create-vs-update condition, which is useful. However, there is no explicit guidance on when to use this instead of story_append_scene, story_snapshot, or story_rollback, which are the closest overlapping siblings.

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