story-architect-mcp

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 discloses what metrics are returned (ratios, tension curve, scene beats) but does not mention whether the tool is read-only, side effects, or return format. For an analysis tool, the described outputs give reasonable transparency, but safety and response structure are unstated.

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, focused sentence that front-loads the key metrics. No fluff or redundancy; every word contributes meaning.

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?

Despite no output schema, the description explicitly enumerates the outputs (ratio, tension curve, scene beats), making the tool's results predictable. For a lightweight analysis tool with two simple parameters, this is adequate context, though a note on return structure or usage examples would push it higher.

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 'arc' and 'chapter' parameter descriptions provided. The main description adds context about what the analysis measures but does not elaborate on the parameters themselves beyond the schema. Baseline 3 applies since the schema handles 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 clearly states the tool measures action/dialogue/description ratios, tension curve, and scene beats, specifying the verb 'measure' and the resource (pacing). It is specific enough to distinguish from sibling tools like story_analyze_voice, though it doesn't explicitly name the distinction.

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 for pacing analysis but does not explicitly state when to use this tool versus alternatives. The parameter description hints at analyzing an entire arc vs. a specific chapter, providing some context, but no explicit when/when-not guidance is given.

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 disclose behavioral traits. It mentions the comparison to style_guide.json but does not state whether the tool is read-only, what it returns, or what happens if the style guide is missing. This is a significant disclosure gap for an analysis 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, information-dense sentence that front-loads the main verb and lists key analysis dimensions. No wasted words, though the phrase 'so with' is a minor bilingual artifact but does not detract from clarity.

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 or annotations, the description should explain return values or side effects. It does neither, and also doesn't mention dependencies like the style_guide.json file's existence. This leaves the agent under-informed about expected behavior.

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 both arc and chapter with complete descriptions. The description adds no extra parameter semantics beyond indicating the analysis scope. Baseline 3 applies due to 100% 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?

The description clearly states the tool analyzes writing voice (sentence length, vocabulary, POV, tense) and detects voice drift against style_guide.json. This is a specific verb+resource pairing that distinguishes it from sibling tools like story_analyze_pacing.

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 use case—checking voice consistency against a style guide—but does not explicitly state when to use it versus alternatives, nor any exclusions. It mentions arc and chapter parameters, which gives context but no explicit selection 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?

The description discloses that it is a refactoring operation and supports dry-run preview, which is useful. But it does not elaborate on the nature of the changes, potential for moving files, or reversibility beyond the schema's mention of snapshot. Since annotations are absent, more behavioral detail would be beneficial.

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 two short sentences, front-loaded with the primary purpose and followed by a key usage note. It is efficient, though it could be slightly more informative without becoming verbose.

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

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

Given the tool's complexity (restructuring directories), the description provides a basic overview but lacks details about what the preview output looks like or what the actual restructuring entails. It is adequate but has room for improvement.

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 covers all parameters with descriptions (100% coverage), so the description does not need to add much. It adds the dry-run/confirm detail, but that is already in the schema. No extra semantic value is provided beyond the baseline.

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 it 'classifies and standardizes the novel project folder structure according to the standard layout' which is a specific verb and resource, distinguishing it from sibling tools like story_scan_messy_project or story_init. It is unambiguous.

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?

