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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and external-data exposure are covered. The description adds useful scope detail by naming the three data groups included and signaling that builds are limited ('most recent'), but it says nothing about how many builds/versions are returned, whether version data is truncated, or what happens for an app with no releases.

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 tightly-packed sentence with the aggregate scope front-loaded and the three result groups enumerated in order. No filler, no restatement 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?

With no output schema, the description usefully documents what comes back (details, versions with review/release and phased-release progress, recent builds with processing state), which is the critical information for an agent deciding whether one call suffices. The only meaningful omission is any guidance on the required appId parameter.

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

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

There is one required parameter (appId) with 0% schema description coverage, so the description carries the full burden of explaining it. The description never mentions appId at all — no format, no source, no id-type distinction (numeric App Store ID vs. resource id). This is a real gap for a required parameter.

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

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

The description names a specific verb ('one-call status') and resource (an app) and enumerates exactly which sub-resources are returned: app details, latest versions with review/release/phased-release state, and recent builds with processing state. This clearly distinguishes it from single-resource siblings like asc_list_builds or asc_list_app_info, though it never names those siblings explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'one-call status' implies the aggregation use case, so an agent can infer it should be preferred over several individual list calls. However, there is no explicit 'use this when...' statement, no mention of alternatives like asc_list_app_info or asc_list_builds, and no exclusion for when a targeted list is better.

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

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

Goes well beyond the annotations by disclosing that inputs are validated against Apple's OpenAPI spec, that responses are compacted with resource links removed (and that `raw` restores them), and that blocked calls explain how to enable the required access mode. It doesn't cover rate limiting or how the blanket destructiveHint maps to individual operations.

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

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

The purpose is the first clause, followed by dense, example-driven payload syntax and then access-mode constraints. Every sentence carries non-redundant information; no filler or 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 schema-less-return, generic dispatch tool this covers validation, payload shapes, pagination, compaction, and auth gating. The one remaining gap is how an agent discovers a valid operationId, which is left entirely to the unmentioned asc_search_operations/asc_describe_operation siblings.

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 75%, and the description compensates by spelling out query key syntax with Apple's exact names (filter[app], sort, fields[builds], include, limit) and the JSON:API body envelope shape. Only pathParams and maxItems are left to the schema, which documents them adequately.

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 ('Execute any App Store Connect API operation by operationId') and makes clear this is the generic escape hatch versus the dedicated siblings like asc_list_builds or asc_app_overview. An agent can tell instantly that this tool requires an operationId rather than a resource-shaped parameter 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 concrete routing rules: follow nextUrl with asc_fetch_url or pass fetchAll, and use write/full access mode for creates/updates/deletes. However it never states when to prefer a dedicated sibling (e.g. asc_list_builds) over this generic call, nor points to asc_search_operations/asc_describe_operation for finding the operationId.

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 openWorldHint=true, so the safety profile is covered. The description adds meaningful behavioral context by stating exactly what the check reveals: API key validity, server mode (readonly/write/full), spec version, and rate-limit status.

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 states what the tool does and what it returns, the second gives usage guidance. No filler, and the primary purpose 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?

For a zero-parameter diagnostic tool with no output schema, the description fully covers what an agent needs: what the tool checks, what information it returns, and when to invoke it.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly does not discuss parameter syntax, as there are none.

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 ('Verify') and resource ('API key') plus concrete outputs (server mode, spec version, rate-limit status). It is clearly distinguishable from all sibling tools, which are data-listing or operation-calling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says to run this first when setting up or when calls fail with auth errors, giving clear trigger conditions. It does not name alternatives or state when not to use it, but no alternative diagnostic tool exists among the siblings.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds valuable behavioral context by detailing exactly what content is returned (params, sparse fieldsets, body schema), which matters because there is no output schema. It does not mention response format or whether results are cached, leaving a small gap.

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, both earning their place: the first enumerates the return payload, the second gives the routing instruction. Return content is front-loaded and the alternative tool is placed last.

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 discovery/describe tool with no output schema, the description adequately conveys what an agent will get back and when to call it. It stops just short of describing return shape or error behavior, but nothing essential for correct invocation is missing.

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

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

