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

Annotations declare readOnlyHint=true and openWorldHint=true. The description adds key behavioral context: 'MCP 负责方法、门禁与结构化证据，不替 Agent 声称绝对最优架构。' This clarifies that the tool does not guarantee optimal architecture, providing important limitations. It also implies structured evidence gathering and gating. No contradictions detected.

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

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

The description is extremely concise: two sentences that cover purpose, usage modes, composition guidance, and behavioral disclaimer. Every sentence provides unique value. There is no redundancy. It is front-loaded with the core purpose and then adds nuance. Perfect for a tool with many parameters that need schema-level documentation.

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 complexity (19 parameters, nested objects, no output schema), the description does not explain return values or the overall process of ARC-8. However, it sets appropriate expectations by stating the tool provides '方法、门禁与结构化证据'. For a highly complex architecture tool, a 4 is suitable as it covers intent and limitations without over-specifying internal details.

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 68%, meaning many parameters have descriptions. The description adds value by framing the overall purpose and the mode parameter as the entry point. However, many parameters (e.g., 'diff', 'baseline', 'decision') have schema descriptions that already explain them. The description does not deeply elaborate on these, but given moderate coverage, a 4 is justified for reinforcing the context without repeating 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's purpose: '独立架构领域能力，使用 ARC-8 完成架构评估、设计、校验和漂移检查。' It specifies the verb ('架构推理与变更'), resource ('架构'), and the four modes (assess, design, validate, drift). This distinguishes it from siblings like 'code_review' or 'code_insight' which focus on code-level aspects, not architecture-level reasoning.

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 says '可直接调用，也可由功能、Bug 或重构流程按需组合', indicating when to call it directly versus compose within workflows. It doesn't explicitly exclude cases or name alternatives, but hints at composition with other flows. A 4 is appropriate because it provides clear context for usage but lacks explicit when-not-to-use or alternative tool mentions.

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 state readOnlyHint and idempotentHint, so the safety profile is covered. The description adds value by detailing what the validation checks (placeholder, missing sections, etc.) and implying a report output. 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, well-structured sentence that front-loads the purpose, includes the validation scope, and embeds usage timing. No superfluous 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?

For a read-only validation tool with no output schema, the description covers the essential context: what is checked, when to use it, and the follow-up action. It could benefit from mentioning the report format or exit behavior, but it is sufficient for correct invocation. The rich annotations compensate for missing details.

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 each parameter already documented (e.g., feature_name pattern, project_root auto-detection). The description reinforces the feature_name path pattern but does not add substantial new semantics beyond 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 clearly states a specific verb (校验) and resource (功能规格 docs/specs/<feature_name>/requirements|design|tasks.md), and lists exact validation checks (placeholder detection, missing sections, FR/acceptance criteria, FR coverage). This distinguishes it from all sibling tools, which focus on coding, review, or memory tasks.

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 to call (写完规格后、进入实现前) and the rerun loop (未通过按报告补全后重跑). It provides clear contextual guidance, though it does not explicitly mention when not to use it or name alternative tools. The when-to-use is strong enough for a 4.

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, indicating a safe read operation. The description adds details on multiple analysis modes, default backend, and automatic degradation with error reporting, providing useful behavioral context beyond 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 extremely concise, using two sentences to convey purpose, modes, and fallback behavior. Every word serves a purpose without 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?

While the high-level purpose is clear, the description does not explain the return value or output format. Given the complexity (10 parameters, 4 modes) and no output schema, some indication of what the user gets would improve 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?

Schema coverage is 100%, so the baseline is 3. The description does not add additional parameter-level meaning; the schema already describes each parameter adequately.

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: analyzing call chains, context, and impact using a code graph. It specifies the modes (query/context/impact) and the default backend (GitNexus), making it distinct from siblings like code_review.

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 explicitly states when to use this tool (when analyzing code graph relationships) and mentions auto-degradation when unavailable. It does not provide explicit exclusions or alternatives, but the context is 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?

注释已声明readOnlyHint和idempotentHint，描述在此基础上补充了'确定性收集 changed files、Plan声明范围、产物、测试、公共契约、架构和revision证据，代码语义问题由Agent审查'，揭示了工具的行为边界和非侵入性，未与注释矛盾。

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?

