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

The description goes well beyond the readOnlyHint annotation by disclosing the exact verification steps: API clients exchange tokens with Huawei, and Service Accounts locally sign JWT and call a query interface. This informs the agent that the tool may perform network calls and credential validation despite being read-only. No contradiction with annotations exists.

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

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

The description is a single dense sentence that front-loads what is displayed and then provides the verification details. Every clause adds value, and the structure is easy to parse. No filler or repetition.

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

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

For a zero-parameter diagnostic tool with readOnlyHint, this description is complete. It covers what is displayed, what is verified, and how each credential type is validated. Since there is no output schema, the description sufficiently communicates the tool's behavior and expected result.

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

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

The tool has zero parameters and schema coverage is 100%, so there is nothing for the description to add. The baseline of 4 applies because the description correctly omits parameter details that would be redundant.

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 action (display and verify) and the resource (AGC auth configuration: credentials, sites, read-only mode). It distinguishes this tool from the sibling tools, which focus on API requests, app info, reviews, and file operations. The addition of concrete verification steps leaves no ambiguity about what this tool does.

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

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

The description implies this tool should be used to inspect and validate AGC authentication setup, especially before making API calls. However, it does not explicitly state when to use it compared with alternatives, nor does it mention any exclusions or prerequisites. The intended usage is understandable but left to inference.

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

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

Annotations already mark readOnlyHint and openWorldHint. The description adds meaningful behavioral context beyond those: content is pulled live from Huawei's documentation center and cached locally for 7 days, and it accepts title/docId fragments as well as full docIds. This is useful operational information; no contradictions with annotations.

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

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

The description is two dense sentences: the first states the deliverable and format, the second states source/caching behavior and input sourcing. No filler or repetition of schema field names.

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 doc-fetch tool with no output schema, the description fully characterizes the return value (Markdown with URL, parameter tables, response fields, examples) and the includeExamples default. It gives enough operational detail to select and invoke the tool correctly, with annotations covering the safety profile.

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

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

Schema coverage is 100%, so the baseline is 3, and the description goes beyond the schema by explaining that docId can come from agc_search_api's doc field, or be an exact title or a docId fragment. This resolves ambiguity not present in the schema's terse docId description.

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

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

The description opens with a concrete verb-resource pair: it reads the full contents of a Connect API document, and enumerates what that content contains (Markdown, interface URL, header/query/body parameter tables, response fields, examples). It also explicitly ties docId to agc_search_api's doc field, which differentiates it from the search sibling.

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 gives clear context: use this after agc_search_api, whose doc field supplies docId, and it notes the alternative input forms (exact title or docId fragment). It does not explicitly state when not to use it or name excluded alternatives, but the routing from search to retrieval is clear.

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

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

Annotations already declare readOnlyHint and openWorldHint, and the description does not contradict them. It adds useful constraints (max 50 names) and the fact that the result is an appId, but it does not describe response shape, ordering, error behavior, or how open-world results should be interpreted.

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

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

A single sentence with no filler: it front-loads the input constraint and states the output. Every word earns its place.

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

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

For a single-parameter, read-only lookup tool, the description covers what is consumed and what is produced at a sufficient level. It could be more explicit about how multiple package names map to returned appIds, but the low complexity and readOnly/openWorld annotations make the current description reasonably complete.

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

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

