asc_create_app

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

With no annotations, the description carries the burden well: it discloses the Apple ID requirement, the interactive 2FA dependency, that this is a write that creates an app shell, and the automatic name-selection fallback on 'name taken' errors. It stops short of stating permissions, rate limits, or what the partial shell contains.

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 paragraphs, front-loaded with the purpose and verb. The middle paragraph justifying why produce stays is slightly tangential but provides useful context; overall efficient with no egregious padding.

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 6-param write tool with no annotations, it covers the critical creation flow, name-uniqueness behavior, and returns app_id (output schema also exists). The main gap is the undocumented sku/approval_id/primary_language parameters, but the core invocation path is 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 0%, so the description must compensate for all 6 params. It thoroughly explains candidate_names and app_name (backward-compat, converted to a one-element list) and the returned app_id, but sku, approval_id, primary_language, and bundle_id go entirely undocumented in both schema and 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?

States a specific verb and resource ('Create an app SHELL in App Store Connect') with the underlying mechanism (fastlane produce). It distinguishes itself from siblings by noting it is 'the one ASC write that does not go through the asc CLI' and is separate from asc_create_bundle_id or subscription creation.

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?

Explains why this tool exists versus the asc CLI and `asc web apps create` (the latter needs an interactive 2FA web session), which effectively routes the agent here. It lacks an explicit when-not statement or a named sibling to prefer for related tasks, but the context for selecting it is clear.

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