Mentions dry-run mode (confirm=false) to preview before executing, which gives context on safe usage. However, it does not explicitly state when to use this tool versus alternatives or provide exclusions, so guidance remains implied rather than explicit.

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 present, so the description carries the full burden of behavioral disclosure. It mentions analysis and chart generation but omits the fact that the tool accepts an optional 'addEvent' parameter, implying it can modify the timeline. This is a significant undisclosed side-effect for a tool that might otherwise appear read-only.

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 two concise sentences, front-loaded with the core action (analyze) and the output (Gantt chart). No unnecessary words or repetition.

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 adequately covers the main purpose of conflict detection and Gantt generation. However, given the presence of an optional nested 'addEvent' parameter and no output schema, it would be more complete if it explained the event-adding behavior and the expected response format. Still, the core functionality is clearly captured.

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 schema includes descriptions for 'addEvent' and all its nested properties. The description adds no parameter-level detail, but per the baseline rule this is acceptable when the schema is fully self-explanatory.

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: analyze absolute and relative timeline milestones and events to detect conflicts, then output a Mermaid Gantt chart. This specific verb+resource pairing distinguishes it from sibling analysis tools like story_analyze_pacing or story_analyze_voice.

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 that this tool is for detecting timeline conflicts and generating a visualization. It does not explicitly name alternatives or exclusions, but the intended use case is evident from the purpose statement.

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 disclose side effects and return values. It states the output is a markdown file but does not mention whether this overwrites files, requires write permissions, or returns a path. It also omits that a story project must be set prior to export, leaving the agent without critical behavioral 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?

The entire description is a single, front-loaded sentence with no filler. It communicates the core purpose, output format, and contents in about 15 words, earning the maximum score.

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

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

Given the absence of an output schema and annotations, the description is not complete. It fails to explain what the tool returns (e.g., success message, file path), requirements (active project), and edge cases. The provided information is enough for a basic understanding but insufficient for safe invocation.

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

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

All three parameters have descriptions in the schema (100% coverage), so the baseline is 3. The description's mention of 'mục lục' (table of contents) overlaps with includeOutline, but its phrasing 'kèm mục lục' (with TOC) conflicts with the schema default of false for includeOutline. This inconsistency slightly confuses rather than adds value.

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 specific verb 'Đóng gói và xuất bản' (package and publish) with the object 'toàn bộ tác phẩm' (entire work), making it clear this is an export tool. It distinguishes from siblings which are project management/analysis tools. The phrase 'file markdown hoàn chỉnh kèm mục lục và thông tin tác giả' specifies the output format precisely.

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 does not explicitly name alternatives or state when to use this tool over others, but the verb 'xuất bản' (publish) clearly implies an export use case. Among sibling tools focused on project configuration, analysis, and refactoring, the export purpose is unambiguous. However, it lacks explicit guidance on prerequisites such as an initialized 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?

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?

With no annotations provided, the description bears full responsibility for disclosing behavior. It indicates reading inputs and creating a prompt, but does not mention whether the tool has side effects on project state, requires an initialized project, or persists the generated prompt. This leaves important 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, compact sentence with a clear input-to-output flow, front-loading the key purpose. It is concise and well-structured, with no wasted words.

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 lacks an output schema, and the description does not specify the return format (e.g., raw text prompt) or explain how the `strategy` parameter (continue/rewrite/expand) changes the generated prompt. While the core purpose is clear, these gaps reduce completeness for an agent deciding how to handle the tool's output.

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 documents all three parameters with descriptions, including the strategy enum, achieving 100% schema coverage. The tool description adds no additional parameter-specific information, 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 tool reads previous chapter, outline, lore, style guide, and Chekhov Guns, and creates a polished System Prompt for the next writing turn. This distinctive purpose separates it from sibling tools that manage project structure, export, or analysis.

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 use before a writing turn ("cho lượt viết tiếp theo") but does not explicitly state when to use this tool versus alternatives like story_analyze_pacing or story_query_context. No when-not-to-use guidance is 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?

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?

Không có annotations, mô tả phải tự đảm bảo minh bạch hành vi. Nó chỉ nói 'tạo cấu trúc thư mục và metadata' nhưng không đề cập đến việc có ghi đè dữ liệu cũ không, yêu cầu quyền, tính an toàn khi thư mục đã tồn tại, hay hậu quả của việc chạy nhiều lần.

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?

Một câu duy nhất, ngắn gọn, front-loaded với hành động chính và liệt kê các cấu trúc cụ thể. Không có từ thừa hay lặp lại thông tin đã có trong schema.

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?