The schema already documents packageNames with comma-separated format and an example, so the baseline is high. The description adds the meaningful max-50 bound that is not present in the schema, which helps an agent correctly size the input before calling the tool.

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 names the exact operation and resource: query AGC app ID from package names, with the specific limit of 50 comma-separated names. It is clearly a package-name-to-appId lookup, though it does not explicitly contrast itself with sibling tools like agc_list_apps or agc_get_app_info.

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 choose this tool over sibling alternatives, nor any when-not-to-use conditions. The only context is the operation itself; no alternative tool is named or excluded.

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 openWorldHint=true, so the agent knows this is a safe read operation. The description adds that it returns multiple categories of information (basic info, language descriptions, review comments, staged release info), which is useful. However, it doesn't disclose details like pagination, response size, or that review comments might be nested within the response.

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 main purpose and lists the key content categories. It's efficient and doesn't waste words, though it could be slightly more structured with separators.

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 query tool with 80% schema coverage and no output schema, the description covers the main purpose and content categories. However, it doesn't mention the relationship between releaseType and versionId (though the schema does), nor does it clarify what '分阶段发布信息' means in practice. The openWorldHint suggests the tool may return data from external sources, but the description doesn't elaborate.

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 80%, so the schema already documents most parameters. The description adds the overall purpose but doesn't add meaning beyond the schema for individual parameters. The releaseType and versionId relationship is already in the schema. Baseline 3 is appropriate.

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

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

The description states a clear verb ('查询' = query) and resource ('应用详细信息' = app detailed info), listing specific content categories: basic info, language descriptions, review comments, staged release info. It distinguishes from siblings like agc_list_apps (which lists apps) and agc_list_reviews (which lists reviews), though it doesn't explicitly name them.

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

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

The description implies usage for querying app details, and the schema's platform/releaseType fields provide some context (e.g., harmonyos vs android, releaseType=6 requires versionId). However, it doesn't explicitly state when to use this tool vs alternatives like agc_list_apps or agc_list_reviews, nor does it mention 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?

The readOnlyHint and openWorldHint annotations already communicate safety and openness. The description adds value by explaining successStatus values (0/1/2), which is useful output context not present in the schema. It does not describe error handling, missing packages, or rate limits, but with annotations covering the read-only nature, 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?

The description is a single concise sentence that front-loads the core action and includes the key status mapping. It is efficient, though slightly too terse and omits the compile aspect from 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?

For a status-query tool with no output schema, the description should at least clarify the return semantics and suggest when to call it. It does explain successStatus but misses usage timing, the compile-vs-parse ambiguity, and any note about batch behavior. The schema covers parameters, but the overall context feels 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 67%, and the description adds no parameter-level explanations. The schema documents pkgIds and platform, but appId remains undescribed in both schema and description. The description's mention of successStatus does not aid parameter understanding, so it fails to compensate for the appId 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 the action ('查询') and resource ('软件包解析状态'), and the title clarifies it relates to compile/parse status. It is distinguishable from sibling tools like agc_get_app_info by the specific status focus. However, the description only says '解析' (parse) while the title says '编译/解析' (compile/parse), a minor inconsistency.

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 typical triggers (e.g., after package upload), prerequisites, or why to use this instead of agc_get_app_info. Usage context must be inferred entirely 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.

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

注解已标明 readOnlyHint=true，描述额外补充了注解未覆盖的行为约束：仅已上架应用有数据、时间跨度限制、需要凭据。这些是有价值的上下文，但未披露分页或返回格式等行为细节。

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 也处理了大部分参数说明。虽无输出 schema，但对返回内容的概括已足够，缺少示例和分页说明属于次要不足。

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

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

输入 schema 的参数描述覆盖率达到 83%，大多数参数已由 schema 说明，描述本身未增加参数级语义。appId 缺少描述但整体覆盖率仍高，因此给予基准 3 分。

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

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

描述明确了操作对象（应用评分）和动作（查询），并指出返回汇总（平均分、各星级数量）和明细，功能边界清楚。但没有明确与兄弟工具 agc_list_reviews 区分，因此未达到满分。

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?

描述给出了明确的使用条件：仅已上架应用有数据、时间跨度不超过 6 个月、需要 API 客户端凭据。虽然没有明确说何时不使用或给出替代工具，但这些上下文足以帮助智能体判断适用场景。

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 annotation, the description adds crucial behavioral details: download URL validity (~5 minutes), optional local download with preview, and the 180-day time span limit. These are not in the annotations and materially help the agent decide how to handle results. 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 well-structured: it front-loads the core purpose and behavior, then uses a bullet list for the report types. Every sentence carries necessary information; the length is justified by the need to enumerate 16 report types. No redundancy.

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

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

