appdesigns App Store screenshots

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

Annotations only establish that this is a non-read-only, non-destructive, closed-world write. The description goes well beyond: it discloses the return payload (preview image per variant, warnings, design_handle, open_url), that checks run before returning, that nothing is public and no account is needed, and a 72-hour window before the design must be opened and saved.

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 correctly with the when-to-use clause, but the enumeration of asset types ("a product page header, search result, or In-App Event card or page... an X, LinkedIn or Instagram post...") and layer types largely restates the asset enum and layer schema. Those clauses are long and duplicate structured data rather than adding value.

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 takes on return-value disclosure itself (preview images, warnings, design_handle, open_url) and covers the lifecycle caveat of the 72-hour expiry plus the no-account requirement. For an 8-parameter creation tool, nothing needed 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 coverage is 100%, so the schema already carries per-field meaning. The description nevertheless adds cross-parameter workflow semantics: 1-4 variants where the first is the preferred direction, layers as background+art+icon+text+phone frames with moves, and how project_id/screenshots_from/same_project_as relate to prior tool calls.

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 a listing art design) and scopes it precisely: listing art that loops as video or a still marketing image, delivered as an editable project. It names the sibling relationships explicitly (design_handle for update_design, project_handle from create_project), so an agent can separate it from update_design and make_screenshot_set 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?

"Use this when you have designed art for an app yourself and the user should get it as an editable project" gives the triggering condition, and it adds an alternative rule: "Use it, not same_project_as, to add to something the user already saved." It also clarifies that screenshots_from must come from a create_project set in the same conversation.

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 destructive=true, idempotent=false, readOnly=false; the description goes well beyond that by disclosing the revision-conflict behavior ('If the asset changed since, nothing changes and you read it again'), that the edit takes effect immediately like an editor edit, that the reply carries the new revision plus previews and warnings, and the full auth requirement per mode (signed in for asset_id, no sign-in for handle, with per-client login instructions).

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 core routing and auth information is front-loaded, but the middle is one very long run-on sentence enumerating layer/screen/background/canvas operations that the schema already documents, which adds length without new decision-relevant content. It is information-dense yet hard 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 complex, destructive, no-output-schema tool, the description covers everything an agent needs before calling: prerequisites (get_asset first), the required revision token, both addressing modes, the auth difference between them, immediate-effect semantics, conflict behavior, and what the reply contains (revision, previews, warnings).

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 parameters are already documented in structured data. The description adds useful framing ('Send only what changes, with the revision get_asset returned'), but the op-by-op behavior it recounts largely mirrors the schema's own op enum and layer descriptions, so it does not meaningfully exceed the 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 (change) and resource (an asset) and immediately distinguishes the two mutually exclusive target modes: asset_id for 'one the user saved' versus handle for 'a set or design you made in this conversation'. It also names the operation vocabulary (layers, screens, background, loop, canvas) so the agent knows the scope of the edit 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 gated on 'after get_asset', requires the returned revision, and gives a clear routing rule against siblings: 'A set or design changed this way keeps changing here: update_project and update_design no longer apply to it.' It also names search_library and set_canvas as the paths for specific sub-needs, which is exactly the when-to-use/when-to-use-something-else guidance an agent needs.

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?