Tool có 7 tham số, không có output schema, và mô tả chỉ nói về hành động tạo lập. Nó thiếu thông tin về kết quả trả về (ví dụ: project info) hoặc các bước tiếp theo, nhưng với một tool khởi tạo đơn giản thì mức độ này tạm đủ.

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 mô tả 100% tham số với đầy đủ description, nên baseline là 3. Mô tả tool không thêm thông tin cụ thể về cú pháp hoặc quan hệ giữa các tham số, chỉ khái quát 'metadata ban đầu'.

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?

Mô tả rõ ràng với động từ cụ thể 'Khởi tạo' và tài nguyên 'dự án tiểu thuyết mới', kèm chi tiết cấu trúc thư mục chuẩn (.story/, bible/, manuscript/, outline/) và metadata ban đầu. Điều này phân biệt rõ với các sibling như story_set_project hay story_scan_messy_project vì nó tạo mới từ đầu.

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?

Từ 'mới' ngầm cho biết dùng khi bắt đầu dự án, nhưng không nêu rõ khi nào không nên dùng, hoặc so sánh với các tool thay thế như story_scan_messy_project cho dự án đã tồn tại. Không có hướng dẫn loại trừ rõ rà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 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 present, so the description carries full behavioral disclosure burden. It does convey that a new entry is created ('mới'), indicating an append operation, but it omits other traits like duplicate handling, authorization needs, or return format. For a write operation, this provides only minimal transparency.

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 action and object, with no unnecessary words. It earns its place completely.

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 and no annotations, so the description is the only source of contextual information. While the simple logging purpose and rich schema parameter descriptions partially compensate, the description does not mention expected return values or side effects, leaving a moderate gap in completeness.

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 provides descriptions for all four parameters (title, chapters, severity with enum and default, and description), achieving 100% coverage. The tool description adds no parameter-specific guidance beyond what the schema already contains, so it meets the baseline for high 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?

The description uses the specific verb 'Ghi nhận' (record/log) and identifies the resource as 'điểm mâu thuẫn hoặc lỗ hổng cốt truyện' (contradiction or plot hole) with a destination 'hệ thống theo dõi' (tracking system). This clearly distinguishes the tool from siblings like story_resolve_plot_hole, which handles resolution rather than creation.

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 clearly implies this tool is for recording new plot holes, providing clear context. However, it does not explicitly state when not to use it or mention alternatives such as story_resolve_plot_hole or story_log_setup, so it lacks explicit exclusions or alternative 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?

No annotations are provided, and the description only says 'mark' without disclosing side effects, persistence, prerequisites, or reversibility. As a state-changing operation, this leaves too much 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 one concise, well-structured sentence with a clarifying dash. It is front-loaded with the action and uses no filler, making it highly 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?

Given the tool's simplicity and full schema coverage, the description is minimally viable. However, it lacks context about how setups integrate with the broader project workflow (e.g., listing unfired setups) and what the operation returns, leaving gaps for an agent.

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 itself adds no additional parameter semantics, matching the baseline score of 3.

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 ('Đánh dấu' / mark) and resource ('chi tiết cài cắm mới' / new planted detail), and explicitly ties it to Chekhov's Gun needing a future payoff. This clearly distinguishes it from siblings like story_log_payoff and story_log_plot_hole.

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: use this tool when introducing a setup that will require a payoff later. However, it does not explicitly reference alternatives or exclusions, so it gets a 4 rather than a 5.

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

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

