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

Annotations indicate the tool is not read-only, is idempotent, and non-destructive. The description adds that it returns build and captured output but does not elaborate on side effects or state changes beyond 'rebuild'. This is partially covered by annotations, but the description itself adds limited transparency about 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?

The description is concise, consisting of two short sentences that convey the action and the return value without unnecessary details. It is well-structured and to the point.

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 parameters and output schema, the description adequately explains what the tool does and what it returns. It could specify the exact format or nature of the 'build' output, but for a parameterless tool this 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?

There are no parameters in the schema, so coverage is trivially 100%. The baseline for high coverage is 3, and the description adds no parameter-specific details since none exist.

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 that the tool rebuilds all README files, providing a specific verb and resource. It distinguishes itself from sibling tools that handle configuration, validation, statistics, import, story creation, scanning, and chapter reading/writing, which are unrelated to building READMEs.

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 mentions 'equivalent story build' but does not explicitly specify when to use this tool over alternatives. It lacks guidance on scenarios such as regenerating outdated READMEs or when to prefer this over other operations. The context is implied but not 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?

The description clearly states it creates a new story with a folder, config.json, and text.md draft, which is a write operation. Annotations already indicate not read-only and not destructive, so no contradiction. However, it doesn't mention idempotency or behavior if the story already exists, leaving some ambiguity. The parenthetical adds useful file structure details beyond the simple purpose, but it doesn't cover failure modes or side effects beyond creating files.

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?

Single sentence, clear verb, specific output. Zero waste, front-loaded with main 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 description explains the tool's output (folder + config.json + text.md draft) which is valuable. However, it doesn't mention what happens if the story already exists, or any constraints on naming, or the effect of optional parameters. Given there is no output schema and the tool is a creator, some additional behavioral context would be helpful but not strictly required.

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 descriptions cover all 7 parameters (coverage 100%), so the description doesn't need to add per-parameter meaning. The description adds high-level context that it creates a draft, but the schema already covers each parameter's purpose. 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

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 no guidance on when to use this tool versus alternatives (e.g., import_json, build) or any caveats like

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?

Beyond the annotations, the description discloses that writes are preceded by repository-level schema validation, failed validation means no write, and null values remove optional fields. It also states identity/audit fields cannot be modified. This is valuable behavioral detail; no contradiction with annotations was found.

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 compact and dense, with the purpose in the first sentence and supporting constraints following efficiently. Every sentence adds necessary information without redundancy, making it appropriately sized for the tool's complexity.

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 output schema, the description covers the essential operational behavior: editable fields, removal semantics, validation guarantees, and the required build step. It does not describe return values or error formats, but the given annotations and schema make the description sufficiently complete for selection and 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?

Although the input schema already covers parameter names and basics, the fields object is generic and benefits greatly from the description's explicit enumeration of valid field keys, null semantics, and prohibited fields. This adds real meaning beyond the schema's minimal 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 opens with a specific action—updating story config.json metadata fields—and enumerates the exact editable fields. It clearly distinguishes this tool from siblings like write_chapter or create_story by scoping to metadata and explicitly listing what can and cannot be changed.

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

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

The description gives clear usage context: which fields may be edited, which are forbidden, the null-removal behavior, schema validation, and the follow-up requirement to run build. It does not explicitly name alternatives, but the field restrictions and post-condition effectively guide when to use the 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?

Annotations indicate readOnlyHint=false, idempotentHint=false, destructiveHint=false, meaning the tool is not read-only, not idempotent, and not destructive. The description does not contradict these, but it also does not add much behavioral context beyond what annotations provide. It does not mention potential side effects, error handling, or whether existing stories are overwritten. Given the annotations are present, the description adds minimal extra value.

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 clearly states the purpose and the CLI isomorphism. It is front-loaded with the main action and resource, and there is no wasted text. It earns a high score for efficiency.

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 one parameter with full schema coverage, no output schema, and annotations are present. The description is adequate for a simple import tool, but it could be more complete by mentioning what happens on import (e.g., validation, overwrite behavior) or any prerequisites. Given the simplicity, a 3 is reasonable.

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%: the 'stories' parameter is described as a list of story objects with required 'title' and optional fields. The description adds the context that it is a batch import and isomorphic with CLI, but does not add further parameter-level detail beyond the schema. Baseline 3 is appropriate since the schema already documents the parameter well.

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 imports stories from structured JSON, with a specific verb ('import') and resource ('stories'). It also mentions it is isomorphic with the CLI 'import json' command, which helps distinguish it from sibling tools like create_story or scan_stories. However, it could be more explicit about the exact scope (e.g., batch vs single) but the '批量' (batch) is included.

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 batch importing stories from JSON, and the mention of CLI isomorphism provides some context. However, it does not explicitly state when to use this tool versus alternatives like create_story (for single story creation) or validate (for validation). No exclusions or alternative tool names are 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?

注解仅有 readOnlyHint=true，描述额外揭示了按需加载和 tailLength 截断尾部内容的行为，并给出了使用目的。未描述返回值结构或缺省行为，但 readOnlyHint 已覆盖安全维度，且未与注解矛盾。

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?

两句话，第一句点明核心功能，第二句解释 tailLength 的目的，无冗余信息，结构紧凑且信息密度高。

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?

工具复杂度低，Schema 与 readOnlyHint 已覆盖参数及安全语义，描述提供了核心使用上下文。未明示返回格式，但 schema 已说明缺省行为，整体对选择与调用足够完整。

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

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

