Upload a build

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent, closed-world mutation, so the safety profile is covered; the description adds genuinely new behavior on top: an .aab is converted into a single APK for testers, notes are visible to testers on Pro/Team, and putting the build in a channel makes that channel's stable link serve this build. It stops short of operational traits like file-size limits, upload duration, or what happens on a failed or duplicate upload.

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 short sentences, zero filler, and the primary action and accepted formats are front-loaded ahead of the .aab conversion caveat and the optional-parameter behavior. Nothing is repeated from the schema or annotations.

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 correctly compensates by stating the return values (install link and store readiness result), and the annotations plus the .aab conversion note cover the mutation semantics. What remains thin is failure/edge behavior, such as rejected files or overwrite handling, which matters for a non-idempotent upload 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%, so the baseline is 3, and the description earns an increment by explaining the consequence of the channel parameter ('whose stable link then opens this build') rather than just restating 'put the build into this channel', plus clarifying what the file path may contain across all three formats. The notes parameter is only described in the schema, so the added meaning is uneven.

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 definition opens with a specific verb and resource ('Upload an .ipa, .apk or .aab from this computer to AppForShare') and names the two things it returns, so an agent knows exactly what the operation accomplishes. It conveys the ingest role well enough to distinguish it implicitly from list/delete/info siblings, but it never explicitly contrasts itself with the closest-sounding alternative, store_upload_status.

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 context is implied rather than stated: 'from this computer' scopes it to a local artifact, and the channel sentence describes a downstream workflow, but there is no explicit when-to-use or when-not-to-use guidance and no routing to an alternative for cases like uploading from a CI build or re-pointing an existing build.

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