Given the complexity (12 parameters, nested objects, no output schema), the description covers the main flow (export, download, preview) and key constraints (time span). It does not detail the response format or explain all optional parameters, but the schema already documents many, and the description provides enough for an agent to successfully invoke the tool. Slightly incomplete for edge cases like extraQuery.

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

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

The description significantly enriches the 'report' parameter by mapping each enum value to its meaning (e.g., harmony-download = HarmonyOS 应用下载安装). It also clarifies downloadTo's purpose. However, it does not explain filters, groupBy, extraQuery, or site beyond the schema's partial descriptions (67% coverage). It adds value but does not fully compensate for all undocumented 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 exports operational reports in CSV/Excel, returns a download URL, and optionally downloads and previews. It lists all report types with meanings, making it unambiguous. It is distinct from sibling tools like agc_request or agc_get_api_doc because it is specifically for report export.

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 clear context on when to use it (when exporting reports) and gives a practical tip (pass downloadTo if content is needed). It does not explicitly mention alternatives or when not to use it, but the sibling tools are clearly different, so the guidance is adequate though not exhaustive.

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 openWorldHint=true. The description adds useful context about the 'current team' scope and the API-workaround rationale, but it does not disclose behaviors like pagination, data volume, or authentication failure handling. This is acceptable for a simple read-only list, but not deeply transparent.

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 compact sentences: the primary behavior is front-loaded, and the parenthetical implementation note is short and relevant. There is no filler or redundant 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 read-only listing tool with one optional parameter, the description covers scope, returned data, and the implementation rationale. Combined with the readOnlyHint annotation and the fully documented schema, an agent has everything needed to invoke it correctly.

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

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

The single optional projectId parameter is fully described in the schema ('only query a certain project; list all if not passed'), so the description does not need to add parameter details. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the action ('list all AGC projects and apps under each project') and enumerates the returned fields (appId, name, package name, device type). It also identifies the implementation source, making the tool's purpose unambiguous and distinguishable from more specific AGC tools like agc_get_app_info.

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 clear context: this is the general listing tool for projects and apps, and it explains why it exists (the official API is OAuth-only, so it uses the project management API instead). It does not explicitly name alternatives or when-not-to-use conditions, but the listing intention is clear enough for an agent to route appropriately.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses meaningful behavioral traits: the comments API does not support Service Account authentication, results are limited to 6-month spans, and site-country coupling restricts queries. This adds real operational context that annotations do not provide.

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

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

The description is two dense sentences with no filler. The primary purpose is front-loaded, followed by the most critical operational constraints. Every phrase earns its place.

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

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

Given the 14-parameter complexity, the description covers authentication, time limits, and site-country rules. With a rich schema and readOnly/openWorld annotations, it is mostly complete; the main omission is any indication of return shape or pagination behavior, which would further help an agent.

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

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

Schema description coverage is 86%, so the schema already documents most parameters. The description adds cross-parameter semantics: begin/end are limited to 6 months, and site must align with the countries being queried. It does not add nuance for all optional filters like devReplyStates or sort, but the schema largely covers their 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?

The description states a specific action ('查询应用评论列表') and resource, and adds important scope constraints (6-month span, single-site country limitation). It does not explicitly differentiate from siblings like agc_get_ratings or agc_reply_review, but the list semantics are clear and distinct enough.

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

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

The description provides explicit usage constraints: time span must not exceed 6 months, only one site's countries can be queried at a time, API client credentials are required, and the site must match the country's site. It does not name alternatives or state when not to use this tool, so it falls 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?

The description discloses that the reply is public and requires user confirmation before calling, which is important behavioral context beyond the annotations (readOnlyHint false). It does not contradict the annotations. However, it does not mention rate limits, authentication requirements, or whether replies can be edited later, but the schema covers the update parameter. Overall, it adds meaningful context about the public nature and the need for confirmation.

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

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