工具较复杂（9参数，无输出模式），描述覆盖了适用场景和行为边界，但未说明输出格式或返回内容。缺少输出说明使得完整性不足，但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描述覆盖率为100%，所有9个参数已在输入模式中详细说明。描述未添加任何参数相关的内容，因此按照规则基线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?

描述明确使用'当用户需要审查代码、真实 Git diff 或托管 Plan 的交付一致性时使用'，具体指出了三种适用场景，动词'审查'配合资源'代码/diff/Plan'。进一步说明工具职责边界（收集证据，不伪装静态扫描器），与兄弟工具code_insight等自然区分。

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?

描述直接给出了使用条件（审查代码、diff、Plan一致性），提供了清晰的上下文。但未明确罗列何时不适合使用，也未提及兄弟工具作为替代，因此无法达到最高分。

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 significant behavioral context beyond annotations: it clarifies that evidence without reference/revision is not reviewable, explains rejection conditions, and states the monotonic nature of evidence requirements. This complements the annotations (idempotentHint=true, destructiveHint=false) by detailing exactly what the tool checks and rejects, without contradiction.

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

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

The description is a single, front-loaded paragraph of three sentences. Every sentence adds essential information: the core function, rejection criteria, and parameter constraint. There is no redundancy or filler, achieving high density of useful guidance.

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

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

The tool has 5 parameters, no output schema, and moderate complexity. The description covers behavior and constraints well but fails to specify what the tool returns on success (e.g., confirmation, next steps) or any side effects. Given the absence of an output schema, these gaps reduce completeness for an agent invoking the 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?

With 60% schema coverage, the description compensates by explaining parameter behavior for 'required_evidence_kinds' (only additive, not removing) and 'feature_name' (triggers check_spec call). While 'docs_dir' and 'project_root' are not elaborated, the description adds meaningful constraints beyond the schema, earning above 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 the tool's purpose: to close a Delegated Plan by verifying its declared evidence and quality gates. It uses specific verbs ('收敛' meaning converge/close) and identifies the resource ('Delegated Plan'). This distinguishes it from sibling tools like plan_heartbeat (status check) and resume_plan (resume), making selection 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?

The description provides strong usage context by detailing conditions for rejection (incomplete steps, missing evidence) and the constraint that parameters can only add evidence requirements, not weaken the Plan. While it does not explicitly name alternative tools, it implicitly advises using converge only when all gate criteria are met. The guidance is clear and actionable.

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 indicate readOnlyHint=true and idempotentHint=true, so the tool's safe, non-destructive nature is covered. The description adds value by stating the outputs (故事点、时间范围、风险点), giving agents insight into what they can expect. No contradictions 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 two sentences long: the first states the usage trigger, and the second summarizes outputs. Every word is purposeful with no redundancy or filler. Front-loaded with the most critical information (when to use).

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 4 optional parameters and no output schema, the description covers the core purpose, usage context, and output types. It could be improved by mentioning that all parameters are optional or by providing a hint about the output structure (e.g., how risk points are represented), but it is largely complete for an estimation tool.

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

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

Schema description coverage is 100%, meaning structured descriptions already exist for all four parameters. The tool description does not add any additional meaning beyond the schema, such as explaining how 'experience_level' affects estimation or the relationship between 'team_size' and output ranges. 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 explicitly states the tool's purpose: estimating development workload and task time. It specifies outputs (story points, time ranges, risk points) and the action verb '估算' (estimate) plus resource '开发工作量' (development workload). This clearly distinguishes it from siblings like 'plan_heartbeat' or 'init_project', which are not estimation-focused.

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 starts with '当用户需要估算开发工作量、评估任务时间时使用' (use when user needs to estimate development workload or assess task time), providing a clear usage context. However, it does not explicitly mention when not to use this tool or compare it to sibling tools, leaving some ambiguity for alternative selection.

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 和 idempotentHint=true，描述进一步补充了工具的具体行为：返回规范说明、步骤、模板和示例，不直接写入最终消息，并提示不应该被当作空结果。两者一致，无矛盾，且提供了额外上下文。得 4 分。

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

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

仅用两句话清晰表达了目的、输入、输出和行为约束，信息密度高且前置关键内容，没有冗余。得满分 5 分。

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

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

