appdesigns App Store screenshots

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

Annotations cover the mutation profile (readOnly=false, destructive=false, openWorld=true, idempotent=false), but the description adds substantial non-annotation behavior: nothing is public, no account is needed, the design waits 72 hours to be opened and saved, and it returns a preview image, warnings, a design_handle, and open_url. These lifecycle and side-effect details go well beyond the structured fields.

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 usage condition is front-loaded, but the body is a dense run-on sentence heavy with nested parentheticals enumerating asset types and layer kinds. Much of it earns its place (return values, editor handoff, 72-hour window), yet the packing makes it harder to scan than necessary.

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 complex, non-idempotent creation tool with no output schema, the description compensates by naming the return contents (preview image per variant, warnings, design_handle, open_url) and the post-creation editor workflow. It is largely complete, though the relationship to create_project/make_screenshot_set could be sharper.

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 100%, so the schema already documents all 8 parameters in depth. The description adds only marginal param meaning (variants are directions, design_handle feeds update_design, open_url opens the editor), so the baseline of 3 applies.

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 opens with a specific verb+resource and scope: creating app listing art designs (looping video headers, search results, event cards, and still marketing images) as an editable project. It distinguishes itself from siblings by naming create_project's screenshot sets, update_design for later edits, and the editor flow, so an agent can route correctly.

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?

It gives a clear trigger ("use this when you have designed art for an app yourself and the user should get it as an editable project") and points to update_design for subsequent tweaks. It does not explicitly state when NOT to use it versus create_project or make_screenshot_set, so no exclusion guidance is present.

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

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

Annotations only declare the generic profile (not read-only, not idempotent, not destructive), but the description adds real lifecycle facts: upload and finish within 1 hour or the project lapses, a finished project waits 72 hours to be opened, nothing is public, no account is needed, and the user saves the set on open. This is exactly the kind of context annotations cannot carry.

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-loads the when-to-use condition before any mechanics, and nearly every sentence carries information (precondition, exclusion, payload shape, return value, timing, privacy). It is dense rather than bloated, though the long single paragraph could be split for scanability.

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 an 11-parameter, no-output-schema tool, the description covers what an agent needs: what the tool produces (project_handle and upload command), the mandatory follow-up (finish_project), and the time budget for each stage. Nothing essential to a correct invocation 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 100%, so the schema already documents all 11 parameters thoroughly, including enums, defaults, and fallback behavior. The description adds little parameter-level detail beyond restating '1 to 6 screenshots in store order, each with a screen name and a headline', so baseline 3 applies.

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: it 'starts a screenshot set' of 1-6 screens, and names its return artifacts (project_handle plus one upload command). It is clearly distinguishable from siblings like finish_project, make_screenshot_set, and create_design.

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?

Gives an explicit precondition ('when you can run shell commands on the user's machine and have their app's screenshots as local files') and an explicit exclusion ('Not for a chat without a terminal, such as ChatGPT, where the upload command cannot run'). It also routes the agent forward: run the upload command once, then call finish_project with the handle.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description adds substantial context beyond that: the asset mutates immediately, the reply carries the new revision, previews of changed screens and warnings, the revision guard means a stale revision causes no change, and edits are applied atomically ("all or none").

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?

It is front-loaded well with the core purpose and the asset_id/handle fork, but the middle collapses a very large op surface into one sprawling run-on sentence, making it hard to scan. The content is largely non-redundant, but the wall-of-text form costs readability.

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 4-parameter mutation tool with no output schema, the description covers everything an agent needs: when to call it, auth per target type, revision/conflict semantics, atomicity, the shape of the reply, and the relationship to update_project/update_design. Nothing material is left unstated.

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 100%, so the schema already carries most parameter meaning and a baseline of 3 applies. The description nonetheless adds semantics the schema does not: "Send only what changes, with the revision get_asset returned" clarifies partial-update and revision-chaining behavior, and the handle/asset_id distinction is framed as a usage choice rather than a type.

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 opens with a specific verb+resource ("change something") and immediately scopes it to two targets: a saved asset via asset_id or an in-conversation set/design via handle. It then enumerates concrete capabilities (restyle text, move/resize layers, add SVG art, reorder screens, set_canvas) and explicitly distinguishes itself from siblings by stating that update_project and update_design no longer apply once an asset is edited this way.

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?

