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

Annotations indicate readOnlyHint=false and destructiveHint=false, so the description adds value by revealing that the tool returns an analysis_id for reuse in create_coding_plan, implying a side effect (saving analysis results). However, it does not detail permissions or what gets modified.

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, front-loaded with the core action and followed by key details (focus, output usage). No redundant information.

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

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

Given the complexity (5 parameters, no output schema), the description covers main points: analysis type, focus, return ID and its use. However, it omits details on the format of the analysis result and the role of parameters like branch, max_files, and context_chunks.

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 context about the overall purpose (architecture/risk/test) and highlights the focus parameter, but does not elaborate on the interplay of parameters beyond what the schema 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 clearly states it performs structured analysis (architecture, risks, test suggestions) on a repository, mentions the optional focus parameter, and links the output to a specific sibling tool (create_coding_plan). This distinguishes it from other tools like summarize_branch or get_repository.

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 structured analysis is needed, but does not explicitly exclude scenarios or mention alternatives. For example, it does not contrast with other analysis tools like search_rag_chunks or find_related_chunks.

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 this is a mutation (not readOnly) and not destructive. The description adds that it creates a plan and returns IDs, but does not elaborate on side effects like overwriting existing plans. 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 two sentences, concise, and front-loaded with the core purpose. No unnecessary words, and every sentence adds value.

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 moderate complexity (6 params, no output schema), the description captures the purpose, role in workflow, and key output fields. It could detail the return structure more, but it is sufficiently complete for an agent to understand the tool's 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?

With 100% schema description coverage, the schema already explains all parameters. The description mentions 'code evidence' relating to analysis_id/context_chunks but adds no new semantics beyond the schema. 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 generates a structured coding plan with steps, risks, and test suggestions, returning plan_id/version_id. It specifies it is a mandatory pre-execution step, distinguishing it from siblings like execute_coding_plan and improve_coding_plan.

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 before executing coding and optionally reuses analysis from analyze_repository, but does not explicitly state when not to use it or provide direct alternatives. Siblings imply differentiation, but the description lacks explicit guidance.

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

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

Annotations already indicate write capability and external state changes. The description adds context about writing back to Feishu and returning an ID. However, it does not disclose behavior when boolean flags are false or potential failure modes.

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

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

The description is only two sentences, efficiently conveying the primary action and return value. It is front-loaded and contains no superfluous information.

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

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

The description explains the return value (technical_plan_id) and the main behavior. It is mostly complete given the absence of an output schema, but lacks details on error handling or behavior when write_comment and create_document are both false.

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 each parameter. The description does not add significant new meaning beyond mapping 'context' to parameters like context_id. The return value is mentioned but not in parameter context.

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 a technical plan based on work item context and code evidence, and can write back to Feishu documents and comments. It distinguishes itself from siblings like 'create_coding_plan' by specifying the output and target platform.

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 after obtaining context from 'get_feishu_work_item_context' but does not explicitly state when to use this tool over alternatives like 'create_coding_plan'. No exclusion criteria or alternative suggestions are provided.

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

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

Annotations show non-readonly, non-destructive, which is consistent. Description adds that it creates a case with specific fields, but does not disclose details like whether it overwrites existing cases or any side effects. Adequate but not extensive.

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

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

Single sentence, efficient, and front-loaded with purpose. No wasted words.

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

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

Given 5 parameters with full schema coverage and no output schema, the description sufficiently explains what the tool does. It is complete enough for understanding the tool's purpose and usage.

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. Description adds value by linking parameters to the three aspects of a learning case (root cause, solution, tests), providing context beyond the schema descriptions.

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

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

The description clearly states the tool creates a learning case from a technical plan/execution, capturing root cause, solution, and tests. It distinguishes from sibling 'search_learning_cases' which retrieves 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 implies usage for depositing experience for future retrieval, and the sibling list includes search_learning_cases for retrieval. However, it does not explicitly state when to use or not use this tool, nor provide alternatives.

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

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

Discloses that title/description reuse summarize_branch draft when omitted, adding behavior beyond annotations. Annotations already indicate non-readOnly, non-idempotent, non-destructive, so description complements well.

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

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

Three sentences, front-loaded main action, then options, then default behavior. No 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?

Covers main goal, parameter relationships, and default behavior. No output schema needed. Minor gap: missing explanation if no draft exists when title/description omitted.

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?

Adds conditional grouping and default draft reuse beyond the schema descriptions. Schema coverage is 100%, but description adds valuable context.

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?

