CocosMCP

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

Annotations already state destructiveHint=true and readOnlyHint=false, so the agent knows this is a mutating, destructive operation. However, the description adds no behavioral context beyond what annotations supply—nothing about overwriting, path semantics, or side effects—so it fails to enrich the warning.

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 short, but it is a pure restatement of the title and does not earn its place. Conciseness is only valuable when the included sentences carry information; here the single sentence is empty.

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 6 parameters, nested objects, a destructive annotation, and no output schema, the description provides virtually no operational context. An agent would not know import path semantics, error conditions, or expected effects.

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

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

Schema description coverage is 0%, meaning the description must fully compensate for missing parameter documentation. The description says nothing about sourcePath, targetUrl, or how they relate to the project, leaving the two required parameters semantically black boxes.

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?

Tautological: description restates name/title.

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

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

No guidance is provided on when to choose this tool over sibling tools. With 34 siblings performing overlapping asset and project operations, an agent would have no way to route to this tool correctly.

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, openWorldHint=false, and destructiveHint=false, covering the safety profile. The description adds no behavioral context beyond what annotations provide — no mention of return shape, pagination behavior, or scope of results. Since annotations carry the burden and the description contributes nothing extra, this scores low.

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 short, which is efficient, but the brevity stems from under-specification rather than deliberate pruning. It repeats the title exactly and adds no information, so conciseness is not earned through informative 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?

With 6 parameters, a nested params object, 0% schema description coverage, and no output schema, the description is inadequate. An agent lacks information about return format, filtering semantics, and result paging. This is a query tool that should document what it returns and how filtering behaves.

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 0%, so the description must compensate for the undocumented parameters, but it does not. It vaguely hints at 'type and path filtering' which maps loosely to the `type` and `pattern` parameters, but gives no detail on pattern syntax, limit/offset semantics, or the required projectId. Nearly all parameter meaning must be inferred from names.

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?

Tautological: description restates name/title.

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

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

No guidance is given on when to use this tool versus the many sibling query tools, nor any exclusions or prerequisites. The agent must infer usage entirely from the name and schema. A query tool that overlaps with scene/node/operation queries should state its selection criteria.

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=false and destructiveHint=false, so the description's job is to add behavioral context, which it does: assets are moved via AssetDB to preserve UUID, the operation rejects when changes are detected (revision check tied to expectedRevision), and partial failures return recovery records. This gives the agent meaningful error-handling and mutation semantics beyond the annotations. 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?

Two dense sentences with no filler; the core purpose is front-loaded and the behavioral caveats are packed efficiently. It is appropriately sized, though the terseness contributes to the parameter-semantics gap.

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

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

With 9 parameters, 0% schema coverage, and no output schema, this tool needs substantial description to be callable correctly. The description covers the core contract (preserve planHash/scope, reject on drift, return recovery records) but omits what urls and recursive control, how the recovery record is structured, and what instanceId/runtimeInstanceId/operationId mean. An agent would have to guess at several parameters.

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 0%, so the description carries the full burden for explaining 9 parameters, but it only touches on two: scopeUrl/recursive ('保留预览范围') and planHash. The '遇到变化拒绝' clause hints at expectedRevision, but urls, recursive, instanceId, operationId, runtimeInstanceId, and projectId are left unexplained in both the schema and description. This is a significant gap.

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

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

States a specific verb ('执行'/execute) and resource (reviewed asset organization plan), and the phrase '已审查计划' (reviewed plan) implies this is the execution step following cocos_assets_organize_plan. It distinguishes itself from the planning sibling but doesn't explicitly name it or other execute-type siblings like cocos_workflow_execute, so it falls short of a 5.

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

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

The description implies usage context — it must be called with a preserved preview scope and planHash, and it rejects when the workspace has drifted ('遇到变化拒绝'), which signals it is meant for applying a pre-validated plan. However, it never names alternative tools or states when NOT to use it, leaving the agent to infer the boundary with cocos_assets_organize_plan and cocos_workflow_execute.

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 establish readOnlyHint=true and destructiveHint=false. The description adds behavioral context beyond that: it returns a plan (not execution), specifies the fields returned (source/target, UUID, conflicts, skip reasons), and clarifies the default scope. This enriches the agent's understanding of what the tool does and its non-destructive 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, compact structure with the main purpose front-loaded and additional behavioral notes appended. It avoids redundancy and communicates the key message efficiently, though it could be slightly more structured with direct parameter hints.

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

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

With no output schema and no parameter descriptions, the description carries the entire burden. It mentions return fields and default scope but does not explain parameter semantics, edge cases, or exact response structure. For an 8-parameter tool, this is insufficient for confident correct 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 coverage is 0% and the description provides no explanation of the 8 parameters. It only hints at default scope without connecting it to specific parameters like scopeUrl or recursive. This is a severe gap for an agent to correctly invoke the tool with appropriate 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 states the tool plans resource organization by asset type, returns source/target, UUID, conflicts and skip reasons, and is a preview before execution. It implicitly distinguishes from the apply sibling by emphasizing review before execution, though it doesn't name the apply tool explicitly.

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

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

The description mentions default scope (assets root) and that the agent should review path references before executing, implying a planning step. However, it does not explicitly state when to use this tool versus cocos_assets_organize_apply or how it fits into the workflow, leaving usage 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 and destructiveHint=false. The description adds meaningful behavioral context beyond those annotations: it is purely a static integrity check, does not execute the artifact, and explicitly disclaims installability or runnability. No contradiction with the annotations.

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

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

