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

The annotations already mark this as a mutating but non-destructive operation. The description adds the key behavioral detail that inputs are copied by default, which is not visible from annotations alone. Secondary effects such as NOTES.md updates are left to the schema, but the core side-effect is disclosed.

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 redundant content. The default-copy clause earns its place as the key non-obvious behavior.

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 plus schema is sufficient to invoke the tool, but it leaves some workflow context unspecified: when to choose cb_branch over related tools, what '同源 inputs' exactly refers to, and what a successful creation returns. For a five-parameter mutation tool with sparse annotations and no output schema, a bit more context would be expected.

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 schema already documents all five parameters, including defaults for from and no_copy_inputs. The description's '默认复制同源 inputs' reiterates the default-copy behavior in more human terms but does little beyond what the schema already provides.

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

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

The description uses a specific verb (创建/creates) with a concrete resource (实验分支/experimental branch) and adds a default behavior (copying inputs). This makes it easy to distinguish from sibling tools like cb_checkout, cb_rename, or cb_discard, which operate on branches rather than create them.

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

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

The intended use is implied by the verb and resource—create an experimental branch—but the description gives no explicit when-to-use guidance or exclusions. It does not mention alternatives such as cb_checkout for switching or cb_promote for integrating, so the agent must infer the usage context from the sibling names.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description reinforces this with '（只读）'. It adds useful behavioral context by naming the exact categories of issues reported: orphan branch directories, missing PROMPT.md, and missing archives. No contradiction with annotations.

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

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

The description is a single compact sentence with the read-only nature and purpose front-loaded, followed by concrete examples of what the tool reports. Every part earns its place and there is no filler or repetition of structured fields.

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 low-complexity, one-parameter read-only tool with output schema and annotations covering safety, the description is essentially complete. The only minor gap is the trailing '等问题' ('etc.'), which leaves the full set of checks imprecisely bounded, but this is a small omission given the output schema exists.

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 single parameter 'root' is fully documented in the schema with 'Conversation Branch 工作区根目录', so schema coverage is 100%. The description does not add extra detail about the parameter beyond connecting it to the workspace being checked, which is acceptable but not additive.

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 ('体检'/'check') and resource ('工作区结构'/'workspace structure'), and lists concrete checks: orphan branch directories, missing PROMPT.md, and archive issues. This clearly distinguishes it from operation-oriented siblings like cb_rename, cb_checkout, and cb_discard.

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 makes the intended use clear—audit the workspace structure for consistency issues—but it does not explicitly state when to choose cb_check over cb_status, cb_diff, or cb_compare, nor does it give any when-not-to-use guidance. Usage is implied rather than stated.

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

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

Annotations already declare idempotentHint=true, readOnlyHint=false, destructiveHint=false. The description adds the behavioral context that the mainline is read-only during experiments and that HEAD determines what can be modified. It doesn't describe side effects like whether working tree changes are preserved or whether checkout fails on dirty state, but the annotations cover the safety profile reasonably.

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?

One sentence, front-loaded with the action and scope, and the parenthetical adds essential context without waste. Every word 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 two-parameter tool with full schema coverage and idempotentHint=true, the description is nearly complete. It explains the conceptual model (HEAD determines what can be modified) which is important for correct use. It doesn't describe return values, but there is no output schema and the tool is simple enough that this 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 (name, root) are already documented in the schema. The description adds no additional parameter-level meaning beyond what the schema provides. 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 states a specific verb ('切换 HEAD') and resource ('到指定分支'), and clarifies that during experiments the mainline is read-only and HEAD determines what can be modified. This is clear enough to distinguish it from sibling tools like cb_branch or cb_check, though it doesn't explicitly name a sibling 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?

