Upload a build

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

Annotations already declare idempotentHint=true and destructiveHint=false, but the description adds value beyond them: the ASC_WRITE=1 auth requirement and the concrete idempotency mechanism ('steps already done are skipped'). It also notes Apple processing typically takes 5-30 minutes and that the result explains how to resume, which the annotations do not convey.

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

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

Front-loaded with the core action and each sentence carries distinct information (method choice, build prerequisite, versioning rule, downstream step, auth/re-run note). It is dense and slightly long, but no sentence is filler, so it stays efficient rather than bloated.

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

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

For a mutation tool with 8 params, no output schema and open-world behavior, the description covers prerequisites, auth, idempotency, the 5-30 minute processing wait, and the resume path. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is high (88%), so the baseline is 3, but the description adds real meaning: it clarifies the method enum tradeoff, the .ipa/.pkg file expectation, and the critical constraint that build_number (CFBundleVersion) must be new and higher on every upload. That last point is not derivable from the schema alone.

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

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

States a specific verb and resource ('Uploads an exported .ipa (or macOS .pkg) to App Store Connect') and distinguishes itself from the sibling distribute_build by naming it as the downstream step. An agent can identify exactly what this tool does and where it sits in the pipeline without opening the schema.

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?

Explicitly explains when to use each method ('api' uses Apple's build upload API, no Xcode; 'altool' shells out to xcrun altool on a Mac) and gives prerequisites: build the .ipa first with xcodebuild archive/-exportArchive, and use a new higher build number. It also names the follow-up action (distribute_build), leaving no inference required.

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