The description is a single compound sentence with no filler. The core verification purpose is front-loaded, and the non-execution caveat is added concisely without repeating annotation 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 read-only verification tool, the description covers target scope, what is checked, and what is not performed. It does not describe the result format or how it relates to build_status, which is a minor gap given there is no output schema, but the invocation context is otherwise 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 description coverage is 0%, so the description must compensate. The description links '入口' to entryPaths and suggests the artifact-checking context for jobId, but it does not explicitly explain projectId/jobId roles or entryPaths format. It only partially compensates for the missing 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 specifies a concrete verb ('检查/verify') and a precise resource: the complete file set, entry points, and SHA-256 checksums of a successful build. It also explicitly disambiguates itself from execution/runtime siblings by stating it does not imply installability/runnability and does not execute artifacts.

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

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

It clearly scopes the tool to successful tasks ('已成功任务'), giving an agent a clear context for when it applies. It does not explicitly name sibling alternatives like cocos_build_status or cocos_runtime_instances, but the usage context is still clear enough to avoid 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 carry destructiveHint=true and readOnlyHint=false, which already disclose this is a mutating, destructive operation, and the description aligns with that (no contradiction). The description adds the 'executing' precondition but discloses nothing about side effects, irreversibility, or what happens to a canceled build. With the annotation covering the safety profile, a 3 is appropriate.

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 front-loaded sentence with zero filler. It is appropriately brief for its limited content, though the brevity partly reflects how little substance it carries.

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

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

For a destructive mutation tool with no output schema and two undocumented required parameters, this description is thin. It lacks parameter explanations, expected effects, and usage preconditions — an agent would struggle to call it correctly without external knowledge of the build system.

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 0% and the description names neither parameter. projectId and jobId are entirely unexplained — no guidance on what they identify, their format, or where to obtain them. The description makes no attempt to compensate for the schema gap.

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 '取消正在执行的构建任务' (cancel an executing build task) states a specific verb (cancel), a specific resource (build task), and a precondition (currently executing). The verb clearly distinguishes it from siblings like cocos_build_start and cocos_build_status, though it doesn't explicitly name or contrast those 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?

No guidance on when to use this tool versus siblings. It doesn't state prerequisites (e.g., that a build must be running), when not to use it, or that cocos_build_status might be a safer first check. The 'executing' condition is implied but never made 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 declare readOnlyHint=true and destructiveHint=false, so the safe read-only nature is covered. The description adds no extra behavioral context such as side effects, filtering semantics, pagination, or whether it includes all tasks or only active ones. It does not contradict the annotations.

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

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

The description is a single short sentence with no filler or repetition. It is appropriately sized for a simple list operation and front-loads the essential action and scope.

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 read-only list tool with one required parameter, the description is minimally viable, but it omits information about the return value or output structure, especially since no output schema exists. It gives an agent just enough to understand the purpose, but not enough to fully predict what will be returned.

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 0%, and the description barely compensates. It implies that projectId identifies the project whose build tasks are listed, but it does not explain how to obtain a valid projectId, what format is expected, or any additional meaning beyond the parameter name.

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

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

