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

Although annotations declare readOnlyHint and openWorldHint, the description adds substantial behavioral detail: it walks request → report → instance → every segment, downloads signed URLs, gunzips TSV, returns parsed rows, and warns that reading only the first segment yields a plausible but partial result. It also clarifies the account-level semantics of ONGOING accessType, going far beyond the annotations.

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, with the core purpose in the first sentence. Every subsequent sentence contributes distinct information: the retrieval mechanics, the partial-data pitfall, the list mode, and the non-creating side-effect warning. There is 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?

Given there is no output schema, the description sufficiently explains what the tool returns (parsed rows from TSV), how it traverses all data segments, how to use list mode, and that it never creates report requests. An agent has enough information to invoke the tool correctly and understand its scope and limitations.

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 high at 83%, with app, date, max_rows, list_only, and report_name already explained in the schema. The description reinforces the report_name list behavior but does not add meaningful semantics for granularity or the other parameters, so it meets the baseline without exceeding it.

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

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

The description opens with 'Fetch an analytics report as rows', giving a specific verb and resource. It then describes the full retrieval pipeline and explicitly distinguishes this tool from report-creating operations with 'Never creates a report request', which separates it from write-oriented siblings.

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 description gives clear operational guidance: omit report_name to list available reports, and never use this to create a report request because ONGOING accessType is a standing commitment. It does not explicitly name sibling alternatives for report creation, so it falls just short of the most explicit alternative-routing guidance.

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

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

Beyond the destructiveHint/openWorldHint annotations, the description discloses important behavioral traits: territories already in the target state are skipped, a partial failure does not abandon the remaining territories, and every territory is re-read and compared afterwards. This is exactly the kind of operational nuance an agent needs.

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 dense but every sentence earns its place: purpose, technical constraint, failure semantics, verification behavior, and a known limitation. The main action is front-loaded and the supporting details follow a logical order.

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?

The description covers the operation, scale, failure handling, verification process, and a key limitation. There is no output schema, so return-value details are not required; the confirmation token is already documented in the input schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

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

All parameters already have schema descriptions with 100% coverage, so the description does not need to restate them. It adds little parameter-specific meaning beyond what the schema already provides, which is acceptable but not exceptional.

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

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

The description opens with a precise verb and resource: 'Turn an app's App Store availability on or off, territory by territory.' It clearly establishes the tool's scope and mechanical nature (one PATCH per territory, up to 175), leaving no doubt about what the tool accomplishes.

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 description explains why bulk usage is impossible ('Apple offers no bulk endpoint') and explicitly calls out a limitation ('Cannot set availableInNewTerritories: that is web-UI only'). It would be stronger with an explicit mention of sibling alternatives, but the conditions and constraints are clear.

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 readOnlyHint=true; the description reinforces this and adds genuinely new behavior: it handles both API styles, follows/concatenates pagination, and warns that short lists may be one page where 'truncated' should not be treated as complete. No contradiction with annotations.

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 earns its place: role, capabilities, and a pagination caveat. The phrase 'both APIs, path and query parameters' is slightly awkward/ambiguous, but the description remains compact and front-loaded.

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 generic read call with six parameters and no output schema, the description covers the crucial behavior: read-only safety, pagination/truncation, and routing writes to asc_write. It does not describe error handling or return shapes, but the schema covers parameter semantics and the tool's generic nature makes exhaustive return documentation impractical.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

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

Schema description coverage is 100%, with detailed parameter documentation for query, paginate, max_pages, environment, operationId, and path_params. The description itself adds no parameter-level meaning beyond the schema, so the baseline 3 applies.

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

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

Description states a clear verb and scope: 'Read from Apple' and explicitly says 'READ operations only', with writes routed to asc_write. It also names core capabilities (both APIs, path/query params, pagination), so the generic name asc_call does not leave the agent guessing.

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 description gives an explicit exclusion: 'anything that changes data goes through asc_write', and it gives operational guidance about truncated pages. It does not name alternative read-only siblings like asc_pricing_get or asc_analytics_report, so it is clear but not fully exhaustive.

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?

