Skip to main content
Glama
swlittles

App Store Connect MCP

by swlittles
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Replace one screenshot

replace_screenshot
DestructiveIdempotent

Swap an existing App Store screenshot with a new image while preserving its position. Upload and process the replacement before removing the old one, with dry-run confirmation.

Instructions

Replaces one screenshot with a new image, keeping its place. Identify it by position (1-based, from list_screenshots) or by screenshot_id. The new image is uploaded and processed before the old one is removed, so the listing never has a gap (except in a full set of 10, where the old one has to go first). If a run stops partway, it says how to continue: call again with screenshot_id so the right screenshot is replaced even if positions shifted.

Destructive: dry_run defaults to true and returns the plan. Show it to the user, then call again with dry_run: false. Needs ASC_WRITE=1.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
appNoApp ID, bundle ID or exact app name. Defaults to ASC_APP_ID, or to the only app the key can see.
fileYesAbsolute path of the new image.
localeNoLocalization, e.g. en-US. Defaults to the app's primary locale.
dry_runNoDefaults to true: return the plan without changing anything. Call again with dry_run: false to apply it.
versionNoApp Store version string (e.g. "1.2"), "editable" (the version being prepared; the default) or "live".
platformNoPlatform. Defaults to IOS.
positionNoPosition to replace, 1-based, as shown by list_screenshots.
display_typeYesScreenshot display type, e.g. APP_IPHONE_67 (6.9" iPhone, 1320×2868), APP_IPHONE_65, APP_IPAD_PRO_3GEN_129 (13" iPad, 2064×2752), APP_DESKTOP, APP_APPLE_TV, APP_APPLE_VISION_PRO, APP_WATCH_ULTRA.
wait_minutesNoMinutes to wait for Apple to process uploaded images (usually under a minute). If time runs out, re-run the same call to continue.
screenshot_idNoID of the screenshot to replace. Safer than position when continuing an interrupted run.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.3.0

TDQS

A4.5/5.0
Behavior5/5

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

Goes well beyond the annotations (destructiveHint, idempotentHint, openWorldHint): it explains the upload-before-delete ordering, the exception when a full set of 10 forces the old image out first, the dry_run default flow, resume semantics, and the ASC_WRITE=1 permission requirement.

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

Conciseness4/5

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

Front-loaded with the core action, then layered with the ordering nuance, resume behavior, and a clearly separated destructive/dry-run paragraph. The 10-item-set edge case is a bit granular but still earns its place as a real exception.

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

Completeness4/5

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

For a 10-parameter destructive tool with no output schema, it covers permissions, dry-run flow, ordering side effects, and how to recover a partial run. It could say more about what the dry-run plan or final result contains, but 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.

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning the schema does not: the position-vs-screenshot_id tradeoff ('safer than position when continuing an interrupted run'), the intent of the dry_run default, and where positions come from.

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

Purpose5/5

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

States a specific verb and resource ('Replaces one screenshot with a new image, keeping its place') and pins the scope to a single item, which distinguishes it from the bulk siblings upload_screenshots, reorder_screenshots and delete_screenshots without needing to open a schema.

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

Usage Guidelines4/5

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

Gives clear operational guidance: identify by 1-based position from list_screenshots or by screenshot_id, run dry_run first and confirm, and re-call after an interrupted run. It does not explicitly name an alternative tool ('to add instead of replace, use upload_screenshots'), 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.

Deploy Server

Other Tools