说明了返回值（规范、步骤、模板、示例），也提示了未提供 changes 时的行为（在参数 schema 中说明）。缺少输出 schema，但描述已涵盖关键信息。在兄弟工具较多的情况下，整体完整度较好，得 4 分。

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%，描述本身没有再重复参数细节。根据规则，高覆盖率下基数为 3 分，且描述未新增参数含义，因此得 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?

明确说明用于“生成 Git commit 消息”，并指明返回规范说明、步骤、模板和示例。描述中指出了工具的行为边界（不直接代写最终消息），但未明确与兄弟工具（如 git_work_report）区分，因此为 4 分。

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?

指出了使用场景（需要生成 commit 消息时），并澄清了工具不直接写入消息、不应被判断为空结果。但没有明确说明何时不适合使用，也未列出替代工具。因此得 3 分。

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 behavioral context beyond the annotations (readOnlyHint, idempotentHint) by clarifying that it is a '指南型工具' (guide-type tool) where 'MCP 不自动生成或运行测试' (MCP does not automatically generate or run tests) and '由 Agent 生成完整测试代码' (the agent generates complete test code). This explains the tool's role as a guide, not a direct executor. 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 exceptionally concise: two sentences, front-loaded with the purpose, and every sentence provides essential information. 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?

Given the 100% schema coverage, no output schema, and no nested objects, the description adequately covers the tool's purpose and behavior. It explains the guide nature and the agent's role. A minor gap is the lack of information about the return value or output, but this is mitigated by the readOnlyHint and the description's clarity.

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

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

Schema description coverage is 100%, so the baseline is 3. The tool description does not add any parameter-specific information beyond what the schema already provides. The mention of '注入 code/file_path 与测试清单' is too vague to add meaningful semantics.

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

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

The description clearly states the tool's purpose: '当用户需要为代码生成单元测试时使用' (use when user needs to generate unit tests for code). It specifies the verb (generate), resource (unit tests), and distinguishes from sibling tools like code_review or refactor by being exclusively for test generation.

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 explicitly states the usage condition: '当用户需要为代码生成单元测试时使用' (use when user needs to generate unit tests). It provides clear context but does not list when not to use or mention alternatives, which would be beneficial given the large sibling set.

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 key behavioral traits: it reads Git diffs, uses AI to analyze content, and outputs only the 'work content' section. The annotations confirm readOnlyHint=true and idempotentHint=true, which aligns with the read-only behavior described. The description adds details about the output format and what is excluded, going beyond 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 well-structured with clear sections for core functionality, output format, and usage examples. It is concise for the amount of information conveyed, though some redundancy exists (e.g., both title and description mention 'Git 工作报告'). Each section adds value without unnecessary verbosity.

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 moderate complexity, 5 parameters with full schema coverage, no output schema, and read-only annotations, the description is complete. It explains the tool's mechanism, output format, and usage, leaving no obvious gaps for an agent to misinterpret. The lack of output schema is compensated by the explicit output format rules.

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 baseline is 3. The description adds significant value by explaining the date/start_date/end_date parameters in natural language with usage examples, clarifying the two modes. It also explains project_root's fallback behavior ('按当前 MCP 工作区解析'), which is not in the schema description.

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 identifies the tool's purpose: generating work reports from Git diff analysis, for daily and periodic modes. It explicitly states the verb '生成' (generate) and the resource '工作报告' (work report), distinguishing it from siblings like 'gencommit' or 'code_review' which are related but different operations.

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 explicit usage contexts: daily mode (single date) and periodic mode (date range), with concrete examples. However, it does not explicitly state when NOT to use this tool or compare to alternatives like 'gencommit' for commit messages, though the context is clear from the sibling list.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false. The description adds behavioral context by stating the tool is based on 'Spec-Driven Development' and generates specific document types (需求分析/技术设计/任务拆解). The parameter description for `project_root` further details file creation behavior and path restrictions. This adds value beyond the annotations, though the description itself could be more explicit about side effects.

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 sentences long, front-loads the key use case, and contains no filler. Every sentence adds value: usage trigger, methodology, and output content. It is efficiently structured for quick comprehension.

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 type (specification document with sections) but does not specify the return format (e.g., file path, text content, or JSON). Since there is no output schema, the description should clarify what the tool returns to the caller. The parameter `project_root` is well-documented, but the overall completeness is lacking for a tool that generates documents without explicit output guidance.

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% – all parameters have descriptions. The `input` parameter description explains the allowed format (one-sentence or short description), `project_name` provides a default value, and `project_root` has a detailed explanation of path resolution and edge cases. The tool description does not add parameter-specific information beyond what is already in the schema, 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's purpose: '当用户提供一句话需求时使用' (use when user provides a one-sentence requirement) and '生成完整的项目规格文档' (generate complete project spec doc). It identifies the action (analyze requirement and generate documents) and context (initial project clarification). However, it does not explicitly differentiate from sibling tools like `init_project_context` or `start_product`, which could be confused for similar use cases.

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 specifies when to use the tool ('当用户提供一句话需求时使用', '适合项目初期的需求澄清和规划'), providing clear context. However, it does not mention when not to use it or list alternative tools for different scenarios (e.g., `init_project_context` for adding context to existing projects). No explicit exclusions or guidance on choosing between this and similar tools.

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 idempotent and non-destructive. Description adds that the tool writes to specific files (AGENTS.md, layout.json) and delegates follow-up actions. Could be more explicit about side effects or overwrite 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, front-loading the core action and directing use cases. It packs essential information without 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?

