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 already declare non-read-only, open-world, non-destructive. The description adds real value beyond them: a ~40-60 second runtime estimate and the shape of the output (watermarked previews, slide list, studio link). It does not say whether a new set is created or an existing one overwritten, which is the main remaining ambiguity.

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?

One dense paragraph, front-loaded with the action and what is produced, with runtime appended last. Every sentence carries information; nothing is 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?

No output schema exists, so describing the return shape (previews, slide list, studio link) is necessary and done. Missing is the lifecycle context an agent needs: that the result is a set later editable via edit_set or exported via export_set, and any cost/credit implications of a 40-60 second generation.

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 three enums are fully documented in the schema (device sizes, opener styles, include modes). The description contributes nothing about focus, app_id, or device behavior, so baseline 3 is right.

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 concrete verb and artifact: art-directs a full App Store screenshot set (opening shot, headlines, close-ups, palette). This clearly distinguishes it from edit_set/export_set/get_set. It stops short of explicitly naming the sibling it differs from, so not 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?

'from the uploaded screenshots' implies the upload prerequisite, and the app_id param points at list_apps/add_app, but the description never says when to call this versus edit_set (revise an existing set) or get_set. Usage is inferable rather than stated.

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=false, destructive=false and openWorld=true, so the safety profile is covered; the description adds real value beyond that by disclosing the side effect (previews are re-rendered) and the cost model (Free), which matters for deciding to iterate here repeatedly. It does not disclose whether edits are reversible, whether removal renumbers remaining slides, or whether re-render is synchronous — gaps that matter for a destructive=false but write-shaped tool.

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 front-loaded sentences with no filler; the editable targets come first and the side effect/cost trail as a short addendum. The parenthetical lists and shorthand like 'header_*' are dense but each clause carries information, so 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?

For a 14-parameter mutation tool with no output schema and no documentation of what is returned after a re-render, the description covers the main edit modes but leaves notable holes: how header-only edits interact with include, whether slide and header fields can be mixed in one call, and what happens to slide numbering after remove. It is adequate to attempt a call, not complete enough to predict 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 coverage is only 57% across 14 parameters, so the description has to carry weight. It does map several undocumented params to meaning (opener = 'opening shot', move_to = 'position', remove = 'remove it', device = 'device size', header_* = App Store header), but it never explains the layout enum values, the include modes, or whether the 'or'-separated edit modes are mutually exclusive or combinable in one call.

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 enumerates the editable surfaces: one slide and its parts, the opening shot, device size, or the App Store header (header_*). That makes it operationally distinct from read-only siblings like get_set and from design_set/export_set. It stops short of naming an alternative sibling explicitly, which keeps it out of 5 territory.

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 implied by the enumeration of what can be edited, but there is no explicit when-to-use guidance, no statement of when to prefer design_set or upload_screenshots, and no stated prerequisites (e.g., a set must exist and be unlocked before editing). The agent must infer that 'Free' and 'Re-renders previews' make this a cheap iterative 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 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?

Adds meaningful behavior beyond the annotations: the URL is one-time, valid for 30 minutes, accepts multipart field 'files', and caps at 10 files per request. It doesn't cover auth requirements or what happens on expiry, but it substantially enriches the safety profile already supplied by readOnlyHint=false, destructiveHint=false, and openWorldHint=true.

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 return value, followed by the routing guidance. Every clause carries useful information with no repetition.

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 two-parameter tool with no output schema, the description covers what is returned, how long it is valid, how to use it, and when to prefer it. Minor gaps around auth headers and failure modes remain, but the essential calling context is present.

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 app_id and replace are already documented in the input schema. The description adds operational detail about the URL's 'files' field and the 10-file limit, but does not clarify the tool's own input parameters beyond that. Baseline 3 is appropriate when the schema does the heavy lifting.

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 a one-time upload URL. It explicitly distinguishes itself from the sibling upload_screenshots by naming the alternative and the condition that selects it, so an agent can route correctly 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 explicit when-to-use guidance: prefer this over upload_screenshots when a shell is available, so large images don't pass through the conversation. The alternative and the routing condition are named directly.

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 flag destructiveHint=true and openWorldHint=true; the description goes further by specifying exactly what is destroyed (that language's screenshots for this device size are replaced), that it never submits for review, and that an external App Store Connect connection is required. That is real context beyond the structured hints.

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?

Four sentences, each carrying distinct load: action and scope first, exclusion second, scope limit third, prerequisites fourth. No restating of the title or 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 destructive, open-world mutation with no output schema, the description covers action, scope, exclusion, prerequisites, and the create_version fallback path. It doesn't say what a successful or partial upload returns (screenshot counts, failures), which would help an agent interpret 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 coverage is only 33%, so the description must compensate. It explains create_version behaviorally (only after asking the user and finding no editable version) and implies locale via 'that language's screenshots'; set_id is covered by the schema itself. Locale's default and matching rules remain slightly underspecified.

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: uploads the unlocked set into the app's editable App Store Connect version, replacing that locale's screenshots for the current device size. It also names the case it is not for (iPhone Duo -> export_set), so an agent can separate it from export_set 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 preconditions (user must have connected App Store Connect), a branch instruction (if no editable version, ask the user then retry with create_version=true), and one exclusion (not iPhone Duo). It does not clarify its relationship to the sibling upload_screenshots, so the boundary against every alternative isn't fully drawn.

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?

The description discloses the most important behavioral fact — that the call overwrites the app's existing screenshot library unless replace=false — which is exactly the kind of side effect an agent must know. However, this overwrite-by-default behavior conflicts with the annotation destructiveHint=false, producing contradictory safety signals, and nothing is said about validation failures, size limits, or fetch behavior for remote https URLs.

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, each front-loaded with the most decision-relevant fact: count/ordering first, payload format second, the destructive default last. No filler and no restatement 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?

For a 3-parameter mutation with no output schema, the description covers the essentials an agent needs to call it safely: payload forms, ordering, count range, and overwrite semantics. It would be stronger if it mentioned what is returned (e.g., resulting screenshot IDs) or limits on remote URL fetching.

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 app_id is documented), so the description has to carry images and replace, and it does: item count 1-10 with an ideal 4-10, ordering semantics, accepted formats (base64 PNG/JPEG or public https URL), and the exact meaning of replace=true/false with a concrete use case. Only minor gaps remain (per-item size limits, mixed URL/base64 allowed?).

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?

Specific verb + resource + target ('Upload 1-10 raw screenshots of the app'), with the accepted payload shapes spelled out (base64 PNG/JPEG or public https URL). It does not explicitly distinguish itself from siblings like get_upload_link or send_to_app_store, so an agent must infer the boundary.

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 actionable conditions: default replaces the library, pass replace=false when adding iPad or iPhone Duo captures alongside iPhone ones, and aim for 4-10 plain captures in the desired order. It lacks an explicit 'when not to use this vs X' statement against siblings, but the context needed to choose correct parameter values is present.

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