It states the prerequisite ("after get_asset"), the two usage modes with their respective auth requirements, and the routing rule against alternatives (update_project/update_design stop applying). Sign-in instructions are spelled out per agent (Claude Code, Codex, other agents), leaving little to inference.

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

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

The description discloses behavior well beyond the annotations: files are rendered by the appdesigns editor in the user's browser (the same pixels its Export saves), open_url produces them, and get_export with the returned export_id yields a download command. It also spells out the auth requirement in detail for asset_id (sign-in via /mcp, `claude mcp login`, or `codex mcp login`) versus no sign-in for handle. This is rich, actionable context for a non-idempotent operation.

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 content is front-loaded with the primary use case, but it is delivered as one dense paragraph of nested parentheticals, which makes the open_url/get_export workflow hard to parse. The information is mostly justified by the tool's multi-step nature, yet the structure could be split into clearer sentences without losing content.

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?

There is no output schema, so the description carries the burden of explaining the return flow, and it does so by pointing to open_url (generation) and get_export (download command). Auth requirements and the two input paths are covered. The one gap is that it never explicitly states what export_asset itself returns (e.g., an export_id/URL) beyond implying it through the follow-up call.

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 100%, so the schema already documents format, handle, and asset_id, including the enum and the handle/asset_id trade-off. The description reinforces the meaning of asset_id (something saved) and handle (something made in-conversation), but adds little syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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 names a specific verb and resource: it exports the finished files (a PNG per screen, an MP4 for looping screens) of a saved asset or an in-conversation handle. It distinguishes itself from the get_export sibling by describing the two-step flow where open_url generates the files and get_export downloads them. The core purpose is clear, though it is buried inside a long narrative sentence rather than stated up front.

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?

It gives an explicit trigger ("when the user wants the finished files... to upload to App Store Connect or the Play Console") and clearly separates the two input modes: asset_id for something saved vs handle for something made in-conversation and not yet saved. It does not name an explicit alternative tool to avoid, but the asset_id/handle routing is precise enough to select the right mode.

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

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

Annotations only give generic flags (destructiveHint=true, openWorldHint=true, idempotentHint=true). The description supplies the actual behavior those flags imply: the listing becomes public, a human reviews it in 24-48 hours, an email is sent when live, and the app is discoverable by other makers. It also documents the icon fallback chain and auth requirements with per-agent sign-in remediation, which annotations cannot express.

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 when-to-use trigger and the public-listing warning are front-loaded, and nearly every sentence carries operational content. It loses a point for density: the sign-in remediation is a single heavily nested sentence with two parentheticals, which is harder to parse than the rest of the description.

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 carries the return-value burden and does so: it tells the agent the submission is reviewed and confirmed by email rather than returning immediately. Combined with asset requirements, auth handling, and consent guidance, an agent has everything needed to decide and call correctly.

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, but the description adds provenance the schema lacks — that asset_id originates from save_to_account or list_projects — and restates the icon derivation order (App Store lookup, then project icon, then icon.param) as a single coherent rule. It adds context beyond field-level docs without introducing new syntax.

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 opens with a precise trigger ('when the user wants their app in the appdesigns gallery') and states the concrete effect: a saved screenshot set is submitted for review and published as a browsable template. This distinguishes it unambiguously from siblings like make_screenshot_set, save_to_account, and edit_asset, which manipulate assets rather than submit them for public listing.

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?

