Agent C — App Store Screenshots

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

Annotations already declare this is a non-read-only, open-world, non-destructive write. The description adds genuinely useful behavior the annotations cannot: import of a live app is asynchronous and takes ~10-30s, and the caller must poll list_apps until status is 'ready'. It omits failure modes (invalid URL, duplicate app) but the async contract is the key gap it closes.

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, no filler, and the primary path (App Store link) is front-loaded ahead of the fallback and the latency/polling caveat.

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 two-optional-parameter mutation tool with full schema coverage, existing annotations, and no output schema, the description covers the essential unknown — that the operation is asynchronous and requires polling. Error/duplicate handling is the only notable omission.

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 are documented in the schema, including the 'not on the App Store yet' note for name. The description restates that condition rather than adding new syntax or format detail, 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 ('Add an app') and explains the two distinct input modes — App Store link vs. bare name for unreleased apps. It names list_apps, but only as a polling target rather than as an alternative tool, so sibling differentiation is partial.

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 clear conditional guidance: use the App Store link for live apps, use the name for apps not yet released. It also tells the agent what to do afterward (poll list_apps). It stops short of explicit when-not-to-use guidance or naming a competing sibling like edit_set.

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 readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description adds meaningful behavioral context beyond that: it returns watermarked previews, a slide list, and a studio link, and it takes ~40-60 seconds. However, it does not clarify whether this overwrites anything, what 'watermarked' implies for downstream use, or what preconditions exist (e.g., uploaded screenshots required first).

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 compact sentences: purpose, output, timing. Front-loaded with the core action and no filler. Slightly telegraphic—'Claude art-directs'—but efficient throughout.

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, so the description usefully sketches the return (watermarked previews, slide list, studio link) and the runtime. But it omits prerequisites (uploaded screenshots / app must exist) and whether the result is a persisted set the other sibling tools (edit_set, export_set, get_set) operate on. Adequate but with notable gaps for a generative, open-world 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 description coverage is 80%, so the schema already documents most parameters including enums for device, opener, and include, and focus. The description adds no per-parameter syntax or format detail beyond what is in the schema, 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 states a concrete verb and resource: Claude art-directs a full App Store screenshot set (opening shot, headline per slide, close-ups, palette) from uploaded screenshots. This is specific about what gets produced. It does not explicitly differentiate from siblings like edit_set or export_set, but the generative nature is clear enough that confusion is unlikely.

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?

Phrasing implies usage (create a new set needing uploads), but there is no explicit when-to-use guidance or condition contrasting this with edit_set, get_set, or export_set. An agent must infer that design_set is the initial creation step and edit_set modifies an existing set.

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 readOnlyHint=false and destructiveHint=false, so the write/safe profile is largely covered. The description adds real context beyond that: 'Re-renders previews' discloses a side effect and 'Free' discloses cost/credit behavior. It still omits prerequisites such as locking/unlocking state before editing.

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 dense sentences with the scope front-loaded, then side effect and cost trailing. Little waste, though cramming a long enumeration into one sentence slightly hurts scannability.

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 14-parameter mutation tool with no output schema, the description covers the field groupings, the re-render side effect, and cost, which is adequate. But it omits prerequisites (existing/unlocked set, set_id provenance) and any indication of what a successful edit returns, leaving gaps an agent would want.

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?

With 14 params and only 50% schema coverage, the description meaningfully compensates by mapping parameters to concepts: headline/subline/screenshot/layout/position (move_to)/remove for a slide, opener for the opening shot, device for size, and header_* for the App Store header. The include param and set_id are left to 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 (Change/edit) and resource (a set), and enumerates the concrete facets it mutates: a slide's headline, subline, screenshot, layout, position, removal, the opener, device size, and the App Store header. This makes the tool distinguishable from design_set/create-style siblings, though it never explicitly contrasts with them.

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?