Schema 已覆盖全部 3 个参数（100%），基线为 3。描述对 tailLength 补充了“用于续写衔接”这一使用语义，超出 schema 的节省 Token 说明，增加了额外价值。

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?

描述明确说明工具读取指定故事的章节内容，使用具体动词“读取”和资源“章节内容”，并支持按章节索引按需加载。与 write_chapter、scan_stories 等写/列工具能清楚区分。

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?

描述给出了 tailLength 的明确使用场景（续写衔接、节省 Token），说明按需加载的上下文，但未显式提及与 scan_stories 等替代工具的取舍或排除条件。

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 readOnlyHint annotation already establishes the safety profile, and the description adds useful context about the default concise response and verbose full-detail behavior. It also clarifies that the tool returns all stories, but it does not disclose pagination, sorting, or potential large-result behavior, so transparency is adequate 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, front-loaded sentence that states the tool's core purpose first and then explains the optional parameter behavior. Every clause earns its place, with no repetition of the schema or annotations and no unnecessary 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 the simple one-parameter schema, the readOnlyHint annotation, and the absence of an output schema, the description adequately covers what is returned (concise list vs. full metadata) and the metadata fields. It could be more explicit about what the concise list contains or how large result sets are handled, but for this complexity level it is sufficiently 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 fully documents the verbose parameter, including its default value and meaning (100% schema coverage). The description adds the token-saving rationale but no additional syntax, format, or edge-case details beyond what the schema 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 ('列出') and resource ('所有故事'), and enumerates the metadata fields returned (标题/类型/状态/字数/系列). This clearly differentiates it from siblings like read_chapter, write_chapter, and create_story, which operate on individual stories rather than listing all stories.

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

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

The description gives clear guidance on choosing between the default concise output and verbose=true to save tokens. However, it does not explicitly state when to use this tool versus alternative sibling tools, nor does it mention any exclusions or prerequisites, so the intended usage context is 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?

The readOnlyHint annotation already declares this is a read-only operation, and the description does not contradict it. The description adds context by listing the specific statistics returned, which is useful for anticipating the output, but it discloses no additional behavioral traits (e.g., rate limits, permissions, or response format). With annotations covering safety, the description provides moderate value beyond them.

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 states the exact purpose and enumerates the key output categories. Every word earns its place, with no verbose filler or redundant phrasing. It is concisely structured and immediately understandable.

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 (zero parameters, readOnlyHint annotation, no output schema), the description is fully adequate. It lists the five categories of statistics the agent can expect, which compensates for the absence of an output schema. For a stat-fetching tool with no inputs, this is 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 tool has zero parameters, so the baseline per the rubric is 4. The description doesn't need to document parameter details since none exist, and the schema coverage is trivially 100% with no fields. The description effectively communicates the fixed output scope, compensating for the lack of an output 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 ('获取' = get) and resource ('故事库写作统计' = story library writing statistics), and enumerates the specific metric categories (total words, chapter count, series grouping, health, repeated phrases). This clearly distinguishes it from sibling tools like read_chapter or create_story, which serve different purposes.

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 purpose implies when to use this tool (when writing statistics are needed), but there is no explicit guidance on when not to use it or mention of alternative tools. The decision to use it over siblings is left to the agent based on the clearly stated output scope, but no exclusions or alternatives 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?

The description adds the scope of checks and CLI equivalence, but does not disclose expected behavior on failure, output format, or side effects. Since readOnlyHint=true is already annotated, the read-only nature is covered; the description adds modest context beyond that but no deeper behavioral detail.

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, well-structured sentence that front-loads the action, lists the compliance dimensions, and provides a CLI equivalent. Every element adds value with no redundancy.

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

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

For a simple, zero-parameter, read-only tool, the description covers the core purpose well. However, with no output schema, it omits what the tool returns or how compliance results are reported, which would be useful for an agent deciding next steps after validation.

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 accepts zero parameters, so schema coverage is effectively 100% and no parameter explanation is needed. A baseline of 4 for 0-param tools 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: checking repository compliance, with concrete areas (directory naming, required files, config/schema, encoding). The CLI equivalence ('story validate') adds a precise reference and differentiates it from sibling tools like build or scan_stories.

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 is used for compliance validation but provides no explicit context about when to run it or when to prefer alternatives. No exclusions or alternative-tool references are given, so usage guidance remains only implied.

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

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

Annotations already show non-read-only, idempotent, and non-destructive traits. The description adds atomic-write behavior and the non-blocking validate-after-write behavior, which provide meaningful operational context beyond annotations. No contradiction found.

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 compact sentences, front-loaded with the primary purpose and atomicity, followed by optional validation behavior. Every word earns its place with no filler 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?

Given complete schema coverage, annotations, and moderate complexity, the description is sufficient for correct invocation. It explains the write target and validation behavior, though it does not describe the normal return value; this is acceptable in the absence of an output schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by specifying that content is written to text.md and that validate=true triggers an immediate, non-blocking compliance check, enriching the parameter semantics 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?

Description clearly states the specific action ('将正文写入指定故事') and the target artifact ('原子写入 text.md'), distinguishing it from sibling tools such as read_chapter, edit_config, and validate. The purpose 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?

It does not explicitly state when to use this tool versus alternatives or mention exclusions. It gives useful guidance for the validate flag (non-blocking compliance check), but no comparison with sibling tools or clear when-to-use context.

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