While purpose and usage are clear, the description lacks details on the returned plan structure and how the agent should use it. With no output schema, more completeness would improve agent understanding.

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. The description does not add additional semantic context beyond the schema, so 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 states the tool generates/updates project context writing plan, writing AGENTS.md and layout.json, and directs the agent to write associated documents. It distinguishes from sibling tools like start_feature and start_bugfix by indicating separate workflows.

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 instructs when to use alternatives: for new features use start_feature, for bug fixes use start_bugfix. This provides clear context for tool selection.

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 claims the tool generates interview record files (side effects), but annotations declare readOnlyHint=true and idempotentHint=true, which imply no state changes. This is a direct contradiction, severely undermining transparency. Without annotations, the description itself would provide some behavioral context, but the contradiction makes it 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 a single sentence that packs essential information: use case, function, output, and type constraint. It is concise but could be better structured (e.g., separate sentences for clarity). Still, it efficiently conveys key points.

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 a nested object parameter ('answers') and no output schema. The description fails to explain the structure of the interview answers or the format of the generated record file. It mentions the output is used by other tools but lacks details needed for correct invocation and understanding the tool's full 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%, so the baseline is 3. The description does not add significant meaning beyond the schema descriptions for 'answers', 'description', and 'feature_name'. It mentions that 'answers' are for submitting results and 'description' starts the interview, but this is already captured in 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's purpose: clarify requirements through structured questions when they are unclear. It specifies that it generates interview record files for subsequent tools and only supports 'feature' type. While it lacks explicit differentiation from sibling tools like 'ask_user', the purpose is well-defined.

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 explicitly states when to use: when user requirements are unclear and need clarification. It also mentions the output is used by start_feature/add_feature, indicating the tool's place in the workflow. However, it does not provide when-not-to-use scenarios or alternative tools.

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 meaningful behavioral context beyond annotations: it clarifies the tool only records state, does not execute the agent's actions, and reveals a dependency on 'converge' (which will reject evidence lacking reference/revision). Annotations already declare idempotentHint=true and destructiveHint=false, which the description does not contradict. The description reinforces the non-destructive, bookkeeping nature.

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 paragraph of about 100 Chinese characters, front-loading the purpose and then key constraints. Every sentence adds value. It could be slightly improved with bullet points or separate sections for first call vs subsequent calls, but it is already very concise without waste.

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

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

Given the tool has 16 parameters, deep nesting, no output schema, and is part of a complex Delegated Plan workflow, the description is too minimal. It does not explain what the tool returns (likely just success/failure), how to handle conflicts or errors, the lifecycle of a heartbeat sequence, or what happens if the plan_id is invalid. For such complexity, more completeness is needed to guide the agent fully.

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

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