It names the source tools for the required asset_id (save_to_account or list_projects), states the preconditions (3+ screens, a store link, an icon), and adds an explicit behavioral rule: 'Ask the user before calling it: the listing is public.' It also covers the when-not case by explaining what happens on an unauthenticated call and how to remedy it.

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

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

The description explains behavior annotations cannot: calling again yields a fresh link and retires the previous one, which directly accounts for idempotentHint=false and destructiveHint=true. It stops short of describing auth requirements, failure behavior on invalid files, or rate limits.

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?

Two tight sentences: the validation behavior is front-loaded, followed by the link lifecycle. Every clause earns its place, and the re-call/retirement caveat is genuinely load-bearing rather than filler.

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 explains the return value (the editor link) and its lifecycle. It covers validation, return, and non-idempotency well, but omits what happens when validation fails, which an agent calling a checker would want to know.

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% and the single project_handle parameter is fully documented there (including that create_project returned it), so the description adds no parameter detail. Baseline 3 is appropriate when the schema carries the parameter burden.

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 states specific verbs and resources: it validates that every project screenshot was uploaded and is a real PNG/JPEG, then returns an editor link. This is clearly distinct from siblings like make_screenshot_set or save_to_account, though it never names those siblings to sharpen the contrast.

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 is only implied – an agent infers this is the finalization step after uploading screenshots, and that the returned link is then saved via save_to_account, but no explicit when-to-use or when-not-to-use guidance or alternative routing is given.

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

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

Annotations already declare read-only/idempotent/non-destructive, but the description adds substantive behavioral context beyond them: the auth dance for asset_id versus none for handle, and the fact that the returned revision is the token edit_asset requires. That is genuinely useful operational detail.

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 usage, which is good, but the body is one sprawling sentence with deeply nested parentheticals (auth instructions inside a clause about asset_id) that is dense and hard to parse. Content earns its place, but the packaging is not tight.

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?

There is no output schema, so the description must carry return-value semantics — and it does, detailing screens, layers, styles, loops, warnings, previews and the revision field. Combined with full auth guidance, an agent has everything needed to call it correctly.

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, but the description adds meaning: it explains that asset_id is a user-saved object needing sign-in while handle is an in-conversation artifact needing none, clarifying why two identifiers exist. It doesn't add much on the previews parameter beyond the schema's 'from 1, default all.'

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+resource (read one asset) and enumerates exactly what comes back: screens with backgrounds, layers, styles, loops, warnings, preview images, and the revision. It also names the sibling it complements (edit_asset), so the agent can place it 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 says when to use it ('before changing an asset with edit_asset, or when the user asks what one looks like') and gives the two mutually exclusive access paths (asset_id vs handle) with their differing sign-in requirements. There is little left to infer.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint false), and the description reinforces this with 'Read-only; changes nothing'. It goes further by disclosing the return payload in the absence of an output schema: size, cropping/covering, layer format, the moves, the quality bar and the hand-off to the user. It omits auth, freshness or rate-limit context, so not a full 5.

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 usage condition, followed by the return contents, then a terse safety confirmation. The second sentence is long and list-heavy, but each clause describes a distinct part of the returned recipe and none is filler.

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 read-only, single-parameter lookup with no output schema, the description carries the full burden of explaining what comes back and does so thoroughly (size, crops, layer format with phone frames, moves, quality bar, hand-off). An agent has everything needed to call it correctly and to know what to do with the result.

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 100% with a fully enumerated single parameter, so the baseline is 3. The description adds value by mapping human intents ('an animated product page header', 'a search result', 'In-App Event art', 'a launch post for X, LinkedIn or Instagram', 'a link preview', 'a Play feature graphic') onto the enum values, helping the agent pick the right asset string.

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 — returns the appdesigns recipe for a named asset as markdown — and enumerates the asset classes it covers (App Store header, search result, In-App Event art, social/marketing images). It also distinguishes itself from the sibling create_design by describing the recipe as 'the layer format create_design takes', so an agent can tell the two apart without opening either 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?