No when-to-use or when-not guidance is given. It doesn't state that the set must already exist (from design_set), whether it must be unlocked, or how this differs from design_set, add_app, or upload_screenshots. Usage is only inferable from the name.

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 the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the description need only add context. It does: no watermark, exact App Store pixels, link validity of 7 days, and conditional inclusion of header/search images when the set has a header. It stops short of stating auth/Permission needs or rate limits, keeping it at 4 rather than 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?

Two sentences, front-loaded with the core action and outcome, then the qualifying conditional detail. Every clause (pixels, no watermark, link TTL, image dimensions) earns its place.

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 tool with no output schema, the description covers what is produced (download links with 7-day validity) and the exact deliverables (3840x1646 header, 3840x2560 search image). 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% and the single set_id param is documented as 'set_id returned by design_set.' The description adds no syntax or meaning beyond the schema, 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?

States a specific verb and outcome ('Render the unlocked set ... and return download links') with the exact resource and pixel fidelity, and the granted/unlocked scope cleanly separates it from design_set, get_set, and unlock_set. An agent immediately knows this is the export step.

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?

The phrase 'the unlocked set' implies the unlock_set prerequisite, which is useful context, but no alternatives (get_set, send_to_app_store) are named and there is no explicit when-to-use or when-not guidance. Usage is only implied.

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=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the useful fact that returned data is live/current state including unlock status and regenerated previews, but says nothing about freshness latency, pagination, or failure modes.

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?

A single tight sentence with the payload description front-loaded and zero filler. It is a noun phrase rather than a full sentence, which slightly blurs the action being performed.

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 characterize the return value, and it does name the three returned elements. Combined with the annotation-covered read-only profile, an agent has enough to call it correctly, though richer detail would help.

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?

Only one parameter and schema description coverage is 100%, so the schema carries the semantics. The description adds nothing about set_id beyond what the schema already 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?

Names the resource (a set) and enumerates exactly what is fetched: current slides, unlock status, and fresh preview images. That is specific enough to separate it from edit_set, unlock_set, and export_set, though it never uses an explicit retrieval verb.

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?

There is no statement of when to call this versus siblings such as list_apps or design_set, and no prerequisites or follow-up guidance. Only the implicit read-a-set use case hints at context.

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 mark the tool as non-read-only and open-world, but the description adds substantial behavioral context: one-time URL, 30-minute validity, curl multipart usage, field name 'files', and a limit of 10 files per request. That goes 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?

The description is compact and front-loaded: it states the tool's purpose, then the upload mechanics, then the routing advice. Every phrase contributes useful information without waste.

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 this tool and context, the description covers purpose, invocation method, constraints, return behavior, and alternative. With no output schema, it explains what is returned, and the input schema covers the parameters.

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 both app_id and replace are already documented structurally. The description does not add further meaning to either parameter, so the baseline score of 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 states a specific action, returning a one-time URL for uploading screenshots, and clearly identifies the use case of uploading image files from disk with curl. It also distinguishes itself from the sibling upload_screenshots tool by naming it directly.

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 guidance: use this instead of upload_screenshots when you have a shell, so large images don't pass through the conversation. This names the alternative and the condition that selects 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 declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful return-value context by noting each app comes with its screenshot count, but says nothing about pagination, sorting, or result size for an open-world read.

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?

A single compact sentence with no filler, front-loading the resource and then the included metric. Slightly under-specified rather than padded, which is the right failure mode for a zero-arg list 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 is the only source of return-value information, and it does disclose the key payload (apps plus per-app screenshot counts). However it omits ordering, pagination, and errors, which matters since the annotation marks this as an open-world read.

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?

The tool takes zero parameters, so there is no parameter surface for the description to compensate for. Baseline 4 applies; the description correctly avoids inventing parameters.

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?

