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

No annotations are provided, so the description must carry the full burden. It discloses a prerequisite (must load the SKILL) and that it reads from a capability registry. However, it does not explicitly state that the operation is read-only or describe the return format or behavior when the skill is not loaded. The verb 'list' implies a safe read, but robust behavioral detail is lacking.

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

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

The description is concise with two sentences and no filler. However, the main purpose appears in the second sentence, following the prerequisite, so it is not ideally front-loaded. Nevertheless, each sentence provides necessary information.

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

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

The tool is simple with one optional parameter and no output schema. The description explains the core functionality and a prerequisite, but it does not specify return values or behavior when no category is provided. With no annotations, these gaps leave some ambiguity for an agent.

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

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

The schema has a single 'category' parameter with enum values and a description, achieving 100% schema description coverage. The description only reiterates the ability to filter by category, which adds no new semantic information beyond the schema. The baseline of 3 applies since the schema is complete.

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 '列出能力注册表中的全部精选能力（可按分类筛选）' with a specific verb (list) and resource (all curated capabilities in the capability registry). This distinguishes it from sibling tools like capability_search by focusing on broad listing and overview rather than targeted searching.

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

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

The description provides a clear prerequisite (load the deveco-unified-mcp SKILL before use) and states its purpose is '供发现与总览' (for discovery and overview), which gives context for when to use it. However, it does not explicitly contrast with alternatives like capability_search or specify when not to use it.

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?

With no annotations, the description carries the full burden. It discloses that operations may be long-running, failure messages usually contain solution hints, and internally it performs parameter validation before calling devecocli or the skill marketplace API. However, it does not address side effects, permissions, or whether operations are reversible/ cancellable.

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

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

Three sentences, each earning its place: prerequisite, execution mechanism, and operational caveats. Information is front-loaded and there is no fluff.

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

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

For a generic executor with only 2 parameters and no output schema, the description covers the essential context: prerequisite, ID sourcing, internal flow, time expectations, and failure behavior. It lacks explicit output/return format, but that is reasonable given the absence of an output schema and the tool's generic nature.

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 already provides complete descriptions for both parameters (capability_id with examples, args with key-name guidance). The description adds minor context about sourcing capability IDs from list/search tools and the existence of parameter validation, but these are incremental over the rich schema.

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

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

The description clearly identifies the tool as an executor of HarmonyOS development capabilities by ID, with a specific mechanism (parameter validation → devecocli or skill marketplace API). It distinguishes itself from sibling tools by explaining that capability IDs come from capability_search or capability_list, positioning itself as the execution counterpart.

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

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

Provides explicit workflow guidance: load the SKILL first, obtain capability IDs via capability_search or capability_list, and warns about long-running build/run operations. However, it does not explicitly state when not to use this tool or name specific alternative tools beyond the ID-acquisition ones.

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?

No annotations are provided, so the description must disclose behavior. It mentions that the tool performs RAG-style retrieval, returns a capability card with usage teaching, and has a prerequisite (load SKILL). However, it does not explicitly state that the operation is read-only or has no side effects, though this is implied by '检索' (search). It adds moderate context beyond the name and schema.

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, consisting of three sentences that respectively cover prerequisite, purpose, and usage workflow. Every sentence adds value: the SKILL requirement, the retrieval nature, and the follow-up with capability_run. No fluff or redundancy.

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

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

The description covers the prerequisite (load SKILL), the tool's purpose, when to use it, what it returns (capability card with parameters/examples/pitfalls), and the follow-up action (capability_run). Given there is no output schema, this sufficiently orients the agent. Minor gaps like explicit mention of pagination or default behavior are not critical for a simple search tool.

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

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

Schema coverage is 100%, with descriptions for all three parameters: query (natural language with examples), limit (return count), and category (with enum). The description does not add extra parameter details, but the schema already provides sufficient semantics. The baseline of 3 is appropriate when the schema fully documents 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 states it is a 'RAG 式检索精选能力注册表' (RAG-style retrieval of curated capability registry), giving a specific verb and resource. It also distinguishes itself from sibling capability_run by explicitly positioning this tool as the first step to find capabilities before executing them. It could more explicitly differentiate from docs_search or skills_find, but its focus on capabilities is clear.

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

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