Clearly states '在 GitHub / GitLab 创建 PR / MR', specifying the action and platforms. Distinct from sibling tools that focus on analysis or planning.

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?

Provides two parameter options (execution_id or repository_id+source_branch+target_branch) and explains default behavior for title/description. Implicitly clear when to use, but lacks explicit when-not or alternatives.

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

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

Annotations already indicate this is not read-only and not destructive. The description adds that it creates a task matrix, but does not disclose additional behavioral traits such as permissions, reversibility, or impact on existing plans.

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

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

The description is a single, front-loaded sentence that efficiently conveys the core purpose. It could be slightly expanded for clarity, but it is concise and fits the tool's simplicity.

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 parameter and no output schema, the description covers the main purpose. However, it lacks any indication of return value or behavior when tasks already exist, which would be helpful for 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 one parameter (technical_plan_id) fully described as '技术方案 UUID'. The description does not add extra meaning beyond what the schema 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?

The description clearly states the action (拆解/分解), the resource (技术方案 -> 任务矩阵), and the grouping by repository. It distinguishes from sibling tools like execute_work_item_repo_tasks and create_coding_plan by focusing on cross-repo task decomposition.

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 this tool is used for cross-repo requirement splitting, but it does not explicitly state when to use it versus alternatives, nor does it provide any 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?

描述补充了注释未包含的行为细节：耗时较长（默认超时1小时）、在隔离容器中运行、返回execution_id供轮询、需要用户确认。无注释矛盾。

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?

无输出模式，但描述了返回execution_id和耗时行为，足以让代理理解异步轮询流程。结合输入模式，信息完整。

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?

输入模式覆盖100%参数且已有描述，描述未额外增加参数含义。基线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?

明确指定操作动词（执行）、资源（编码计划）和范围（隔离容器，Claude Code实际写代码/跑测试/推分支）。与create_coding_plan、improve_coding_plan等兄弟工具明显区分。

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?

强调执行前必须经用户确认计划内容，并说明耗时长、返回execution_id供轮询。未明确列出何时不使用或替代工具，但上下文已足够引导正确使用。

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

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

The description discloses that the tool is long-running and requires user confirmation, complementing annotations (readOnlyHint=false, openWorldHint=true). It adds behavioral context about dispatching coding and creating MRs, which is not captured in annotations. No contradiction found.

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

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

The description is two sentences long, front-loading the core action and then adding constraints. Every sentence provides essential 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?

Given 8 parameters and no output schema, the description covers the main purpose and input constraint. However, it lacks details on success/failure behavior, monitoring, or expected output, leaving some gaps for a complex batch operation.

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

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

Input schema has 100% coverage, so baseline is 3. The description adds context for key parameters (technical_plan_id, task_ids) but does not elaborate on other properties like dispatch, write_back, or timeout_seconds beyond the schema.

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

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

The description explicitly states the tool executes batches of repository tasks under a technical plan, including dispatching coding, creating merge requests, and writing back to Feishu. It distinguishes from sibling tools like execute_coding_plan by mentioning Feishu integration and MR creation, but does not directly contrast with 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 description notes that technical_plan_id or task_ids must be provided and warns about long duration and user confirmation. However, it does not specify when to use this tool versus alternatives like execute_coding_plan or create_merge_request.

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, destructiveHint=false. The description adds behavioral context: graph diffusion with 1-2 hops, direction choice, and relation type filtering. It does not contradict annotations and provides useful beyond-annotation details.

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: first sentence states the action and scope, second specifies parameter constraints. Every word is necessary, and the structure is front-loaded with the core function.

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

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

Given the absence of an output schema, the description could benefit from mentioning return format (e.g., list of chunks with relationship info). However, for a search tool with clear parameters and good annotations, the description is largely complete for correct selection and invocation.

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

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