With readOnlyHint=true, the safety profile is already known, but the description adds value by disclosing the output content (parameters, request body schema, risk tier). This is especially useful because there is no output schema.

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, front-loaded, and every sentence earns its place. The core value is stated first, followed by a clear usage directive.

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, read-only tool with no output schema, the description adequately covers what the tool returns and when to call it. Minor omissions are the source of operationId and a definition of the risk tier, but these are not critical.

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 0%, so the description must compensate for the parameter semantics. It implies operationId selects the operation, but it does not explain where to get an operationId or what format it takes. The parameter is simple and self-describing, but the gap prevents a higher score.

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 clearly states the tool returns full detail for one operation: every parameter, request body schema, and risk tier. This is specific and distinguishable from siblings like asc_search_endpoints (search/discovery) and asc_write/asc_call (execution).

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 instruction 'Call this before any write' explicitly states when the tool should be used. It does not name alternatives explicitly, but the reference to write operations effectively excludes the sibling write tools and provides a clear usage 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 declare readOnlyHint=true, so the read-only nature is covered. The description adds value beyond that by revealing that the tool baches requests via 'included resources' and that it returns delivery state, which is behavioral/payload context not present in the schema or annotations.

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 two concise sentences. The primary action and resource are front-loaded in the first sentence, and the second sentence provides a valuable efficiency context without fluff.

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 low-complexity read-only list tool, this description is complete: it names the resource, the scope ('on a version'), the included output detail ('delivery state'), and the batching behavior. The schema covers all three parameters, and annotations cover the read-only safety profile, so 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%, so the schema fully documents app, locale, and version. The description only loosely references locale and version ('per locale per set', 'on a version') without adding format or relationship details, so it does not meaningfully improve 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?

The description states a specific verb ('List') and a specific resource ('screenshot sets and screenshots on a version'), and adds the useful detail that each asset's delivery state is included. It is clearly distinguishable from sibling tools like asc_upload_screenshot and asc_pricing_get because the action and resource are explicit.

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 explicit guidance on when to prefer this tool over alternatives, nor any statement of when not to use it. The efficiency note about included resources implies a bulk-listing use case, but it does not tell an agent 'use this to inspect current screenshots' or 'use asc_upload_screenshot to modify them.'

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 readOnlyHint/openWorldHint annotations already signal a read-only external-facing check; the description goes further by disclosing the specific states inspected and the outcome format (GO or NO-GO, with each gap naming a fixing operation). It reveals the tool can catch ambiguous states like PROCESSING builds or WAITITNG_FOR_EXPORT_COMPLIANCE, so there are no surprises in behavior.

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

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

Two tight sentences: the first defines scope and output, the second illustrates the hidden states it catches. No filler or redundant restatement of the schema. The key question is front-loaded.

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?

Given the tool's multi-dimensional check and no output schema, the description is complete: it names the return type, the categories evaluated, and the action-oriented gap reporting. An agent can decide when to call it and what to expect without further documentation.

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 input schema already documents both parameters at 100% coverage: app is a Bundle ID/store name/numeric Apple ID, version is an optional version string. The description does not add anything about parameter formats or defaults beyond the schema, so it sits at 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?

The description states the tool's purpose with a specific verb ('Answer... can this version actually be submitted?') and a clear resource ('a version'). It enumerates the dimensions checked (build state, export compliance, localisations, screenshots, review contact details, open submission), which differentiates it from sibling status or write tools. The GO/NO-GO return is explicit.

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 establishes a clear use case: determine submission readiness before release. It implies this is a diagnostic to run before acting, and notes it catches non-obvious blocking states, but it does not explicitly name alternatives or when not to use it. Context is clear enough, though exclusions and sibling routing are left to the agent.

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 readOnly and openWorld. The description goes further by explaining the underlying multi-hop data model, the currency-ons-territory quirk, and the collapse of ~175 lookups into a few requests. This is genuinely useful behavioral context beyond structured annotations.

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 with the purpose front-loaded. Each sentence earns its place: scope/result organization, efficiency/scale, and a domain gotcha. No filler or 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?

Given 100% parameter schema coverage and readOnly/openWorld annotations, the definition covers what is read, how results are organized, and why this tool is preferable to manual lookups. A formal response shape is not specified, and alternatives are not directly named, but the description is strong enough 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?

The schema already covers all three parameters explicitly, including examples and 'omit for all' guidance, so the baseline is 3. The description adds related context about currency resolution but does not add new syntactic or constraint-level param details.

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?

