Apple Developer MCP by Nova (CIVAI)

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

With no annotations, the description carries the full burden, and it does disclose meaningful traits: the tool performs multiple state-changing operations, blocks while polling until build processing is VALID, and has a de facto default for encryption compliance. It omits what happens on timeout or a build that never reaches VALID, whether re-attaching overwrites a prior build, and what auth it needs — significant gaps for a mutating multi-step tool.

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

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

A single front-loaded sentence that leads with the trigger condition and then walks the steps in execution order, so the agent reads the workflow in the correct sequence. Every clause carries information; the only cost is that the run-on style makes it slightly dense.

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 five-parameter orchestration tool with no annotations and no output schema, the description covers the happy-path sequence adequately. It leaves out failure and timeout semantics, whether the call is safely retryable, what the response contains, and the role of notification_message — enough missing context that an agent could be surprised in production.

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 40%, so the description must compensate, and it partially does: it ties asc_app_id to listing builds, build_id to attachment, and glosses uses_non_exempt_encryption as 'usually false'. It says nothing about notification_message (the odd one out among the parameters) or about what app_store_version_id represents beyond the attach target. Partial compensation justifies a 3.

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 composite action and enumerates its steps: list builds for asc_app_id, wait for VALID processing, attach build_id to app_store_version_id, and set export compliance. That is concrete enough that an agent knows exactly what the tool accomplishes. It does not differentiate itself from siblings that perform the same sub-steps (set_version_build, set_export_compliance, wait_build_processed), which keeps it at a 4.

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 opening clause 'After Expo/CI has uploaded the .ipa to ASC' establishes the precondition for use, which is real guidance. However, it never says when an agent should pick this orchestration tool rather than calling the individual sibling tools, nor does it state exclusions or prerequisites such as an authenticated ASC session. Usage is implied rather than prescribed.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says what the tool does and when to use it; it does not mention permissions, side effects, idempotency, error handling, or what happens if the attachment fails. The single sequencing hint is not enough for a mutation tool.

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

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

The description is two sentences, front-loaded with purpose and followed by usage guidance. It is efficient, though the phantom parameter mention is a structural flaw that wastes some clarity.

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 annotations, no output schema, and a schema that contains only one unrelated optional parameter, the description is critically incomplete. It does not explain how to specify which item to attach or which submission to target, leaving the tool effectively unusable as described.

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 description references 'review_submission_id', but that parameter does not exist in the schema—only 'notification_message' is present. The description adds no meaning to the actual parameter and introduces a misleading identifier that could cause an agent to pass an unsupported argument.

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 (attach) and resource (app store version or build item) to an existing review submission. It names the key identifier (review_submission_id) and names a sibling (create_review_submission). However, the schema does not contain review_submission_id, which creates confusion about what exactly is being operated on.

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 explicitly says to use this after create_review_submission when building a submission manually, giving a clear context for use. It does not mention when not to use or list alternatives, but the conditional guidance is strong.

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 no annotations, the description carries the full behavioral burden and delivers almost nothing: 'Create' implies a mutation, but there is no mention of required permissions, what happens on duplicate bundle_id/SKU, whether the app is created in a live or editable state, or how failures surface. Only the external system (App Store Connect) hints at auth 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?

A single short phrase with no waste and the operation front-loaded, but it is under-specified rather than truly concise. Nothing in it is filler, yet nothing in it is informative either.

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 6-parameter, 3-required mutation tool with no annotations and no output schema, the description should cover prerequisites (existing bundle id, auth) and post-conditions. It covers none of these, leaving an agent unable to call it correctly without inspecting sibling tools.

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 17% — only notification_message is documented, and that documentation lives in the schema, not the description. The description adds zero meaning for bundle_id, app_name, sku, primary_locale, or version_string, so with 6 params and low coverage it fails to compensate.

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

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

States a specific verb and resource ('Create ... app') scoped to App Store Connect, which is enough to separate it from create_app_bundle and create_bundle_id. It stops short of explicitly naming those siblings as different, but the noun distinction is clear.

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 guidance on when to use this versus create_app_bundle/create_bundle_id, and no prerequisites stated. A caller is left to guess that a bundle_id must already exist and that an authenticated ASC session is required before calling.

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 no annotations, the description carries the burden, and it does add one genuinely useful behavioral fact: a 403 can occur when the tenant permits GET only, telling the agent this is a privileged write. It says nothing about reversibility, side effects on existing bundles, or what a successful creation yields.

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 caveat is parenthetically attached rather than buried. It is efficient, though the terseness contributes to the gaps elsewhere.

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 zero annotations, no output schema, and zero required parameters (unusual for a create), the description should explain what a bundle is, what happens when bundle_name or primary_app_id are omitted, and what comes back. It covers only the failure mode.

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 three parameters (bundle_name, primary_app_id, notification_message) are already documented in the schema. The description adds no additional semantics such as defaults or what happens when a parameter is omitted, 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 and resource ('Create ASC app bundle'), which clearly separates it from read-side siblings like list_app_bundles or get_app. It does not name any sibling explicitly, so it lands just short of a 5.

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

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

There is no statement of when to use this versus list_app_bundles or create_app, and no prerequisites are given. The only guidance is an implicit 'this may fail' caveat, which is not a usage rule.

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 no annotations, the description carries the full burden. It does well to flag that the .p8 is one-time, sensitive and should never be committed, but it omits required account permissions, whether key count is limited, and what happens if the download step is skipped or fails.

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 that front-load the action and then the security caveat. Nothing is padded, though the second sentence could be split so the credential warning stands 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 mutation tool with no annotations and no output schema, the description never says what is returned (key ID, issuer ID, scope) or that creation is persistent and must be revoked with revoke_asc_api_key. The credential warning is helpful but the picture is incomplete.

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%: download_p8 and notification_message are already described in-schema, and api_key_nickname (the required param) and api_key_role are not. The description only reinforces download_p8's one-time nature and adds nothing about nickname or role, so it barely exceeds the baseline.

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

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

States a specific verb and resource ("Create an App Store Connect API team key") that clearly separates it from list_asc_api_keys, download_asc_api_key and revoke_asc_api_key. It doesn't name those siblings explicitly, but the resource noun does the disambiguation work.

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?

Creation is implied by the verb, and the mention of downloading the key hints at the create-then-retrieve flow, but there is no explicit when-to-use guidance, no prerequisites (e.g. role/permission requirements), and no pointer to download_asc_api_key as the fallback.

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 no annotations, the description carries the full burden. It usefully discloses the auth/session requirement, which is real behavioral context, but says nothing about duplicate-ID behavior, idempotency, or what a successful registration returns.

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 the verb first and the prerequisite in parentheses. No filler, though the parenthetical could be expanded into a usable precondition statement.

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

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

For a mutation tool with no annotations, no output schema, and thin parameter coverage, the description leaves too much unstated: conflict handling, whether the operation is reversible, and what the caller gets back. The auth prerequisite alone is not enough.

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

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

Schema description coverage is only 40% across 5 parameters, so the description needs to compensate and does not — bundle_id, bundle_display_name, and bundle_platform are neither explained nor exemplified. Only developer_team_id and notification_message carry schema 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?

States a specific verb and resource: 'Register a new bundle ID on developer.apple.com'. This is clearly distinguishable from list_bundle_ids, get_bundle_id, and delete_bundle_id, though it does not explicitly distinguish itself from the sibling create_app_bundle.

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 one concrete precondition: a Developer Identifiers session obtained from start_browser_auth. It does not say when to prefer this over create_app_bundle, nor what to do if the bundle ID already exists.

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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that the submission is empty and enters READY_FOR_REVIEW, but it does not cover permissions/auth requirements, duplicate-submission behavior, side effects, or what happens to the notification_message during failure.

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, front-loaded with the core purpose and immediately followed by the key alternative. There is no redundant or wasted text.

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, one-optional-parameter tool with full schema coverage, the description is nearly complete for selection and invocation. It could still say how the target app is identified or what a successful creation returns, which matters for a mutation tool with no output 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 100%, so the single optional notification_message parameter is already documented in the schema. The description adds no further parameter semantics beyond context about the empty submission state, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: create a new, empty review submission. It adds the important state (READY_FOR_REVIEW) and purpose (so a version/build can be attached before submit), making it distinguishable from the submit-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?

It explicitly says when to use this tool versus press_submit_for_review: create empty first when attaching a build is needed, or submit current version in one step. The alternative and selection condition are both named directly.

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

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

With no annotations provided, the description carries the full disclosure burden. It does add valuable behavioral context by naming the required auth session, but for a destructive removal operation it says nothing about irreversibility, confirmation, cascading effects on associated builds/profiles, or failure behavior (despite a notification_message parameter hinting at follow-up failure handling).

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 sentence that front-loads the action and target before the parenthetical prerequisite. No filler or 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?