Gives a clear triggering condition: use it when the user wants listing art or a marketing image designed 'and you will draw it yourself', i.e. the agent renders the asset rather than having a tool do it. It never states an explicit exclusion or names create_design as the follow-up call, so the routing is implied rather than spelled out.

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

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

Annotations flag destructiveHint=true and idempotentHint=false for what sounds like a read, and the description explains exactly why: each call with files ready creates new links and retires earlier ones, so only the latest works. It also discloses the 24-hour expiry and the full sign-in story (which agents need auth, which commands to run). This is rich behavior well beyond the annotation surface.

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?

Information-dense and mostly earning its length, but delivered as one enormous semicolon-chained sentence with nested parentheticals, which hurts scanability. The usage trigger is front-loaded, and little could be cut without losing the auth and expiry semantics.

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 carries the return-value burden and does so: readiness state, the returned download command in both bash and PowerShell, and where files go next in App Store Connect or the Play Console. Auth requirements and link expiry are covered, so an agent has everything needed to call and interpret it.

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, but the description adds real meaning: it explains that passing handle removes the sign-in requirement for conversation-created assets, and ties export_id to the 24-hour link lifetime. That conditional-auth behavior 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?

The description states a specific function: it reports whether export files are ready and, if so, returns them alongside a download command plus next-step destinations. However, it opens with sequencing advice ("Use this after export_asset") rather than a clean statement of purpose, so the agent must infer the core function from the second clause. It does distinguish itself from export_asset by naming it and describing the follow-on role.

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?

Explicit when-to-use: after export_asset, once the user has the editor open. It also handles the conditional case for the handle parameter (pass it for in-conversation exports) versus the sign-in path, and instructs running the command from the latest call. The alternative is named directly, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered; the description reinforces it ('Read-only; changes nothing') and, more valuably, discloses the actual payload — capture commands, demo-data steps requiring user consent, caption rules, upload hand-off. It stops short of noting pagination/format edge cases, but for a read-only retrieval tool this is rich context.

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 triggering scenario, then the return payload, then the exclusion — a sensible order. It is dense and longer than most definitions, but each clause (consent requirement, deep links, hand-off) maps to distinct content in the returned recipe rather than 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?

With no output schema, the description must explain the return value, and it does so thoroughly by itemizing the recipe's sections. Combined with annotations covering safety, an agent has everything needed to decide and call correctly.

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 100% and both parameters have enums with per-value documentation, so the schema carries the load. The description only implies the platform/store scoping via 'for one platform and store' and adds no format or interaction detail beyond the schema — the baseline 3 applies.

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 ('Returns the full appdesigns recipe for one platform and store, as markdown') and enumerates the recipe's contents. It clearly distinguishes itself from the execution siblings (make_screenshot_set, replace_screenshots) by being the tool that hands back instructions rather than performing captures.

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?