Starts with a specific verb and resource: 'Read subscription pricing...'. It also specifies scope (every territory, per app), output behavior (currency resolved, territories grouped by price), and the read-versus-write distinction is clear against the asc_pricing_set sibling.

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 description makes the intended use clear: efficiently reading pricing across territories and spotting outliers, while avoiding manual multi-hop lookups. It doesn't explicitly name alternatives or state when not to use it, but the read framing and performance benefit supply enough 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description discloses the exact destructive consequence: Apple defaults preserve_current_price to false, so omitting it silently re-prices existing subscribers at renewal. This is precisely the kind of behavioral warning an agent needs before invoking a mutation.

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 earning its place: the action, the critical required-parameter behavior, and the prerequisite lookup. The warning is front-loaded immediately after the action, so an agent is unlikely to miss the risk.

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 7-parameter write with no output schema, it covers the core behavior, the dangerous default, and the prerequisite lookup. It does not contextualize the gated confirm field or territory/start_date semantics, though those are documented in the schema, so the description is strong but not exhaustive.

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 adds real value by explaining the boolean semantics of preserve_current_price and by telling the agent where price_point_id comes from. It does not need to repeat the schema's existing parameter descriptions.

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?

Opens with a specific verb and resource — 'Change a subscription price' — and the rest of the description sharpens the action by explaining the preserve_current_price effect. This is clearly distinct from the sibling asc_pricing_get (read) and asc_write (generic write) 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?

States the clear use case: changing a subscription price and choosing whether existing subscribers keep or migrate their price. It also gives a concrete prerequisite step for obtaining a price point id, but it does not explicitly name when to prefer this over asc_write or call out when not to use 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, and the description aligns with that by presenting this as a search/find operation. It adds useful context beyond the annotations: API versions, operation counts, and the warning that some resources are not where the URL pattern implies. No side effects are claimed, so there is no contradiction.

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 two sentences and every clause earns its place: scope, API versions, search dimensions, output use, and a routing heuristic. Key information is front-loaded, with no filler or redundant restating of the tool name.

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 search tool with no output schema, the description covers the essential return contract ('returns operationIds for asc_call and asc_write'), the targeted APIs, and valid search dimensions. It is slightly light on how filters combine and what response metadata accompanies the operationIds, but an agent has enough context to invoke the tool 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 67%, so the description partially carries the burden for undocumented parameters. 'Search by keyword, method, tag or risk tier' maps query, method, tag, and risk to their intended roles, and api/limit have schema descriptions with defaults. However, the risk tier values are not explained, and the combination semantics of multiple filters are left implicit, so the description only partially compensates for the schema gaps.

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

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

The description opens with an unambiguous verb and resource: 'Find operations across the App Store Connect API... and the App Store Server API / StoreKit 2.' It also states the search dimensions and the concrete output: 'returns operationIds for asc_call and asc_write.' This clearly differentiates the tool from siblings like asc_call and asc_describe_endpoint.

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 instruction 'Start here rather than guessing a path' establishes when this tool should be used before calling or writing operations, and naming asc_call and asc_write as consumers of the returned operationIds gives the agent a natural next step. It does not explicitly enumerate when to skip this tool and go directly to a sibling, so it stops short of a full 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 already mark readOnlyHint=true, so the read-only nature is known. The description adds meaningful context beyond that: it verifies credentials, reports server reachability, and includes rate-limit budget. These details clarify what the tool actually does during execution and what kind of information it surfaces.

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 tightly packed sentences with no filler. The primary action is front-loaded in the first sentence, and the diagnostic use case follows in the second. Every word contributes meaning.

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 zero-parameter, read-only status tool with no output schema, this description is complete. It explains what the tool does, what it reports (reachability, rate-limit budget), and when to invoke it. Nothing essential is missing for an agent 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?

The tool takes zero parameters, so there is no parameter burden. With 100% schema description coverage (vacuously) and no parameters to explain, the baseline of 4 applies. The description needs to add no parameter detail and appropriately focuses on behavior.

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: 'Verify credentials and report what this server can reach.' It clearly identifies a status/health-check operation distinct from sibling tools like asc_call, asc_write, or asc_pricing_get. The purpose is unambiguous and action-oriented.

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?