Identifies the resource (the user's apps in Agent C) and a notable included field (screenshot count per app), but it is a noun phrase without a verb, so the act of listing is only implied by the tool name. It is distinguishable from siblings like add_app or upload_screenshots, but the scope (all apps? paginated?) is unstated.

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?

No indication of when to call this versus sibling tools such as get_set or design_set, and no prerequisites or context are given. The agent must infer usage entirely from the name and the resource description.

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 and openWorldHint=true, and the description adds meaningful context on top: it specifies the destructive behavior is a replacement of that language's screenshots for this device size, that it never submits for review, and that an external auth connection to App Store Connect is required. That is exactly the extra behavioral detail 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?

Three tight sentences front-loading the action and scope, then exclusions, then prerequisites and the fallback. No filler or repetition of the title.

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 a small parameter set, the description covers the key agent-facing concerns: what is overwritten, that review submission is out of scope, auth prerequisites, and the create_version fallback path. Minor gaps remain around error/partial-failure behavior and the locale parameter's role, but nothing critical is missing for correct invocation.

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 only 33% (only set_id is documented), so the description must compensate. It usefully explains create_version's purpose and the condition for setting it, but never names or explains the locale parameter beyond the oblique phrase 'that language's screenshots'. Partial compensation warrants the 3 baseline-and-hold.

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 (upload) plus resource (unlocked set) and destination (the app's editable version in App Store Connect), and narrows scope to one language's screenshots for one device size. This clearly separates it from siblings like export_set, upload_screenshots, and design_set.

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 concrete precondition (user must have connected App Store Connect in Agent C) and an explicit branch for the missing-editable-version case, including telling the agent to ask the user first. It does not contrast against sibling tools such as export_set or upload_screenshots, so it stops short of full when/when-not/alternatives 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?

Beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false), it discloses the free-unlock-first logic, that the agent returns a $9.99 Stripe link the USER must personally open and pay, and that Studio subscribers are already unlocked. It also mandates user confirmation, which is essential behavioral context for an open-world paid action.

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

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

Three short sentences, each carrying distinct information, with the action and outcome front-loaded and the consent requirement placed last as a directive. No 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 covers both possible outcomes (immediate unlock vs. returned checkout link) and the subscriber bypass, so an agent knows what it will get back and what to do next. Nothing needed to invoke 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% and there is a single required parameter already documented as 'set_id returned by design_set'. The description adds no parameter detail, which is the expected baseline when the schema does the work.

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 ('Unlock clean, full-resolution files for a set') and pins down exactly what unlocking produces. It is immediately distinguishable from siblings like design_set, edit_set, and export_set.

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 context for use: try a free unlock if available, otherwise the paid checkout path, and 'Ask the user before calling' sets the consent gate. It does not name alternative tools, but no sibling competes for this action, so the guidance is effectively complete.

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, openWorldHint=true, destructiveHint=false, so safety is partly covered. The description adds genuinely useful behavior beyond that: the default library-replacement semantics, the accepted payload formats (base64 PNG/JPEG or public https URL), and ordering significance. It does not cover auth/permission requirements, rate limits, or what the response contains. Note a mild tension with destructiveHint=false, since replacing the library by default discards prior screenshots.

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 dense sentences, front-loaded with the core action and count, followed by payload formats and the default mutation. Each sentence carries information, though the first sentence packs count, ordering, and content-quality advice together and could be split for scannability.

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 3-parameter upload tool with no output schema, the description covers the essentials an agent needs to call it: payload forms, count bounds, ordering, and the replace default. Missing only secondary details such as permission requirements and whether replace=false appends rather than clears.

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 only 33% (images and replace have no schema descriptions), so the description has to compensate and largely does: it explains that each images entry is base64 PNG/JPEG or an https URL, that order matters, that 1-10 are accepted, and that replace defaults to true and overwrites the library. Only app_id is left entirely to 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?

Names a specific verb and resource ('Upload 1-10 raw screenshots of the app') and pins the scope with a count range and an explicit default behavior ('By default replaces the app's screenshot library'). It does not explicitly differentiate itself from the related sibling get_upload_link, which is the main reason it falls short of 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?

Offers implied usage guidance ('ideally 4-10, in the order you'd like them considered') and states the default replace behavior, but never says when to use this tool instead of get_upload_link or the other set-management siblings, nor when to prefer replace=false. Usage context is present but not routed.

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