Schema description coverage is 100%, but the description adds the critical constraint that chunk_id, file_path, and symbol_name are mutually exclusive and one must be provided. This is not present in the schema and adds significant value for correct tool use.

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 it finds related code chunks via call/invoke/import relationships with 1-2 hop diffusion. This clearly differentiates it from sibling tools like grep_repository (text search) and get_related_entities (broader relationship search). The verb '查找' and resource '相关代码块' are specific.

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 indicates use for impact analysis and call chain analysis (影响面与调用链分析). It also specifies the mutual exclusivity of chunk_id, file_path, and symbol_name. However, it does not explicitly state when not to use this tool or suggest alternatives, slightly reducing the score from 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating safe, idempotent reads. The description adds value by listing the exact return fields (status, commit_sha, file_changes, test_results, last_diff, runner_logs, recovery_state), which enhances behavioral understanding beyond what annotations provide.

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 concise sentences. The first enumerates the return fields, and the second specifies usage context. There is no unnecessary information, and key details are front-loaded.

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 a single parameter with full schema coverage, annotations, and no output schema, the description enumerates return fields adequately. It does not address pagination or error handling, but for a straightforward query tool, this is sufficient for the agent to use effectively.

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 covers the single parameter 'execution_id' with format 'uuid' and description '执行 UUID'. The description does not add further detail about the parameter, but schema coverage is 100%, 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 uses the verb '查询' (query) and specifies the resource '编码执行状态与产物' (coding execution status and artifacts). It lists the specific fields returned, making it distinct from sibling tools like execute_coding_plan. This provides clear, specific action and resource identification.

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 states '执行后轮询与失败诊断用' (for polling after execution and failure diagnosis), which explicitly indicates when to use this tool. Although it does not explicitly exclude other scenarios, the context is clear and sufficient for an AI agent to decide.

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, destructiveHint=false. The description adds that the timeline is a pure version chain not relying on vector DB, providing extra 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?

A single sentence that front-loads the main purpose. It is efficient, though the structure could be slightly improved with separate clauses.

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?

No output schema, so the description should provide more details on the return format. It hints at a timeline of plans and codings but lacks explicit structure. Annotations are rich, but for a query tool, more completeness is needed.

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 mentions 'v1→vN' and '各次编码' implying version details, but does not add significant meaning beyond what the schema already describes for each parameter.

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

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

Description clearly states it queries the complete iteration trajectory of a knowledge entity, listing plans and codings in a timeline. This is a specific verb-resource combination and distinguishes it from siblings like search_delivery_knowledge.

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

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

Usage is implied for tracing version history, but no explicit guidance on when to use versus siblings like get_related_entities or when not to use.

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, openWorldHint=true, and destructiveHint=false. The description adds that it aggregates multiple data types (fields, relations, docs, comments) and returns a context_id, which is helpful but does not contradict 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 covering purpose, output, and a key constraint. No redundant information; every sentence adds value.

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

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

Despite no output schema, the description explains the output (context_id) and its downstream use, and lists what data is aggregated. Together with annotations and schema, this is sufficient for a read-only aggregation 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 coverage is 100% with clear descriptions for each parameter. The description adds a cross-parameter constraint ('project_id and project_key at least one') that is not in the schema, improving parameter understanding.

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 aggregates Feishu work item context (fields, relationships, documents, comments) and returns a context_id for use by create_feishu_technical_plan. This specific verb-resource combination distinguishes it from siblings like get_related_entities or get_entity_timeline.

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 condition that project_id or project_key must be provided, and implies usage for creating technical plans via the mentioned sibling. However, it does not explicitly compare to other search or get tools in 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context about the traversal path and hop range (1-3 hops), which goes beyond the annotations. 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 two sentences with the main purpose front-loaded. Every sentence adds value and there is no 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?

No output schema is provided, and the description does not explain the return format or structure of the graph traversal results. The tool is moderately complex, so more guidance on expected output 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 description coverage is 100%, so the baseline is 3. The description adds minimal value beyond schema descriptions, only providing context about the traversal path which relates to direction and hops.

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 (查看/view) and the resource (关联上下游/related upstream and downstream), and specifies the traversal path (需求→方案→代码变更→MR). It distinguishes from sibling tools like find_related_chunks by focusing on graph traversal between specific entity types.

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

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

The description implies usage for exploring relationships but does not explicitly state when to use this tool versus alternatives (e.g., find_related_chunks). No when-not-to-use guidance is provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description is not required to repeat these. It adds value by specifying what is returned (metadata, index status with examples) and is consistent with the annotations. No contradictions.

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, front-loaded with the core purpose, and contains no unnecessary words. It is concise and effective.

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 one parameter, no output schema, and annotations covering safety, the description adequately explains the return focus (metadata and index status) with examples. It could mention what happens if the repository does not exist, but 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% (one parameter, repository_id, with a description). The tool description does not add any additional 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 the tool queries a single repository's metadata and index status, with specific examples like default branch and index health. It is a specific verb-resource combination that distinguishes from sibling tools like analyze_repository or get_repository_file.

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

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