The description discloses a key side effect: it automatically updates a file at .story/relationships.json. However, it does not clarify whether relationships are appended, overwritten, or deduplicated, nor does it mention any prerequisites or return behavior. With no annotations provided, the description carries the full burden of behavioral transparency and falls short.

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, which is brief and front-loaded, but it is under-specified and introduces ambiguity with 'analyze the manuscript'. It is concise in length but not in clarity, so a score of 3 reflects that it is not an effective use of the single sentence.

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 and no annotations, the description needs to explain what the tool accepts, what it does, and what the user should expect in return. It only mentions updating a file and does not cover the mandatory parameters, the editing flow, or the response format. This is inadequate for a tool with side effects.

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 descriptions for all 5 parameters, including the enum for type. Since schema description coverage is 100%, the description adds no extra meaning beyond what the schema provides, matching the baseline of 3.

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 it updates the character relationship graph, citing the specific file .story/relationships.json. However, the phrase 'Phân tích bản thảo' (analyze the manuscript) is ambiguous and not reflected in the input schema, which instead expects explicit source, target, and type parameters. This creates confusion about whether the tool analyzes a manuscript or simply records a provided relationship.

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 provided on when to use this tool versus alternatives like story_extract_entities_to_bible or story_scan_messy_project. The description gives no context about whether it is intended for adding one relationship at a time, batch processing, or analyzing an entire manuscript.

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 of behavioral disclosure. It only mentions extraction and synthesis but does not disclose whether the tool is read-only, whether it modifies state, how it selects content, or what the return format looks like. 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 sentence that is concise and front-loaded with the core action. However, it is a dense run-on with many components in parentheses, which slightly reduces readability. Still, it avoids unnecessary words.

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

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

Given the lack of annotations and output schema, the description should explain more about what the tool returns and how the token budget is enforced. It doesn't mention the response format, whether the summary is a list or prose, or how 'optimal' is determined. This leaves the agent guessing about expected behavior.

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% for both parameters (query and budgetTokens), and their descriptions are clear. The description adds context about what types of content are included (Lore, Characters, etc.), but it does not add extra meaning to individual parameters 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 clearly states the tool extracts and synthesizes an optimal context budget from specific story components (Lore, Character Profiles, Timeline, Foreshadowing, Plot Holes) within a token limit. It distinguishes itself from sibling tools by being the only context query/synthesis tool, though the term 'Context Budget' is not fully explained.

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: the tool should be used when you need a token-budgeted context summary for a query. However, it does not explicitly state when to use it over sibling tools like story_get_project_info or story_analyze_pacing, nor does it provide 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?

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 must carry the full behavioral disclosure burden. It mentions duplicate detection, encoding identification, and classification with confidence scores, which are useful. However, it does not explicitly state whether the scan is read-only, whether files are modified, or how the confidence score is derived. This leaves some 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, compact sentence that front-loads the main action ('scan') and enumerates key behaviors. Every phrase earns its place with 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?

Given no output schema, the description does not explain the return value or output format beyond stating 'classification with confidence score'. For a complex scanning tool that detects duplicates, encoding, and classifies files, more detail about the result structure would be helpful. The core purpose is covered, but the output behavior is underspecified.

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

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

Schema coverage is 100%, so the baseline is 3. The description mentions duplicate detection, which aligns with the detectDuplicates parameter, but it does not add extra meaning about the path or when to disable duplicate detection. It does not go beyond the schema descriptions.

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 scans the entire messy novel project and lists specific actions: detect duplicates, identify encoding, and classify files into 4 groups with confidence scores. This specific verb+resource combination distinguishes it from sibling tools like story_get_project_info 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 phrase 'messy project' implies it should be used when a project is disorganized, but there is no explicit when-to-use guidance or comparison with alternatives. It lacks exclusions or references to sibling tools that might serve similar purposes.

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. It does state that the tool changes the active project and avoids a restart, which is useful. However, it does not mention validation behavior, whether the path must exist, or effects on subsequent operations. For a mutation tool, this is minimal but not misleading.

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 two short sentences, front-loaded with the primary action and includes the key non-restart benefit. No wasted words; every sentence earns its place.

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

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

For a simple setter with one parameter and no output schema, the description is mostly complete. It explains the core function and an important operational benefit. It could optionally mention whether the path must exist or how errors are handled, but given the simplicity, it is sufficient.

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 parameter's description already explains that it is a path (absolute or relative to cwd). The tool description adds no additional parameter semantics, so the schema carries the burden. 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's function: 'Set or switch target novel project' with a specific verb and resource. It distinguishes itself from siblings by being the only tool that changes the active project path, and adds the benefit of no server restart needed.

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: whenever you need to set or switch the active project. It also highlights a key advantage over alternatives ('without restarting MCP server'), but does not explicitly mention when not to use it or list alternatives. That said, the usage context is clear for a simple setter.

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.