For a destructive tool with no annotations and no output schema, the description covers the action and auth prerequisite but leaves out consequences, reversibility, and what a successful call returns or changes. Adequate to start but not 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%, so all four parameters are already documented, including the fallback resolution via ascBundleIds when the record id is omitted. The description adds no parameter-level meaning beyond that, so baseline 3 applies.

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

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

The description uses a specific verb+resource ('Remove a bundle ID') and names the target system (developer.apple.com), which cleanly separates it from siblings like create_bundle_id, get_bundle_id, and list_bundle_ids without needing to open 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?

It states a concrete precondition — a Developer Identifiers session obtained from start_browser_auth — which tells the agent the calling context. It stops short of naming alternatives (e.g. when to delete vs. merely update a bundle ID) or exclusions, so it falls short of a 5.

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

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

No annotations are provided, so the description carries the full burden. It does disclose the destructive nature, the safety narrowing ('empty', 'zero items'), and the dry-run escape hatch, but says nothing about required auth/permissions, reversibility, or what happens to non-empty drafts when review_submission_id is supplied.

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, front-loaded with the destructive action and its constraint, then the dry-run tip, then the ordering hint. Nothing is wasted or redundant.

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 annotations and no output schema, the description covers the essentials for a destructive tool: what qualifies as an orphan, how to preview safely, and its place in the submit workflow. Minor gaps remain around permissions and what dry_run returns, but an agent can call it correctly.

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

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

Schema coverage is 75% and the schema itself documents dry_run, notification_message, and review_submission_id. The description restates the dry_run semantics and implicitly covers review_submission_id scope, but adds no meaning for the undocumented asc_app_id or for how notification_message interacts with dry_run.

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 (Delete) and a narrowly scoped resource (empty READY_FOR_REVIEW review submission drafts with zero items) for an app. An agent can distinguish this from sibling delete_* tools and from press_submit_for_review without opening the schema.

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

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

Explicitly instructs 'Use dry_run=true to list orphans only' and positions the tool as a precursor to press_submit_for_review ('Clears slots before...'). It gives clear context and sequencing but does not state when NOT to use it or name a direct alternative for orphan cleanup.

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?

No annotations exist, so the description carries the full burden: it does disclose that the operation is destructive, offers a dry-run preview, and names a prerequisite dependency, which is the most important context for a write tool. It is silent on whether deletion is irreversible, what happens to non-targeted display types, and whether partial failures are possible — meaningful gaps for an irreversible bulk delete.

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 doing distinct work: scope, safe-mode workflow, and dependency. Front-loaded with the destructive action and no filler.

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

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

With no output schema and no annotations, the agent gets the action, a dry-run escape hatch, and one dependency, which is enough to attempt a correct call. It still lacks return/listing shape, confirmation of irreversibility, and clarification of the localization_id requirement mismatch — all things the description is the only place to learn.

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%, and the description adds real value for two parameters: the dry_run preview behavior and the provenance of localization_id. However, it asserts localization_id is required while the schema's required list contains only screenshot_display_types, leaving an unresolved ambiguity about conditional requirement, and notification_message (schema-described) is not addressed.

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 ('delete screenshots') plus an explicit scope ('targeted iPhone display types, e.g. APP_IPHONE_61 only'), which makes clear it is a selective bulk delete rather than a single-item delete. It does not name or differentiate against the closest siblings (upload_screenshot, upload_screenshots, list_app_media_sets), but the operation itself is unambiguous.

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

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

Gives a concrete safety workflow ('Use dry_run=true to list without DELETE') and a prerequisite pointing at a sibling tool ('Requires localization_id from get_app_store_version'), which tells the agent where to source a required argument. It does not state when to prefer this over listing followed by a single delete, nor any exclusion conditions.

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 no annotations, the description carries the full disclosure burden, and it does surface one non-obvious consequence: omitting tester_emails leaves ASC showing 0 Testers and TestFlight empty. It also flags the "VALID build" prerequisite. But for a 17-parameter mutation it says nothing about beta review gating (skip_beta_review), whether external groups require review, or what side effects/notifications occur.

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

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

Two sentences, front-loaded with the core action and the pitfall second. Dense but readable, and no sentence is filler. The second sentence's phrasing ("or call invite_testflight_testers testing_scope=internal") is slightly compressed but still parseable.

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 17-parameter tool with no annotations and no output schema, the description is far too thin: build selection logic, beta review behavior, and the majority of beta_* parameters are undocumented anywhere. An agent could call it, but would likely misuse build_selection or skip_beta_review without trial and error.

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

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

Schema description coverage is only 12%, so the description must compensate and largely does not. It clarifies tester_emails (ASC team addresses) and the internal/external meaning of testing_scope, but leaves build_id vs build_number vs build_selection=latest, beta_group_name, skip_beta_review, and the six beta_* metadata fields entirely unexplained.

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

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

States a specific verb and resource ("Add a VALID build to TestFlight internal or external beta group") and immediately distinguishes the internal vs external paths. It names the sibling invite_testflight_testers, so an agent can route between them, though it never clarifies how this relates to submit_testflight_beta_review or set_version_build.

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 an explicit conditional: for internal distribution, either pass tester_emails or call invite_testflight_testers with testing_scope=internal. That is real when-to-use guidance tied to a named alternative. It stops short of saying when external distribution is appropriate or whether beta review must precede 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?

With no annotations, the description carries the full disclosure burden, and it does surface the critical trait that the key is one-time/irreversible and gated on canDownload. It omits authentication/team-role requirements, whether a re-download is possible after this call, and how the payload is delivered (file, base64, path).

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

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

A single front-loaded sentence with no filler; the precondition is placed where an agent will read it 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?

There is no output schema and no annotations, so the description is the only source of behavior, yet it never explains what the call returns (the raw .p8 content, a file location, or a reference) or what the agent should do if canDownload is already false. For a download/secret-exfiltration tool this is a real 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 50%: notification_message is documented in the schema, and api_key_id has no description. The phrase 'for an existing API key' only loosely gestures at api_key_id and does not say how to obtain a valid id or what format it takes, so the description adds little 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 names a specific verb ('Download') and a specific artifact (the one-time .p8 private key for an existing API key), which is unambiguous and distinct from siblings like create_asc_api_key or list_asc_api_keys. It does not explicitly contrast itself with those siblings, keeping it just short of a 5.

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

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

It gives a clear precondition — 'when canDownload is still true' — which implies when to call and when the call will fail. However, it names no alternatives (e.g. create_asc_api_key to mint a new key, list_asc_api_keys to find the id) and gives no guidance on what to do if canDownload is false.

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?

No annotations are provided, so the description carries the full burden, and it discloses almost nothing: no read-only confirmation, no auth requirements, no indication of what is returned or whether it mutates state. The one useful behavioral note is that contracts are human-signed, implying a manual step cannot be automated, but that is a fragment rather than a coherent disclosure.

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 is a single short sentence with no wasted clauses, so it is concise. However, it is cryptic jargon-heavy phrasing rather than a front-loaded statement of purpose, so brevity comes at the cost of comprehension.

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 annotations, no output schema, and an undocumented required-context parameter, the description would need to explain the return shape and the parameters. Instead it offers a terse phrase that leaves an agent unsure what it will receive or how to call it correctly.

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

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

Schema coverage is only 50%: notification_message is documented in the schema, but asc_app_id is undocumented anywhere. The description adds no parameter meaning at all, so the coverage gap is not compensated for.

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 hints at content (business portal links for Agreements/Tax/Banking, price schedule hints) but never states a verb or explicitly says it retrieves account compliance status, which the name implies. It gives an agent a rough idea of the payload but no clear statement of what the tool does, and it does not differentiate itself from siblings like get_pre_submit_status or get_review_path.

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 guidance on when to call this versus alternatives such as get_pre_submit_status or set_export_compliance. The parenthetical '(contracts are human-signed)' is a situational hint but not an explicit when-to-use or when-not-to-use rule.

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 no annotations, the description carries the full burden. It implies a read-only lookup by using 'Get' and lists the returned fields, which is helpful, but it says nothing about authentication, error behavior when the id doesn't exist, or scoping.

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, front-loaded with the action and a concrete field list, with zero filler. Nothing wasteful, though the second sentence could carry more distinguishing detail for the same length.

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

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

For a simple single-object read with no output schema, the description covers what the tool returns at a field level. But the missing asc_app_id contract leaves an agent unable to reconcile the description with the actual input schema, which is a material completeness 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?