The description implies usage for retrieving repository metadata/index status, but does not explicitly state when to use it over alternatives or provide exclusions. Sibling tools exist (e.g., analyze_repository), and no guidance is given on choosing between them.

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, destructiveHint=false, and idempotentHint=true. The description goes beyond by detailing the fallback behavior (git mirror first, then index chunks) and the source indicator in responses. This adds useful context not present in 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 that are front-loaded and contain no redundant information. Every word adds value, explaining the core function, line-range support, and fallback mechanism.

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, strong annotations, and complete schema, the description covers all necessary behavioral details (fallback, line ranges). No output schema is needed for a file-read operation.

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

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

Schema coverage is 100% with each parameter described. The description does not add meaning beyond the schema; it simply restates the line-range capability. Baseline 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 reads a single file within a repository with optional line range support. It also explains the two fallback sources (git mirror vs. index chunks), distinguishing it from sibling tools like grep_repository or list_repository_files.

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

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

The description implies usage for reading file content with line ranges but does not explicitly state when to prefer this tool over alternatives (e.g., grep_repository for searching content, list_repository_files for listing). No exclusions or when-not-to-use guidance is provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds value by explaining deterministic snapshot behavior (matches_index), cross-repo result grouping, and truncation details (max_tokens, max_matches with truncated=true flag). No contradictions.

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 well-structured: purpose first, then sibling comparison, then details on defaults and usage tips. Every sentence adds value. Slightly lengthy but appropriate given tool complexity.

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

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

For a tool with 15 parameters and no output schema, description covers purpose, sibling differentiation, default behaviors, output modes, cross-repo opt-in, and snapshot consistency. Does not describe return format but that may be assumed from tool type. Adequately complete for agent decision-making.

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. Description adds minimal per-parameter insight beyond schema; it mentions output_mode and cross-repo parameters but mostly restates schema info. The description does provide context for overall parameter usage but doesn't significantly deepen individual parameter understanding.

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 verb ('精确文本检索'), resource ('仓库本地 git 镜像快照'), and method ('ripgrep / git grep, 确定性全量结果'). Explicitly distinguishes from sibling 'search_rag_chunks' by stating the complementary relationship and when to use each.

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?

Provides explicit when-to-use ('穷举所有出现位置' problems) and when-not-to-use (semantic recall insufficient for exhaustive coverage). Mentions default behavior (single repo, matches_index=true), cross-repo opt-in requirement, and suggests using output_mode=files_only first for distribution analysis.

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 non-readOnly and non-destructive. Description adds that it generates a new version and returns specific fields (version_id, change_summary, risk_delta), providing behavioral context beyond annotations. However, it does not discuss permissions or whether the original plan is modified.

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

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

Single sentence that is front-loaded with the action and result. Every part adds value, no 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?

Description explains purpose and return fields, but lacks explicit guidance on parameters like max_steps or context_chunks beyond what schema provides. Despite no output schema, it mentions key return values, making it fairly complete for a revision 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?

Input schema has 100% description coverage. Description does not add meaning beyond the schema for parameters like plan_id or feedback. The output mentioned is not parameter-level detail. 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 it revises an existing coding plan based on feedback and returns a new version with version_id, change_summary, and risk_delta. This distinguishes it from siblings like create_coding_plan (create new) and execute_coding_plan (execute).

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 use when feedback is available to revise a plan, but does not explicitly state when to use vs alternatives or when not to use. No exclusions or context for selection are provided.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds transparency about pagination and recursion support, and confirms it lists directory structure, not file contents, extending beyond annotation coverage.

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

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

The description is a single, front-loaded sentence that efficiently conveys the core functionality and key features without extraneous content.

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 is adequate for a straightforward listing tool, but the absence of an output schema means the agent lacks information about the return format (e.g., file names, sizes, types). 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?

With 100% schema description coverage, each parameter is already well-documented. The description does not add significant extra meaning beyond the scope already provided by the input 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 verb (列出) and resource (仓库目录结构), and specifies key features (支持分页与递归). It distinguishes from siblings like get_repository_file (which retrieves a single file) and grep_repository (text search) by focusing on directory structure browsing.

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 indicates usage for browsing project layout, providing clear context. However, it does not explicitly exclude alternative uses or compare with siblings, leaving some guidance implicit.

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, which indicate safe, read-only behavior. The description adds value by disclosing the output (sorted candidates and index health) and its role as an initial discovery step, providing 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 two sentences long, front-loaded with the primary action and outcome. Every sentence is meaningful, with no redundant or unnecessary information.

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

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