Explicit when-to-use ('working in an app's code and can run commands ... user wants App Store or Google Play screenshots') and explicit when-not ('Not for a chat without a terminal, where the screenshots come as attachments instead'). Nothing about routing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value beyond them by disclosing store-specific content (App Store = Apple devices only, Google Play = Android phones) and that omitted values fall back to defaults. The trailing 'Read-only' is redundant with the annotations but harmless.

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 sentences, front-loaded with the usage trigger and scoping constraint; nothing is wasted except the redundant 'Read-only' tail that the annotations already assert. Tight and easy to scan.

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 single-parameter, no-output-schema read tool, the description covers trigger conditions, store scoping, default behaviour, and the shape of what is returned. An agent has everything needed to call it correctly.

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% and the store enum already carries its own description and default. The description nonetheless adds meaning the enum cannot: what each store value actually yields in the result set, and that defaults apply when the parameter is omitted.

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 (List) and resource (device frames) plus the attributes returned: devices, frame colours and canvas sizes. It is easily distinguished from siblings such as list_projects and make_screenshot_set, which serve different resources.

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?

Gives explicit triggering conditions: when the user asks which devices/colours/sizes exist, or before choosing a non-default device for a screenshot set. It stops short of naming an alternative tool or a when-not condition, but the context is clear enough to route correctly.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description goes beyond them by disclosing the auth requirement and the exact failure mode (a call without sign-in fails asking for sign-in), with remediation steps. That is meaningful added context, though the agent-specific login commands are verbose.

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?

Usage intent is front-loaded, but the long parenthetical with per-agent login commands (`/mcp`, `claude mcp login`, `codex mcp login`) is disproportionate detail for a tool description and bloats an otherwise tidy two-sentence core.

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 compensates by describing the return shape (per-project asset lists with id, kind, canvas size, last edit, and unmet needs). Combined with the explained auth failure path, it is largely complete for a read-only list 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% and the single 'query' parameter is fully documented as a case-insensitive name filter, so the schema does the work. The description adds nothing about the parameter, which is the expected baseline when the schema is complete.

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 states a specific verb+resource (lists projects, one per app) and enumerates exactly what comes back per asset (asset_id, kind, canvas size, last edit) plus what each project still needs. It is clearly distinct from mutation siblings like create_project or edit_asset, though it never names them explicitly.

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?

It gives a concrete when-to-use: the user wants to work on something already made in appdesigns (change a screenshot set, header/event art, add to a project, see what's missing). That contrasts implicitly with the create/edit siblings, but no alternative tool is named and no explicit when-not condition is given.

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

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

Annotations only tell the agent this is a non-read-only, non-destructive, non-idempotent write. The description adds real lifecycle context the annotations cannot: private storage, a 72-hour retention window or until saved, no account required, and that open_url exposes an editable project. It stops short of saying what happens on repeat invocations or whether existing sets are overwritten, so not a perfect 5.

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?

It is long but front-loaded with the core use case, and the dense constraint clause is information-rich rather than padded. There is mild redundancy in the closing privacy statements ('stored privately... Nothing is public and no account is needed'), which keeps it from a 5.

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 9-parameter mutation tool with no output schema, the description covers inputs, ordering rules, storage/lifecycle behavior, the open_url follow-up, and the privacy model. An agent has everything needed to invoke it correctly and set user expectations.

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, but the description adds constraints absent from the schema: 1–6 screenshots, accepted formats (PNG/JPEG/WebP/GIF), a 20 MB per-file cap, uniform orientation, and strict store-order correspondence between screenshots and screens entries. These materially reduce invocation errors.

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 states a specific verb and artifact ('make App Store or Google Play screenshots... store listing images, framed screenshots or app mockups') and scopes it to screenshots the user attached in this conversation. It is clearly distinguishable from siblings like replace_screenshots or create_project.

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?

It gives explicit when-to-use (user attached their own raw app screenshots and wants store images) and when-not-to-use (already-framed images, inventing screens, nothing attached), and tells the agent what to do instead in each excluded case. This is textbook routing guidance.

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

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

Beyond the annotations, the description discloses a two-call workflow: the first call returns an upload command, the user runs it, then the second call validates PNG/JPEG files and swaps them in. It explains authentication requirements for asset_id versus handle and notes the reply contains a new revision and previews. This is rich operational detail consistent with destructiveHint=true and idempotentHint=false.

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 front-loaded with the usage condition and all details are relevant to a complex two-step, auth-dependent operation. It is dense and delivered as a single long paragraph, but it avoids repetition and earns most of its length.

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 non-readOnly, destructive, multi-call tool with no output schema, the description covers the complete workflow, validation rules, authentication differences, and return values. It gives an agent everything needed to invoke the tool correctly and interpret the two responses.

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. The description adds meaningful beyond-schema semantics by assigning parameters to specific calls: asset_id/handle and screens in the first call, then asset_id/handle, replace_handle, and revision in the second. It also clarifies that layer is optional and only for phone frame layers.

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 states a specific verb and resource: replacing screenshots in a set's phone screens, including recaptures, fixed screens, and phone frame layers. It distinguishes saved sets (asset_id) from in-conversation sets/designs (handle) and references get_asset for layer IDs, so an agent can identify the tool's scope 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?

It gives clear when-to-use guidance: when a set needs new screenshots for a recapture, fixed screen, or phone frame layer. It also explains the two-call sequence and auth requirements for each mode. It does not explicitly name a sibling alternative for creating new sets, but the usage context is otherwise well specified.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses the target library, default project behavior when no project is named, that there is 'no link to open and nothing for them to press', the returned fields (asset_id, revision for edit_asset, open_url), and the full auth failure/remediation path. This is unusually rich behavioral context.

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 when-to-use clause is correctly front-loaded, but the closing paragraph embeds lengthy per-agent sign-in remediation (Claude Code /mcp instructions, Codex command, 'other agents open the sign-in page themselves'). Actionable, yet disproportionate to a one-parameter tool and dilutes the core message.

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 naming the return values, and it covers the auth prerequisite and side effects. The only shortfall is the stale project_id/same_project_as reference that contradicts the one-parameter schema.

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 100% for the single 'handle' parameter, so the baseline would be 3, but the description instead references 'project_id or same_project_as' as if they were inputs — neither exists in the schema. That misdirects an agent toward parameters it cannot pass, which is worse than adding no parameter detail.

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 uses a specific verb and resource ('Saves it straight into their appdesigns library') and situates it precisely in the workflow: after finish_project/update_project or create_design/update_design. It is clearly distinguishable from the adjacent save/update siblings (create_design, update_design, edit_asset).

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?

It states exactly when to call ('when the user is signed in and a set you made is ready ... once the previews look right') and names the upstream tools that must run first. It also gives an explicit precondition (user signed in to appdesigns) with the alternatives for what happens without it.

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

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

Annotations already cover read-only, idempotent, non-destructive, and closed-world traits, and 'Read-only' merely repeats them. The description goes further by disclosing the return shape (matches with paths, one composite image ordered left-to-right then down) and the fallback behavior when nothing matches (it lists the categories).

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 usage condition is front-loaded and the return behavior follows, so it reads in the right order with no preamble. It is a dense run-on paragraph with a few expendable asides ('and more (a few thousand pieces)'), which keeps it short of a 5.

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 carries the return-format burden and does so: paths, image, ordering, and the no-match category list. Pagination or the significance of limit beyond the schema default is not addressed, but nothing critical for a correct invocation 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 100%, so query, limit, and category are all documented in the schema with examples and defaults. The description adds only the implicit reinforcement of 'best matches' ordering, which the schema's limit field already states, so baseline 3 is appropriate.

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 names a specific verb (search) and resource (the appdesigns library of ready-made pieces) and enumerates the asset classes it covers (SF Symbols, emoji, 3D shapes, badges, marks). It also distinguishes itself from siblings by positioning create_design and edit_asset as downstream consumers of the returned paths rather than alternatives.

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?

It gives an explicit triggering condition: use this when a design or saved asset needs a ready-made piece rather than art you draw, which implicitly rules out the drawing/creation path. However, it never names the sibling it replaces for custom art nor when to prefer get_asset, so there are no explicit exclusions or named alternatives.

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

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

Annotations declare non-read-only, non-idempotent, non-destructive, and the description is consistent, adding real value beyond them: the original is untouched, images are copied, a saved copy lands in the same project, a copy of an unsaved set gets its own handle/link and joins the project on save. It also details exact auth steps per agent (Claude Code /mcp, Codex login command). Return behavior (screen previews + warnings) is disclosed, though line-break-wrapping behavior is described only loosely.

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 trigger and the two modes, and every sentence carries real information (behavior, return, auth). It is dense with long parenthetical clauses, so it reads more as a wall of text than a scannable spec, but nothing is truly redundant given the tool's complexity.

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 compensates fully: it describes the return (a preview of every screen plus warnings) and the remedy (fix lines with edit_asset), covers both input modes, the per-language call limit, and per-agent authentication. Nothing an agent needs to invoke 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 100%, so the baseline is 3, but the description adds semantics beyond the schema: it explains where text-layer ids come from (get_asset lists them), that every word-bearing text layer must be translated, that asset_id comes from list_projects and handle from create_project/create_design, and the 'one call per language' constraint on language.

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 states a specific verb+resource ('makes a copy in that language' of a 'screenshot set or listing asset') and immediately distinguishes the two modes (asset_id for saved sets vs handle for sets made in-conversation). It names sibling tools (get_asset, edit_asset) so the agent can place it in the workflow without opening schemas.

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?

It opens with an explicit trigger ('Use this when the user wants... in another language'), names the alternative inputs and when each applies (asset_id = saved, needs sign-in; handle = unsaved, no sign-in), and states 'One call per language.' Exclusions and prerequisites are explicit.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and non-read-only, so the safety profile is covered. The description adds real value beyond that: 'Send only what changes' (patch semantics), that it returns preview images and warnings, and that the open_url from create_design then opens the new version.

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-loads the core action and scope in the first clause and wastes no sentences, but the trailing sentence about edit_asset and saved designs is dense and somewhat tangled. It mostly earns its place, though it could be split for clarity.

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 fills that gap by stating what is returned (preview images and warnings) and how the returned open_url behaves. Combined with sibling routing, an agent has enough to call it, though the edit_asset/saved-design relationship remains slightly ambiguous.

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 schema already documents both top-level parameters and every nested op field, including the meaning of design_handle. The description's 'send only what changes' reinforces partial-update semantics but adds little syntax or meaning beyond what the schema provides, making 3 the correct baseline.

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 ('Changes a design create_design made') and enumerates the exact scope of operations (layer field edits, add/remove/reorder, variant background/loop/title replacement, add/remove variant). It explicitly ties itself to create_design, distinguishing it from siblings that also mutate designs.

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?

Sets the operative condition 'before the user saves it' and routes the agent to alternatives ('one the user already saved changes in the editor (or with edit_asset)'). The edit_asset vs editor guidance is present but expressed indirectly rather than as a crisp when-not rule.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=true, and the description is consistent with that: it discloses that names/headlines/colours are overwritten while 'the uploaded screenshots stay as they are'. It adds real context beyond the annotations by stating the return payload ('new previews and warnings'), that finish_project's open_url then opens the new version, and that edit_asset needs no sign-in (implying this path does). It stops short of stating auth or failure behaviour for this tool itself.

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 change operation before the alternative paths, and every sentence carries routing or behavioural information. The middle is dense with semicolons and slightly run-on, which costs a point but does not bury the actionable content.

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?

No output schema exists, and the description compensates by naming the return values (new previews and warnings) and their consumer (finish_project's open_url). Combined with the change scope, the unchanged-screenshots guarantee, and the full routing to edit_asset, an agent has everything needed to call it correctly in the project lifecycle.

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 100%, so the schema already documents device, screens, frame_color, background_color and project_handle with formats, lengths and examples. The description reinforces which fields are mutable and that only changed screens are sent, but adds no syntax or constraint beyond what the schema states. Baseline 3 applies.

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 ('Changes a screenshot set create_project made') and pins the exact scope: screen name, headline, background colour, frame colour, device. It explicitly names the sibling it is not for ('For anything more ... use edit_asset') and distinguishes pre-save sets from already-saved ones, so an agent can separate it from edit_asset, create_project and finish_project without opening a 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?

Gives explicit when-to-use ('before the user saves it') and when-not-to-use, naming edit_asset as the alternative for extra changes, for a different canvas, and for sets the user already saved (by asset_id). It also states that once edit_asset has touched the set, the agent should stay with edit_asset. Nothing is left to inference.

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