上传并关联应用软件包

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.