Schema coverage is only 25% (4 of 16 parameters have descriptions). The description compensates by stating that 'plan' is required on first call and that subsequent calls merge various categories like evidence, artifacts, acceptance_results, etc. However, it does not explain individual parameter semantics for fields like 'unresolved_items', 'last_verified_revision', or the differences between 'memory_candidates' and 'architecture_candidates'. The constraint for evidence (reference/revision) is helpful but insufficient for the overall parameter richness.

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 records lightweight checkpoints during Delegated Plan execution, with the specific verb '记录' and resource '检查点'. It also distinguishes itself from siblings by focusing on status recording rather than execution ('只记录状态，不代替 Agent 执行'). However, it does not explicitly differentiate from all 24 sibling tools.

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

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

Explicitly states that the first call must provide a complete plan and subsequent calls merge various fields (steps, evidence, artifacts, etc). It also provides a key constraint: for convergence, evidence must include 'reference' or 'revision' unless it is 'requirements'. This gives clear usage context. However, no explicit 'when NOT to use' or comparison to alternatives like 'converge' 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?

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral context: it is a guidance tool that injects code/file_path, analyzes, and outputs a refactoring plan JSON, and explicitly states that MCP does not modify source files. No contradictions 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?

Two sentences with no wasted words. The description is front-loaded with the purpose and immediately clarifies the tool's non-modifying nature and output format.

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 4 parameters (0 required) and no output schema, the description explains the output (refactoring plan JSON) and behavior (no file modification). It lacks details on how conflicting inputs (both code and file_path) are handled, but overall it is sufficient for an agent to understand the tool's capabilities.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters adequately. The description mentions 'injection of code/file_path' but adds no new information 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?

Description clearly states the tool is for refactoring code and improving code structure. It specifies it's a guidance tool that outputs a refactoring plan JSON without modifying files, distinguishing it from sibling tools like fix_bug or add_feature.

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?

Description explicitly indicates when to use ('当用户需要重构代码、改善代码结构时使用') and mentions it's a guidance tool with no automatic file modification. It does not explicitly state when not to use, but the context is clear enough for an agent to choose appropriately among siblings.

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

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

Annotations already mark readOnlyHint and idempotentHint. The description adds valuable context: it performs dependency calculation, returns a mustContinue flag, and imposes a post-call behavior requirement. No contradictions 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 relatively concise and front-loaded with the core action. But it could be slightly more streamlined; the behavioral prohibition at the end, while important, adds length. Still, 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?

Given the tool's complexity (reading a plan, computing dependencies, returning a mustContinue flag), the description covers the purpose, usage, and key behavioral constraints. It mentions the output components (next step, blocked steps, resumeContext) but lacks a detailed return structure since no output schema exists. It is nearly complete but could elaborate on the format of the returned data.

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 50% (only plan_id has a description). The description adds meaning for plan_id by explaining its optionality and default behavior. However, project_root is entirely undocumented in both schema and description, so the description does not fully compensate for the coverage gap. Baseline 3 is appropriate given the partial addition.

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 verb (read, calculate), resource (Delegated Plan checkpoint from .mcp-probe-kit/plans/), and specific outputs (next executable step, blocked steps, resumeContext). It distinguishes itself from siblings like plan_heartbeat by noting it only reads state and does not execute, and contrasts with execution-oriented tools.

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

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

The description explicitly explains when to use the tool (resume a plan, both with explicit plan_id or auto-detection), what to do after invocation (must immediately execute nextStep/nextTool and call plan_heartbeat), and what not to do (prohibited from only reporting results and stopping). This provides clear guidance and alternatives by implication.

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 states the tool performs bug fixing (mutation), but annotations declare readOnlyHint=true. This is a direct contradiction. The description does not disclose any behavioral traits beyond the workflow steps, and the annotation conflict severely undermines 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?

Description is two sentences, front-loaded with purpose, and contains no extraneous information. Every word serves a purpose.

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 having 13 parameters and no output schema, the description only outlines the workflow process. It fails to describe return values, side effects, or prerequisites. The annotation contradiction further reduces 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?

Schema coverage is 100% with all parameters having descriptions. The tool description adds no additional semantic meaning beyond what the schema already provides, so 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?

Description clearly states the tool is for finding problems, fixing bugs, and troubleshooting anomalies. It also describes the default workflow steps. However, it does not differentiate from the sibling tool 'fix_bug', which appears to have overlapping functionality.

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?