Goes well beyond the annotations: it explains that files are produced by the appdesigns editor in the browser, that open_url must be opened there to generate them (PNG per screen, MP4 for looping screens), and that get_export with export_id yields the download command. It also spells out exact authentication requirements per host (Claude Code /mcp Authenticate, codex mcp login), which the annotations do not cover.

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 ('Use this when the user wants the finished files'), which is ideal. However, the body is a dense single paragraph with nested parentheticals (auth instructions inlined mid-sentence) that could be split for scannability; every sentence is informative but the structure taxes reading.

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 and an open-ended return path, the description compensates by outlining the full three-step flow (open_url to render, export_asset to get export_id, get_export to download) and the auth preconditions for each mode. Nothing an agent needs to call this 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 coverage is 100%, so baseline is 3, but the description adds real meaning: asset_id requires sign-in while handle requires none, and it clarifies handle is for an unsaved set/design made in this conversation. Format behavior (MP4 for looping screens vs PNG) is echoed from the schema's enum description, so only marginally additive.

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 (export an asset's files) and immediately distinguishes the two input modes: asset_id (something the user saved) vs handle (something made in this conversation). It also names the downstream sibling get_export, so an agent can locate it against the rest of the export flow.

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 frames when to use it ('when the user wants the finished files... to upload to App Store Connect or the Play Console'), and routes between the two modes. It stops short of naming when NOT to use it or which sibling to prefer for adjacent tasks (e.g. get_asset vs export_asset), so it is strong context rather than full when/when-not coverage.

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 establish read-only/idempotent/non-destructive, and the description adds substantial context on top: the full return shape (screens, backgrounds, bottom-first layers with id/position/style, animation loop, warnings, preview images), the fact that it returns the revision edit_asset needs, and detailed auth requirements per identifier including exact login commands.

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?

Dense but front-loaded: usage context comes first, then return shape, then auth. It is a single long run-on paragraph with heavy parentheticals, which hurts scanability, but almost every clause carries information an agent needs (revision linkage, auth commands, layer ordering).

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 return-value burden and does so thoroughly (screens, layers, styles, loop, warnings, previews, revision). Combined with the auth guidance and identifier selection rules, 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 beyond the schema by tying each identifier to an auth consequence: asset_id requires signing in to appdesigns (with concrete login steps), while handle requires none. The previews parameter is not elaborated in the description, relying entirely on the schema.

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 ('read one asset') and immediately scopes it to two use cases: pre-edit inspection and answering 'what does it look like'. It distinguishes itself from siblings by naming edit_asset and by explaining the two lookup keys (asset_id vs handle) that separate it from list_projects-style tools.

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 call it ('before changing an asset with edit_asset, or when the user asks what one looks like') and gives the conditional selection rule between asset_id and handle, including which one requires sign-in. Nothing about when to use it 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/non-destructive, so 'Read-only; changes nothing' is largely redundant. However, with no output schema the description usefully discloses what is returned: size, crops/covers, layer format, moves, quality bar, and the hand-off to the user.

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 sentences, front-loaded with the usage condition followed by the return contract. Dense but every clause carries information; the asset enumeration is somewhat long but maps directly to the use cases.

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 simple read-only, single-enum tool with no output schema, the description covers the trigger, the return content, and the safety profile. Minor gaps remain (no mention of error cases or how the recipe relates to subsequent edit/export steps), but nothing essential 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% and the single enum parameter is fully documented in the schema. The description only restates the asset list and the 'as create_design names it' convention already present in the schema, adding no new syntax or format meaning.

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: returns the appdesigns recipe (markdown) for a named asset type, and enumerates concrete use cases (listing art, marketing image). It clearly distinguishes itself from create_design by saying the agent 'will draw it yourself' rather than creating the 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?

Gives explicit trigger conditions ('when the user wants App Store listing art ... or a marketing image') and implies the follow-on flow by referencing the layer format create_design takes. No explicit when-not or named alternative for the actual creation step, 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.

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

Discloses rich behavior beyond the annotations: link lifetime (24h after export), that each ready call mints new links and retires the earlier ones (explaining the non-idempotent, non-read-only profile), and the auth requirement plus exact commands to authenticate. This is exactly the context annotations cannot 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?

Every clause carries useful information, but it is delivered as one marathon run-on sentence that is not front-loaded with the purpose, making it hard to parse. The content earns its place; the structure does not.

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 carries the return-value burden: it explains that files come back with a bash/PowerShell download command, where they land, and the next steps in App Store Connect and the Play Console. Auth and expiry behavior round it out.

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 baseline is 3. The description adds meaning by tying handle usage to the auth outcome (no sign-in needed) and its relationship to items made in the current conversation, going beyond the bare schema note. export_id is only implicitly explained, keeping this just short of a 5.

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 action: it reports whether the exported files are ready and returns them with a download command plus destination guidance. It clearly distinguishes itself from the sibling export_asset by positioning itself as the post-export step. The purpose is stated but somewhat buried after the leading usage clause rather than front-loaded.

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 states when to call it ("after export_asset, once the user has the editor open") and the correct sequencing. It also names the condition for passing handle (something made in this conversation) and the fallback sign-in path per agent, 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/non-destructive, so the bar is lower, yet the description adds substantial new context: a hard auth prerequisite, the exact failure mode ('a call without it fails asking for sign-in'), and per-agent remediation steps. It also discloses the return contents (asset_id, kind, canvas size, last edit) and the derived 'what each project still needs' summary, none of which the annotations 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?

The purpose and scope are front-loaded well in the first two sentences, but the auth remediation parenthetical (three agent-specific login procedures plus a terminal command) consumes the majority of the text and is disproportionate to a read-only list tool. The final 'Read-only.' fragment is redundant with the 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 usefully describes the return shape and the auth prerequisite, which is most of what an agent needs for a one-parameter list call. It omits pagination/result limits and empty-result behavior, so it is not fully 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?

There is a single optional 'query' parameter and schema description coverage is 100%, so the schema already documents the case-insensitive substring match and 80-char cap. The description adds nothing about the parameter, so the baseline 3 for schema-carried semantics 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 gives a specific verb and resource ('Lists their projects (one per app) with every saved asset in each') and even enumerates the returned fields, which clearly separates it from asset-level siblings like get_asset or list_devices. It stops short of explicitly naming or contrasting with any sibling, so it lands at a strong 4 rather than a 5.

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 when-to-use trigger ('Use this when the user wants to work on something they already made in appdesigns') and backs it with concrete scenarios: changing a screenshot set, header/event art, adding to a project, seeing what's missing. There are no stated exclusions and no named alternative tools (e.g. search_library, get_asset) for the adjacent cases, so it is clear context without routing.

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 cover the safety profile (not read-only, not destructive, not open-world), and the description goes well beyond them by disclosing storage privacy, the 72-hour lifetime until save-to-account, that nothing is public, and that no account is required. It does not explain failure modes (e.g., what happens on >6MB or mixed-orientation input) beyond constraints.

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 condition and the when-not-to-use rules before the mechanics. It is long, but nearly every clause carries a constraint; a couple of store-listing examples could be trimmed without loss.

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 9-parameter mutation tool with no output schema, the description covers inputs, constraints, privacy, and that open_url opens the result as an editable project. It stops short of describing the returned reference (URL id, expiry token) that the agent would pass to open_url, which is the main remaining gap.

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 baseline is 3, but the description adds cross-parameter semantics the schema cannot: screens entries must be in the same order as screenshots, one per screenshot, the first sells the app, and mixed orientation is disallowed (landscape input yields a landscape App Store set).

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 (make a screenshot set from attached screenshots) and names the concrete deliverables: App Store/Play listing images, framed screenshots, mockups. It is clearly distinguishable from siblings like create_design or replace_screenshots because it is scoped to raw user-attached 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?

Explicitly gives both when-to-use (user attached their own app screenshots and wants store images) and when-not-to-use (already-framed images, inventing screens, nothing attached), with the corrective action for each exclusion. This is exactly the routing an agent needs against 17 siblings.

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 safety profile (destructive, not read-only, not idempotent); the description adds substantial context beyond that — the required two-call sequence, that an upload command (bash/PowerShell) must be run between calls, file validation rules (PNG/JPEG, phone-screen shape), what the reply contains, and detailed per-client authentication steps.

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 trigger is usefully front-loaded, but the body is a dense run-on sentence with nested parentheses that is harder to parse than it needs to be. Information is mostly load-bearing, but the packaging is not clean.

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 multi-call, no-output-schema tool, the description covers the full workflow, the intermediate upload step, validation, the returned revision/previews, and auth differences per client. 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 coverage is 100% and each parameter already carries a 'First call'/'Second call' description, so the schema does the heavy lifting. The description mainly repeats the asset_id/handle/revision/replace_handle roles rather than adding syntax or edge-case meaning beyond what is documented.

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 ('Put new screenshots in a set') and immediately scopes the operation to 'replace' semantics with a two-call flow, distinguishing it from make_screenshot_set and edit_asset. An agent can tell what it does 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?

Gives concrete triggering conditions ('a recapture, a fixed screen, or a phone frame layer to fill') and splits usage by asset_id (saved set, needs sign-in) vs handle (in-conversation, no sign-in). It does not explicitly exclude or route away from sibling tools like edit_asset, 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.

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

Annotations only give the safety profile (readOnly=false, idempotent=true, destructive=false); the description adds the substantive behavior: where the asset lands (named project, project_id/same_project_as, else a new project), that no link needs opening, the returned asset_id/revision/open_url, the auth requirement, and the exact failure+recovery path per agent. That is rich disclosure 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?

Usage is front-loaded and most content earns its place, but it is delivered as one sprawling run-on sentence with deeply nested parentheses, and the per-client sign-in instructions (/mcp, claude mcp login, codex mcp login) add bulk that is tangential to calling the tool.

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 describing the return values (asset_id, revision, open_url) and covers the auth requirement and failure mode. It is slightly undercut by naming parameters absent from the schema, which leaves a small ambiguity about what the call actually accepts.

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% for the single 'handle' parameter, so the baseline is 3. The description adds placement logic but does so by referencing 'project_id' and 'same_project_as', which do not exist in the provided schema — that mismatched parameter vocabulary can mislead an agent rather than clarify.

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 saves a finished set straight into the user's appdesigns library, with no link to open and nothing to press. It names the upstream siblings (finish_project/update_project, create_design/update_design) that must precede it, so an agent can place it precisely in the workflow.

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 states the triggering condition ('when the user is signed in and a set you made is ready ... once the previews look right') and names the exact prerequisite tools. It also states the when-not path: a call without sign-in fails and must be followed by an authentication step.

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 readOnly/idempotent/non-destructive, so the bar is low, and the description still adds real behavioral detail: result shape (path plus one ordered image, left-to-right then down), the no-match fallback (lists categories), and corpus scale (a few thousand pieces). 'Read-only' is redundant with readOnlyHint 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?

Front-loaded with the use condition and tightly packed, with each clause carrying information. It is one long run-on construction with parenthetical asides, which slightly hurts scannability, but nothing is wasted.

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, and the description compensates by explaining the return contents, ordering of the preview image, and the empty-result behavior. Combined with annotation coverage and a fully documented schema, an agent has everything needed to select and 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 description coverage is 100% and all three parameters carry their own descriptions with examples, so the schema does the heavy lifting. The description reinforces the category fallback behavior but adds no syntax or format meaning for query, limit, or category beyond what the schema already states.

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 (search the appdesigns library) and enumerates the content domain in concrete terms (SF Symbols, emoji, 3D shapes, glows and blobs, badges, payment and social marks). It also distinguishes itself from siblings by naming create_design and edit_asset as the consumers of the returned path rather than competitors.

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?

Opens with an explicit use condition: 'Use this when a design or a saved asset needs a ready-made piece rather than art you draw.' That cleanly separates it from authoring tools. It does not name a specific alternative tool for the draw-it-yourself case, so it stops short of full when-not/alternatives routing.

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?

Far exceeds the annotations (which only say it is a non-destructive, non-idempotent write). It discloses that the original is untouched, where the copy lands (same project for asset_id, a new set with its own handle for handle), that the result is a preview of every screen plus warnings, and the exact sign-in requirements per agent for the asset_id path.

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 use case is front-loaded, but it is a single dense paragraph packed with parentheticals, including verbose per-agent sign-in commands (Claude Code /mcp flow, Codex command line). The sign-in detail is useful but makes the description hard to scan; it could be structured more tightly.

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 no output schema, it covers preconditions (sign-in per input mode), what is created and where, what is returned (screen previews and warnings), and the follow-up remedy (edit_asset). 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 coverage is 100%, so the baseline is 3, but the description adds real workflow meaning: texts must cover every text layer listed by get_asset, translations are done by the model, and line breaks should be checked and fixed with edit_asset. The asset_id/handle distinction is also framed in terms of sign-in behavior rather than just repeating the schema.

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 makes a copy of a screenshot set/listing asset in another language (App Store / Google Play localization), and it distinguishes the two input modes (saved asset_id vs. conversation-made handle). An agent can tell this apart from make_screenshot_set or edit_asset without opening any 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 ('when the user wants a screenshot set or listing asset in another language'), routes the agent to asset_id vs. handle based on whether the user saved it, and states 'one call per language'. It does not explicitly exclude or compare against siblings like make_screenshot_set, 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.

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

Annotations cover mutation/safety flags (readOnly=false, destructive=false, idempotent=false), so the bar is lower. The description still adds real behavior: it discloses the return value (new preview images and warnings), the side effect that the original open_url now opens the new version, and the lifecycle rule that edits apply only pre-save. It does not mention permission/auth requirements, which keeps it short of a 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?

Purpose and the 'send only what changes' contract are front-loaded, and every sentence carries substantive information. The final sentence about edit_asset/editor lifecycle is dense and harder to parse, costing a point on structure rather than on 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?

There is no output schema, and the description compensates by explaining that it returns preview images and warnings and that the prior open_url resolves to the new version. Combined with the lifecycle and alternative-path guidance, an agent has everything needed to invoke 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 description coverage is 100%, so the baseline is 3. The description nonetheless adds patch semantics not obvious from the schema alone ('Send only what changes') and summarizes the op vocabulary, helping the agent understand that changes is an ordered partial-update list rather than a full replacement.

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 (changes a design) and enumerates the concrete operations (set/add/remove/move layers, replace variant background/loop/title, add/remove variant), and anchors the resource as 'a design create_design made, before the user saves it.' It clearly distinguishes itself from create_design (the origin) and edit_asset (the alternate path for saved assets).

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 scopes when to use it (drafts not yet saved by the user) and names the alternatives with their selection conditions: designs changed via edit_asset stay there, and user-saved designs change in the editor or via edit_asset by asset_id. 'Send only what changes' also gives the patch-style invocation contract.

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, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description still adds real value beyond that: it discloses that uploaded screenshots are left untouched, that new previews and warnings are returned, and that the open_url from finish_project resolves to the new version. It does not state auth requirements for update_project itself, which keeps it short of a 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?

The mutation scope is front-loaded in the first sentence, followed by the routing rules. It is dense and every clause carries information, though the multi-clause edit_asset routing sentence is heavier than it needs to be and could be split.

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 stating the return (new previews and warnings) and the downstream consequence for finish_project's open_url. Combined with full schema coverage and the edit_asset fallback path, an agent has everything needed to call this correctly and to know when to stop.

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. The description maps its mutable fields onto the parameters (screen_name, headline, background_color, frame_color, device) but adds no syntax, format or default information beyond what the schema already documents in detail (e.g. the #RRGGBB pattern and headline length guidance live in the schema).

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 enumerates exactly what is mutable: screen name, headline, background colour, frame colour, device. It explicitly distinguishes itself from create_project (which made the set) and from edit_asset (which handles everything else), so an agent can route without opening any 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 and when-not-to-use: use this only before the user saves; for anything more (device placement, size, fold, text styles, pieces, another canvas) use edit_asset with the same project_handle; a set already saved must be changed via edit_asset by asset_id. Alternatives and the conditions that select them are named outright.

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