The description is two concise sentences that front-load the purpose and include the critical pre-call instruction. There is no redundant or filler 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?

For a mutating tool with 9 parameters and no output schema, the description does not explain error conditions, prerequisites (e.g., authentication), or the differences between creating a new reply, replying to a nested reply (toReplyId), or updating an existing reply (updateReplyId). The schema covers these, but the description is minimal and leaves room for an agent to misunderstand the nuances. It is adequate but lacks deeper 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 schema provides descriptions for 78% of the parameters, so the description does not need to explain them. The tool description itself does not add any parameter-specific guidance beyond what the schema already provides. Given the high coverage, a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: publicly replying to user comments or to a user's follow-up reply, as a developer. It specifies the action (回复) and the resource (用户评论/追加回复), and distinguishes it from read-only review tools like agc_list_reviews. The visibility condition (回复会对所有用户可见) adds clarity.

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 includes a pre-call guideline (确认回复内容 with the user) but does not explain when to use this tool versus alternatives or any exclusions. Since there is no sibling tool for replying, it is not a major gap, but the guidance is minimal and does not address conditions like when to use updateReplyId or toReplyId.

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 agent knows it can be destructive. The description adds useful behavioral context: automatic auth header addition, site-based domain selection, and return format (HTTP status + raw JSON). It also advises checking documentation first, which is a safety measure. No contradiction with annotations.

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

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

The description is concise, front-loaded with the main purpose, then examples, a prerequisite instruction, and return format. Every sentence earns its place with no fluff or repetition.

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

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

For a generic API caller with 7 parameters and no output schema, the description covers purpose, when to use, how to use (with prerequisite), and return format. It does not mention error handling or rate limits, but these are less critical given the annotations and the instruction to consult documentation. It is adequately complete.

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

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

Schema coverage is 86% and the schema descriptions are detailed (path parameters, auth default selection, site options, query array expansion, header business parameters). The description does not add significant parameter semantics beyond the schema; it only mentions auth and site behavior already covered in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool calls any Connect API endpoint with current credentials, adding auth headers and selecting domain by site. It explicitly lists example domains (PMS, Provisioning, Testing, etc.) and distinguishes from dedicated tools by saying it is for interfaces without dedicated tools. This is a specific verb+resource with clear 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 description explicitly says it is for interfaces without dedicated tools and instructs to first use agc_get_api_doc to confirm method, path, and parameters. This gives clear when-to-use guidance and a prerequisite, effectively routing the agent away from misuse. It also implies when not to use it (when a dedicated tool exists).

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 the description adds meaningful behavioral details: the catalog size, bilingual keyword support, and that space-separated keywords mean simultaneous matching. It also reinforces openWorldHint=false by specifying the search is within the built-in catalog. 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 first establishes scope and keyword behavior, the second provides the follow-up workflow. Information is front-loaded and every clause earns its place, despite the minor 'Connect Connect' typo.

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 is complete enough for an agent to select and invoke it: it explains what the catalog contains, keyword semantics, and the downstream workflow. It does not explicitly describe the return format, but the mention of finding endpoints and then checking params via agc_get_api_doc makes this sufficiently clear.

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%, giving a baseline of 3. The description adds extra meaning for the query parameter (Chinese or English keywords, space-separated terms match simultaneously), which goes beyond the schema's examples. It does not cover group/platform beyond what the schema already provides, so a 4 is appropriate.

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

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

The description states a specific action ('search by keyword') against a specific resource ('built-in AppGallery Connect API catalog'), with concrete scope (~200 endpoints, 450 docs). It clearly differentiates from agc_get_api_doc by saying the next step after finding an endpoint is to use that tool, though it does not explicitly contrast with sibling search tools like harmonyos_search_docs.

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

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