The description '列出工程的构建任务' states a specific verb (list) and resource (the project's build tasks), and the project scope is clear. It does not explicitly contrast itself with sibling tools like cocos_build_start or cocos_build_status, but the list action is evident from the wording.

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

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

No guidance is given about when to use this tool versus alternatives such as cocos_build_status, cocos_build_logs, or cocos_build_cancel. The description only states what it does, not when it should be preferred or what prerequisites exist.

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 destructiveHint=false, so the tool is known to be safe. However, the description adds no extra behavior: it doesn't mention pagination details, ordering of logs, or any potential limits. The description is minimal and fails to disclose that pagination may require multiple calls or that logs might be truncated. It does not conflict with annotations, but it also doesn't enrich them.

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

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

The description is extremely concise, one short phrase. Every word is informative. It is front-loaded with the action and resource, and there is zero waste. Given the brevity, it earns full marks for conciseness.

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

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

With 4 parameters, no output schema, and no annotations supplying behavioral details, the description is clearly incomplete. It only conveys that logs are read page by page, but does not cover key context like the meaning of projectId/jobId, pagination parameters (limit/offset), or the format of the response. An agent would struggle to correctly invoke this tool without additional inference.

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 0%, meaning the plain schema provides no descriptions for parameters. The description mentions '分页' (pagination) but not the specific parameters 'limit' and 'offset' that implement it, nor 'projectId' and 'jobId' which identify which logs to fetch. The description does not compensate for the lack of schema documentation; an agent must infer from parameter names alone, which is insufficient, especially since 'jobId' and 'projectId' are not self-explanatory in 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 action (page-read) and the specific resource (build logs). Although it's brief, it directly indicates what the tool does distinguishably from sibling tools like cocos_build_status (which checks build status) and cocos_build_list (which lists builds). It lacks explicit differentiation, but the verb and resource combination is sufficient.

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

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

There is no guidance on when to use this tool versus alternatives such as cocos_build_status or cocos_build_list. The description only implies that it's for reading logs, but does not specify scenarios like 'when you need to debug a failed build' or exclude cases where other tools are appropriate. For an agent with many sibling tools, this is a clear gap.

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?

注解已提供 destructiveHint=true 和 readOnlyHint=false，描述在此基础上额外说明了构建依赖本机 GUI 和已安装的平台工具，并通过'返回任务 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?

对于一个无输出 schema、含嵌套 options 参数且被标记为 destructive 的构建启动工具，描述给出了基本动作、前置条件和返回的任务 ID，足以发起调用。但缺少异步生命周期说明，例如应通过 cocos_build_status 轮询进度、用 cocos_build_cancel 取消，也没有提及失败条件或构建产物影响。

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 的字段描述覆盖率为 0%，描述需要用自然语言弥补参数含义，但这里只通过'Creator CLI''平台工具''已注册工程'间接对应 creatorPath、platform、projectId，未解释取值规则或格式。options 对象完全没有说明，因此参数语义披露不足。

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?

描述以具体动词'构建'和资源'已注册工程'为核心，并明确返回任务 ID，能够与 cocos_build_status、cocos_build_cancel、cocos_build_list 等兄弟工具清晰区分。标题虽接近，但描述补充了'已注册工程'和'返回任务 ID'这些关键细节。

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?

描述隐含了使用场景：用于启动一个已注册工程的构建，并且需要本机 GUI 和已安装的平台工具。但没有明确说明何时应该改用 cocos_build_status 查询进度、用 cocos_build_cancel 取消，或与其他构建相关工具对比，因此只有隐含指引而非明确路由。

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 destructiveHint=false, so safety is covered. The description adds the returned data categories, but it does not explain behavior like in-progress status handling, whether the call blocks until a build finishes, or how status values are represented.

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, direct sentence that conveys the core action and target items. It has no filler, and the verb is front-loaded, making it that it is genuinely concise without being vague in its core intent.

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

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

With no output schema, the description must explain what an agent should expect back, but it only lists 'status, artifacts, and log paths' without detailing values, enum possibilities for status, or shape of the response. This incompleteness leaves a agent uncertain about how to consume the results or handle in-flight builds.

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 has no descriptions for projectId or jobId, leaving no meaning beyond field names. Since schema coverage is 0%, the description was expected to clarify how these parameters function, but it only refers to 'build task' without linking to the actual 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's purpose: query build task status, artifacts, and log paths. It is specific enough to distinguish from build_start/build_cancel, but it does not explicitly differentiate itself from cocos_build_logs, which could imply log content rather than log paths.

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

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

The description provides no explicit usage context, when-to-use, or exclusions. It only states the core function, leaving the agent to infer when to use this over siblings like cocos_build_logs or cocos_build_list based on the name alone.

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 establish readOnlyHint=true and destructiveHint=false. The description adds value by disclosing the categories of information returned (version range, side effects, source validation status, historical evidence), which enriches the agent's understanding of what the tool reports without contradicting the read-only annotation.

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

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

A single dense sentence that front-loads the action verb and enumerates exactly what is retrieved. Every clause earns its place with no filler or redundancy.

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

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

With one simple parameter, no output schema, and read-only annotations, the description compensates by enumerating the return categories (schema, version range, side effects, validation status, evidence). It is complete enough for a describe tool; a minor gap is not mentioning that capabilityId typically comes from a prior cocos_capability_search.

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 0%, so the description bears responsibility for the parameter. However, there is only one parameter, capabilityId, whose semantics are self-evident from its name and the tool title. The description adds no explicit detail about the parameter but none is critically needed for a single string ID.

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

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

The description states a specific verb ('获取' - retrieve) and a well-defined resource: precise parameter schema, version range, side effects, validation status, and historical evidence for a given capability. This implicitly differentiates it from cocos_capability_search (which finds capabilities) and cocos_capability_execute (which runs them), though it never names those siblings explicitly.

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 by the need for a capabilityId and the describe-vs-search contrast with cocos_capability_search, but there is no explicit statement of when to prefer this tool over alternatives or when not to use it. An agent must infer that this is the follow-up to a search.

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 the operation as destructive and open-world, and the description adds meaningful behavioral caveats: it will not execute arbitrary eval, it executes according to a capability-defined schema, and callers must use the returned assetLocation.url rather than assuming an assets root. No contradiction with annotations is present.

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

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

The description is compact and each sentence adds a specific operational rule or caveat, with no filler. It is not front-loaded around the core purpose, but it remains tight and useful for a dangerous generic executor.

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 covers important preconditions, modification guidance, and the no-eval guarantee, but it omits the response shape, error behavior, and does not explicitly instruct the agent to call cocos_capability_describe to obtain the capability schema. Given the tool's open-world and destructive nature, more completion would be justified.

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 0%, so the description must carry parameter meaning, but it only explains expectedRevision and operationId. projectId, capabilityId, instanceId, runtimeInstanceId, and the params object are left unexplained beyond their names; pointing to the capability's schema helps for the params object but not for the top-level metadata.

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 title and description together convey that this tool executes a registered capability, and the description adds specificity by saying execution follows the capability's schema and that the executor will not run arbitrary eval. It is clear enough but does not explicitly contrast itself with sibling execution tools like workflow_execute or build_start.

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 concrete operational context: it mandates calling asset.location before creating resources, points to asset.organize.plan/apply for reorganizing existing assets, and recommends expectedRevision and a stable operationId for modifications. It does not explicitly say when to prefer this tool over sibling execution tools, but the prerequisites and workflow guidance are 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds only a sequencing hint (search before execute) but nothing about return format, pagination, or limitations. With annotations present, the description contributes little beyond what is already structured.

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 short (one phrase) but under-specified. It is not effectively concise because it omits essential operational details. Front-loading is minimal, and the single sentence fails to convey the tool's purpose or usage meaningfully.

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

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

With four parameters, no output schema, and no parameter descriptions, the tool is severely under-documented. An agent cannot reliably invoke this tool correctly without external knowledge. The description does not even hint at what the search returns or how to construct a valid query.

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 0%, and the description provides no information about the four parameters (query, module, limit, offset). The agent cannot infer what values are expected, what the query field searches, or how module filters results. This is a critical gap.

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

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

The description states a search operation directory, which is a clear verb+resource, but it is too vague to distinguish from sibling tools like cocos_operation_query or cocos_capability_describe. It doesn't specify what exactly is searched (capabilities? operations?) or what the results look like, leaving the agent to infer the scope.

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

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

The phrase '先查询再执行长尾功能' implies a search-before-execute workflow for long-tail functions, but it never names alternatives or provides explicit when-to-use versus when-not-to-use guidance. There is no mention of the relationship to cocos_capability_describe or cocos_capability_execute, leaving the agent to guess.

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 destructiveHint=true and readOnlyHint=false, indicating a mutating operation. The description adds no behavioral context beyond that—no side effects, prerequisites, or reversibility details. With annotations present, the bar is lower, but the description still fails to provide any value beyond what structured fields already convey.

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

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

The description is a single short sentence, but this is under-specification rather than effective conciseness. It omits critical information and does not front-load any actionable detail beyond a vague restatement of the tool name.

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

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

For a mutation tool with six parameters (including nested objects), no output schema, and zero schema coverage, the description is completely inadequate. An agent has no way to understand required arguments, effects, or how to construct a valid call. The description fails to meet the informational needs of 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?

Schema description coverage is 0%, meaning the schema provides no parameter explanations. The description does not mention any parameters, so it does not compensate for the lack of schema documentation. An agent cannot infer what nodeId or type mean from the 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?

Tautological: description restates name/title.

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of conditions, exclusions, or comparisons to sibling tools such as cocos_component_set, leaving the agent to infer usage from the name alone.

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=false and destructiveHint=true, and the description's 'modify' aligns with that. The description adds one useful behavioral detail: operations are verified by reading back. But it does not clarify side effects, destructive scope, or what happens if verification fails. 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 sentence with no wasted words and gets straight to the point. It is concise but repeats the title exactly, adding little structural value or scoping beyond the tool name.

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?

This is a destructive tool with six parameters, a nested object, no output schema, and zero parameter documentation. The description does not explain required inputs, read-back behavior in detail, what kinds of properties/references are supported, or any safety caveats. It is far from adequate for an agent to invoke this 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 0%, and the description does not explain any of the six parameters. It vaguely hints that 'properties and references' are involved, which maps loosely to the 'properties' field, but it does not clarify componentId, projectId, expectedRevision, or the nested structure. This is minimal compensation for a schema that provides no parameter documentation.

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?

Tautological: description restates name/title.

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 offers no guidance about when to use this tool versus alternatives, no context, and no exclusions. It merely states the action ('modify component properties and references') without explaining scenarios, prerequisites, or related 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 already declare the tool read-only and non-destructive. The description adds useful behavioral context beyond that, especially the caveat 'partial 不代表没有可用操作' (partial does not mean no usable operations), which helps an agent interpret coverage results correctly.

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

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

The description is a single focused sentence that front-loads the primary purpose and adds one valuable interpretative caveat. There is no redundant wording or filler.

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

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

For a zero-parameter, read-only coverage tool, the description provides the main data categories and scope ('全部 54 个模块'). It does not detail the return format, but the lack of parameters and the straightforward query nature make the current description mostly 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?

The input schema has zero parameters and schema description coverage is 100%, so no parameter documentation is needed. Per the baseline for zero-parameter tools, this is adequate.

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 ('查看全部 54 个模块...') and the specific resource: scope acceptance, capabilities, independent service tool counts, and historical evidence. It is specific but does not explicitly differentiate itself from sibling tools such as cocos_capability_search or cocos_operation_query.

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 is a high-level coverage overview, but it gives no explicit guidance on when to use this tool versus alternatives, nor does it state when not to use it. The partial-coverage clarification is interpretive, not usage-routing 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?

Beyond the readOnlyHint=true annotation, the description adds a relevant behavioral guarantee: no authentication credentials are returned, and the instances are already open. This extra constraint helps an agent avoid expecting credentials, though output shape and empty/error behavior are not covered.

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

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

One concise sentence states the purpose and adds a relevant caveat. There is no filler, and the important credential warning is placed at the end without hurting readability.

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 one-parameter read tool, the description is acceptable, but there is no output schema and the description does not outline the returned content or an empty/failure case. This is not critical but is a clear gap given the complete absence of output schema 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?

The schema gives projectId as a string, but its description coverage is 0%. The tool description merely says 'the specified project,' which does not materially explain the meaning of projectId, its possible identifiers, or how it is obtained. The description does not compensate for the low schema coverage.

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

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

The description states a specific verb and resource: it lists opened Creator instances for a specified project. It is clear operationally, but it does not differentiate from cocos_runtime_instances except through the tool name and title, so sibling distinction is left to inference.

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

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

The phrasing implies use when the agent needs to see already-open Creator sessions for a project. However, there is no explicit when-to-use versus the runtime sibling, and the 'specified project' parameter is not developed into whichever timing or alternative context.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, and the description does not contradict that. However, the description adds only that it returns actual node information; it does not explain side effects, whether existing nodes are modified, what happens on partial failure, or what the returned node information is used for.

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 brief sentence with no filler or redundancy. It is front-loaded and easy to parse, though it adds almost no information beyond the title.

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

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

With six parameters, no output schema, no parameter documentation, a destructive annotation, and many sibling tools, this minimal description is far from sufficient. An agent cannot reliably determine required inputs, expected behavior, or return format from the provided context.

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

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

Schema description coverage is 0%, and the description provides no explanation for six parameters including the nested params object, projectId, parentId, assetUuid, operationId, or expectedRevision. The description completely fails to compensate for the schema's lack of parameter documentation.

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?

Tautological: description restates name/title.

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

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

There is no guidance on when to use this tool versus alternatives such as cocos_node_set, cocos_prefab_instantiate, or cocos_component_add. The description does not mention prerequisites, parent-node requirements, or cases where a different node-related tool should be chosen.

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 read-only nature is already declared by annotations (readOnlyHint=true, destructiveHint=false). The description adds no further behavioral context such as whether the scene must be open, whether it reads runtime or saved state, or what the return value contains. It merely restates the operation.

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

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

The description is a single, lean sentence with no fluff or repetition beyond the title. It is front-loaded and easy to parse, though it offers no structural depth; the brevity is a plus for conciseness but not for completeness.

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 six parameters, a nested params object, no output schema, and no parameter descriptions, the description is far too sparse. It omits what the query returns, how the optional identifiers are used, and any preconditions, leaving an agent to rely on guesswork.

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 0%, so the description must compensate, but it only implies the meaning of nodeId via the noun 'node'. Optional parameters like instanceId, operationId, expectedRevision, and runtimeInstanceId are entirely unexplained, leaving an agent with significant ambiguity on how to invoke the tool correctly.

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?

Tautological: description restates name/title.

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

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

No guidance is provided for when to use this tool versus related alternatives such as cocos_scene_query, cocos_asset_query, or cocos_capability_describe. There are no conditions, prerequisites, or exclusions 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 establish that the operation is mutating and destructive (readOnlyHint=false, destructiveHint=true), so the description aligns with them. It adds one useful behavioral trait beyond the annotations: the tool does not merely set properties but also reads back to verify the change. However, it does not disclose what side effects are involved, whether changes persist, or what happens to pre-existing properties.

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 very short and front-loaded with the core action, and every word is purposeful. But it is essentially identical to the title and provides no elaborative structure, so it reads as under-specified rather than succinctly structured.

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

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

For a destructive 6-parameter tool with a nested object, no output schema, and many related siblings, the description is incomplete. An agent cannot infer the return format, how read-back verification is exposed, the meaning of optional parameters, or the scope of the destructive behavior. The description alone is not enough to call this tool correctly in varied contexts.

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 0%, so the description must compensate for the six parameters, but it only gestures at the 'properties' object via '节点属性' and leaves nodeId, projectId, instanceId, operationId, expectedRevision, and runtimeInstanceId entirely unexplained. This is a significant gap for a tool with a nested properties object and optional concurrency-related 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?

Tautological: description restates name/title.

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

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

No guidance is given about when to choose this tool over alternatives like cocos_node_query, cocos_node_create, or cocos_component_set, nor are exclusions or prerequisite conditions mentioned. The description only describes the action itself without any decision context.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful context about the post-timeout/idempotency use case, which goes beyond annotations. However, it does not disclose what the response contains, what states an operation can be in, or what errors might occur.

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

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

The description is a single sentence that front-loads the trigger condition and purpose with no filler. It is concise and efficient for the apparent simplicity of the tool.

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

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

With no output schema and 0% schema description coverage, the description needs to explain what the query returns and how the parameters relate. It only gives the after-timeout use case, leaving an agent unable to determine how to interpret the result or where operationId comes from.

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 0%, so the description must compensate. It only mentions operationId by name without explaining its origin or meaning, and it says nothing about projectId or instanceId, leaving required parameters under-specified.

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?

Title '查询操作结果' and description clearly identify a read-only query of an operation by operationId, with the specific purpose of checking after timeout or disconnection. It is distinct enough from sibling tools, though it does not explicitly describe the shape of the returned result.

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 triggering condition ('超时或断线后') and the intended benefit (avoid duplicate execution of modifications). It does not name alternatives or exclusion criteria, so it stops short of full routing 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 mark this as destructive (destructiveHint=true) and non-read-only, but the description adds no behavioral context beyond the title. It does not mention what changes in the scene, whether the prefab is instantiated as a child of something, or any side effects. The description does not contradict the annotations, so no contradiction is flagged.

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

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

The description is a single short phrase, which is concise but under-specified. It only repeats the title and provides no structured information, earning it a low score because brevity here is a result of omission, not efficient communication.

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

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

With 6 parameters, no output schema, destructive annotations, and a large set of sibling tools, this tool needs far more than a one-line restatement. The description is completely inadequate for an agent to understand how to invoke it correctly or interpret its effects.

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

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

Schema description coverage is 0%, and the description provides no parameter explanations. Required fields like uuid and optional fields like parentId are completely unexplained, so the agent cannot infer their meaning or formatting from the description. This is a critical gap given the nested params object.

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?

Tautological: description restates name/title.

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

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

The description gives no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. It merely restates the tool's purpose, so an agent has no information about when this is the right choice among the many sibling 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 already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description adds valuable context that the list reflects projects registered at service startup, implying a snapshot that may not include later changes. This is beyond the annotations and helps the agent understand the scope and potential staleness of the data.

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 leads with the verb and resource, and the qualifier is placed naturally. There is no fluff or redundant phrasing. It is perfectly concise and front-loaded, making it easy for an agent to parse quickly.

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—no parameters, read-only, no output schema—the description is nearly complete. It states the purpose and the timing qualifier. While it does not explicitly describe the return format, the verb '列出' strongly implies a list of project identifiers or details, which is sufficient for a tool of this complexity. The lack of an output schema means the description could have clarified the return, 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?

The tool has zero parameters, and the schema coverage is 100% (empty schema). According to the rubric, a baseline of 4 applies for zero-parameter tools. The description does not need to explain any parameter semantics because there are none, and it does not attempt to add irrelevant information.

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 '列出' (list), the resource '工程' (projects), and a specific qualifier '服务启动时注册的' (registered at service startup), which distinguishes it from other listing tools like cocos_instances or cocos_build_list. The purpose is unambiguous and immediately understandable.

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: use this tool when you need to list projects. However, it provides no explicit guidance on when to use this versus sibling tools like cocos_instances, and it does not mention any exclusions or alternatives. The usage context is clear but not elaborated.

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 already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. Beyond that, the description adds no behavioral context such as output format, side effects, or any preconditions; it merely restates the tool's purpose.

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 short, but it is essentially the title repeated and carries no added information. This is under-specification rather than effective conciseness, since the single sentence does not meaningfully aid tool selection or invocation.

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 6 parameters, nested objects, no output schema, and zero parameter documentation, the one-line description is severely inadequate. An agent cannot determine how to invoke the tool correctly, what inputs matter, or what result to expect.

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 0%, and the description provides no explanations for the two required parameters (projectId, params) or the many generic fields inside params. With no parameter guidance in either the schema or the description, an agent cannot infer what arguments to supply.

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?

Tautological: description restates name/title.

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

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

There is no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. An agent is given no context for deciding between cocos_runtime_capture and other capture-related or scene-related 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 already declare readOnlyHint=true and destructiveHint=false, establishing the operation is safe. The description adds the useful qualifiers 'connected' and 'development', but it does not reveal what the returned data looks like or how connection state is determined. It does not contradict the annotations.

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

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

The description is a single, front-loaded sentence with no filler. It states the operation and resource efficiently, adding the key qualifiers 'connected' and 'development' without extraneous detail.

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 read-only listing tool with one parameterستان completeness is adequate, but the description leaves projectId semantics unexplained and fails to distinguish this tool from cocos_instances. There is also no output schema or return-value description, so an agent only receives minimal context.

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

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

The only parameter, projectId, has no schema description (0% coverage), and the tool description does not explain its meaning, expected format, or how to obtain it. Because schema coverage is low, the description should compensate, but it provides no parameter-level guidance.

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 action (listing) and a specific resource (connected development runtime instances). It is distinct from generic names like cocos_instances, but it does not explicitly differentiate itself from that sibling tool.

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

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

The description gives no guidance on when to use this tool versus cocos_instances or other instance-related tools. There are no stated exclusions, prerequisites, or alternative tool recommendations, so the agent must infer the usage context from the tool name and description alone.

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 the tool read-only and non-destructive, and the description adds no behavioral context beyond that. It does not explain what a 'structured difference' returns, whether a baseline snapshot must already exist, or how the comparison is performed, missing an opportunity to add value beyond the structured hints.

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

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

The description is a single sentence with no filler or redundant words, so it is efficient and front-loaded with the core operation. However, this conciseness comes at the cost of omitting necessary details, making it short but not fully 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 six parameters, a nested object, and no output schema, the description is severely incomplete. It fails to describe return values, prerequisite states, or the meaning of parameters beyond a vague mention of 'baseline', making it difficult for an agent to call 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 0%, so the description bears the full burden of explaining parameters. It only mentions 'baseline snapshot' as a concept, but does not specify the required format or type for the 'baseline' parameter (e.g., a snapshot ID), nor does it clarify the roles of the other six 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?

Tautological: description restates name/title.

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

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

No guidance is given on when to use this tool versus alternatives such as cocos_scene_query or cocos_scene_snapshot. The agent must infer the intended use case solely from the operation name and the minimal description, leaving ambiguity about prerequisites or typical 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?

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation, but the description itself adds no behavioral context beyond the title. It does not explain what hierarchy structure is returned, how pagination behaves, or what includeInternal/includeComponents control.

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 short, but that brevity is under-specification rather than efficient conciseness. It repeats the title and provides no structured or front-loaded information to help the agent invoke the tool correctly.

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 six parameters, no output schema, and no parameter documentation, this one-phrase description is inadequate. The agent cannot determine what fields are returned, what the params mean, or how the hierarchy is scoped, so it is not complete enough to call reliably.

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 0% and the description names none of the six parameters, despite parameters like rootId, includeInternal, and includeComponents needing explanation. The only hint, 'paginated', maps vaguely to limit/offset and does not compensate for the missing schema documentation.

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?

Tautological: description restates name/title.

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 contains no guidance about when to use this tool instead of the many related scene/node/query tools. There is no context, no when-not-to-use, and no mention of alternatives among the sibling 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 already declare destructiveHint=true, so the agent knows this operation can be destructive. The description adds the specific guardrail behavior: it refuses to switch when there are unsaved changes, which is valuable context beyond the annotation. However, it doesn't disclose what happens on refusal (error? no-op?), whether the current scene is closed, or any side effects on the editor state. With annotations covering the destructive nature, the description adds some but not rich behavioral context.

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

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

The description is a single concise sentence that front-loads the primary action and includes the key behavioral constraint. Every word earns its place, and there is no fluff. It is appropriately sized for the information it conveys, though it could be slightly more structured with separate sentences for action and behavior.

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

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

This is a mutation tool (destructiveHint=true) with 6 parameters, 0% schema description coverage, and no output schema. The description is too thin to fully support correct invocation: it doesn't explain the uuid parameter, the meaning of projectId, the refusal behavior's error handling, or what happens after a successful open. An agent would need to infer too much about how to call this 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 0%, so the description must compensate for the 6 parameters. The description mentions 'scene' and 'unsaved changes' but doesn't explain that the 'uuid' parameter identifies the scene to open, nor what projectId, instanceId, operationId, expectedRevision, or runtimeInstanceId mean. The nested params object with a required uuid is left entirely undocumented. The description adds almost no parameter-level meaning.

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?

Tautological: description restates name/title.

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 you want to open an existing scene, and it warns that it will refuse if there are unsaved changes. This gives some context about a precondition (no unsaved changes) but doesn't explicitly state when to use alternatives like cocos_scene_query or cocos_scene_snapshot, nor does it mention any workflow prerequisites like needing a projectId or instanceId.

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 destructiveHint=false, so the description's 'read' aligns with them. The phrase '修改状态' is most plausibly interpreted as 'modification state' (a query target) rather than a write action, so it does not contradict annotations. However, the description adds little beyond the annotation safety profile—only a vague hint about what is queried.

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

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

The description is a single short sentence, which is technically concise, but it is under-specified rather than efficiently structured. It lacks any hierarchy or key information placement, and every word is vague. Brevity here is not a virtue; it is avoidance of necessary detail.

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 six parameters, no output schema, and a nested params object, the description is utterly insufficient. It does not explain the operation context, expected inputs, return values, or relation to siblings. An agent cannot safely invoke this tool based on the provided information.

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 0% and the description offers no parameter details whatsoever. With six parameters including projectId, operationId, instanceId, and a params object, an agent has no idea what values to supply or what the params object should contain. The description completely fails to compensate for the absent schema documentation.

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?

Tautological: description restates name/title.

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

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

No guidance is given on when to use this tool versus the many scene-related siblings (snapshot, diff, hierarchy, open, save, node_query, etc.). No exclusions or alternative conditions are mentioned, leaving the agent to guess which tool fits the task.

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 signal a destructive mutation (destructiveHint=true, readOnlyHint=false), and the description's 'save' is consistent. However, the description adds little beyond what annotations provide and does not explain what happens on save, what state is queried, or what 'modification status' means.

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

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

The description is a single short phrase, but this brevity is under-specification rather than effective conciseness. Every word restates the title; no useful content is 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?

For a destructive tool (destructiveHint=true) with 6 undocumented parameters and no output schema, this definition is grossly incomplete. An agent has no idea what to pass, what the save does, what gets destroyed, or what the query returns.

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 0% with 6 parameters, and the description mentions none of them. The description must compensate for the schema gap but provides zero parameter information, leaving projectId, params, operationId, expectedRevision, and the instance fields unexplained.

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?

Tautological: description restates name/title.

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

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

No guidance on when to use this tool versus alternatives. With many scene-related siblings (cocos_scene_query, cocos_scene_snapshot, cocos_scene_diff, cocos_scene_open, cocos_scene_validate), there is no differentiation and no context for 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds the concept of 'replayable' (可重放) and 'serialized snapshot' (序列化快照), which implies the output is a serialized representation that can be used to replay the scene state. However, it does not disclose what exactly is captured, whether the snapshot is stored or returned, or any side effects. With annotations covering the safety profile, a 3 is appropriate – the description adds some behavioral context but not rich detail.

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

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

The description is a single sentence, which is concise and front-loaded with the core action. However, it is also a near-verbatim repetition of the title, adding little new information. It earns its place as a minimal statement but does not use the available space to add differentiating or clarifying details. It is not bloated, but it is under-specified.

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 6 parameters, no output schema, and no parameter descriptions, the description is incomplete. It does not explain what the snapshot contains, how it is returned, whether it is stored, or how 'replayable' works. The sibling tools suggest a rich scene-management context, and this tool's description does not provide enough context for an agent to know what to expect from the call or how to interpret the result. The annotations cover safety, but the operational context is missing.

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

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

Schema description coverage is 0%, and the description does not explain any parameters. The schema shows required projectId and params, with params being an empty object, but the description does not clarify what projectId refers to or what params should contain. Since the schema provides no descriptions and the description text adds no parameter meaning, the agent has to guess. The empty params object is particularly confusing – it suggests no parameters are needed, but the schema requires it. The description should at least explain that params is an empty placeholder or what projectId identifies.

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?

Tautological: description restates name/title.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention that this is a read-only snapshot operation, nor does it explain when one would prefer it over cocos_scene_query, cocos_scene_diff, or cocos_runtime_capture. The agent is left to infer usage from the name and description alone, with no explicit context or exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's 'check' is consistent. However, the description adds no behavioral context beyond annotations—it does not explain what happens when issues are found, whether it returns a report, or any side effects. Since it does not contradict annotations and the read-only nature is covered, a baseline 3 is appropriate.

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, extremely concise and front-loaded with the core action. However, it simply repeats the title verbatim, adding no new structure or detail. It earns a 4 for brevity but lacks any additional organizational 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?

The tool has six parameters, no output schema, and no parameter descriptions. The description gives no information about what inputs are expected, what the tool returns, or when to invoke it. For a validation tool that likely requires specific scene context and produces a report, this is severely incomplete.

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

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

Schema description coverage is 0%—none of the six parameters (projectId, params, instanceId, operationId, expectedRevision, runtimeInstanceId) have descriptions. The tool description does not explain any of them either. With zero schema coverage, the description must compensate, but it provides no parameter semantics whatsoever.

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?

Tautological: description restates name/title.

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

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

There is no guidance on when to use this tool versus alternatives. It does not mention scenarios like pre-build validation, prerequisites, or exclusions. The agent receives no context to decide between this and other cocos_scene_* 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 declare destructiveHint: true, and the description adds a note about 'partial failure uses local compensation' – a behavioral detail not covered by annotations. However, this note is vague (what is 'local compensation'? what side effects occur?), and it does not disclose destructiveness or any other concrete effects. It adds minimal value beyond the annotation, but does not contradict it.

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 identical to the title. It is under-specified, not concise; it provides no front-loaded critical information and every word merely repeats what is already in the name. It fails to earn its place as a useful description.

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 (6 parameters, nested document schema, destructive annotation, no output schema), the description is grossly inadequate. It does not explain the return value format (UUID mapping), the meaning of 'planned UI tree', or how partial failure compensation works. An agent cannot safely or correctly invoke this tool based on this description.

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 0%, so the description must explain parameter meaning, but it provides none. It does not mention projectId, params, parentId, document, planHash, or any of the nested structures. Agents have no semantic guidance for constructing valid inputs.

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

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

Tautological: description restates name/title.

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

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

There is no guidance on when to use this tool versus alternatives. The description does not mention prerequisites, expected inputs (like planHash), or when to prefer this over related build or scene tools. An agent cannot determine the appropriate context from this description.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description adds value by disclosing failure behavior ('默认遇到失败即停止') and return information (completed steps and compensation hints). It does not contradict annotations and provides context beyond the structured data.

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

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

The description is a single, front-loaded sentence that states the core purpose and key behavior with no extraneous words. It is concise and well-structured for a tool of this nature.

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 (4 parameters, nested schema, no output schema), the description is insufficient. It omits details on how to structure steps, the meaning of continueOnError, how to reference prior step outputs, and what the compensation hints look like. An agent would struggle to construct a valid request without additional schema descriptions.

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 0%, and the description does not explain any parameters such as steps, projectId, continueOnError, or workflowId. The nested structure of steps (with fields like paramRefs, waitFor, capabilityId) remains completely undocumented, leaving the agent without essential guidance for correct invocation.

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 executes planned capabilities in sequence, with a specific verb and resource. It distinguishes itself from sibling tools like cocos_workflow_plan (planning) and cocos_capability_execute (single capability) by emphasizing '已规划能力' (planned capabilities) and sequential execution.

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 pre-planned workflows via '已规划能力', but does not explicitly state when to use this tool versus alternatives like cocos_capability_execute or cocos_workflow_plan. No exclusions or alternative conditions are provided; the guidance is implicit rather than explicit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds that it validates parameters, versions, risks, and side effects, which is useful behavioral context beyond the annotations. However, it does not disclose return format, error handling, or how the validation results are presented.

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 Chinese sentence. It front-loads the primary action (batch validate) and then adds the key clarification (non-modifying). No wasted words.

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

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

The tool has a complex schema with a required array of step objects containing many nested fields, and there is no output schema. The description provides no details about step structure, field meanings, constraints, or what the tool returns. This is critically incomplete 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?

The schema has 0% description coverage, and the description provides no parameter explanations. It does not clarify what projectId and steps mean, nor the semantics of nested fields like waitFor, paramRefs, runtimeRef, expectedRevision, etc. The agent must rely solely on names, which is insufficient for correct invocation.

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 validates capability parameters, versions, risks, and side effects, and explicitly notes it does not modify the project. This distinguishes it from execution tools like cocos_workflow_execute and aligns with the title 'plan workflow'. The action and resource are specific and 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 implies usage for planning/validation before execution by stating 'planning will not modify the project'. However, it does not explicitly name alternative tools or conditions for when not to use it. The context is clear but lacks explicit routing to 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 communicate that this is a read-only, non-destructive operation, and the description is consistent with that. The description adds useful context about workflow step progress, failure location, and final result, but it does not disclose behavior for unknown workflows, missing workflow IDs, or the response format.

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

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

The description is a single, efficient, front-loaded sentence with no filler, and it directly states the query result categories. It is structurally clean, though slightly too sparse to fully support the tool's missing parameter 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?

For a simple two-parameter read-only query, the description is close to viable because it states the output values. It is not fully complete: no output schema exists, the parameters have no descriptions, and the description does not mention how the caller would link projectId/workflowId to an existing persisted workflow.

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

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

Schema description coverage is 0%, so the free-text description should compensate by explaining projectId and workflowId and how to obtain them. It does not. The parameter names are suggestive but the description itself adds no semantic meaning beyond 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 uses a clear action verb (查询) and a concrete resource (持久化工作流), and it lists the exact information returned: step progress, failure location, and final result. It does not explicitly contrast it with sibling tools like cocos_workflow_plan or cocos_workflow_execute, so it stops short of a 5.

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

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

The description explains what status information is returned but gives no guidance about when to call this tool instead of alternatives, whether the workflow must already be running or completed, or what to do when no status is available. The agent is left to infer any usage context from the tool name.

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