There is a single parameter with 100% schema description coverage, and the schema itself provides example operation IDs (apps_getCollection). The description adds no additional meaning about operationId beyond what the schema already conveys, so the baseline of 3 is correct.

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 (describe/show) applied to a well-defined resource (one App Store Connect API operation), with an explicit enumeration of the payload: path params, query params, sparse fieldsets, and request-body schema. This clearly distinguishes it from the sibling asc_call_operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use it ('Call this before asc_call_operation for any operation you haven't used yet'), naming both the companion tool and the condition that triggers use. No inference required.

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

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

Annotations only declare readOnlyHint and openWorldHint, so the description carries real added value: it discloses the download pipeline (fetched from Apple's links, checksum-verified, unzipped, merged) and that rows are returned inline. It omits rate-limit/error behavior and how partial failures across multiple dates (maxInstances) are handled.

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

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

Three sentences, front-loaded with the action, then the processing behavior, then the name-discovery pointer. No redundant restatement of the title or schema fields.

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 nine optional parameters, no output schema, and only annotations covering the safety profile, the description should clarify the valid parameter combinations (reportId path vs appId+reportName path) and what truncated/inline rows mean. It covers the return shape at a high level ('its rows') but leaves the invocation strategy ambiguous.

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

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

Schema coverage is high (89%), so the schema already documents dates, maxRows, maxInstances, saveTo and granularity. The description adds only that the date range scopes the download and that rows are returned inline; it says nothing about when reportId alone suffices versus the appId+reportName combination, which is the least obvious part of the parameter set.

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

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

States a specific verb and resource ('Download one analytics report ... for a date range and return its rows') with concrete report-name examples. It distinguishes itself from asc_list_analytics_reports by routing name discovery there, but does not explicitly separate itself from the sibling download tools for sales and finance reports.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear prerequisite workflow: 'Find report names with asc_list_analytics_reports' before calling this tool. There are no explicit exclusions or negative cases (e.g., when to prefer the sales/finance downloaders), so it stops short of full when/when-not 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?

The annotations already state readOnlyHint=true and openWorldHint=true, so the safety profile of this tool is already covered. The description adds substantial behavior information: it returns parsed rows rather than an opaque file, and it says how the special region codes work, including the WW/FINANCE_DETAIL coupling. Auth needs and rate limits are unstated.

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

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

It has two sentences and no wasted words: the core action is front-loaded, and the region-code detail follows in the second sentence. Every clause carries information.

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 six-parameter download tool with no output schema, the description explains what is returned (parsed rows) and which regions are valid. Two gaps remain: it doesn't say what happens when the data exceeds maxRows, and it doesn't cover what authentication the tool needs for the open-world request.

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 description coverage is 83%, so the schema already documents all six parameters, which sets the baseline score at 3. The description expands regionCode beyond the schema's terse examples, listing every valid region and the semantics of ZZ and WW. It adds nothing for vendorNumber, reportDate, maxRows, or saveTo.

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 definition names a specific verb and resource ('Download a monthly financial report') plus the domain concept ('proceeds by region'), which clearly separates it from asc_download_sales_report and asc_download_analytics_report. It never names those siblings outright, so the differentiation depends on the agent inferring from the word 'finance'.

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 useful context (region codes, consolidated ZZ, WW restricted to FINANCE_DETAIL) that limits how the tool can be used. However, it never states when to pick this tool over the sibling download tools, and it doesn't explain any prerequisites.

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 and openWorldHint, so the safety profile is covered. The description adds real operational context beyond that: the result is returned as parsed rows, the vendor number's location in App Store Connect, and the one-day availability lag that affects reportDate choices.

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: what is returned, how to obtain the required vendor number, and the freshness constraint. Nothing is redundant and the core action 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?

For an eight-parameter tool with no output schema, the definition covers the essentials: parsed rows as output, saveTo/maxRows documented in schema, and the timing caveat. It stops short of describing what the parsed rows contain or how to interpret an empty report, which is a minor gap.

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

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

Schema coverage is 75%, so the description needs to add some meaning, and it does for the undocumented vendorNumber by saying where to find it, plus a timing note relevant to reportDate defaults. It does not explain the reportType/reportSubType interactions, but those enums are documented in the schema.

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

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

The description gives a specific verb ('Download') and a well-defined resource ('a Sales and Trends report'), and parenthetically enumerates the report families it covers. It distinguishes itself from asc_download_finance_report by naming the Sales and Trends report domain, though it never explicitly routes to or away from that 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?

Usage context is implied rather than stated: it explains where to find the vendor number and notes that reports usually appear a day after the reporting date, which implicitly guides timing. But there is no explicit when-to-use/when-not guidance and no mention of the finance or analytics report siblings as alternatives.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds one genuinely useful constraint not in structured data: only Apple's API host is allowed. It does not mention the saveTo side effect of writing a file to disk, nor response/pagination 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 sentences, front-loaded with the action and input, then the host restriction. No filler and nothing redundant with the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only fetch with annotations covering safety and a well-described second parameter, this is largely complete. Minor gaps: it doesn't say whether the response's own nextUrl can be re-fed to paginate, and it doesn't flag that saveTo writes a file.

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 50%; the url param has only format=uri in the schema, and the description supplies its real meaning (must be an absolute api.appstoreconnect.apple.com URL, typically a nextUrl or related link). The fully documented saveTo param needs no repetition in the description.

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 (GET) and resource (a full api.appstoreconnect.apple.com URL), and clarifies the input shape versus the sibling operation tools that take operation names/paths. It does not explicitly name a sibling, but the concrete examples (nextUrl, relationship related link) make the boundary clear enough to select it without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear invocation context: use it when you already hold an absolute URL from a prior response or a relationship link. No explicit exclusions or named alternatives are given, so an agent must infer that asc_call_operation is for constructing calls rather than replaying URLs.

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 and openWorldHint, so the safety profile is covered. The description adds meaningful behavioral context beyond that: the setup dependency and the dual-mode behavior (listing reports vs. listing dates for one report). It does not describe pagination, auth, or output shape.

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 efficiently structured sentence front-loads the primary action and uses a parenthetical to enumerate categories without waste. The precondition sentence is short and 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 read-only listing tool with no output schema, the description covers purpose, modes, and the setup prerequisite. Return-value details and pagination behavior are unstated, but the core information needed to invoke it correctly 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 only 33%, with reportId being the sole documented parameter. The description partially compensates by enumerating the category families and explaining the reportId mode, but appId's format/role and the category's default behavior are left implicit.

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 resource (analytics reports for an app), enumerates the report families, and explains the second mode triggered by reportId. This clearly distinguishes it from download-oriented siblings such as asc_download_analytics_report.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a concrete precondition — reports only exist after asc_analytics_setup has run — and explains the reportId branch for retrieving available dates. It does not explicitly name alternative tools or state when not to use it, keeping it below a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description still adds real behavioral context: it returns both the live app info and the in-progress next-version info, and flags which fields are editable. That dual live/edit result shape is not derivable from the annotations or 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?

Two sentences, front-loaded with the field list and closed with the live-vs-edit distinction. No filler and nothing repeated from the title alone.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only single-parameter listing tool with no output schema, the description covers what comes back, in which variants (live and pending version), and editability. The only real gap is the unmentioned appId scoping.

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 single required parameter appId has 0% schema description coverage, and the description never mentions it, so nothing explains that the tool is scoped to one app. 'Per language' hints at a locale dimension that does not even appear in the schema, which could mislead.

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 (show/list) and resource (app-level store details per language) and enumerates the fields returned: name, subtitle, privacy policy and privacy choices URLs. The 'app-level' qualifier implicitly separates it from version-scoped siblings such as asc_list_version_localizations, though no sibling is named.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: a reader infers you call this to inspect app-level metadata rather than version localizations or app overview. There is no explicit when-to-use, no stated prerequisites, and no named alternative among the many listing siblings.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description usefully discloses the shape of the result (ids, names, bundle ids, SKUs), but says nothing about pagination behavior or how the default limit of 100 affects a large account.

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 short sentences with zero waste; the primary purpose is front-loaded and the prerequisite note follows. Nothing could be trimmed without losing information.

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 sensibly compensates by listing the returned fields, and annotations cover the read-only/open-world nature. The one gap is pagination and limit handling, which an agent listing a large account would want to know.

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

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

Schema description coverage is 100% – each of the three filter parameters is documented in the schema itself. The description adds no filter semantics, syntax, or matching behavior beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb (List) and resource (apps in the App Store Connect account) and even enumerates the fields returned (ids, names, bundle ids, SKUs). It does not, however, distinguish itself from the sibling asc_app_overview, which plausibly overlaps as an app-information tool.

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?

'App ids are needed by most other tools' implies this is a prerequisite discovery call, which is useful implied guidance. It names no explicit alternative and gives no when-not-to-use condition, so usage is only implied 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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description goes beyond them by naming the concrete fields returned (ids, hasAccessToAllBuilds, public link settings), which is real added value given there is no output schema. It stops short of stating pagination or return-format 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?

A single front-loaded sentence with no filler; the resource and its scope come first, followed by returned fields. The nested parentheticals make it slightly dense but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read tool with annotations and no output schema, this is largely complete: it identifies the resource, scope, and returned fields. Remaining gaps (appId format, pagination, whether public links only apply to external groups) are minor but real.

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% for the single appId parameter, so the description should compensate. 'An app's' implies appId identifies the app but gives no format guidance (numeric App Store ID vs. bundle ID) or scoping notes, leaving the agent to infer 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?

States a specific verb ('List') and a precisely scoped resource ('an app's TestFlight beta groups (internal and external)'). No sibling tool covers beta groups, so an agent can distinguish it from asc_list_builds or asc_list_app_info without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: an agent infers it should call this when it needs beta group data for a given app. There is no explicit when-to-use, no prerequisites, and no named alternative or follow-up tool.

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 and openWorldHint, so the safety profile is covered. The description adds useful behavior (newest-first ordering and the shape of each returned record), but says nothing about pagination behavior beyond the schema's default-25 limit or about how the optional filters narrow results.

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 front-loaded sentence that names the resource, the ordering, and the payload. No filler and nothing buried.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully previews the returned fields, but for a 5-parameter list tool it omits the filtering semantics of version, buildNumber, and processingState and does not mention pagination, leaving gaps an agent must guess at.

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 60%, so appId and processingState lack descriptions. The description enumerates returned fields rather than explaining the filter parameters, and 'platform'/'expiry' are not even inputs, so it adds only marginal meaning over the schema. Baseline 3 for partially covered 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?

States a specific verb and resource ('List an app's builds') plus ordering ('newest first') and the returned field set. It is unmistakably distinct from the other asc_list_* siblings, though it never names an alternative to route between 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 guidance, no mention of alternatives such as asc_app_overview, and no indication that the optional version/buildNumber/processingState parameters act as filters. The agent is left to infer that this is the raw build-list call.

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 openWorldHint=true, so the safety and external-data profile are covered. The description adds useful return-content context by naming rating, title, body, territory, and developer response, but it does not disclose pagination behavior or other operational traits beyond what the schema provides.

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 tight sentences with no filler. The primary listing behavior is front-loaded, and the filter tip follows immediately.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only list tool with no output schema, the description is mostly complete: it names the returned review fields and explains the key unansweredOnly filter. The main remaining gap is that pagination and sorting behavior are left entirely to the schema.

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

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

Schema description coverage is 67%, so the schema documents several parameters already. The description adds meaning specifically for unansweredOnly by explaining its purpose, but it does not clarify sort defaults, rating filtering, territory codes, or limit behavior beyond the schema text.

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

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

The description gives a specific verb and resource: list an app's App Store customer reviews. It also names returned fields, so the agent can tell this is a review-listing tool rather than a generic app/build/resource lister. It does not explicitly contrast with sibling tools, which keeps it below 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?

The description states one useful usage condition: use unansweredOnly to find reviews that still need a reply. That is helpful but narrow; it does not say when to use this tool versus alternatives or describe 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 and openWorldHint, so the safety profile is covered. The description adds meaningful context beyond that: results carry Apple's processing state or errors, which tells the agent that returned media may not yet be live and that failures surface here. Pagination and volume/rate behavior are still unstated.

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, with the resource and returned fields front-loaded and the usage hint last. Every clause 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?

With 7 optional parameters and no output schema, the description does the needed work of enumerating the return shape so an agent can interpret results. It stops short of explaining the target/localizationIds relationship for custom product pages and experiment treatments, which is the one part of the input contract left implicit.

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 and every parameter is already self-documented. The description's 'per language and device size' framing reinforces the locales grouping but adds no syntax or precedence detail, e.g. it doesn't say how versionId, appId, and versionString interact when several are supplied.

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: screenshots and app preview videos of an App Store version, scoped per language and device size. It also previews the returned payload (file names in display order, sizes, processing state or errors), so an agent knows exactly what it gets back without opening anything else.

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 line 'Use it before and after uploading' gives a timing hint (verify state before/after a media upload), which is real guidance. However, it names no alternative tool or condition for choosing between targets such as version vs customProductPage vs experimentTreatment, so selection still has to be inferred from the schema enums.

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 openWorldHint=false, so the safety profile is covered. The description adds real value by disclosing the return content (each group plus its operation count) and that this is a no-parameter enumeration of the whole API surface, though it says nothing about result size, ordering, or caching.

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. The enumeration purpose is front-loaded, and the follow-up action is appended only after the primary purpose is established.

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 parameters and no output schema, the description must carry the return-value explanation itself, and it does ('resource group with its operation count', plus examples). Purpose, usage trigger, and follow-up path are all present, so nothing an agent needs in order to invoke it 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?

The tool takes zero parameters, so the baseline is 4 and there is no parameter semantics to add. The description correctly signals that the call is argument-free and that the tag it produces is consumed by asc_search_operations.

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 ('List every resource group (tag) in the App Store Connect API') and immediately clarifies the returned payload ('with its operation count'), with concrete examples (Apps, Builds, BetaGroups). It is clearly distinguishable from sibling tools like asc_search_operations, which it names.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit condition for use ('browse the API when you don't know what to search for') and routes the agent to the follow-up tool with the required argument ('then call asc_search_operations with a tag'). The inverse case (you already know the tag) is implied strongly enough that no alternative is left ambiguous.

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=true annotation already establishes this is a safe read, and the description adds the useful scope note that results are per-locale and lists the returned metadata fields. It says nothing about pagination, locale coverage limits, or the openWorldHint implication that data may change between calls.

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 compact sentences with no filler, and the field enumeration comes before the id-provenance hint so the agent gets the payoff first.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by naming the returned fields, so the agent knows the shape of the response. What remains unstated is pagination behavior and whether all locales are always present, which for an openWorldHint list tool would be worth one more sentence.

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 single parameter is fully documented in the schema at 100% coverage, so the schema baseline already applies. The description earns credit above baseline by explaining the provenance of versionId, which the schema only labels as 'appStoreVersion id'.

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?

A specific verb plus resource ('List the per-locale App Store metadata of a version') followed by an enumeration of the exact fields returned. The agent can distinguish this from siblings such as asc_app_overview, which the description explicitly positions as the source of version ids.

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 tells the agent where version ids come from ('Get version ids from asc_app_overview'), which is the key precondition for calling it. What is missing is any statement of when not to use it or which sibling covers adjacent needs, so it stays below a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, but the description adds the crucial context that explains this: the tool merely opens a browser page and the user performs any mutation, which is why a 'settings' tool is non-destructive. It also enumerates what the page exposes (API key, access mode, client setup), which goes 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?

Three sentences, front-loaded with the action, then the page contents, then the trigger conditions and the constraint. Each sentence carries distinct information with no repetition of the name or 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 zero-parameter, no-output-schema tool, the description covers what happens, why it is safe despite touching credentials, and when to invoke it. An agent has everything needed to decide to call it and to explain the outcome to the user.

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 has zero parameters, so the baseline is 4; there is no parameter semantics for the description to compensate for. Nothing in the text conflicts with the empty input contract.

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 — opening the local settings page in the user's browser — and immediately scopes it with what the page is for (API key, access mode, client registration). This clearly separates it from every sibling, which are all data-retrieval or operation-invocation tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names the triggering conditions: credentials missing or rejected, or the user wanting writes enabled. It also sets the boundary that only the user can change settings there, so the agent knows this is a hand-off, not a programmatic fix.

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 openWorldHint=false, so the safety profile is covered; the description adds the corpus size (1,300+) and, importantly, the return contract (operationIds) plus how they chain into describe/call. It omits pagination/result-cap behavior and deprecation handling, but nothing is contradicted and the added workflow context is genuinely useful.

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

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

Three sentences, front-loaded with what the tool does, then the return contract, then the sibling preference. Every sentence carries distinct information and there is no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description compensates by stating what is returned (operationIds) and the next-step tools, which is the key integration detail. Minor gaps remain around result limits and deprecated-operation behavior, which are left entirely to the schema.

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

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

Schema coverage is 80%, so the baseline is 3, and the description adds meaning by giving concrete query examples ('customer reviews', 'testflight testers', 'subscription prices', 'xcode cloud builds') that illustrate the keyword style the query parameter expects. It adds nothing for tag/method/includeDeprecated, which the schema already documents.

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+resource with scope ('Search all 1,300+ App Store Connect API operations') and distinguishes itself from curated siblings by positioning itself as the fallback for non-curated operations. It also names the downstream tools (asc_describe_operation, asc_call_operation), so an agent can place it in the workflow without reading 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 a clear usage rule: 'Prefer a curated asc_* tool when one fits the task,' which is an explicit when-not-to-use signal with a named alternative class. It doesn't spell out when to pick search over asc_list_resource_groups or when a keyword search is preferred over a direct describe, so it stops short of full routing guidance.

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