The description gives a clear workflow context: search the catalog first, then use agc_get_api_doc for parameters, then invoke via dedicated tools or agc_request. It implies when this tool is appropriate but does not explicitly state exclusions or alternatives, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and openWorldHint=true. The description adds valuable context: '这是对外生效的操作，调用前请与用户确认' (this is an externally effective operation, confirm with user before calling). It also mentions preconditions about app info and package parsing. This goes beyond the annotations by adding the user-confirmation requirement and readiness checks, which is useful for an agent.

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

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

The description is concise, with the main action front-loaded. It includes preconditions, a warning about external effect, and platform-specific endpoint details in a few sentences. No wasted words. It's well-structured and easy to parse.

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 (nested 'phased' object, platform-specific behavior, and external effects), the description covers the key context: preconditions, user confirmation, and platform routing. The schema handles parameter details like releaseTime and phased settings. There's no output schema, but the description doesn't need to explain return values. It's fairly complete for an agent to call it correctly.

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

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

Schema description coverage is 80%, so the schema already documents most parameters. The description doesn't add extra meaning beyond what the schema provides, except for noting the platform-specific endpoints which relate to the 'platform' parameter. Since the schema covers the parameters well, a baseline of 3 is appropriate; the description adds marginal value.

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: '提交应用审核发布（上架）' (submit app review release/listing). It specifies the resource (app) and the operation (submit for review). It also distinguishes between HarmonyOS and Android endpoints, which helps differentiate from sibling tools like agc_update_app_package or agc_list_reviews. The purpose is unambiguous and specific.

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

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

The description provides clear preconditions: '调用前应确认应用信息完整、软件包已解析成功' (confirm app info is complete and package parsed successfully before calling). It also warns that this is an externally effective operation and requires user confirmation. While it doesn't explicitly name alternative tools, the context makes it clear this is the submission action, and the platform-specific endpoints guide usage. This is adequate 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 declare destructiveHint=true and readOnlyHint=false, and the description aligns by stating it writes to the draft version. It adds valuable behavioral context: the operation is asynchronous, requires a ~2-minute wait, and returns a packageId or pkgVersion. This goes beyond the annotations, which only signal danger, not the async nature or the need to poll the compile status.

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

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

The description is a single dense sentence that front-loads the core purpose and packs in essential details (platform differences, input modes, async wait, sibling tool). While efficient and free of fluff, it could be more scannable if split into bullet points or short paragraphs. Still, every clause carries information.

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

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

Given the tool's complexity (8 parameters, two platforms, two input modes, async behavior) and lack of an output schema, the description covers the key operational aspects: how to provide the file, what each platform returns, and the follow-up action (check compile status). It doesn't detail error scenarios or prerequisites like having a draft version, but it provides enough for 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 88%, so most parameters are already documented. The description adds meaningful context for the filePath vs objectId relationship (mutually exclusive alternatives) and clarifies platform-specific behavior (which API each uses). It also hints at the releaseType/releasePhase defaults, though those are in the schema. Overall, it adds value beyond the schema without redundancy.

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: upload a software package and associate it with the current draft version of the app. It specifies the resource (app package), the action (upload and write), and distinguishes between HarmonyOS and Android paths with distinct API endpoints. This differentiates it from siblings like agc_upload_file (which only uploads) and agc_submit_app (which submits for release).

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 the two input modes (filePath for direct upload, objectId+fileName for already-uploaded files) and instructs to wait ~2 minutes before publishing, pointing to agc_get_package_compile_status for status checks. It doesn't explicitly state when to use alternative tools, but the context makes it clear this tool handles both upload and association, and it references a sibling for follow-up. Some explicit 'when not to use' guidance would push it to 5.

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

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