The description clearly states that any HarmonyOS development task (构建、运行、日志、文档、技能…) should first use this tool, and that the returned capability card should then be executed with capability_run. It also gives the prerequisite of loading the deveco-unified-mcp SKILL. It does not explicitly mention when not to use it, but the workflow is well-defined.

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?

With no annotations provided, the description carries full transparency burden. It discloses the tool lists documentation categories and implies a read-only action, but it does not describe the output structure, potential side effects, or why the SKILL must be loaded first. The prerequisite is a useful behavioral note, yet overall behavioral detail is minimal for a tool with no annotations.

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

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

The description is two short sentences: the first is a necessary prerequisite instruction, the second states the core action with examples. No filler or redundancy. Every word earns its place, and the structure front-loads the operational requirement before the main purpose.

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

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

For a simple catalog-listing tool with no parameters and no output schema, the description is largely complete: it states what the tool does, gives example output content, and notes a prerequisite. It does not describe the exact return format, but given the simplicity and clear scope, this is a minor gap rather than a significant deficiency.

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

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

The tool has zero parameters, so there is nothing to explain beyond the schema. The description does not need to add parameter meaning, and the empty schema already communicates the absence of inputs. Per calibration rules, zero parameters warrants a baseline score of 4, and the description does not undercut this.

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

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

The description clearly states the tool's function: '列出官方文档库的分类' (list categories of the official documentation library), with concrete examples of categories. This distinguishes it from sibling tools like docs_search and docs_read, which handle searching/reading content rather than catalog navigation.

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

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

The description provides a clear prerequisite: users must load the 'deveco-unified-mcp' SKILL before use. However, it gives no explicit guidance on when to choose this tool over alternatives (e.g., docs_tree) or when not to use it. The usage context is implied but not contrasted with 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?

No annotations are provided, so the description carries full burden. It discloses that the tool retrieves full markdown content and that SKILL loading is required, which are useful behavioral details. It doesn't address error handling or side effects, but for a read-only docs tool, this is adequate.

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

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

The description is two concise sentences, front-loaded with the prerequisite and then the core purpose. Every sentence earns its place without redundancy.

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

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

The tool is simple (one ID parameter). The description covers the return format (full markdown), required prerequisite (SKILL), and ID source (docs_search). It references SKILL.md for more detail. Minor gaps like error behavior don't significantly impair completeness.

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

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

The schema already fully describes the single parameter with an example. The description adds crucial semantic context: the document ID must come from the documentId field of docs_search results, preventing arbitrary or guessed IDs. This goes beyond schema.

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

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

The description clearly states the action (read by document ID), the resource (HarmonyOS official documentation), and the output format (markdown). It distinguishes itself from sibling tools like docs_search (which searches) and docs_catalog/docs_tree (which browse).

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 explicitly instructs to load the deveco-unified-mcp SKILL before use and states that the document ID must come from docs_search results, effectively giving the workflow: search first, then read. This is clear guidance on prerequisites and data source, distinguishing when to use this tool.

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

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

With no annotations, the description carries the full transparency burden. It discloses the corpus scope and included document categories but does not describe result behavior (e.g., snippets, paths, relevance ordering) or any side effects. This is adequate but not more.

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

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

The description is only three sentences: prerequisite, function, and usage context. Every sentence contributes meaningful operational guidance, and the most important prerequisite is front-loaded. 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?

For a search tool with no output schema, the description covers the corpus, scope, and when to use it, and points to the SKILL manual for workflow standards. It does not explicitly mention how results should be consumed (e.g., via docs_read), but the schema and SKILL reference fill most gaps.

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

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

The input schema covers 100% of parameters with descriptions, defaults, enums, and examples. The tool description adds general purpose and use-case context but no parameter-specific meaning beyond what the schema already provides. Baseline of 3 is appropriate.

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

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

The description uses a specific verb ('全文检索') and a clearly defined resource: local 2000+万字 HarmonyOS 官方文档 across enumerated categories. It distinguishes this search tool from sibling read/browse tools by positioning it as the pre-coding lookup step.

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 explicit usage context: before writing ArkTS/ArkUI code, when unsure about an API, component, or concept. It also mandates loading the SKILL first as a prerequisite. However, it does not explicitly name sibling alternatives or state when not to use this tool.

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

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