The description gives context for when to use it: during experiments, when the mainline is read-only and HEAD determines what can be changed. It implies this is the tool for switching the active branch, but it doesn't explicitly contrast with alternatives like cb_branch or cb_checkout-like siblings. Still, the context is clear enough for an agent to infer usage.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false. The description adds valuable behavioral context beyond annotations: it writes to COMPARE.md (a concrete side effect) and explicitly states it does not modify the mainline. This gives the agent a clearer picture of the operation's scope and safety.

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 (generate multi-branch comparison) and immediately includes the key side effects (writes COMPARE.md, does not modify mainline). Every word earns its place; there is zero 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 tool with one parameter, no output schema, and helpful annotations, the description covers the core function and main side effect. However, it lacks details on what the comparison actually entails (e.g., which branches are compared, what '横向对比' produces), prerequisites, or how the result is structured. It is adequate for a simple tool but not comprehensive.

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 a description for the only parameter 'root' with 100% coverage. The tool description does not add any further parameter semantics, so the baseline of 3 is appropriate—the schema carries the full burden here.

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 clear action ('生成' generate) and a resource (multi-branch horizontal comparison), with a specific output file (COMPARE.md). It is not a tautology and implies a distinct purpose from simple diff tools by emphasizing '多分支' (multi-branch). However, it does not explicitly name a sibling tool, so differentiation is left to inference.

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

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

No guidance is given on when to use this tool versus alternatives like cb_diff or cb_branch. The phrase '不改主线' (does not modify mainline) is a safety constraint, not a usage directive. There are no exclusions or conditions that would help an agent select this tool appropriately.

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 provide idempotentHint=true and destructiveHint=false, and the description adds the meaningful behavior that it writes into the branch's DIFF.md while leaving the mainline untouched. It could further state whether an existing DIFF.md is overwritten, but the side-effect boundary is clear.

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?