Description implies when to use (bug fixing/troubleshooting) but provides no explicit when-not-to-use or alternatives. Given the presence of sibling 'fix_bug', the lack of comparative guidance could lead to confusion.

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: true and openWorldHint: true, which might seem contradictory since the tool orchestrates feature creation. The description clarifies its orchestrative, non-destructive nature: it generates specs and plans but doesn't modify code. It adds behavioral detail beyond annotations (e.g., the auto detection of parent-child layout). However, it could be more transparent about exactly what side effects occur (e.g., file creation, project state changes).

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 moderately concise for a tool with many parameters and complex orchestration. It front-loads the essential purpose and usage guidelines. However, it's somewhat dense and could benefit from clear separation of concerns (e.g., bullet points for different behavioral aspects) to improve scannability.

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 (11 parameters, conditional orchestration, sibling differentiation needs), the description covers core aspects: purpose, when-to-use, orchestration flow, and key parameter semantics. It lacks an output description, but there is no output schema to rely on. It could be more complete by explaining the overall workflow in more detail, but it's adequate for an agent to select and invoke the tool 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 coverage is 100%, so the baseline is 3. The description adds significant value by explaining the semantics of description (must summarize confirmed scope, not just pass through user's last confirmation) and spec_layout's auto behavior (complex needs trigger parent-child planning). It also clarifies that feature_name is optional and auto-extracted. However, the description doesn't detail all 11 parameters individually.

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 this is the primary entry point for new features, enhancements, major version upgrades, and cross-module development. It distinguishes itself from siblings like start_bugfix (bug fixes) and start_onboard (onboarding) by its scope and purpose.

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 explicit when-to-use guidance: it's the first choice for complex multi-module or multi-phase requirements. It also explicitly states when NOT to use it and what to use instead: '仅在规格布局和子规格已明确、且只需渲染规格模板时才直接用 add_feature.' This is excellent usage guidance.

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

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

Annotations already provide readOnlyHint=true and openWorldHint=true, indicating the tool is safe and may access external resources. The description adds that it generates context documentation, but does not detail the process or potential side effects beyond what annotations convey. No contradiction detected.

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 consists of two very concise sentences that convey the purpose and process without any wasted words. It is front-loaded and 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?

For a simple tool with two optional parameters and no output schema, the description is adequate but minimal. It does not explain what 'context documentation' entails, prerequisites, or expected outcomes, which could improve 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 schema covers both parameters with descriptions, achieving 100% coverage. The tool description does not add any additional semantics beyond the schema, so a 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 is used for quickly starting a new project by generating context documentation. It distinguishes from siblings like 'init_project' by focusing on onboarding and documentation generation, but does not explicitly differentiate from potentially similar tools.

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

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

The description provides a clear context for when to use the tool (when starting a new project), but does not specify when not to use it or mention alternative tools among the siblings.

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

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

The annotations state readOnlyHint=true and idempotentHint=true, but the description describes a workflow that runs multiple steps and may produce artifacts. It does add context that it will call ui_design_system and start_ui, and update project context, which goes beyond annotations. It also clarifies that it won't reference non-existent tools. This adds useful behavioral context without contradicting annotations (since readOnlyHint=true might be questionable but not contradicted).

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 (two sentences) and front-loaded with the main purpose. It covers key workflow actions and mentions tool dependencies in the first sentence. It's not overly verbose, but could possibly be more concise by removing redundant mentions. Still 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 complexity of a workflow-orchestrating tool with 9 parameters (many optional) and no output schema, the description provides essential context about the workflow, what it generates, and which tools it integrates. It also clarifies implicit behavior. It lacks details about return values or step-by-step behavior, but given the schema covers parameters well, 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?