Provides explicit guidance: 'Run this first when anything fails — it distinguishes a bad key from a bad request.' This tells the agent when to use the tool and what diagnostic value it provides. It doesn't name alternatives or when-not-to-use, but the conditional use case is strong and practical.

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 annotations, the description discloses the reserve→upload→commit sequence, asynchronous validation, and the surprising behavior that a rejected image commits cleanly and only then reports FAILED. The aspect-ratio example adds concrete failure context. No contradiction with the annotations exists.

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 dense and non-redundant: the action, the resource distinction, a concrete validation constraint, and the async failure model. It is appropriately sized for the complexity and front-loads the main purpose.

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 destructive annotations and no output schema, the description covers the operation's side-effect sequence, validation behavior, and failure mode well. It could add what success returns or how confirm interacts with gating, but overall it is strong and nearly 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?

Schema description coverage is 100% and parameter descriptions already document iap, file_path, confirm, dry_run, and file_name, so the baseline is 3. The aspect-ratio guidance adds useful context for file_path, but the description does not substantially extend parameter semantics beyond 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?

The description opens with a specific verb and resource: uploading the App Store review screenshot for an in-app purchase, and names the reserve→upload→commit sequence. It also differentiates this from a listing screenshot, which helps disambiguate against sibling tools like asc_upload_screenshot.

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 description gives a clear use case: this is the usual reason an in-app purchase stays in MISSING_METADATA when everything else is complete, so an agent knows when it is needed. It also explicitly says this resource is different from a listing screenshot, but it does not name the sibling tool to use as an alternative.

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 a non-obvious failure mode: a wrong checksum or offset silently leaves the asset stuck, appearing as if nothing happened. This goes well beyond the annotations (destructiveHint=true, openWorldHint=true) by explaining the side-effectful behavior and exact sequencing.

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 two sentences with a clear structure: the first defines the core workflow, the second explains why it exists and what can go wrong. Every clause contributes meaningful operational detail without repetition 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?

The description fully conveys the multi-step process, the dependence on Apple-supplied headers, and the critical silent-failure risk, giving an agent the operational context needed to invoke it correctly. It does not cover the return value or prerequisites in detail, but the schema and annotations already handle parameter and safety context, and no output schema exists to constrain expectations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

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

Schema description coverage is 100%, so all five parameters already have meaningful schema-level descriptions. The tool description mentions checksum and offset concepts but does not map them to specific input parameters, adding little parameter-level value beyond 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?

The description states a specific verb ('Upload') and resource ('screenshot image') and adds the concrete reserve → upload → commit workflow, making the tool's unique function clear. However, it does not explicitly distinguish itself from the sibling asc_upload_iap_screenshot, so it lacks direct sibling differentiation.

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 description provides clear context for when to use the tool: it exists because the raw API cannot perform the full upload sequence in one call. It does not mention alternative sibling tools or explicit when-not conditions, but the underlying rationale effectively guides usage.

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?

While annotations already flag readOnly=false and destructive=true, the description adds meaningful behavioral context: consequential tiers (REVENUE, DESTRUCIVE, INFRASRUCTURE, ACCESS, RELEASE) prompt for user confirmation, and dry_run validates without sending. This helps an agent anticipate side effects and safety gating beyond the raw annotation booleans.

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 with no wasted words. The purpose is front-loaded, consequential behaviors are stated next, and the dry_run and schema-discovery guidance are packed into the final two sentences. Every sentence justifies 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 complex write tool with no output schema, the description covers the key operational concerns: mutation scope, user confirmation gates, dry-run safety, and where to find the correct body schema. It does not describe return values or error behavior, but given that the response depends on the endpoint and the agent is pointed to asc_describe_endpoint, this is a reasonable completeness level.

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 input schema already documents all 7 parameters thoroughly (100% coverage), including JSON:API body, base64 uploads, query filter syntax, and the confirm token. The description adds value only by directing the agent to asc_describe_endpoint for the operation-specific body schema and recommending dry_run, but it does not substantially expand parameter meaning beyond 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?

The description opens with a specific verb-plus-resource statement: 'Change something in App Store Connect: create, update or delete,' which clearly identifies the tool as a writ operation and differentiates it from read-oriented siblings like asc_call and asc_status. It is immediately clear what the tool does and what category of operations it covers.

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 guidance to 'Use dry_run first when you are unsure what a call will do' and to 'Read asc_descibe_endpoint first to get the body schema right,' which are concrete stepps for safe and correct usage. It also explains that consequential tiers require user confirmation before anything is sent. However, it does not explicitly state when not to use asc_write in favor of a read-only sibling like asc_call.

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