One compact sentence that front-loads the action and scope, then states the side effect and safety constraint. No filler or repetition of schema details.

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 four parameters, high schema coverage, and annotations covering idempotence and non-destructiveness, the description supplies the key behavioral context: writing DIFF.md and not touching mainline. It lacks a note on return values, but with no output schema the write side effect is likely the primary result.

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 carries parameter documentation. The description adds the 'parent version (or mainline)' distinction that maps to against/against_main, but it does not elaborate on name constraints or root semantics beyond what the schema already says.

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: generate rule differences between a branch PROMPT and its parent version or mainline, with an explicit side effect (write branch DIFF.md) and exclusion (don't modify mainline). This clearly distinguishes it from siblings like cb_compare and cb_status.

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 a branch-diff artifact is needed and clarifies the main-vs-parent comparison options, but it doesn't explicitly say when to choose cb_diff over cb_compare or other siblings. No alternative tool or exclusion condition is named.

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 mark destructiveHint=true, but the description adds valuable nuance: default behavior archives to archive/, purge causes true irreversible deletion, and HEAD automatically moves to main when its branch is discarded. This is exactly the kind of behavioral context that goes beyond structured annotations.

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

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

Three concise sentences cover purpose, the two modes, mutual exclusivity, default vs purge behavior, and HEAD handling. Every clause contributes necessary information 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 the 4-parameter schema, annotations, and absence of an output schema, the description is complete for invocation: it states required input constraints, destructive behavior, default archival, and edge-case HEAD handling. No critical gap remains for correct use.

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 useful semantics beyond the schema: names and keep are mutually exclusive and one must be provided, and it clarifies the default archive destination (archive/), which is not in the schema. This meaningfully raises the score.

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 clear verb+resource ('舍弃实验分支') and explains the two mutually exclusive modes (names/keep). It does not explicitly name a sibling alternative, but the behavior described (discard vs rename/checkout/promote) is distinct enough to separate it from 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?

The description gives clear prerequisites: names and keep are mutually exclusive and exactly one is required, and purge changes the operation from archive to irreversible deletion. However, it does not explicitly say when to prefer cb_discard over related tools like cb_rollback or cb_promote, so usage guidance vs alternatives is 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?

The description explicitly discloses that the tool does not change workspace state ('不改工作区状态'), which is valuable behavioral context beyond the annotations. Annotations only say readOnlyHint=false and destructiveHint=false, so the description clarifies the actual side-effect profile: it creates an export directory but leaves the workspace untouched. This is meaningful transparency for an export/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 compact sentence that front-loads the core action and immediately states the most important behavioral constraint. It contains no filler, repeated title information, or redundant restatement of the schema. Every phrase 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 tool with full schema coverage and no nested objects or output schema, the description covers the essential context: what is produced, the side-effect constraint, and the intended use case (testing in a new conversation). It could add more about the package's internal structure or post-export steps, but nothing critical is missing for an agent to decide to use it correctly.

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 input schema already documents all three parameters (root, name, to) with useful detail such as naming constraints and the required pre-existing container directory. The tool description itself adds little parameter-level meaning beyond noting the generated directory concept, which is already reflected in the 'to' parameter's description. 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 uses a specific verb-resource pair ('导出分支交接包' / export branch handoff package) and clearly states what is produced: a self-contained directory for a new conversation. It also adds the key distinguishing property '不改工作区状态', which separates it from the mutation-oriented siblings (cb_discard, cb_rollback, cb_promote). No sibling tool appears to offer export functionality, so differentiation from the sibling list is clear.

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 a clear usage context: the package can be handed to a brand-new conversation for testing. However, it does not explicitly state when to prefer this tool over alternatives, nor does it mention any exclusions or prerequisites beyond what the schema already says (e.g., that the container directory must exist). Usage guidance 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?

注解已声明 readOnlyHint=false、destructiveHint=false、idempotentHint=false，描述补充了具体行为（创建 .branches/ 和主线），但没有说明是否覆盖已有文件、是否要求 root 为空、失败时是否部分创建等。描述与注解不矛盾，但行为细节有限。

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?

描述为单句，简洁且信息密度高，直接说明核心行为。但缺少使用场景或注意事项，略有提升空间。

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?

对于初始化工具，描述覆盖了核心行为，但缺少关键上下文：是否要求 root 为空、是否可重复执行、初始化后如何验证（无输出 schema）。考虑到工具复杂度较低，3 分合理。

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 覆盖率为 100%，两个参数（root、prompt）在 schema 中已有描述。描述中提到的 '主线' 与 prompt 参数相关，但没有额外说明 prompt 的格式或默认模板内容。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?

描述明确说明工具的作用：初始化工作区，在 root 下建立 .branches/ 与主线。动词（初始化）+ 资源（工作区）+ 具体行为（建立 .branches/ 与主线）都清晰，且与兄弟工具（cb_branch、cb_checkout 等）明显区分。

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?

描述隐含了使用场景（首次初始化工作区），但没有明确说明何时使用 vs 不使用，也没有提及替代工具或前置条件（如 root 是否必须为空、是否可重复运行）。虽然从名称和描述可以推断，但缺少显式指引。

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the '只读' (read-only) label, which is consistent with annotations. It doesn't add behavioral context beyond that, such as what events are included, ordering, or whether the timeline is filtered by branch. With annotations covering the safety profile, a 3 is appropriate – the description adds minimal behavioral context beyond the annotations.

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

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

The description is a single concise sentence that states the core purpose and read-only nature. It's front-loaded with the key information. It could arguably add a bit more context about what the timeline contains, but for a simple read-only tool, the brevity is appropriate.

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 (2 params, 1 required, no nested objects, output schema present), the description is mostly complete. The annotations cover the safety profile, and the schema covers parameters. The only gap is that the description doesn't explain what kind of events appear in the timeline or how the output is structured, but the output schema likely covers that. For a read-only timeline viewer, this is adequate.

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

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

Schema description coverage is 100%, so both parameters (root and limit) are already documented in the schema. The description doesn't add parameter-level detail beyond what the schema provides. The 'limit' parameter's meaning ('只看最近 N 条事件') is already in the schema, and 'root' is described as the workspace root. Baseline 3 is correct 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 '查看工作区事件时间线（只读）' clearly states the tool's purpose: viewing the workspace event timeline, and explicitly marks it as read-only. It distinguishes itself from sibling tools like cb_diff, cb_status, and cb_checkout by focusing on the event timeline rather than file diffs, status, or branch operations. However, it doesn't explicitly name a sibling alternative, so it doesn't fully differentiate itself from all 14 siblings.

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 context: it's a read-only timeline viewer for the workspace, and the '只读' (read-only) marker suggests it's safe to use for inspection. However, it doesn't explicitly state when to use this tool versus alternatives like cb_status or cb_log. The annotation readOnlyHint=true reinforces the safe-inspection context, but the description itself provides no explicit when/when-not guidance.

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

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

The description only says 'update' and does not explain whether NOTES.md is overwritten, appended to, created if missing, or whether the branch must already exist. Annotations already indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so there is no contradiction, but the description adds very little behavioral context beyond those annotations.

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

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

The description is a single short sentence with no filler, and the core action and target are front-loaded. It is concise, though it sacrifices helpful detail for brevity.

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 note-update operation, the schema and annotations cover parameters and the side-effect profile reasonably well. However, the exact semantics of '更新'—whether it replaces the entire NOTES.md note or updates a specific portion—are not clarified, leaving some ambiguity 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?

The input schema already documents all three parameters (root, name, text) with 100% coverage. The description adds no parameter-specific detail beyond what the schema provides, so the 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 states a specific action ('更新') and a clear target ('分支 NOTES.md 的备注'), which is enough to distinguish this tool from sibling tools like cb_rename, cb_status, cb_log, and cb_diff. Despite being terse, it is unambiguous about what resource is affected.

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 no guidance on when to use this tool versus alternatives, no preconditions, and no exclusions. It only states what the tool does, not the context in which it should be selected.

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 (destructiveHint=true, readOnlyHint=false), the description discloses that the old mainline is archived, the version number is incremented, and the note is written to CHANGELOG.md for audit. This gives an agent a clear picture of side effects and postconditions.

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 front-loads the core operation and then packs in the side effects, approval precondition, and audit requirement. Every clause carries useful information with no 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?

All parameters are documented, annotations are present, and the description spells out the operation, preconditions, and side effects. No output schema is needed for this kind of mutating operation, so nothing critical is missing.

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

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

Input schema already documents all three parameters with 100% coverage. The description reinforces that note is required and auditable, but adds no fundamentally new parameter-level semantics. 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 and resource: promote an experimental branch to become the new mainline, with concrete effects (old mainline archived, version +1). This clearly distinguishes it from sibling tools like cb_branch, cb_checkout, or cb_rollback.

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

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

Explicitly states when this tool is appropriate: promoting an experimental branch to mainline, with mandatory user approval and a required justification note. It does not mention exclusions or alternatives among siblings, so it stops short of a 5.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, implying a mutation that is not destructive, but the description adds no behavioral context beyond the word 'rename'. It does not disclose whether the operation is reversible, whether it updates references elsewhere, or what happens on failure. With annotations present, the bar is lower, but the description still fails to add value beyond the structured hints.

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 phrase with no wasted words. It is appropriately sized for a simple operation, though it lacks richer context. It is front-loaded in that the core action is stated immediately, earning a high score for conciseness even if under-specified in other areas.

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 mutating tool with three parameters and no output schema, the description is incomplete. It does not mention error conditions (e.g., if the branch does not exist), idempotency (annotations say false), or post-rename effects to other workspace state. An agent would need additional information to safely invoke this tool in a real 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?

Schema description coverage is 100%, so each parameter (root, old, new) has a brief semantic description. The tool description itself does not augment parameter understanding. According to the rubric, a baseline of 3 is appropriate when the schema fully documents parameters, and this is the case here, though the descriptions are minimal.

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 clear verb and resource: '重命名实验分支' (rename experimental branch). It is specific enough to distinguish from sibling tools like cb_checkout or cb_branch based on the action. However, it does not clarify what 'experimental branch' means or contrast with other branch types, so it slightly lacks the precision to fully stand apart.

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 use this tool versus alternatives. With a large set of sibling branch tools, an agent gets no indication of when renaming is appropriate, prerequisites (e.g., branch existence), or cases where another operation (e.g., cb_branch) would be better. The description carries no usage direction.

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 flag destructiveHint=true and readOnlyHint=false, so the agent knows this mutates state. The description adds genuinely useful extra context beyond the annotations: the mandatory user-approval gate ('必须由用户明确批准') and the archive-target semantics. It doesn't overstate risks but adds a meaningful operational constraint.

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 that front-loads the core action (rollback mainline to archive) and appends the ref format and approval requirement. No wasted words; the most important behavioral constraint (approval) is well placed at the end for emphasis.

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 rollback with no output schema, the description could state more about consequences: whether the rollback is reversible, what happens to the current mainline state, or whether uncommitted changes are lost. The note field's CHANGELOG behavior is in the schema, but the operational effects of a destructive revert are left 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 all three parameters (ref, note, root) are already documented in the schema. The description adds marginal semantic value by clarifying that ref resolves to an archived version and that user approval is tied to it, but the note and root semantics are already fully covered by the schema. 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 states a specific verb (回滚/rollback), a clear resource (主线/mainline), and a precise target (归档版本/archived version). It's specific enough to distinguish from branch-oriented siblings like cb_checkout and cb_branch, though it doesn't name any sibling explicitly. The action and scope are unmistakable.

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

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

The description gives meaningful usage context: ref may be a version number or an archive directory name, and rollout requires explicit user approval. However, it provides no guidance on when to choose this tool over its alternatives (e.g., cb_checkout vs cb_rollback, or cb_discard for discarding work), and no when-not-to-use conditions.

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 explicitly discloses a non-obvious side effect: despite being a 'view' operation, it rebuilds STATE.md and updates the timestamp in place, while explicitly stating it does not change branch data, version, or HEAD. This provides valuable behavioral transparency beyond the simple boolean annotations.

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

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

The description is a single, well-structured sentence with the primary action front-loaded and important side-effects placed in parentheses. Every part adds meaningful information 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 tool with one fully documented parametercars and an output schema, the description covers the essential behavioral details needed for correct invocation. It lacks sibling differentiation, but that is not necessary for completeness in this case.

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 only parameter 'root' with a clear description. The tool description adds no additional parameter-level information, 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 specific action and object: '查看工作区状态' (view workspace status). It adds concrete detail about rebuilding STATE.md and not changing branch data, which clarifies the tool's function, though it does not explicitly differentiate from sibling tools like cb_check.

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

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

The intended use is implied by the description: the agent should use this tool to view workspace status. However, there is no explicit guidance on when to prefer this tool over alternatives, nor any stated exclusions or prerequisites.

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?

Given the annotations already mark readOnlyHint=false (write operation), the description adds meaningful behavioral context: '只记录' (only record) and '不执行 promote/discard' clarify the exact scope of action, preventing confusion with promotion or rejection. It does not detail append vs. overwrite behavior, but for a straightforward write tool this is acceptable.

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 core purpose and includes a critical qualifier ('只记录，不执行 promote/discard') immediately. Every word contributes value, with no fluff or 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 write tool with 3 required parameters and no output schema, the description sufficiently covers the primary behavior and scope. It doesn't mention edge cases like file existence or formatting, but these are not essential for correct invocation. The context is complete enough for an agent to use the tool appropriately.

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 each parameter described (root, name, from_file). The tool description adds no additional parameter semantics beyond what the schema provides, so the baseline of 3 applies. It does not explain relationships between parameters, but none are needed given the schema's clarity.

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 ('回流', meaning to feed back), a precise resource ('分支 VERDICT.md'), and explicitly notes it only records and does not execute promote/discard. This clearly distinguishes it from sibling tools like cb_promote and cb_discard without requiring schema inspection.

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 its use case: when external test conclusions need to be written to a branch's VERDICT.md. It explicitly excludes promote/discard actions, which provides a boundary against those siblings, though it doesn't enumerate alternative tools or explicit conditions for when to choose it over others like cb_note.

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