The schema description coverage is 100%, meaning all 9 parameters are documented in the schema itself. The tool description does not add significant additional parameter semantics beyond what the schema already provides, except maybe the overall workflow context. Therefore, 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 explains the tool's purpose: it is an entry point for a complete product design workflow that generates a delegated plan, creates PRD and prototype documents, and calls other tools. It also explicitly clarifies that it doesn't reference non-existent tools, which helps distinguish it from potential alternative tools. However, it doesn't provide strong differentiation from sibling tools like start_feature or start_ui, but the workflow context 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 implies when to use this tool: when starting a product design workflow from scratch, it will orchestrate the process and produce documents. It also explicitly notes it doesn't use gen_prd/gen_prototype, preventing misuse. However, it doesn't clearly say when NOT to use it or mention alternatives like start_feature, so it's not fully 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 annotations include readOnlyHint: true and idempotentHint: true, which together suggest the tool is safe and non-destructive. However, the description describes initiating a multi-round cycle that likely makes changes (e.g., '每轮真实验证' implies code modifications and test runs). This contradicts the readOnlyHint, which should indicate a read-only operation. The description does not disclose behavioral traits beyond what annotations provide; it adds that the tool does not create background processes and that safe stop does not equal success, but these are minor. The contradiction between description and annotation is significant, warranting a score of 2.

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 at roughly two sentences. It front-loads the purpose and key behavioral traits. However, the structure could be improved by separating the 'returns' section from the 'not' statements for clarity. There is no redundancy, and each clause serves a purpose, earning a 4.

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 14 parameters with 100% schema coverage, no output schema, and no nested objects. The description provides a high-level overview of what the tool does and its return values (Delegated Plan, Heartbeat evidence, optional front-end scripts). However, given the complexity of the tool (a multi-round development orchestrator), more context about the return format, how to use the evidence, and how failures are reported would be valuable. The presence of annotation contradictions further reduces completeness, making a 3 appropriate.

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 every parameter already has a description in the schema. The tool description does not add any parameter-specific semantics beyond what the schema provides. However, there are 14 parameters, many with default behaviors tied to mode, and the description does not summarize key relationships (e.g., how mode affects max_rounds, confirm_every, etc.). The baseline for 100% coverage is 3, but given the complexity and the fact that the description could have provided a high-level overview of parameter interactions, a 4 is given because the schema descriptions are detailed and the tool description's lack of additional parameter guidance is not severely detrimental.

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 is for long tasks requiring multi-turn small-step implementation with real verification and formal convergence. It uses specific verbs like 'start_ralph' implying initiation of a process, and contrasts with siblings by mentioning '多轮小步实现、每轮真实验证和正式收敛' which distinguishes it from simpler tools like start_feature or start_bugfix. However, the description is in Chinese, which might reduce clarity for non-Chinese speakers, and the title 'Ralph 循环开发编排' provides additional 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 explicitly states the tool is for '长任务' (long tasks) and mentions what it does not do: '不自动运行循环、不创建后台进程' and '安全停止不等于成功'. This gives implicit guidance on when to use it (complex, iterative tasks) and when not (if you need automatic loops or background processes). However, it does not explicitly name alternatives or provide exclusion criteria relative to the listed sibling tools like 'plan_heartbeat' or 'resume_plan', so a 4 is appropriate.

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 include readOnlyHint: true, openWorldHint: true, and idempotentHint: false. The description goes beyond these by disclosing the iterative loop (screenshot scoring), the planning phase before generation, and the acceptance criteria. This adds behavioral context: the tool may ask questions (loop), generate multiple revisions, and depend on external screenshot evaluation. 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 concise: one sentence that captures the three-phase workflow. It front-loads the purpose before listing any parameters. However, given the complexity (19 parameters, multi-step process), a slightly expanded description might be warranted to avoid ambiguity. Minimal waste, but could do more without bloating.

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 high parameter count (19), rich annotations (readOnly, openWorld), and no output schema, the description provides a solid high-level narrative. It explains the iterative and screenshot-based nature of the tool. However, it does not mention what happens if 'loop' mode or 'auto' mode is selected, nor the role of templates or project_root. Still, for a tool with this complexity, the description is reasonably 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?

Schema description coverage is 100%, so the baseline is 3. The description does not add much parameter-level semantics beyond what the schema already provides. It mentions locking visual direction and generating pages, which loosely maps to visual_direction and description, but does not explain complex parameters like requirements_mode or loop_* in greater depth. No extra value beyond 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 orchestrates UI design and development: first locking visual direction and information architecture, then generating key pages, and finally iterating with real screenshots. This is a specific verb+resource (orchestrate UI development) with a step-by-step process. It is reasonably distinguishable from sibling tools like ui_design_system (which likely focuses on design tokens) and ui_search (which is about searching).

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 starting a UI design workflow, but it does not explicitly state when to use this vs. siblings like ui_design_system or converge. There is no guidance on prerequisites (e.g., existing project root?), exclusion criteria, or alternative tools. The context is implicit but not explicit enough to help an agent decide between siblings.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true, meaning the tool doesn't change state and produces consistent results. The description aligns with this by describing generation of a design direction without side effects. It adds value by detailing what the tool outputs (e.g., 'explicit disallowed items'), which goes beyond annotation hints. No contradiction.

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

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