Given the tool's simplicity (2 parameters, no output schema, no nested objects), the description covers its purpose and output role. However, it does not explain what 'index health' means or the exact format of the returned candidates, but this is not critical for understanding the tool's function.

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

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

Schema description coverage is 100%, with both parameters ('query' and 'top_k') fully described in the schema. The description does not add additional meaning or constraints beyond what the schema provides, 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 routes to the most relevant repositories based on a requirement description, returning sorted candidates and index health. It also identifies itself as the first step in repository discovery, but does not explicitly differentiate from sibling tools like 'get_repository' or 'analyze_repository'.

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 by calling it the 'first step in repository discovery', suggesting it should be used before other repository tools. However, it lacks explicit guidance on when not to use it or alternatives, such as when the user already knows the repository.

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 read-only and idempotent; description adds details about the retrieval mechanism (vector recall, graph diffusion, time decay) and output format (with sources and entities), enhancing transparency 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?

Two short sentences that are front-loaded and to the point. No redundancy, every word adds value.

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?

Covers purpose, usage, and high-level behavior. No output schema exists, but description mentions return type. Could be more complete about result ordering or pagination, but sufficient.

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

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

Schema covers 100% of parameters with descriptions. The tool description does not add further parameter-level details, 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 retrieves historical requirements/plans/code changes from a delivery knowledge graph using advanced techniques. It distinguishes from siblings by providing a typical use case ('Have we done similar requirements before?').

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?

Gives explicit usage context with the query example, but does not mention when not to use or list alternatives. Still provides clear 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 indicate read-only and idempotent behavior. Description adds that search is semantic with hints but does not disclose any additional behavioral aspects beyond what annotations provide.

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

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

Single, concise sentence that front-loads the action and context with no wasted words.

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

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

No output schema exists, and description does not explain what the tool returns (e.g., list of cases, details). Lacks information on pagination or result format, leaving gaps for an agent.

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

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

Schema covers all parameters with descriptions (100% coverage). The description only repeats the hint types already in schema, adding no new semantic meaning for 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?

Description specifies verb '检索' (retrieve), resource '学习案例' (learning cases), and context '在生成新方案前查相似经验' (before generating new plans), clearly distinguishing it from sibling tools like 'create_learning_case' or 'analyze_repository'.

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: before generating new plans to look up similar experiences. Implies usage context but does not explicitly state when not to use or mention alternatives 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 declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds useful behavioral context: the hybrid retrieval method (semantic+keyword+graph diffusion) and the output type (code chunks + edges). No contradictions noted.

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 clearly stating the core functionality and its role as the main evidence collection tool. No extraneous words, front-loaded with key information.

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

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

Given the 5 parameters, no output schema, and annotations present, the description provides adequate context for a search tool. It explains the search technique and return types. Minor gap: does not detail the structure of returned chunks and edges, but still sufficient for typical 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 description coverage is 100%, so the schema already documents all parameters. The tool description does not add extra semantic detail beyond the schema, meeting the baseline expectation for high coverage.

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

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

The description clearly states the tool performs Graph RAG hybrid search in a repository, returning code chunks and relationship edges. It identifies itself as 'the main tool for code evidence collection', which distinguishes its purpose among sibling tools, though not by explicitly naming alternatives.

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 needing code evidence via hybrid search, but it does not explicitly state when to use this tool over siblings like grep_repository or find_related_chunks, nor does it provide exclusions or alternatives.

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

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

The description clarifies that the tool generates a summary and draft, implying a read/compute operation without side effects. This adds context beyond the annotations, which only indicate non-destructive and non-readOnly.

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

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

The description is two concise sentences that front-load the purpose and method, with no redundant or extraneous information.

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

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

For a tool with 5 parameters and no output schema, the description adequately explains the invocation patterns and purpose. It does not cover return format or error behavior, but that is acceptable given the tool's simplicity.

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 description adds the logical grouping and mutual exclusivity of parameters, which is not evident from the schema alone. Since schema coverage is 100%, baseline is 3, but the added clarity merits a 4.

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 compares branch differences and generates a readable summary and MR draft, using specific verbs and resources. It distinguishes itself from siblings like analyze_repository and create_merge_request.

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 provides two invocation patterns (execution_id vs repository_id+source+target), guiding the agent on input options. However, it lacks explicit when-not or comparisons to alternative tools.

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