The description discloses that the tool returns an objectId and requires a subsequent call to associate the file, which is useful behavioral context. It also implies a side effect (uploading to an external server), consistent with readOnlyHint=false. However, it does not detail potential constraints like authorization, overwrite behavior, or rate limits; annotations don't carry much of the burden, so the description could be richer.

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 front-loads the purpose and types of files, followed by a clear next-step instruction. No wasted words, and the essential workflow is conveyed efficiently. Slightly longer than strictly necessary but still well-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 tool with 5 parameters and no output schema, the description covers the core purpose, return value (objectId), and the necessary follow-up logic to link the file to an app. It does not explain error handling or scenario-specific requirements like chineseMainlandFlag, but those are covered by the schema. Given the available structure, the description is adequately complete.

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

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

The input schema already provides descriptions for 4 of 5 parameters (80% coverage), including filePath, fileName, releaseType, and chineseMainlandFlag. The tool description adds context about accepted file types (packages, icons, screenshots, etc.), which is helpful, but it does not clarify appId beyond the schema. This is a baseline score where schema handles most 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 uploads local files (listing specific types like .app/.apk/.aab/.rpk, icons, etc.) to the AGC file server and returns an objectId. It also differentiates from siblings by explicitly naming agc_update_app_package as a follow-up step, making the upload-only scope 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 gives clear usage context: it is the first step for associating files with an app, and explicitly instructs the agent to call other interfaces (e.g., agc_update_app_package or agc_request) after obtaining the objectId. It does not mention when not to use this tool or alternatives for other upload scenarios, 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds the Markdown output format and the batch limit of 10, which are useful behavioral details beyond the annotations. No contradictions or missing critical traits are apparent.

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

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

Two sentences with no fluff. The core action, limit, format, and input source are front-loaded. Every word adds value, and the description is appropriately sized for a simple 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?

For a tool with a single parameter, no output schema, and annotations covering safety, the description provides everything an agent needs to call it correctly: what it does, the input source, and the limit. No missing information is evident.

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

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

Schema description coverage is 100%, so the parameter 'names' is documented in the schema with an example. The description adds the key semantic detail that identifiers must come from the parent field of search results, which guides correct parameter construction beyond the schema's generic example. This raises the score above the baseline of 3.

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

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

The description clearly states the action (batch fetch full text), the resource (HarmonyOS official docs), the format (Markdown), and the limit (max 10). It also specifies that identifiers come from the parent field of harmonyos_search_docs results, distinguishing it from the search sibling. The verb 'get' and resource are 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 explicitly ties usage to a prior step: identifiers come from harmonyos_search_docs results. This tells the agent when to use this tool (after search) and where to obtain valid inputs. While it doesn't list exclusions, the implied workflow is clear and sufficient for an agent to select it appropriately.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only nature is covered. The description adds valuable behavioral context: it returns matching text snippets and a document identifier 'parent', and mentions near-real-time synchronization with the official website. This goes beyond annotations by disclosing the return format and data freshness, though it doesn't detail pagination or limits.

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 and front-loaded: it states the core function first, then lists content types, then provides routing alternatives. Every sentence earns its place, with no filler or redundancy. It is well-structured for quick parsing.

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 parameter, no output schema). Annotations cover read-only and open-world behavior. The description adds return format (snippets + parent identifier), how to get full text (harmonyos_get_docs), and when to use alternatives (Connect API). Nothing essential is missing for an agent to call it correctly.

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

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

The schema has one parameter 'query' with a description that already explains it accepts Chinese or English search terms with examples. Schema coverage is 100%. The tool description adds no additional parameter-specific semantics beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool searches HarmonyOS official documentation via Huawei's MCP, listing content categories (version notes, API reference, guides, etc.) and explicitly distinguishes it from siblings by naming harmonyos_get_docs for full text retrieval and agc_search_api/agc_get_api_doc for Connect API parameters. The verb '检索' (search) and resource 'HarmonyOS 官方文档' 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 provides explicit routing guidance: use harmonyos_get_docs when snippets are insufficient, and prefer agc_search_api/agc_get_api_doc for Connect API interface parameters. This tells the agent exactly when to choose this tool over alternatives, leaving no ambiguity.

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