The description is a single, dense sentence that front-loads the core distinction and lists all output deliverables. Every phrase is meaningful, and there is no redundancy. It efficiently uses 50 characters to set context and then specifies outcomes.

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 high parameter schema coverage (100%) and annotations, the description is largely complete. It could be improved by briefly mentioning the return format or what '截图验收标准' entails, but the core directive is clear. The absence of an output schema is compensated by the description listing concrete deliverables.

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 baseline is 3. The description goes beyond by emphasizing that output is executable, not just style tags. While most parameters have thorough schema descriptions, the tool description adds a strategic layer that clarifies purpose, compensating for the lack of extra parameter details in the tool description itself. The description effectively frames all 12 parameters.

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 generates executable visual direction, distinguishing it from a 'collage of style tags'. It lists specific outputs: core tasks, information architecture, content density, typography, color strategy, component principles, explicit disallowed items, and screenshot acceptance criteria. This differentiates it from sibling tools like 'ui_search' (searching) and 'start_ui' (a different UI task).

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 implicitly sets context by contrasting with 'style tag collages', suggesting when not to use it. However, it does not explicitly state when to use this tool versus alternatives like 'start_ui' or 'converge'. The sibling list is diverse, but no direct exclusions or alternatives are mentioned.

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 openWorldHint=false, covering the safety profile. The description adds context about mode behavior (e.g., structure mode limits) but does not disclose additional behavioral traits such as authorization requirements or rate limits. 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 extremely concise: two sentences that front-load the core purpose and immediately follow with mode guidance. Every sentence serves a clear purpose without repetition or fluff.

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

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

Given 8 optional parameters, no output schema, and annotations present, the description covers the modes and usage well. It could be more complete by describing the return format or result structure, but the mode descriptions and parameter schema together provide sufficient context for an agent to use the tool 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 parameters are well-documented in the schema. The overall description does not add significant meaning beyond what each parameter's description already provides. Baseline score of 3 is appropriate as the schema carries the burden.

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 searches for page structures, components, interaction specs, and implementation references. It distinguishes between four modes (structure, search, catalog, template) and recommends structure mode for new UI processes. However, it does not explicitly differentiate this tool from sibling tools like ui_design_system.

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 internal mode usage guidance: prefer structure mode for new UI processes, while old modes remain compatible. It does not, however, give guidance on when to use this tool versus alternative sibling tools, nor does it mention excluded scenarios.

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 states the tool '确保用户项目已存在 .agents/skills/mcp-probe-kit/SKILL.md 与 AGENTS.md 中的 Skill 引用（缺失则自动创建/更新）' which implies file creation/update side-effects. This contradicts the annotation 'readOnlyHint: true' which indicates no state mutation. This is a serious contradiction, scoring 1 per the rubric.

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

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

Three sentences in Chinese, front-loaded with the tool's purpose. Each sentence adds essential information: usage condition, behavior distinction, alternative usage, and side-effect. No wasted words; compact yet complete.

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 large set of sibling tools (23), the description covers the core use case (routing guidance) and parameter behavior. It mentions return types (table, deterministic flow, parameter hints) but lacks explicit output format details. With no output schema, a bit more specificity on the response structure would improve completeness. Otherwise 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 coverage is 100% with clear descriptions. The description adds behavioral meaning beyond the schema: it explains that 'intent' is only for display when scenario=auto and not used for classification, and that 'scenario' controls whether to return a table or deterministic flow. This enhances usability beyond the raw enum values.

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 defines the tool as a fallback guidance when unsure which MCP to use. It distinguishes itself from sibling tools (which are direct task tools) by stating it returns a tool selection table or deterministic flow, not performing intent recognition itself. The verb '兜底选择指南' (fallback selection guide) is specific and differentiated.

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 to use: only after reading Skill and tool descriptions when still uncertain. Also provides when-not: '不做自然语言意图识别' (does not do NLU) and that the agent should judge or clarify. Describes alternative scenarios: use explicit scenario for deterministic flow. Clear boundary conditions.

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