The description tells the agent to call it 'by asc_app_id', but the schema contains no asc_app_id property — the only parameter is notification_message, which the description never mentions. This misdirects the agent about what to supply, even though schema coverage is otherwise 100%.

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 ('Get one app's details') and enumerates the fields returned (name, bundle id, SKU), which distinguishes it from list_apps and get_bundle_id. It never names a sibling explicitly, so differentiation is implied rather than stated.

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 use case — confirm the right app before mutating it, which implicitly separates it from list_apps (browse) and update_app (mutate). No explicit when-not or alternative-naming, so it falls short of a 5.

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

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

No annotations are provided, so the description carries the full disclosure burden. "GET" weakly implies a read, but nothing is said about authentication requirements (the sibling set includes login/session_status and ASC API key tools), pagination, or whether an empty result is possible.

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 single line is front-loaded and free of filler, but its brevity comes at the cost of under-specification rather than genuine economy. There is no wasted word, but there is also almost no content.

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 annotations, no output schema, and an undocumented primary parameter, the description should explain what is returned (version list, versions with state/build info) and any auth context. For a tool in a large ASC workflow set, this is a significant omission.

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

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

Schema coverage is only 50%: notification_message is documented in the schema, but asc_app_id is a bare string with no format, source, or expected value guidance. The description merely restates asc_app_id without adding any semantic detail, so it fails to compensate for the coverage gap.

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?

"GET iOS appStoreVersions for asc_app_id" names a resource and a scope, but the plural "appStoreVersions" conflicts with the singular tool name, leaving ambiguous whether it returns one version or a list. It is also not differentiated from nearby read tools such as get_app, get_build, or get_review_submission.

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 guidance on when to call this versus get_app, get_pre_submit_status, or the list_* tools, and no stated prerequisites. The agent must infer the entire usage context from the name alone.

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 no annotations provided, the description carries the full disclosure burden. It does state the return content (processing state and metadata) and that it is a single-item lookup, but it says nothing about error behavior for unprocessed/invalid builds, what states are possible, or side effects.

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 with the purpose front-loaded and the usage rule second; nothing is padded. The only inefficiency is the misleading "by build_id" clause, which spends words on a parameter that does not exist.

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 tool with no output schema, the description covers intent and return subject adequately. But the unresolved build_id reference leaves the agent without a known way to identify which build to fetch, which is the one thing this tool absolutely requires.

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 description says the lookup is "by build_id," but the schema contains no build_id property at all — only notification_message, which the description never mentions. Schema coverage is 100%, so the baseline would be 3, but the description actively points at a nonexistent parameter, which could lead an agent to construct a malformed call.

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

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

"Get one build's processing state and metadata by build_id" names a specific verb (get), resource (one build) and the attributes returned (processing state, metadata), which cleanly separates it from list_builds. It does not distinguish itself from wait_build_processed, which appears to serve a very similar purpose.

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

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

"Use before attach_build_and_compliance to confirm the build finished processing" gives an explicit sequencing rule with a named sibling, which is genuinely actionable. It omits when to prefer wait_build_processed or list_builds instead, so the alternative-selection guidance is incomplete.

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?

No annotations are supplied, so the description carries the full burden. 'Get details for one existing bundle ID' reasonably implies a non-mutating read, and it hints at the payload ('platform and capabilities'), but it says nothing about auth requirements, error behavior, or what happens when the id is unknown.

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 identity and scope come first, followed by the workflow guidance, so the important routing information 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 simple read with no output schema, an agent still needs to know what 'details' includes beyond platform and capabilities, and how to supply the identifier. The description is directionally sufficient but leaves the return shape and the lookup input underspecified.

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

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

Schema coverage is 100%, so the baseline would be 3, but the only schema property is a generic notification_message unrelated to the operation, while the description claims lookup 'by its ASC resource id' — a parameter the schema does not expose. That mismatch actively misleads an agent about what it must supply.

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 ('Get details for one existing bundle ID') and pins the lookup key to an ASC resource id, which separates it from list_bundle_ids and create_bundle_id. It does not explicitly contrast with other single-resource getters, but the scope is unambiguous.

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

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

Gives a concrete workflow position: call after list_bundle_ids, and before create_app, to confirm platform and capabilities. That is actionable sequencing rather than a generic 'use when needed', though it names no exclusions or failure conditions.

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 no annotations, the description carries the burden and does: it explicitly declares 'Read-only' and lists the checks it evaluates. It doesn't describe the shape of the returned status values, but the read-only nature and checklist scope are well disclosed.

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, front-loaded with the read-only/checklist framing and the when-to-use cue. 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?

For a read-only diagnostic with no output schema, the description communicates scope and the notable orphan_review_submission_ids field. Minor gap: it doesn't clarify what the status values mean or how an agent should act on them, but the essential call context is present.

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

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

Schema coverage is 50%: notification_message is documented in-schema, but asc_app_id is undocumented in both schema and description. The description adds no parameter meaning, so it neither compensates nor overrides; baseline 3 fits the partial coverage.

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 resource (a pre-submit checklist) and enumerates the checks covered (build, privacy, category, copyright), plus the orphan_review_submission_ids detail. It's distinguishable from the submit siblings like press_submit_for_review, though it doesn't explicitly name 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?

The phrase 'before Submit for Review' clearly anchors when to use this tool relative to the submission siblings. It doesn't name an explicit alternative or exclusion, but the timing context is unambiguous.

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?

No annotations are provided, so the description carries the burden. It discloses the key behavioral trait that this is a fallback for data the API doesn't surface and that the output is a browser-openable URL, but it says nothing about auth requirements or what happens on failure.

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, zero waste, with the scope and the sibling reference front-loaded before the usage guidance. Nothing could be cut without losing routing 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 single-optional-parameter read tool with full schema coverage and no output schema, the description is nearly complete: it explains what is returned (two URL types) and the fallback scenario. A note on what the tool returns when no thread exists would close the remaining gap.

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

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

Only one optional parameter, and schema description coverage is 100%, so the schema already documents notification_message fully. The description adds no meaning beyond it — notably it never explains that the parameter is a reply-failure fallback message, which is non-obvious from the tool itself.

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

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

Names a specific verb and resource (get the Resolution Center and App Review URLs) and immediately scopes it to messages Apple has not exposed via list_review_messages, which distinguishes it from the closest sibling. An agent can distinguish it from list_review_messages without opening either schema.

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

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

Explicitly states the trigger: 'Use when an operator needs to open the review thread directly in a browser,' and the clause about messages not exposed via list_review_messages functions as an implicit exclusion routing the agent to the sibling first. No further exclusions or prerequisites are given, but the situation is 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?

With no annotations, the description carries the full burden. It does disclose that this is a read returning status plus attached items, which is useful. However, it says nothing about behavior when the submission is missing, whether results are cached or eventually consistent, or what the follow-up/notification_message fallback implied by the schema actually means.

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 with the core action front-loaded and the usage hint second. No filler. The information is efficiently delivered, though one of the few facts given is wrong.

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 with no output schema and no annotations, the agent needs to know roughly what comes back and how to supply the key. 'Status and attached items' covers the return shape at a high level, but the parameter discrepancy and the absence of any error/empty-state guidance leave real gaps.

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

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

Schema coverage is 100%, so the single parameter's meaning is documented structurally. But the description references a 'review_submission_id' argument that is absent from the schema, while the only actual parameter (notification_message) goes unmentioned. That mismatch is actively misleading for callers trying to map intent to arguments.

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 concrete verb ('Get') and resource ('status and attached items of one review submission'), which is specific enough to distinguish it from sibling mutators like create_review_submission or attach_review_item. The identifier it references ('review_submission_id') does not exist in the schema, which introduces mild confusion but does not obscure the overall purpose.

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 explicitly ties usage to a lifecycle moment: 'Use to check progress after create_review_submission.' That gives the agent a clear triggering context. It stops short of naming alternatives (e.g. get_pre_submit_status) or stating 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?

With no annotations, the description carries the full burden and does well: it discloses that it mutates state (creates/reuses a group, attaches a build, enables a link), the auth requirement, and the external Beta App Review gate that can delay link usability. It stops short of saying whether repeated calls are idempotent, what partial failures leave behind, or what the response looks like beyond the URL.

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

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

One dense, front-loaded sentence that leads with the workflow and ends with the auth and review prerequisites. No filler, though packing four distinct behaviors plus two caveats into one sentence slightly reduces scannability.

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

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

For a 16-parameter mutating workflow with no annotations and no output schema, the description covers the what/what's-required/how-it-can-fail well, but omits the parameter semantics that are the largest risk area here. Adequate on behavior, incomplete on inputs.

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

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

Schema description coverage is only 6% across 16 parameters, so the description must compensate and does not. It never explains build_id vs build_number vs build_selection, the beta_* metadata fields, skip_beta_review (an enum), or the beta_group_name default, leaving most inputs undocumented in both places.

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 spells out the actual multi-step operation (create/reuse an external group, attach a processed build, enable the public link, return the join URL), which corrects the 'get_' name that would otherwise imply a read. It is distinguishable from siblings like invite_testflight_testers or distribute_build_to_testflight by the public-join-link outcome, 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?

It states a prerequisite ('Requires asc_session_cookie (session_status OK)') and a caveat ('First external build may need Beta App Review'), which imply when the call will work. But it gives no guidance on when to choose this over distribute_build_to_testflight or invite_testflight_testers, and no when-not-to-use conditions.

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 no annotations, the description carries the burden and does disclose meaningful behavior: the invite is an email, it expires in 3 days, and it creates/grants team membership. It stops short of stating required privilege level (admin/account holder), what happens on a duplicate invite for an existing member, or whether an invite can be revoked, which matter for a mutation of this kind.

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 earning its place: capability, precondition, and exclusion. The purpose and the sibling exclusion are front-loaded with 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?

For an 8-parameter, 4-required mutation with no annotations, no output schema, and low schema coverage, the description is adequate on intent but thin on mechanics. An agent still cannot tell from the definition what confirm_invite_team_member or limit_visible_apps/visible_app_ids do or that role assignment affects scope.

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

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

Schema description coverage is only 25% across 8 parameters, so the description must compensate and it does not: it never mentions confirm_invite_team_member (the required confirmation gate), visible_app_ids, limit_visible_apps, or the name/email fields. Only asc_roles is partially self-documented in the schema, leaving the majority of parameters with no semantic guidance anywhere.

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 ('Invite a user to your App Store Connect team') with the delivery mechanism and timing ('email invitation, 3-day expiry'). It explicitly distinguishes itself from the nearest sibling, invite_testflight_testers, so an agent can choose without opening either schema.

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

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

Gives an explicit when-to-use condition ('Required for internal TestFlight when they are not already a team user') and an explicit when-not ('Does not replace invite_testflight_testers (external beta emails)'). The two siblings that could be confused are separated by named intent.

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?

No annotations are provided, so the description carries the full burden. It usefully discloses the internal-vs-external prerequisite ('required before TestFlight app shows the build'), but says nothing about idempotency for already-invited emails, partial-failure behavior across a comma-separated list, permissions, or whether invites are emailed immediately.

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

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

Front-loaded with the action, followed by the scope semantics in two compact clauses. Slightly compressed phrasing ('ASC team emails for Internal Testing group') but no wasted sentences.

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 6-parameter mutation with no annotations and no output schema, the description covers scope selection but leaves the agent guessing about identifier parameters, precedence rules, and what a successful call returns or does on partial failure.

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 description adds real meaning for testing_scope (the enum's two values and their semantics) beyond the bare enum list. However, asc_app_id and beta_group_id remain undocumented in both schema and description, and the precedence between beta_group_id and beta_group_name is unstated.

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

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

States a specific verb and resource — 'Add testers to a TestFlight beta group by email' — which is immediately distinguishable from the sibling invite_asc_team_member (App Store Connect team vs. TestFlight beta group). The scope qualifiers further narrow what kind of invite this is.

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 separates the two modes: testing_scope=internal for ASC team emails in the Internal Testing group, testing_scope=external for external group invites, and notes internal is required before the build shows in TestFlight. It does not, however, point to alternatives such as invite_asc_team_member for non-TestFlight team access.

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?

No annotations are provided, so the description carries the full behavioral burden. The 'GET /appBundles' fragment does imply a read-only fetch, but nothing is said about pagination, result volume, authentication requirements, or whether the list is scoped to the current session/app.

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 endpoint reference is compact and useful. It is arguably over-terse for the ambiguity it leaves, 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 simple parameterless list tool with no output schema, the description covers what it fetches but not what comes back, how results are ordered or paged, or how it differs from neighboring list tools. Minimum viable rather than complete.

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

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

There is only one optional parameter and schema description coverage is 100%, so the schema already fully documents notification_message. The description adds nothing about it, but per the high-coverage baseline a 3 is appropriate.

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

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

States a clear verb ('List') and a specific resource ('ASC app bundles'), plus the underlying endpoint (iris GET /appBundles), so an agent knows exactly what is fetched. However, it does nothing to distinguish this from the confusingly similar siblings list_bundle_ids, list_apps, and create_app_bundle; the boundary between an 'app bundle' and a 'bundle ID' is left to inference.

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 prerequisites, and no mention of any alternative. An agent must guess whether to call this or list_bundle_ids / list_apps to answer a bundle-related question.

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 no annotations, the description carries the burden and does disclose that the tool is read-only, which is valuable. However, it doesn't cover auth requirements, rate limits, or what the response looks like beyond implying display sizes, leaving meaningful behavioral gaps.

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, with the read-only nature and resource scope front-loaded before the usage hint. No wasted text.

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 no-annotation, no-output-schema read tool, the description implies the useful return content (which display sizes have assets) and the read-only safety profile. Minor gaps remain around response structure and the purpose of the notification_message parameter, but the core is covered.

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% for the single optional parameter (notification_message), so the schema already documents it fully. The description adds nothing about parameters, which is acceptable at high coverage but not above baseline.

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

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

States a specific verb (List) and resource (screenshot and app preview sets for an app store version localization), enough that an agent can distinguish it from siblings like upload_screenshot or get_app_store_version without consulting 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?

Explicitly instructs 'Use before upload_screenshot to see which display sizes already have assets,' naming the sibling and the triggering condition. It stops short of stating when-not-to-use or naming other alternatives, but the usage context is 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?

No annotations are provided, so the description carries the full burden; it does disclose that results are session/credential-scoped ('visible to the current App Store Connect session'), which is useful auth context. It says nothing about pagination, result ordering, or what happens when the session has no apps, which are meaningful gaps for a listing tool with zero annotation coverage.

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, zero waste, with the identifying purpose stated first and the routing guidance second. Every sentence 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 no-required-param list tool with no output schema, the description supplies the one fact an agent needs downstream — that this is the source of asc_app_id. Slightly incomplete in that it never indicates whether results are paginated or how many apps to expect.

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 a single optional parameter, so the schema already documents notification_message. The description adds no further parameter meaning; baseline 3 applies when structured fields do the work.

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

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

States a specific verb and resource ('List apps') plus a scope qualifier ('visible to the current App Store Connect session') that separates it from the per-app sibling get_app. An agent can pick this tool without opening either schema.

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

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

Explicitly says when to use it ('to find an existing asc_app_id before create_app or any per-app tool'), naming both the downstream alternatives and the condition that selects this tool. Nothing is left to inference.

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

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

No annotations exist, so the description carries the full burden. It usefully discloses an output boundary (no private key material, keys plus issuer id), but says nothing about auth/team-membership prerequisites, whether the list can be empty, or pagination. That is a real gap for a read tool with zero annotation coverage.

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, the core purpose front-loaded, and the negative scope ('does not return private keys') placed immediately after. Nothing is redundant or padded.

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 tool is simple (one optional param, no nested objects, no output schema), and the description covers what comes back at a high level (keys + team issuer id), which is exactly what an agent needs without an output schema. Only the return item structure and auth prerequisites are left unspecified.

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 sole parameter (notification_message) is already fully documented in the schema. The description adds no additional meaning about that parameter, but the baseline of 3 applies when the schema does the work.

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

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

States a specific verb and resource (list ASC API team keys) plus the extra output (team issuer id), and the clause 'Does not return private keys' implicitly separates it from download_asc_api_key. It stops short of naming a sibling explicitly, so differentiation is inferable rather than stated.

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 parenthetical '(for EAS / CI)' hints at the intended scenario, but there is no explicit when-to-use, when-not-to-use, or named alternative (e.g. create_asc_api_key / revoke_asc_api_key / download_asc_api_key). Usage is only implied by the scenario tag.

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 no annotations, the description carries the whole burden. It usefully discloses that pending invitations are included and that the response is trimmed to identifiers and roles, which helps the agent interpret results. It omits permissions requirements, whether results are paginated or truncated, and whether inactive members are excluded beyond the word 'active'.

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 resource and return projection are front-loaded, and the usage trigger follows immediately. 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?

For a no-parameter, read-only listing with no output schema, the description supplies what is needed: scope, what is returned, and a concrete use case. Nothing essential to calling it correctly is missing.

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

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

Only one parameter exists and schema coverage is 100%, so the schema already documents notification_message. The description adds nothing about it — notably it never explains why a read-only listing has a fallback-message parameter. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('List active App Store Connect team members and pending email invitations') plus the exact projection returned ('identifier (email/username) and roles'). This clearly separates it from sibling tools like invite_asc_team_member or invite_testflight_testers.

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

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

Explicitly says when to call it: 'Use before internal TestFlight distribution to confirm someone is on the team and has a TestFlight-eligible role.' It gives clear context but doesn't name alternatives or say when not to use it (e.g. vs. list_asc_api_keys or session_status).

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?

No annotations are provided, so the description carries the burden; it does disclose result ordering ('newest first'), which is genuine behavioral information. It says nothing about pagination, result limits, or behavior when asc_app_id is omitted (it's optional but the description implies it's the filter).

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, front-loaded with the action and resource, and the operational hint follows immediately. No wasted clauses, though the terseness leaves gaps rather than being optimally sized.

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

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

For a simple two-parameter list tool with no output schema, the description gives action, scope, ordering, and a usage trigger. The main omission is what a build entry contains (build numbers vs. IDs), which matters given the 'build number' reference.

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%: notification_message is documented in-schema, while asc_app_id has no schema description but is referenced in the tool description as the app filter. That partially compensates, though the description never explains what happens when asc_app_id is left empty.

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?

Clear verb+resource ('List ASC builds') scoped to asc_app_id, plus an ordering guarantee ('newest first'). It distinguishes itself from the single-build sibling get_build, though it doesn't explicitly name it.

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 a concrete trigger: use before attaching when the operator names a build number, which points the agent toward attach_build_and_compliance as the downstream step. It lacks explicit when-not conditions, but the usage context is 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?

No annotations are provided, so the description carries the full burden, and it does convey that results are team-scoped and come from the Apple developer portal. It says nothing about authentication/login prerequisites, pagination, or the shape of the result set, which matters for a zero-annotation tool.

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

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

Two short sentences, zero filler, with the scope statement front-loaded and the routing advice second. Every sentence 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 simple read-only list operation with no output schema, the description covers what is listed and why, but leaves out prerequisites (login/team membership) and any indication of result volume or filtering. Adequate but with clear gaps for a zero-annotation tool.

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

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

Single optional parameter with 100% schema description coverage, so the schema already explains notification_message fully. The description adds no parameter meaning, but per the coverage rule 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+resource ('List bundle IDs registered on developer.apple.com for the current team') with scope explicitly tied to the current team. The sibling set contains create_bundle_id, get_bundle_id and delete_bundle_id, and the description makes the list-vs-create-vs-get distinction obvious.

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

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

Explicitly states the workflow context: use it to find an existing bundle_id before calling create_bundle_id or get_bundle_id, which is a genuine when-to-use signal. It does not, however, say when NOT to use it (e.g. when the identifier is already known, or how list_app_bundles differs).

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 no annotations, the description carries the full burden. It does add one genuinely useful behavioral fact — threads stay empty until Apple opens a rejection/message thread — which saves an agent from misreading empty results. It does not state that this is a read-only operation, nor any auth or rate-limit context.

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 no filler, and the resource scope is front-loaded ahead of the caveat. Slightly telegraphic — no explicit verb such as 'Lists' — but nothing 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?

No output schema and no annotations mean the description must fully explain behavior, and it only covers empty-thread semantics. The return shape of a 'thread' and the role of the two optional parameters are left unexplained, which is a meaningful gap for a 3-parameter tool.

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

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

Only asc_app_id is given meaning (the scoping key); schema coverage is 33% and both resolution_center_thread_id and notification_message are undocumented in the description. The notification_message parameter is especially opaque for a list operation — an agent cannot infer why a listing tool takes a 'follow-up reply failure' message.

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

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

Names the specific resource (Resolution Center threads and App Review messages) and scopes it to asc_app_id, so an agent knows it reads review-related message threads. It does not explicitly distinguish itself from siblings like get_review_path or get_review_submission, but the resource is distinctive enough to be unambiguous.

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

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

There is no statement of when to call this versus get_review_submission, get_review_path, or attach_review_item, and no prerequisites or exclusions. The note about empty threads hints at timing but is a data caveat, not usage 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?

With no annotations, the description carries the full burden; it does disclose the human-in-the-loop prerequisite (a browser MSA flow must have finished), which is genuinely useful context. It does not say whether the call is read-only, whether it depends on cookies/browser state from that session, what happens when the operator has not finished, or whether it waits/polls.

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 sentence, front-loaded with the precondition and then the action — no waste. The trailing '(checkPermissions)' is internal jargon that adds little for an agent but is not harmful.

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 tool has a trivial schema and no output schema, so the description should say what a successful verification yields (session valid/invalid, what the agent should do on failure). It states the trigger condition but leaves the outcome side unspecified.

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 has 100% schema description coverage, so the schema already explains 'notification_message' fully; the description adds nothing about it, which matches the baseline 3 for high coverage.

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 Developer portal session') plus the mechanism used ('checkPermissions'), which is far better than the bare name 'login' that implies credential submission. It does not differentiate from the sibling 'session_status', which an agent could easily confuse with this 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?

'After operator completes Apple IDMSA in a browser' gives a clear ordering precondition that routes the agent to call this only after browser-based auth. There is no explicit exclusion or named alternative (e.g. 'use session_status for a pure read'), so it stops short of a 5.

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

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

No annotations are provided, so the description carries the full burden. It discloses that it performs a PATCH mutation to submitted=true, but says nothing about irreversibility, what Apple-side consequences follow, required permissions, or error behavior if the follow-up reply fails — all material for an irreversible submit action.

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

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

Two short sentences with no filler, and the precondition leads. But the telegraphic phrasing ('Build already on version: ... PATCH submitted=true') is closer to internal shorthand than a front-loaded explanation an agent can parse cleanly.

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 annotations, no output schema, four parameters at 25% coverage, and a dense set of near-duplicate siblings, the description does far too little. It never establishes the boundary between this tool and submit_for_review / submit_build_for_review, which is the agent's main decision.

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

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

Schema description coverage is only 25%; only notification_message is documented. The description adds the confirm gate meaning but never explains asc_app_id versus app_store_version_id, nor how notification_message relates to the failure path. It does not compensate for the coverage gap.

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 verb+resource is present ('create review submission and PATCH submitted=true'), so the mechanical action is discernible. However, in a sibling cluster containing submit_for_review, submit_build_for_review, and submit_build_and_press_submit, the description gives no basis for telling press_submit_for_review apart from those tools; only the cryptic 'Build already on version' prefix hints at a lower-level step.

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

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

'Build already on version' states a precondition, and 'Requires confirm_submit_for_review=true' flags a guard. But there is no guidance on when to pick this versus the several sibling submit tools, and no statement of 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It identifies the operation as a PATCH of promotional text but says nothing about permissions, reversibility, side effects, error behavior, or response 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?

The description is one front-loaded sentence with no filler. It immediately communicates the operation and the key prerequisite.

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

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

For a mutation tool with no annotations, no output schema, and low parameter documentation coverage, the description is too sparse. It omits important context about effect, permissions, return behavior, and how this tool relates to the nearly identical sibling update_version_localization.

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

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

Schema description coverage is only 33%, but the description does little to compensate. It mentions localization_id and promotional_text by name, yet does not explain their semantics, and it says asc_app_id is required even though that is not a parameter in this 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 and resource: PATCH an app store version localization's promotional text. It is clear what is being changed, but it does not explain how this differs from the sibling update_version_localization tool or what the 'probe' prefix implies.

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 prerequisite condition (asc_app_id / localization_id on tenant), which is useful context for when the tool can be called. However, it provides no guidance on when to use this tool versus update_version_localization or other version-localization tools.

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 no annotations, the description carries the full behavioral burden. It does disclose the most important trait — the revocation is permanent and cannot be undone — but says nothing about permission requirements, whether it requires confirmation upstream, or what happens to integrations using the key. Useful but incomplete for a destructive 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?

One tight sentence with the destructive nature front-loaded and zero filler. Nothing could be cut 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?

For a destructive, unannotated mutation with no output schema, the description covers irreversibility but leaves out permission/auth requirements and the source of api_key_id. It is minimally sufficient to avoid a mistaken call but not 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 coverage is 67%, and the undocumented parameter is api_key_id, which is the critical one — the description never says where that id comes from (e.g. list_asc_api_keys) or what format it takes. The notification_message and confirm_revoke_api_key semantics come entirely from the schema, not 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 (revoke) and resource (App Store Connect API team key), and flags the operation as permanent. An agent can distinguish it from create_asc_api_key, list_asc_api_keys, and download_asc_api_key by the verb alone, though no sibling is named 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 description offers no guidance on when to use this tool versus alternatives — notably it doesn't tell the agent to first enumerate keys with list_asc_api_keys to obtain the id. The only usage-relevant signal is the irreversibility warning, which is a caution rather than a routing rule.

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?

No annotations are provided, so the description carries the full behavioral burden. "check" weakly implies a read-only probe, but the description never states side effects, whether it may trigger a browser auth flow, what failure modes exist, or what the response contains.

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?

Short but under-specified rather than efficient — three words that convey almost no actionable information. Brevity here costs the agent the context it needs and there is no front-loaded statement of purpose to build on.

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 annotations, no output schema, and a description that says nothing about the return value or the state being checked. For a status-check tool, the outcome shape (valid/expired/unauthenticated) is the single most important thing and it is absent.

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

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

With a single parameter at 100% schema coverage, the schema fully documents notification_message, so the description is not required to compensate. The description adds nothing about when the follow-up reply fallback applies, so baseline 3 is appropriate.

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

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

"ASC session check" essentially restates the tool name and title; it does add the expansion of ASC to App Store Connect, but never says what the check verifies (token validity, expiry, authenticated user) or what a caller learns from it. It does not distinguish itself from login or start_browser_auth, which also concern session/auth state.

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 at all. Given siblings like login, start_browser_auth, and probe_update_version_localization, an agent has to guess whether this is a pre-flight validation step, a re-authentication trigger, or a health check.

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 no annotations, the description carries the burden; it discloses the ordering constraint before submit and implies overwrite-on-repeat ('when content descriptors change'), which is useful. It does not state whether a call replaces or merges existing answers, what permissions/account state are needed, or what happens if the questionnaire is left incomplete.

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, front-loaded with the action and followed by usage timing; nothing is wasted. The trailing clause 'required before submit' is slightly awkwardly attached, but it still reads clearly.

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-optional-param, no-annotation, no-output-schema tool, the description covers purpose and timing but omits how questionnaire answers are conveyed and whether repeat calls overwrite prior answers. Adequate to select the tool, thin for invoking it confidently.

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% for the single optional notification_message parameter, so the schema does the heavy lifting and baseline 3 applies. The description adds no parameter meaning, and notably never connects the 'answers/content descriptors' it claims to set to any input, leaving the input-to-action mapping opaque.

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 ('Set the app's age rating questionnaire answers') and clarifies that the subject is content descriptors, which separates it from metadata/privacy siblings like set_app_privacy and set_app_store_metadata. It stops short of explaining how the answers are actually supplied, which is the main ambiguity.

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

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

Gives explicit timing: 'Use once per app, or when content descriptors change,' and flags the prerequisite ('required before submit'), which routes the agent correctly relative to submit_for_review. No alternative tool is named, so it is not a full when/when-not statement.

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 no annotations, the description carries the full burden, and it does disclose the underlying data it writes (iris appDataUsages) and the preset-vs-inline-JSON branching. It says nothing about whether an existing declaration set is overwritten, how publish_app_privacy affects publication, or what permissions/auth are needed — all material for an unpublishable mutation. Partial disclosure, but well short of what a zero-annotation mutation tool 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?

Three sentences, front-loaded with the resource and action, then the preset-vs-custom decision, then a pointer to docs. Little waste; the only soft spot is deferring preset definitions to SKILLS.md rather than summarizing them in a clause.

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 five-parameter, zero-annotation mutation with no output schema, the description is thin: it omits the behavior of three parameters and outsources the actual preset definitions to an external SKILLS.md section the agent may not have in context. It is enough to attempt a call with a preset, but not enough to call it correctly in custom or publish scenarios.

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 40%, so the description should compensate, but it only discusses app_privacy_profile and app_privacy_declarations_json (the latter already fully documented in the schema) and leaves publish_app_privacy, replace_app_privacy, and notification_message untouched. Worse, it names preset values 'contact' and 'analytics' that do not exist in the enum ('collects_contact', 'collects_analytics'), which can produce an invalid call.

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

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

The description states a specific verb and resource — setting App Privacy data-collection declarations via the iris appDataUsages field — which is unmistakable and clearly distinct from siblings like set_age_rating or set_export_compliance. It does not explicitly name a sibling to contrast against, but the resource is unique enough that an agent can route to it without ambiguity.

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 real conditional guidance: use a preset when it fits, use custom 'when the presets don't match what the app actually collects.' However, that guidance only covers which parameter value to pick, not when to call this tool at all, what prerequisites exist (login, existing app), or when not to call it. The cited values 'contact or analytics' also don't match the schema enum ('collects_contact', 'collects_analytics'), which undermines the guidance as written.

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?

No annotations are provided, so the description carries the full behavioral burden. It does not state that this is a mutating write, whether existing values are overwritten or merged, what permissions or app context are required, or how an app/version is identified (no app_id in the params).

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. It is efficient, though its brevity reflects under-specification rather than tight scoping.

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 unannotated mutation tool with four parameters (three undocumented) and no output schema, the description leaves too much unstated — including which resource is targeted and what happens on success or failure. It is not sufficient for correct invocation on its own.

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 25%: copyright, primary_category, and content_rights_declaration have no schema descriptions, and the tool description merely repeats their names without adding accepted values, formats, or examples. The one well-documented parameter (notification_message) is not mentioned in the description at all.

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 ('Set') and names the three App Store metadata fields it modifies: primary category, version copyright, and third-party content rights declaration. That distinguishes it from siblings like set_age_rating or set_pricing_and_availability, though it doesn't explicitly say so.

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 guidance on when to use this tool versus the many other set_* tools (set_age_rating, set_app_privacy, set_export_compliance) or on prerequisites such as an existing app/version context. An agent must infer that this is for metadata-only updates.

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?

No annotations are provided, so the description carries the full behavioral burden. 'PATCH' implies a mutation, but the description does not say what the flag change affects, whether it requires authentication or ownership, whether it is reversible, or what happens when the value is omitted.

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 definition is a single four-word fragment rather than a structured sentence. It is short, but the brevity reflects under-specification, not disciplined conciseness, and it is not actionable on its own.

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

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

For a mutation tool with no annotations, no output schema, zero required parameters, and only 33% schema coverage, the description is far too thin. It does not explain the compliance implications, the expected values, or the effect of the operation, leaving the agent to infer critical behavior.

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

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

Schema description coverage is only 33%, with only notification_message documented in the schema. The description mentions the encryption flag but does not explain uses_non_exempt_encryption semantics (including its string type where a boolean might be expected) or build_id targeting, leaving two of three parameters under-specified.

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 fragment names a specific resource and verb: setting the build export encryption flag via PATCH. But 'PATCH build export encryption flag' is vague about what the flag controls, how it differs from sibling compliance tools like attach_build_and_compliance or get_account_compliance_status, and what value is being 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?

There is no when-to-use or when-not-to-use guidance, no prerequisites, and no named alternative. An agent cannot tell from the description whether this should be called before attaching compliance data, before submission, or after a build is processed.

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 no annotations, the description carries the full burden. It discloses a meaningful prerequisite (Agreements/Tax/Banking required for paid apps) and confirms the read mode is non-destructive, but it doesn't state whether 'set' is reversible, what permissions are needed, or that the name's 'availability' portion goes unaddressed.

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

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

Two dense sentences, no filler, with the core action and key prerequisite front-loaded. It is efficient, though the prerequisite sentence reads as an aside rather than integrated guidance.

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 4-parameter mutation tool with no annotations, no output schema, and 75% of parameters undescribed, this is thin. The availability half of the name is entirely unaddressed and the mode-dependent behavior is not explained.

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 25% (only notification_message is documented), so the description must compensate. It explains price_tier semantics ('0 free, 1+ paid') and that the base territory is USA, which helps, but it never clarifies the format of price_tier as a string or the relationship between pricing_mode and the other 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?

The description states a specific verb pair and resource: 'Set or read USA base price tier', distinguishing it from siblings like set_age_rating or set_app_privacy. However, the tool name mentions 'availability' yet the description covers only pricing, leaving half the stated scope unexplained.

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 'Set or read' phrasing implies the two usage modes and the ASC Business prerequisite is a useful condition, but there is no explicit guidance on when to choose 'set' versus 'read' or when this tool is the wrong pick relative to 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?

No annotations exist, so the description carries the full disclosure burden. It does usefully disclose what is skipped (export-compliance and wait-for-processing steps), which tells the agent about side effects and preconditions, but says nothing about permissions, reversibility, required state of the build, or what happens on failure.

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, zero filler, with the core behavior front-loaded and the routing rule second. 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?

There is no output schema and no annotations, so the description must cover the full contract, and it covers only the happy path and one alternative. It leaves unaddressed which identifiers are mandatory and what the caller gets back, which matters for a mutation tool with all-optional params.

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

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

Schema coverage is only 33% — only notification_message is documented — yet the description never mentions build_id or app_store_version_id, nor does it explain why all three params are optional for an operation that clearly needs identifiers. It adds no meaning beyond the parameter names themselves.

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 ('Set which build is attached to an app store version') and immediately scopes it by naming what it does not do (export-compliance, wait-for-processing). An agent can distinguish it from attach_build_and_compliance and wait_build_processed without opening any schema.

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

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

Explicitly names the alternative (attach_build_and_compliance) plus the exact condition that selects it ('when the build may still be processing'). This is a genuine when-to-use/when-not guidance pair rather than implied 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?

With no annotations, the description carries the full burden and does well: it discloses the no-op/idempotent short-circuit when a saved session is valid, that the viewer is not opened in that case, and that force_reconnect destroys the saved cookie. It does not say whether the call blocks while the user signs in or what a failure result looks like.

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 short sentences, front-loaded with the default safe behavior, then the prerequisite, then the opt-in destructive path. Nothing extraneous; the repeated 'destructive' emphasis is proportionate to 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?

Covers the branching behavior, prerequisite, and risk for a one-parameter tool with no output schema. The only gap is what the tool returns or how long it blocks during interactive sign-in.

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

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

Schema coverage is 100% and the single parameter is already well documented, so baseline is 3; the description adds a usage-level condition (only on explicit user request to sign out/reconnect/clear session) that reinforces the destructive semantics beyond the schema wording.

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 ('Open App Store Connect sign-in') plus the scope constraint ('only when needed'), and names the sibling that should gate it (session_status). An agent can distinguish it from login and session_status without further reading.

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?

Explicit ordering ('Call session_status first') and an explicit exclusion for the destructive path ('Use force_reconnect only when the user explicitly wants to wipe the saved cookie'). Both when-to-use and when-not-to-use are 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?

No annotations are provided, so the description carries the full burden. It reveals that the tool mutates state (attaches a build and submits for review) but says nothing about irreversibility, required ASC credentials/permissions, what happens if the submit step fails, or how notification_message is used on failure.

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 that states the precondition first and the two-step action second, with no filler. It is efficient, though the terse phrasing borders on cryptic.

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 7-parameter mutation tool with no annotations, no output schema, and 14% schema coverage, the description is far too thin. It does not explain the encryption declaration, the notification message, or the failure behavior an agent needs to call this safely.

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

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

Schema description coverage is only 14% across 7 parameters. The description clarifies build_id, build_number, and the 'latest' selection, and implies app_store_version_id via 'current version', but leaves asc_app_id, notification_message, and uses_non_exempt_encryption entirely unexplained in both schema and 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?

The description names a specific composite action: attach a build (latest/build number/build_id) to the current version, then press Submit for Review in ASC. That is a clear verb+resource statement that distinguishes it from siblings like attach_build_and_compliance or press_submit_for_review, though it does not explicitly say how it differs from those.

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?

"Upload done:" implies the precondition (a build has been uploaded) and thus when to call it, but there is no explicit when-not guidance and no named alternatives such as press_submit_for_review or submit_for_review. Usage is 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?

With no annotations, the description carries the full behavioral burden: it implies a mutation and a two-stage attach-then-submit flow, which is useful, but it never states permissions/API-key requirements, whether an existing attached build is replaced, or whether the submit step is reversible. The implicit 'attach' side effect on the store version is left for the agent to infer.

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 that names the action first and the optional branch second, with no padding. The parenthetical and semicolon chaining make it slightly dense but not wasteful.

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 9-parameter, zero-annotation, no-output-schema mutation tool, this is under-explained: the agent does not know success/failure shape, permission needs, or how attach-only versus submit mode interact. The description covers the happy path but not enough to call the tool safely.

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

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

With only 44% schema coverage across 9 parameters, the description does add real value by naming build_selection 'latest', build_number (ASC build version), build_id, and confirm_submit_for_review. It leaves asc_app_id, app_store_version_id, attach_only, uses_non_exempt_encryption and notification_message unexplained, and the interaction/conflict between attach_only and confirm_submit_for_review is not resolved.

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 does state a concrete action (attach a build to the current store version, with an optional submit) and names the build-selection options, so the intent is graspable. However, the tool name promises 'submit_build_for_review' while the primary action is attaching, and the description gives no hint why this differs from siblings like set_version_build, submit_build_and_press_submit, or create_review_submission.

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 explains the internal conditional (submit only when confirm_submit_for_review=true) but never says when an agent should pick this tool over the many neighbouring attach/submit tools. There is no alternative, no prerequisite, and no exclusion 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?

With no annotations, the description carries the full load and does well: it discloses a server-side allowlist check and a confirmation gate, both non-obvious preconditions that a schema alone would hide. It stops short of describing what happens if the allowlist check fails or what the reply contains.

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 and its restrictions, then routing. No filler and no repetition of 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 risky mutation tool with no annotations and no output schema, the description covers preconditions, scope and alternatives well. It omits failure behavior and leaves one parameter unexplained, and its confirm-flag name is inconsistent with 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 only 25%, so the description should compensate, and it partially does by explaining the confirm gate and the app scoping. However, it names the flag confirm_probe_submit while the actual parameter is confirm_submit_for_review, a mismatch that could mislead, and app_store_version_id is undocumented in both places.

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 ('Press Submit for Review') plus two hard scoping conditions (probe/disposable allowlist, confirm flag). This separates it from press_submit_for_review and submit_build_and_press_submit, which are named 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?

Gives an explicit when-to-use ('automated testing against throwaway apps') and a when-not-to-use with two named alternatives for regular apps. Nothing is left to inference about routing.

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

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

No annotations exist, so the description must carry the burden. It discloses the processed-build prerequisite, that missing beta metadata fields are auto-filled ('when provided'), and the required follow-up polling before testers can join. It omits auth requirements, idempotency/duplicate-submission behavior, and failure modes, which keeps it at a 4 rather than 5.

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

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

Three dense sentences, front-loaded with the action and the sibling exclusion, then metadata behavior, then the follow-up workflow. No filler, and every clause carries operational 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?

The description covers the workflow and outcome check well, but for a 15-parameter mutation tool with no annotations and no output schema, it should explain how to choose among the several build-identifier parameters and what happens to the submission response. Adequate but with clear gaps.

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

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

Only 7% of 15 parameters are described in the schema, and the description only vaguely names four field groups (app description, what to test, contact, privacy URL). It does not explain the relationship among asc_app_id, build_id, build_number, and build_selection, nor defaults like beta_group_name='Public Link Testers' or the purpose of beta_marketing_url, beta_feedback_email, and notification_message. The coverage gap is large and only partially compensated.

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 (submit a processed build for TestFlight external Beta App Review) and explicitly names the sibling it is not: press_submit_for_review. An agent can distinguish it from the many other submit_* tools without opening schemas.

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 an explicit exclusion ('Not App Store press_submit_for_review') and a precondition (a processed build), plus the post-call workflow: poll get_testflight_public_link until accepting_public_testers is true before sharing the join URL. That is when/when-not/alternative guidance in compact form.

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?

No annotations are provided, so the description carries the full behavioral burden. It implies a PATCH-style mutation but does not disclose permission requirements, reversibility, partial-update behavior, side effects, or how notification_message affects the action.

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

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

Two concise sentences with the update target front-loaded and the usage condition following immediately. There is no padding or redundant restatement.

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

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

For a mutation tool with no annotations and no output schema, the description is incomplete: it omits permissions, effects, and return behavior. More seriously, it claims the tool updates fields that the input schema does not support, so an agent cannot rely on the description to call it correctly.

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

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

Schema description coverage is 100% for the sole parameter, notification_message, so the schema already documents it. However, the description instead lists name, primary locale, and bundle id as updatable fields, which are absent from the input schema, creating a misleading parameter picture rather than adding meaning.

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

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

The description states a specific verb and resource: update an existing app's name, primary locale, or bundle id. It also names the HTTP operation (PATCH apps) and distinguishes itself from create_app, though the listed fields do not match the input 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?

It gives a clear usage context: correcting app-level metadata after create_app. It does not state when not to use it or name other alternatives, but the create_app distinction is explicit.

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 no annotations, the description carries the full burden. It does add real behavioral signal by disclosing PATCH semantics (partial update, only supplied fields change) and that the operation is scoped to a single locale. However it says nothing about required auth/credentials, whether the localization must already exist, or what happens if an empty required-free payload is sent.

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 scope constraint front-loaded before the exclusion clause. Every clause carries information the agent needs to route the call.

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 five-parameter mutation with no annotations and no output schema, the description covers purpose and scope but leaves the identifier parameter and the failure/no-op behavior unexplained. An agent can still call it, but may not know how to source app_info_localization_id or whether missing fields are cleared or preserved.

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

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

Schema description coverage is only 20%, so the description must compensate, and it does partially by naming three of the five fields (app_name, subtitle, privacy_policy_url) as the updatable set. It says nothing about app_info_localization_id, the identifier that actually selects what gets patched, nor how to obtain it, and it omits notification_message entirely.

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 (update) plus the exact resources (localized app name, subtitle, privacy policy URL) and even names the API operation (PATCH app info localization). It clearly scopes the tool to listing-page text rather than media, though it never names its closest sibling update_version_localization to disambiguate the two localization 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?

It states when to reach for it ('text shown on the App Store listing page') and adds an explicit exclusion ('not screenshots'), which routes the agent away from upload_screenshot/delete_screenshots. It stops short of naming the true alternative, update_version_localization, leaving the boundary between the two localization tools to inference.

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

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

With no annotations, the description carries the full burden. It usefully discloses the sequencing prerequisite and that the scope is the current version, but says nothing about mutation semantics: whether omitted fields are preserved or cleared on update, permission/auth needs, or side effects on an in-flight submission.

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

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

Two front-loaded sentences with zero filler: the action first, then the prerequisite constraint. 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?

A 10-parameter mutation tool with no annotations and no output schema needs more: partial-update behavior, what happens when called twice, whether it affects an already-submitted review, and the conditional demo-account requirement are all absent. The prerequisite note helps but does not cover the gaps.

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 40% across 10 parameters. The phrase 'review contact and demo sign-in' covers the review_contact_* and demo_account_* families, but review_notes, notification_message, and asc_app_id get nothing from the description, and the conditional demo-account logic lives only in the schema.

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

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

States a specific verb pair ('Create or update') and a specific resource ('App Store review contact and demo sign-in for the current version'), plus the internal iris type. No sibling does the same thing, so the resource alone distinguishes it, though it never names an alternative 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?

'Required before press_submit_for_review for login apps' gives a clear ordering constraint and a condition for when it matters. It stops short of saying when it can be skipped or how it relates to submit_for_review / submit_build_and_press_submit, which are also in the sibling list.

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?

No annotations are provided, so the description carries the full behavioral burden. Labelling it a PATCH usefully implies partial update semantics (only supplied fields change), but it says nothing about authentication needs, whether an empty call is a no-op, what happens to fields omitted, or what the response contains — all material for a mutation tool with zero annotation coverage.

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, zero waste, with the field list and the PATCH semantics front-loaded before the disambiguation clause. Dense but every clause carries routing or scoping 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?

There is no output schema and no annotations, and the schema has eight parameters at 13% coverage with an empty required list — a genuinely ambiguous call shape. The description covers the intent and sibling routing well but leaves the agent without guidance on localization_id, empty-payload behavior, or what the mutation returns, which is a meaningful gap for this complexity.

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

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

Schema description coverage is only 13%, so the description must compensate, and it does partially: it names six of the seven updateable payload fields, mapping them to the schema properties. However it never explains localization_id (how it is obtained, whether it is effectively mandatory given an empty required list, and whether omitting it fans out across all localizations), and it ignores notification_message entirely.

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 ("Update") and scopes the resource precisely to the current app store version's localization, enumerating the six copy fields it touches and naming the underlying PATCH endpoint. It explicitly disambiguates from the app-level sibling update_app_info_localization, so an agent can pick the right tool from the name+description alone.

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 second sentence gives an explicit when-to-use ("App Store listing copy tied to a specific version") and an explicit when-not-to-use with the named alternative ("not app-level info (see update_app_info_localization)"). That is a complete routing rule rather than an implied one.

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 no annotations, the description carries the full disclosure burden, and it does add real context: the upload runs through Transporter on the replay host and the .ipa is downloaded from an https URL first. However, it says nothing about required ASC authentication/login state, failure behavior, whether the upload is irreversible or how long it takes, or what a caller should do afterward (e.g., wait_build_processed).

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

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

Three tight sentences with no filler: the action comes first, the routing exclusion second, the input contract last. Every sentence carries distinct 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?

No output schema and no annotations mean the description is the only behavioral source, and it omits post-upload sequencing (the build still needs processing/attachment via siblings) and prerequisite session/auth state. The purpose and input contract are complete, but the surrounding workflow is 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 coverage is 100%, so the baseline is 3, but the description adds something the schema does not state: that ipa_url and ipa_path are alternatives ("Supply ipa_url (https) or the host-local ipa_path"). That either/or relationship is genuinely additive for an all-optional parameter set where the choice matters.

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 ("Upload a .ipa to App Store Connect") plus the exact mechanism (Transporter on the replay host), which is far more than the name alone conveys. It also implicitly separates itself from sibling flows like distribute_build_to_testflight or submit_build_for_review by scoping the action to the upload step only.

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 condition to NOT use it — CI/Expo-built apps should upload through Expo or the CI pipeline directly and skip this tool — and states the positive condition it exists for (builds that must be uploaded from the replay host itself). This is the when/when-not pattern done properly.

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?

Without annotations, the description carries the full behavioral burden. It usefully discloses the two supported image sources, the default display type, and the legacy file-path constraint, but it does not say whether an upload overwrites an existing slot image, what permissions are required, or what errors can occur.

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 action, followed by the per-slide usage rule and the file-path caveat. Every clause adds actionable 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 mutation tool with no annotations and no output schema, the description covers the main upload mechanics well but leaves gaps around localization targeting, notification_message behavior, overwrite semantics, and return/error behavior. It is adequate but not fully complete.

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

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

Schema coverage is 67%, and the description adds meaningful semantics for the key upload parameters: base64 is marked as MCP-preferred, URL is described as an https master image, and file_path is described as legacy and replay-host-only. It also associates the default APP_IPHONE_65 size with the display type, though localization_id and notification_message remain largely schema-documented.

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

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

States a specific verb and resource: upload one App Store screenshot into a single carousel slot. The singular, slot-oriented phrasing implicitly distinguishes it from the plural upload_screenshots sibling, though it does not name that sibling 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?

Gives clear operational context: call once per slide, default size APP_IPHONE_65 / 6.5″, and the constraint that screenshot_file_path only works on the replay host. It does not explicitly compare against upload_screenshots or state when not to use this 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses that the image is auto-resized and that only one display size can be handled per call, but it does not explain prerequisites, whether existing screenshots are replaced, authentication needs, or failure 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?

The description is front-loaded with the core action and uses a compact semicolon-separated structure. It is dense but efficient, with no redundant sentences, though the long clause structure makes it slightly harder to scan.

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

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

For a mutation tool with no annotations and no output schema, the description covers the main upload constraint and image input alternatives. It remains incomplete because it does not explain broader context such as app/version scoping, permissions, return behavior, or effects on existing screenshots.

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

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

Schema description coverage is only 50%, so the description must add meaning. It clarifies screenshot_image_base64 versus screenshot_image_url and the exact-one-display-type rule, but it omits screenshot_file_path, screenshot_display_type as an alias, and notification_message.

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

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

The description states a specific verb and resource: uploading one App Store screenshot for a single iPhone display size from a master image. It is clear what the tool does, but it does not explicitly distinguish itself from the sibling upload_screenshot tool, so it falls short of a 5.

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

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

It explains practical usage constraints: pass base64 or URL, pick exactly one display type per call, and call again for additional sizes. However, it does not say when to use this tool versus upload_screenshot or other siblings, so guidance is implied rather than complete.

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

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

With no annotations, the description carries the full behavioral burden. It discloses that the tool polls and waits for a VALID state, but says nothing about timeout, polling cadence, blocking duration, or what happens if processing fails or the build never becomes VALID.

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 single sentence is front-loaded and free of filler, but it is under-specified rather than concise. Brevity here comes at the cost of the timeout and parameter context an agent needs.

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 blocking wait tool with no annotations and no output schema, the description should explain the wait condition, timeout behavior, and the build_id parameter. None of these are present, so an agent cannot reliably invoke it without guessing.

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 50%: notification_message is documented in the schema, but build_id has no description anywhere. The description does not compensate by explaining what build_id identifies, whether it is optional, or how it defaults.

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 polling action and a target state (build processing VALID), so the general intent is inferable. However, 'VALID' is an unexplained internal state and the description never mentions the build being waited on, leaving the purpose only partially specified.

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 guidance on when to use this instead of get_build or list_builds, no indication that it should follow upload_build, and no note on timeout or failure conditions. The agent must guess the workflow context.

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