No annotations are provided, so the description carries the full burden. It discloses an important prerequisite (loading the deveco-unified-mcp SKILL) and explains behavioral context: the tree structure, page titles, and the fact that page paths serve as document IDs for docs_read. This goes beyond basic function naming, though it omits details like output format or pagination, which are not critical for a simple browsing tool.

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 three sentences long and every sentence earns its place: the first states a prerequisite, the second defines the core function, and the third explains output usage and connection to docs_read. It is front-loaded with the most important operational requirement and contains no redundant fluff.

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

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

Given the absence of an output schema, the description adequately communicates the return concept (directory tree with categories, chapters, pages, and titles) and how to use the results (path as document ID). It covers the workflow and relationships with sibling tools. Some details like depth behavior are already in the schema, so the description is complete enough for a straightforward browsing tool.

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

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

Schema description coverage is 100%, with each parameter (path, depth, catalog) already having clear descriptions in the input schema. The tool's description adds no extra parameter-level meaning; it only mentions that page paths can be used as document IDs, which is output-related rather than parameter-specific. Baseline 3 is appropriate since the schema handles parameter semantics.

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

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

The description clearly states the tool's function: '浏览官方文档库目录树（分类→章节→页面，页面附标题）' (browse official documentation library directory tree: category→chapter→page, pages have titles). It uses a specific verb plus resource and identifies the hierarchical structure, distinguishing it from sibling tools like docs_search and docs_read by positioning it as the initial navigation step.

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

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

The description provides explicit workflow guidance: '先目录定位再全文检索再读全文' (locate via catalog first, then full-text search, then read full text), and notes that page paths from this tool can be used directly with docs_read. It clearly indicates when this tool should be used relative to search and read tools, though it does not explicitly mention when not to use it or compare with docs_catalog.

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?

No annotations are provided, so the description carries the burden. It discloses the prerequisite of loading the SKILL and clarifies that installation happens separately via capability_run, implying the search itself is read-only. It does not detail pagination or auth, but the core behavioral context 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: two sentences covering prerequisite, search location, and installation next step. It is front-loaded and every sentence contributes value, though the dense phrasing slightly reduces 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?

With only one simple parameter and no output schema, this is a straightforward search tool. The description covers the prerequisite, the search scope, and the downstream install action, making it reasonably complete for an agent to invoke correctly. It could mention return format, but that is not critical here.

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 already has 100% coverage with a description and examples for the single keyword parameter. The description only echoes the same example categories without adding new param-specific meaning, so it stays at the baseline.

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

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

The description clearly states the tool searches the HarmonyOS skills marketplace (matrix.openharmony.cn) for expert skill packs, using specific verbs and resource. It differentiates from sibling tools like docs_search and capability_search by targeting the skills marketplace specifically, and mentions the follow-up install via capability_run.

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 provides clear workflow context by requiring the deveco-unified-mcp SKILL to be loaded first, and tells the agent to use capability_run's skills.add to install after finding. It does not explicitly list when not to use it, but the practical guidance is sufficient.

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?

With no annotations provided, the description carries the full burden. It discloses what is checked and notes that the optional device check is slow, which is useful. However, it does not explicitly state whether the tool is read-only, what happens on failure (e.g., missing devecocli), or any side effects. This is adequate but not rich.

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

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

The description is two sentences and to the point. The first sentence is a prerequisite instruction rather than the core purpose, but it is still relevant. It is front-loaded with the SKILL loading requirement, which might be better placed elsewhere, but overall it is efficiently written with no filler.

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

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

The tool is simple (one optional parameter, no output schema, no annotations), and the description lists all the checks it performs. However, it does not explain the return format or what happens if the environment is not ready. While the context of first-use is given, the lack of output description is a gap given there is no output schema.

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

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

The schema covers the single boolean parameter check_devices with a description, so schema coverage is 100%. The tool description adds a slight context by mentioning '(可选)连接设备' but does not go beyond the schema's own description. Since the schema does the heavy lifting, a baseline of 3 is correct.

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 checks the runtime environment (devecocli installation, docs library, HarmonyOS project, optional device connection). The verb '检查' (check) with the listed resources is specific and distinguishes it from sibling tools like docs_* and capability_* which focus on documentation and capabilities. The title also reinforces the purpose.

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

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

The description explicitly says to call this tool first on initial access to confirm the environment, and it also notes the prerequisite of loading the deveco-unified-mcp SKILL. This gives a clear usage context. However, it does not explicitly mention when not to use it or provide direct alternative tools, so a 4 is appropriate.

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