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, and it discloses almost nothing: not whether this persists a setting, applies immediately, is global or per-project, or what happens when the value is null (the schema default). The parenthetical cost remark is the only extra context, and it is incomplete (unclosed).

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 short sentence that is front-loaded and easy to scan, but it is under-specified rather than efficient, and the trailing parenthetical is malformed (missing close parenthesis and a fragmentary dash 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?

An output schema exists, so return values need not be explained, but for a configuration-mutation tool with a 0%-documented nullable parameter and no annotations, the description is far too thin to let an agent invoke 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 0% and the single parameter is named 'providers' (an array, nullable, default null), yet the description talks about 'provider/model selection' in the singular. The relationship between the array parameter and the described model choice is never clarified, so the description fails to compensate for the undocumented 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 phrase 'AI provider/model selection' names the resource but supplies no real verb describing what the tool does to it (set? read? apply?). It does not distinguish itself from siblings like config_set, ai_deploy_proxy, or setup_services, leaving the agent to guess the actual operation.

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

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

There is no when-to-use, when-not-to-use, or alternative-tool guidance at all. With config_set and config_doctor among siblings, the agent has no signal about which configuration entry point to pick.

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 must carry the full behavioral burden. It does disclose useful traits: 'AI keys go only to server-side secrets' and 'LIVE side effects: human approval.' However, it omits critical operational detail: what the human-approval workflow looks like, how approval_id is obtained, what gets mutated (functions, migrations, secrets, auth), and whether deployment is reversible. For a live-effect deploy tool with zero annotations, this is partial transparency.

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

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

Three compact sentences with no filler. The key live-effect warning is placed last, which is a reasonable emphasis, though the conditional 'this is backend_deploy' framing makes the first sentence harder to parse than necessary.

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?

Although an output schema exists, the tool has a live-effect deploy with human approval, four undocumented parameters, and no annotations. The description leaves the approval flow, parameter meanings, and override behavior under-specified. Given the complexity and risk, this is insufficient.

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

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

Schema description coverage is 0%, so all four parameters (app_dir, project_ref, approval_id, daily_limit) are undocumented in both schema and description. The description hints at approvals ('human approval') but does not explain approval_id, does not define project_ref or app_dir, and does not mention daily_limit at all, which is a meaningful limitation knob. The description 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 description names a specific action ('Deploy the AI backend') but then immediately complicates it by saying 'this is backend_deploy' in one mode and 'legacy ai-proxy deploy' in another. It is not clear whether ai_deploy_proxy is its own tool, an alias for backend_deploy, or a mode switch. The sibling list contains both backend_deploy and ai_configure, making the distinction ambiguous.

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 mode-dependent condition ('with app.spec.json in subscription mode this is backend_deploy... credits mode keeps the legacy ai-proxy deploy'), which implies when each behavior applies. However, it does not tell the agent when to call ai_deploy_proxy versus calling backend_deploy directly, nor what prerequisites besides app.spec.json are needed. Usage is implied rather than 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 and does so well: it discloses the asset source and license, the selection rule (most-viewed match), the deterministic color-mapping policy (dominant→primary, others→accent, black/white kept), and critically that recolor is build-time with no runtime Swift code. It omits failure modes (no match found), network/rate-limit behavior, and 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?

The first sentence front-loads the action and destination, followed by compact source, recolor, and parameter notes. Usage of arrows and line-break fragments is dense but each sentence adds real information; only minor trimming is possible.

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?

An output schema exists so return values need not be explained, and the description compensates for 0% schema coverage across the non-obvious parameters. What remains missing is error/failure handling and any dependency on network access to LottieFiles.

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 0%, so the description must compensate and largely does: slot is enumerated (loading | success | empty | onboarding_hero), keyword gets an example, and primary_hex/accent_hex get format rules ('#' optional, format hint '006A63'). app_dir is left undocumented but is self-evident from the output path.

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 two-part action (fetch + recolor a Lottie animation) and names the exact output artifact (Resources/Animations/<slot>.json), which no sibling tool produces. It is immediately distinguishable from nearby tools like mascot_assets, icon_generate, or design_generate.

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 context: the tool is called for every slot of every app, and the keyword parameter is for app-themed overrides. It does not explicitly name competing tools (e.g. mascot_assets, icon_generate) or state when NOT to use it, but the usage 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 full behavioral burden. It usefully discloses paywall defaults, credit fallback values, and the need to keep pack amounts in sync with the server-side PACK_MAP, but it omits mutation side effects, overwrite behavior, permissions, and auth requirements expected of a config-injection 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 compact and front-loads the core purpose, then provides the most important parameter-specific details. The paywall strategy and credit default notes are reasonably concise, though the enum formatting could be slightly clearer.

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 configuration mutation with no annotations and no schema property descriptions, the description is materially incomplete. It partially covers paywall and credit settings but does not explain what most fields represent or how the injection affects the scaffolded app; the output schema only covers return values.

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

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

Schema description coverage is 0% across 16 parameters, so the description must compensate and largely does not. It explains paywall_strategy values and some credit defaults, but leaves most parameters such as posthog_key, privacy_url, supabase_url, product identifiers, and revenuecat_key undocumented.

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: filling in a scaffolded app's AppConfig and StoreKit tokens. It is clear what the tool does, though it does not explicitly distinguish itself from siblings like config_set, setup_services, or app_scaffold beyond the 'scaffolded app' context.

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 'scaffolded app's' implies the prerequisite that scaffolding must already exist, and the paywall_strategy explanation gives some inline guidance. However, it does not say when to use this tool versus alternatives such as config_set or setup_services, nor does it state 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 disclose meaningful side effects: it writes the spec into the app dir, runs xcodegen, initializes the pipeline manifest, and controls monetization mode where 'subscription strips the credit economy'. It omits whether existing directories are overwritten, auth requirements, or failure modes.

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

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

Front-loaded with the core action, and the spec explanation is dense but earns its place given the polymorphic parameter. No filler sentences, though the side-effect list is a long run-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?

An output schema exists so return values need no explanation, and the main 'spec' parameter is covered. However, for a 5-parameter mutation with no annotations, the silent dest_dir and display_name parameters and the absence of overwrite/prerequisite behavior leave 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 description coverage is 0%, so the description must compensate. It explains the 'spec' parameter well (dict of overrides, full dict, or path to app.spec.json) and mentions name/bundle_id defaults, but dest_dir and display_name are never addressed, leaving the agent guessing where output lands.

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 ('Scaffold a new SwiftUI app') plus a second effect ('init the pipeline manifest'), which clearly separates it from siblings like app_sync_spec or design_screens_skeleton. An agent can identify the operation 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?

Usage is implied (start a new app before building), and the description explains the spec fallback behavior ('otherwise the defaults for name/bundle_id'), but it never says when to prefer this over app_sync_spec or design_screens_skeleton, nor any prerequisites (e.g., must dest_dir be empty).

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 operation overwrites generated files and prunes String Catalogs to locales.app, hinting at a destructive/reconciling mutation, but it says nothing about required permissions, reversibility, or what happens to manual edits.

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 sentence, front-loaded with the primary action and parenthetical detail for the secondary effect. Every clause earns its place 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?

An output schema exists, so return values need no explanation, and the description covers the generated artifacts well. It is still incomplete for a mutating tool with zero annotations and an undocumented required parameter.

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

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

The single parameter app_dir has 0% schema description coverage and is never mentioned in the description; the agent can only infer from 'app.spec.json' that a project directory is involved. The description does not compensate for the coverage gap, so it falls below the 0-param baseline of 4.

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 action ('Re-generate') and enumerates the exact artifacts produced: AppSpec.swift, PaywallSource.swift and Configuration.storekit, plus a catalog-pruning side effect. This makes the tool's job unambiguous, though it stops short of explicitly distinguishing itself from close siblings like storekit_generate.

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 editing app.spec.json' supplies a clear triggering condition, which is genuine usage context. However, it names no alternative tool and gives no when-not guidance, so an agent must infer that this is the post-edit sync step.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose one useful fact — that this localization is needed to resolve a MISSING_METADATA condition — but says nothing about permissions, idempotency, what happens to existing localizations, or approval_id 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?

It is short, but brevity here comes from under-specification rather than efficiency — a single parenthetical fragment that is not even a complete sentence. There is no front-loaded statement of the tool's action or scope.

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 and 0% schema description coverage, the description is far too thin. An output schema exists so return values need not be explained, but the inputs, side effects, and usage context are all 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?

Schema description coverage is 0%, and all four parameters (group_id, locale, approval_id, name) are undocumented in the schema. The description adds only a partial hint about 'name' (its role in MISSING_METADATA) and leaves group_id, locale, and approval_id entirely unexplained, failing 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?

The description reads as a parameter label ('Subscription group display name') rather than a statement of what the tool does. It never uses a verb like 'adds' or 'creates', so the agent must infer the action from the tool name alone. It only incidentally distinguishes it from siblings like asc_localize_group.

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 'required for MISSING_METADATA' hints at one triggering condition, but there is no when-to-use guidance, no mention of alternatives (e.g., asc_localize_group vs. this tool), and no prerequisites. The agent gets a fragment of context, not routing guidance.

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

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

With no annotations, the description carries the full burden and does reasonably well: it discloses idempotency (skips if marker present), the default fallback (Apple's standard EULA when terms_url omitted), and a truncation limit (≤4000). It omits auth/permission requirements and exactly which description field is mutated, so it is not exhaustive.

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 clauses, front-loaded with the verb and resource, with the two behavioral caveats (idempotency, truncation) placed after. 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?

An output schema exists, so return values need not be described. The description covers the key behavioral facts (append target, idempotency, default EULA, truncation), but leaves the targeted description field and any authorization prerequisite unstated for a mutation tool with no annotations.

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

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

Schema description coverage is 0%, so the description must compensate. It usefully explains terms_url (defaults to Apple's EULA) and implies per-locale behavior via disclosure_by_locale, but bundle_id, privacy_url, and approval_id carry no added meaning beyond their names.

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 (APPEND) and resource (subscription disclosure + Terms/EULA + Privacy link to the description), plus the compliance context (Apple 3.1.2). This distinguishes it clearly from siblings like asc_localize_subscription or asc_finalize_subscription.

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 implies the usage context (App Store subscription disclosure compliance for Apple 3.1.2) and notes idempotent re-runs, but never states when to use this versus alternatives or what prerequisites apply. Usage is inferable but not spelled out.

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 well: it discloses the Apple ID requirement, the interactive 2FA dependency, that this is a write that creates an app shell, and the automatic name-selection fallback on 'name taken' errors. It stops short of stating permissions, rate limits, or what the partial shell 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 short paragraphs, front-loaded with the purpose and verb. The middle paragraph justifying why produce stays is slightly tangential but provides useful context; overall efficient with no egregious padding.

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

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

For a 6-param write tool with no annotations, it covers the critical creation flow, name-uniqueness behavior, and returns app_id (output schema also exists). The main gap is the undocumented sku/approval_id/primary_language parameters, but the core invocation path is 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 0%, so the description must compensate for all 6 params. It thoroughly explains candidate_names and app_name (backward-compat, converted to a one-element list) and the returned app_id, but sku, approval_id, primary_language, and bundle_id go entirely undocumented 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?

States a specific verb and resource ('Create an app SHELL in App Store Connect') with the underlying mechanism (fastlane produce). It distinguishes itself from siblings by noting it is 'the one ASC write that does not go through the asc CLI' and is separate from asc_create_bundle_id or subscription creation.

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?

Explains why this tool exists versus the asc CLI and `asc web apps create` (the latter needs an interactive 2FA web session), which effectively routes the agent here. It lacks an explicit when-not statement or a named sibling to prefer for related tasks, but the context for selecting it 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 present, the description carries the burden well: it flags 'LIVE write', states 'Human approval' (explaining the approval gate), and explains the capability preconditions and the effect of apply_capabilities/app_dir. It still omits failure/reversibility behavior and the relationship of approval_id to the approval flow.

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 core action is front-loaded in the first clause, and the dense parenthetical enumerates capabilities efficiently. The second paragraph is information-rich but slightly crammed, preventing a 5.

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?

An output schema exists, so return values need not be explained. Given no annotations and a mutation tool with a human-approval gate, the description supplies the essential safety and ordering context, though it does not cover error or reversal 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 coverage is 0%, so the description must compensate. It explains app_dir (checks capabilities right away), apply_capabilities (also applies them), and the capability enum values, but identifier, name, and approval_id receive no explicit mapping in the text. Partial compensation only.

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 bundle id in App Store Connect') and marks it as a LIVE write, which distinguishes it from read-oriented siblings like asc_list_apps and asc_get_app. An agent can identify the operation without opening the schema.

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

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

Gives clear sequencing context: the App ID capabilities must exist BEFORE any key, profile or signing step, and explains the app_dir vs apply_capabilities behavior. It does not name a competing sibling tool or state explicit when-not-to-use conditions, keeping it below a 5.

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

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

No annotations are provided, so the description carries the full burden. The '(LIVE write)' tag is a genuinely useful signal that this mutates production state, but the description says nothing about required permissions, reversibility, side effects on existing products, or the approval_id workflow implied by the schema.

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

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

Two compact clauses with the core purpose front-loaded and zero filler. It is appropriately sized, though the ellipsis in the period list is a minor loss of precision rather than padding.

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

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

An output schema exists, so return values need not be described. However, for a six-parameter mutation tool with no annotations, this is too thin: the relationship between group_id and product_id, the role of the optional approval_id, and the effect of family_shareable are all undisclosed, leaving an agent under-equipped to invoke 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 0% for 6 parameters, so the description must compensate. It only documents one parameter (period), and only partially, by listing sample values (ONE_WEEK/ONE_MONTH/.../ONE_YEAR) that are not encoded as a schema enum. The meaning of group_id, product_id, approval_id, and family_shareable is left 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 clear verb+resource ('Create a subscription product'), which is distinguishable from the sibling asc_create_subscription_group that operates on a group rather than a product. It does not name that sibling or otherwise route the agent, but the resource noun is specific enough to identify the 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?

There is no guidance on when to use this tool versus alternatives such as asc_create_subscription_group, asc_ensure_subscription_prices, or asc_finalize_subscription, nor any stated prerequisites. The only context is the inline '(LIVE write)' flag, which is behavioral rather than usage-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 are provided, so the description carries the full behavioral burden. '(LIVE write)' usefully warns that this affects live data, but nothing is said about required permissions, idempotency, whether the change is reversible, or what happens if the group already exists — meaningful gaps for a live 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?

A single front-loaded sentence with zero waste and the mutation warning in parentheses. It is efficient, though it is terse to the point of under-specification rather than maximally informative.

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?

An output schema exists, so return values need not be described. However, for a live write with no annotations and three completely undocumented parameters, the description is far too thin — no prerequisites, no side-effect detail, no disambiguation from the many subscription-related siblings.

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

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

Schema description coverage is 0% and the description adds no parameter meaning at all. 'For the app' only weakly implies app_id; reference_name and the optional approval_id (which likely relates to an approval-gated live write) are entirely unexplained in both the schema and 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?

The description states a specific verb and resource ('Create a subscription group') with a scope ('for the app'), and 'group' distinguishes it from the sibling asc_create_subscription and from the localization tools. It stops short of explicitly contrasting itself with asc_add_subscription_group_localization or asc_localize_group, so it is clear but not sibling-differentiating.

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 '(LIVE write)' tag signals this is a real mutation rather than a dry run, but there is no guidance on when to call it, what prerequisites (e.g. an existing app record) are needed, or which sibling to use instead. An agent gets no routing information beyond the resource name.

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

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

With no annotations, the description carries the full burden and does reasonably well: it discloses scope (all subscriptions), mutation semantics (sets a price only where none exists), idempotency, the metadata defect it resolves (MISSING_METADATA), and the price-source precedence. It omits permission/approval requirements and any rate 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?

Three tight sentences, front-loaded with the operation and scope, followed by idempotency and price-source resolution. No redundant or filler 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?

For a mutation tool with no annotations and an output schema (so return values need not be described), the description covers scope, idempotency, and price resolution well but leaves approval_id unexplained and omits any authorization or failure-mode context.

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 0%, so the description must compensate. It meaningfully explains usd_price_by_product (keyed by productId) and default_usd as the per-product vs. fallback price source, but says nothing about approval_id, leaving one of four parameters undocumented across 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 verb and resource ('set a price on those that have NONE') and constrains the scope ('ALL of the app's subscriptions'). It is clearly distinguishable in effect, though it does not explicitly name or differentiate from any sibling 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?

Usage is only implied: the reference to clearing MISSING_METADATA and the idempotency note suggest it is a fix-up/backfill tool safe to re-run. There is no explicit statement of when to prefer this over other setup tools, nor any when-not guidance.

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

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

With no annotations, the description carries the full behavioral burden. It discloses important fallback behavior: copyright read from config, contact_email falling back to support_email, and a generic 7-item review_notes template. However, it does not state auth requirements, whether existing values are overwritten, idempotency, or other side effects of this 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?

Front-loaded with purpose, then exclusions, then omitted-parameter rules. Dense but efficient with no filler, though a few parentheticals are terse. Appropriate for the tool's complexity.

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?

An output schema exists, so return values need not be explained. The description covers purpose, timing, exclusions, and key defaults, but with 11 parameters at 0% schema coverage and no annotations, missing parameter and mutation-safety details leave it short of fully self-contained.

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

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

Schema description coverage is 0% across 11 parameters, so the description must compensate. It groups and names most fields and gives specific fallback rules for copyright, contact_email, and review_notes, but approval_id and the required bundle_id are not explained. Compensation is partial.

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 ('Fill') and enumerates the exact submit-blocking fields (Content Rights, Copyright, Age Rating, Free Price, App Review Contact, App Review Notes). Distinguishes itself from generic submit tools by scope ('before submit, per app') and by explicitly excluding App Privacy.

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

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

States when to call it (before submit, per app), what is excluded (App Privacy, must be set via ASC web UI), and dependent fallback configuration (config_set for the copyright key). It names both the alternative path for an excluded field and the source of defaults for omitted parameters.

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 disclose non-obvious behavior: the exact step ordering, that intro offers are created per territory, that `period` is silently ignored (legacy bug), and the implication from 'store_setup does every product idempotently' that this tool is not fully idempotent. It still omits permission/approval requirements and re-run safety.

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-loads the action and the key ordering, and the sentences earn their place, but the arrow notation, nested parentheses, and inline JSON make it dense and harder to parse quickly than it needs to be.

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?

An output schema exists so return values need not be explained, and the description covers ordering, the alternative tool, and the trickiest parameters. However, for a 7-parameter mutation with no annotations it leaves gaps around approval_id, auth requirements, and failure/re-run 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 0%, so the description must compensate. It richly documents the difficult parameters (intro format with a concrete example, period being ignored, offer-product null behavior) but leaves sub_id, name, description, usd_price, and especially approval_id 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 (FINALIZE) and resource (one subscription), plus the internal step order (localization → availability → price → intro offer). It partially distinguishes itself from the crowded sibling set by naming store_setup as the preferred alternative and calling out how offer products differ.

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 routes the agent: 'Prefer store_setup, which does every product idempotently,' and gives the branching rule for spec products vs offer products. Clear when-to-use guidance, though it lacks exclusions for other finalize-adjacent siblings like asc_submit_for_review.

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. 'Find' implies read-only access and '(LIVE)' hints at live data, but the description does not explicitly state read-only safety, authentication requirements, error behavior, or rate limits.

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 wasted words. The parenthetical '(LIVE)' is compact and relevant.

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?

An output schema exists, so return values need not be explained. However, with no annotations and no usage guidance, the description is only minimally complete for an agent choosing between this and sibling app 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 0%, so the description must compensate. It names the bundle id lookup key but adds no format, example, or constraint beyond the schema property name, so it does not meaningfully enrich parameter semantics.

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 'Find', resource 'App Store Connect app', and lookup key 'bundle id'. It clearly implies a single-app lookup, though it does not explicitly distinguish itself from sibling tools like asc_list_apps.

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, prerequisites, or alternative guidance. The phrase 'by bundle id' implies the lookup context, but the description does not tell the agent when to choose this over asc_list_apps or asc_create_app.

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. It usefully signals that this hits the live App Store Connect API (not a mock/dry run) and that an issuer_id credential must be configured first, but it says nothing about pagination, rate limits, or what the LIVE designation implies for 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?

A single 12-word sentence with the resource named first and the LIVE/auth caveat second; every clause carries information and there is no filler.

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

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

An output schema exists, so return values need not be described, and a zero-parameter read tool has little else to specify. The remaining gap is the relationship to asc_get_app and how large result sets are returned.

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

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

The tool takes zero parameters, so the baseline is 4. The mention of issuer_id is an auth prerequisite rather than a call argument, so it does not confuse the empty 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 and resource ('List the apps in App Store Connect'), so the agent knows exactly what it returns. It does not differentiate itself from the sibling asc_get_app (singular fetch) or explain what 'apps' scopes to, so it stops 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?

The parenthetical '(LIVE; requires issuer_id)' implies a precondition for calling it, which is more than nothing. However, there is no guidance on when to pick this over asc_get_app or asc_token_check, and no statement of exclusions, so usage is only implied.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does not say whether this overwrites or merges existing localizations, what permissions or approval flow is involved (the presence of approval_id strongly implies one), or what happens to locales not supplied. For a mutation tool with zero annotation coverage this is a substantial gap.

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

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

It is a single, front-loaded sentence with no filler or restatement of the title. The brevity is appropriate structurally, though it borders on under-specification rather than true economy.

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?

An output schema exists, so return values need not be described, but the description still omits the approval workflow implied by approval_id, the merge/overwrite semantics needed for a mutation, and any differentiation from sibling localization tools. Incomplete for a 3-parameter mutation with no annotations.

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

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

Schema description coverage is 0% across three parameters, including a nested locale-to-string map. The phrase 'in multiple languages' loosely implies name_by_locale, but group_id is unexplained and approval_id — clearly a meaningful workflow parameter — is not mentioned at all, nor is the expected locale key format.

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 clear verb+resource ('Localize the subscription group name') plus scope ('in multiple languages'), so the action is unambiguous. However, it does not distinguish itself from the near-identical sibling asc_add_subscription_group_localization or asc_localize_subscription, which an agent would need to route between.

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 guidance, no prerequisites, and no mention of alternatives despite at least two strongly overlapping siblings (asc_add_subscription_group_localization, asc_localize_subscription). The agent is left to guess which localization tool applies.

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 that IAP-unsupported languages are skipped during localization, a genuine behavior not derivable from the schema, but says nothing about the approval_id-driven approval flow, permissions, idempotency, or whether existing localizations are overwritten.

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, front-loaded sentences with no filler. The items notation is terse but functional given the nested 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?

The output schema covers return values, but for a mutation tool with no annotations and an unexplained approval_id parameter the description is thin. It covers the items payload and skip behavior but omits the approval/auth context an agent would need 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 0%, so the description must compensate. It does clarify the nested items shape (locale:{name,description}), which is valuable, but leaves sub_id and the optional approval_id undocumented 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 verb (localize) and resource (subscription) with a scope qualifier (MULTIPLE LANGUAGES). It is clearly distinguishable from the sibling asc_localize_group, which targets groups rather than subscriptions, 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?

There is no guidance on when to use this tool versus the other localization or subscription-sibling tools, and no prerequisites are stated. The only contextual note, that unsupported languages are skipped, is a behavior, not a usage condition.

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 does well: it states the data source (latest SUBSCRIPTION/SUMMARY sales report, gzip TSV), the auth requirement (Finance-role key and the specific config parameters), and error behavior (403 → clear error). It does not state rate limits or caching, but auth and failure handling are the traits an agent most needs to invoke this correctly, and both are covered.

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 front-loaded with the purpose, then packs auth and error details into compact parentheticals without filler. It is dense and telegraphic but every clause contributes actionable information. A slightly more readable structure would be the only improvement.

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?

An output schema exists, so return values needn't be described, and the description covers purpose, auth, and error handling. The material gap is the two input parameters, which are neither documented in the schema nor the description. For a tool with a real auth dependency and a computed-ratio output, this is adequate but leaves invocation details under-specified.

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

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

Schema description coverage is 0%, so the description must compensate for both parameters, and it does not. Although 'latest ... sales report' hints that days_back controls the lookback window and report_date selects a specific report, neither parameter is named or explained, leaving the agent to guess how they interact or which takes precedence.

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 operation: fetching the latest SUBSCRIPTION/SUMMARY sales report and computing a US proceeds/price ratio to prove Small Business Program status. The verb+resource is concrete, and the ratio thresholds (≈0.85 SBP, ≈0.70 standard) make the intent unambiguous. It does not distinguish itself from siblings, but no sibling shares this function, so the gap is minor.

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

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

Usage is implied ('Small Business Program proof') rather than stated explicitly as a when-to-use, and no alternatives or when-not conditions are named. It does supply the prerequisite (Finance-role key via asc_finance_key_id + asc_finance_key_filepath + asc_vendor_number), which is real guidance. This lands at implied usage with useful prerequisite context, not a full routing 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?

No annotations are provided, so the description carries the full behavioral burden, and it discloses a critical non-obvious trait: human approval is always required even when approvals are disabled. That is genuinely valuable and not derivable from the schema. It stops short of describing what happens after a successful submission (irreversibility, follow-up state), leaving a minor gap.

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

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

Three tight sentences with the action front-loaded, followed by the gating rule and its consequence. Nothing is padded and every sentence adds a distinct, actionable fact.

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, the description adequately covers the preconditions an agent needs to avoid a failed call, and an output schema exists so return values need not be explained. The only real shortfall is the undocumented app_id parameter.

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

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

Schema description coverage is 0%, so the description must compensate. It partially does — it conveys that 'approval_id' must be valid and comes from `appfactory approve <id>`, giving that parameter real meaning. But 'app_id' remains entirely undocumented in both schema and description, so compensation is incomplete.

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

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

The description opens with a specific, unambiguous verb+resource: 'SUBMIT the app to App Store review.' An agent can distinguish this from adjacent siblings like asc_finalize_submission_requirements or deliver_metadata without further reading, since the scope (App Store review submission) is stated 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 gives a strong precondition — a valid approval_id obtained out-of-band via `appfactory approve <id>` — and even states a when-not condition ('Without a valid approval_id nothing is submitted'). It does not, however, compare itself to any alternative tool or explain sequencing relative to finalize/preflight siblings, so it falls short of explicit routing guidance.

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

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

With no annotations, the description carries the full burden and does well: it discloses the exact credential resolution order (config.toml asc_* keys as env, else the asc keychain profile) and explicitly states the live call is read-only, plus how success is proven. It omits failure modes and what a failed check reports, keeping it below 5.

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

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

Two tight sentences with the core action front-loaded and the credential-resolution caveat and success proof following. The parenthetical is dense but earns its place by describing real resolution behavior; nothing is wasted, though the second sentence is somewhat compressed.

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?

An output schema exists, so return values need not be described, and there are no parameters to document. The description covers what is checked and how credentials resolve, which is adequate for a no-arg diagnostic tool; only failure/edge-case behavior is unaddressed.

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

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

The tool takes zero parameters, and the schema confirms an empty properties object, so there is nothing for the description to clarify. Baseline 4 applies; no parameter meaning is missing.

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 precise verb ('Check') and a specific resource (App Store Connect auth via the asc CLI), then enumerates exactly what is verified: binary presence, credential source resolution, and one live read-only call. An agent can distinguish it from asc_list_apps or the various doctor tools 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?

The purpose implies when to use it ('check ASC auth'), and the success criterion (`asc apps list --limit 1` proving key id, issuer and .p8) gives a concrete validation context. However, it names no alternatives despite many overlapping siblings (asc_sbp_check, config_doctor, env_doctor, setup_credentials), leaving the routing decision 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 provided, the description carries the full burden, and it does disclose useful behavior: the name is globally unique and the check is an exact-name collision against iTunes Search. It does not cover read-only vs mutating nature, network/auth requirements, or rate-limit behavior, which is a real gap for an unannotated tool, though the output schema covers return values.

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 core question and followed by the mechanism and the prerequisite call. Every clause earns its place 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 a simple two-parameter read check with an output schema, the description is nearly sufficient, and it correctly omits return-value details. It is still thin on parameter meaning and on how the two name-checking siblings relate, which an agent needs to invoke this 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 0% and the description never mentions either parameter. The 'country' parameter in particular is left unexplained, and there is a subtle tension between 'globally unique' and a country-scoped iTunes lookup that the description could have 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 names a specific verb ('check available') and resource ('App Store name'), and even discloses the mechanism ('iTunes Search exact-name collision'), so the operation is unambiguous. It does not differentiate itself from the sibling aso_find_available_name, which appears to cover similar ground, 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 gives an explicit sequencing instruction ('Call BEFORE asc_create_app'), which tells the agent exactly where this fits in a workflow. However, it offers no when-not guidance and never mentions aso_find_available_name, leaving the choice between the two name-checking siblings 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 and does so well: it discloses the failure contract (ok:False + prices:None), warns that absence means 'unknown' NOT 'free', and explains why iTunes lookup can't substitute. It stops short of documenting auth or rate-limit behavior, but the fragility disclosure is the critical trait for correct interpretation.

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-loads the core purpose, then the sourcing rationale, then the critical fragility warning. Tight and purposeful, though the fragmented parenthetical asides make it slightly choppy.

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?

An output schema exists, so return values needn't be explained, and the description adds the one thing an agent most needs — the failure/absence semantics — plus the app_id source. Only the country parameter and any auth expectations are left uncovered.

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 0%, so the description must compensate. It explains app_id precisely ('iTunes trackId returned by aso_fetch_competitors'), but the country parameter (default 'us') is left entirely undocumented 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?

States a specific verb+resource: retrieves a competitor's subscription/IAP price ladder from the App Store product page. This is clearly distinguishable from siblings like aso_fetch_competitors (which supplies the app_id) and aso_unit_economics (which consumes pricing data).

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 implied usage ('Input to the pricing decision') and a useful chaining hint that app_id comes from aso_fetch_competitors. However, it never states explicit when-to-use/when-not conditions or names an alternative tool for the same task.

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 key state mutation: marking the 'aso' stage done and unblocking the metadata/deliver gate. It omits whether validation failure is fatal, whether the call is idempotent, and any permission requirements, leaving meaningful gaps for a state-changing 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 tight sentence that front-loads the two actions and appends the downstream effect in parentheses. No filler, every clause carries information.

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

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

An output schema exists, so return values need not be described, but the near-total absence of annotations and the completely undocumented parameter leave the tool only minimally specified. For a tool that mutates pipeline state, more on failure handling and sequencing relative to aso_run/pipeline_mark would be expected.

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

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

There is one parameter, app_dir, with 0% schema description coverage, and the description says nothing about it. The name is largely self-explanatory (the app's root directory), but no format or scope detail is added, so it neither compensates for nor meaningfully worsens 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 description gives a specific compound verb+resource: 'Validate the ASO output + mark the 'aso' stage done'. It also names the downstream consequence ('opens the metadata/deliver gate'), which helps separate it from aso_run and aso_validate_metadata. It stops short of explicitly contrasting those siblings, so not a 5.

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

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

The 'opens the metadata/deliver gate' clause implies this is the step that follows ASO generation and precedes metadata/deliver work, giving implied sequencing. However, it never states when to prefer this over aso_validate_metadata or pipeline_mark, nor any preconditions (e.g. ASO output must already exist).

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 two useful traits: the call is live (network-dependent, potentially slow or rate-limited) and read-only (safe, no mutation). It omits auth requirements, rate limits, error behavior, and result ordering.

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 parenthetical efficiently conveys the live/read-only traits. It is terse to the point of under-specification, which caps it below a 5.

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?

An output schema exists, so return values need not be explained, but for a 3-parameter tool with zero schema coverage and no annotations the description is far too thin — it provides no parameter meaning, no usage routing, and no operational caveats.

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

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

Schema description coverage is 0% and the description mentions no parameters at all. Three parameters (term, limit, country) are left entirely undocumented, so an agent gets no guidance on what 'term' should contain or what 'country' accepts.

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 ('Fetch'), a specific resource ('competitor apps'), and the data source ('iTunes Search'). It does not differentiate itself from sibling tools like aso_competitor_iap or aso_search_hints, which an agent would have to disambiguate on its own.

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 '(LIVE, read-only)' tag hints that this hits live external data rather than a cache, but there is no explicit statement of when to use this tool versus the other ASO siblings, no prerequisites, and no exclusions.

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 discloses the selection rule (first available candidate) and the consequence of a taken name, but does not say what happens if every candidate is taken, whether it checks the live App Store, what credentials or permissions are needed, or whether the check is cached or rate-limited.

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 a single front-loaded sentence with no wasted words. The availability constraint and submission consequence are stated efficiently, though the extreme brevity leaves gaps that a longer description could close.

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 tool with two parameters, no annotations, and a live availability-checking purpose, the description is under-specified. It omits the country parameter, does not explain the return semantics beyond what the output schema may show, and says nothing about the no-available-name case.

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

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

Schema description coverage is 0%, so the description must compensate for both parameters. It gives meaning to candidates as App Store name options, but completely omits the country parameter, which defaults to 'us' and could materially affect availability results.

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: picking the first available App Store name from candidates. It is clear what the tool does, but it does not explicitly contrast itself with the sibling tool aso_check_name, which likely has an overlapping name-checking role.

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 implies usage by explaining why availability matters: a taken name gets submission rejected. However, there is no explicit when-to-use or when-not-to-use guidance, and no alternative tool is named for cases where none of the candidates are available.

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 mostly succeeds: it discloses the hard-gate rule, that competitor metrics come from the iTunes Search top 50, that country is PINNED and userRatingCount is per-storefront, that the saturation penalty grows when the median competitor is strong, and that genre AI density is informational and never scored. Gaps remain around read-only/network/cost behavior and error modes.

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

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

The scoring formula is front-loaded in the first sentence, followed by the hard gate and verdict bands. It is dense but every clause conveys a rule; a few telegraphic fragments ('HARD GATE:', 'country PINNED') cost a little readability but waste no space.

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?

An output schema exists, so return values need not be explained, and the description supplies the scoring model, gating rule, and verdict cutoffs an agent needs to interpret results. For a 3-param tool it is nearly complete, missing only explicit term semantics and any note on failure conditions.

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

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

Schema description coverage is 0%, so the description must compensate. It adds real meaning for genre (any App Store category from aso.GENRES, AI density informational) and country (PINNED, per-storefront rating counts), but the required 'term' parameter is only implied and its format/constraints are never stated.

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+resource: it computes a 0-100 go/no-go score for a keyword/idea niche from demand, competitor weakness, saturation, and monetization. That is far more concrete than the bare name aso_niche_score. It does not, however, name the nearest siblings (idea_evaluate, aso_run) to disambiguate, so an agent must infer the boundary from the formula 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?

Usage is implied through the HARD GATE ('0 autocomplete suggestions = REJECT') and the verdict thresholds (GO>=60, MAYBE>=40, WEAK, REJECT), which tell the agent what output to expect but not when to call this instead of idea_evaluate or aso_run. No explicit when-not or prerequisite guidance is given.

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. 'Start' implies a state-changing operation that likely writes skeleton files, but the description never states side effects, whether it requires prior setup, or whether it is idempotent. The only behavioral hint is that it is mandatory and emits instructions.

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

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

A single tight sentence with no waste, and the mandatory status plus outputs are front-loaded. It is appropriately sized, though extremely terse for a stage-entry tool.

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

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

The output schema covers return values, so those need not be described. But with no annotations, an undocumented required parameter, and no explanation of side effects or ordering against sibling ASO tools, the definition leaves real gaps for an agent invoking a stage-start operation.

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

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

There is one required parameter, app_dir, and schema description coverage is 0%, so neither the schema nor the description explains it. The description adds no meaning about what app_dir should point to (repo root, app folder) or its expected format.

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 verb ('Start') and a resource ('the ASO stage') and mentions the outputs (skeleton + skill instructions). However, 'start the ASO stage' is vague and does not distinguish this from sibling ASO tools such as aso_scaffold_outputs, aso_validate_metadata, or aso_complete, so an agent cannot easily tell which ASO entry point to pick.

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 labels itself a 'mandatory step', which implies it should be run at the beginning of the ASO flow. It names no alternatives and gives no when-not-to-use conditions or prerequisites relative to the many other aso_* 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?

With no annotations, the description carries the full burden. It discloses what gets created but not whether existing files are overwritten, whether the operation is idempotent, whether it requires credentials/permissions, or what happens if the directory already exists — important for a file-creating scaffold.

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. Efficient, though the parenthetical about '32 languages' is terse to the point of ambiguity.

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?

An output schema exists so return values need not be described, but for a file-writing scaffold with zero annotation coverage and 0% parameter documentation, the description leaves the agent without enough to call it safely or 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 0% and none of app_name, base_dir, or locales is explained in prose. The phrase '32 languages' faintly implies the locale default, but the required base_dir and app_name are left entirely to the schema's bare types.

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 (Create) and resource (the outputs/<App>/ skeleton) and names concrete artifacts it produces (apple-metadata.md, 32 languages). Clear enough for an agent to know what it does, though it never distinguishes itself from plausible siblings like app_scaffold or design_screens_skeleton.

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 alternatives among the many scaffolding/metadata siblings. Usage is only weakly implied by the word 'skeleton'.

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 no-auth/free access, that results come in Apple's own popularity order, that expand=True appends a–z to build a keyword universe, and critically that an endpoint error returns ok:False rather than an empty list. Rate limits and the effect of the country parameter are not covered, keeping it below 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?

Dense and front-loaded: the core identity ('App Store autocomplete = REAL search demand') leads, followed by role, then behavior and error semantics. Every sentence adds information with no padding.

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

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

An output schema exists so return values need not be explained, and the description covers the gate logic and error-handling caveat well. The remaining gap is the country parameter's impact on results, which an agent would need to know for non-US stores.

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

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

Schema description coverage is 0%, so the description must compensate. It explains expand=True thoroughly (a–z expansion, keyword universe collection) and term is self-evident, but the country parameter and its effect on locale-specific results are entirely undocumented 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?

States a specific verb+resource ('App Store autocomplete') and its semantic meaning ('REAL search demand'), plus its role as an 'IDEA-STAGE HARD GATE'. An agent can distinguish this from sibling ASO tools like aso_find_available_name or aso_niche_score without opening the schema.

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

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

Gives a clear decision rule for when to use it (idea-stage validation) and how to interpret results (0 suggestions → REJECT the idea). It does not explicitly name competing sibling tools or exclusions, 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?

With no annotations, the description carries the full burden. It does disclose a valuable failure mode (invalid genre returns ok:False, never the overall chart), which goes beyond the schema. But it says nothing about auth requirements, rate limits, pagination, or scoping, 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?

Front-loaded with the core purpose before the parameter detail, and the long genre enumeration is justified because the schema has no enum. Slightly verbose but every segment 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?

An output schema exists, so return values need not be explained here. Combined with the genre documentation and the explicit filter-failure rule, the agent has enough to call it correctly; only the undocumented limit/country params keep it from a 5.

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 0%, so the description must compensate for all three params. It documents genre thoroughly (category name from aso.GENRES or its id, None = overall chart), but limit and country are left entirely unexplained. It covers one of three parameters well.

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 plus a use framing: 'Top-grossing apps (revenue proxy) — proven-idea hunting.' An agent immediately knows this returns a revenue-ranked chart. It does not name or contrast a sibling (e.g., aso_fetch_competitors, aso_niche_score), so it stops short of 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?

'proven-idea hunting' implies a use context, and the description warns that an ignored genre filter fails rather than silently returning the overall chart. However, there is no explicit when-to-use / when-not / alternative-tool routing against the many ASO siblings, so guidance remains implied.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose what the tool produces (margin, break-even, warnings), the apple_cut default rule (0.15 Small Business, else 0.30), and its advisory role in validating scaffold credits. It does not state whether it is purely read-only, whether it persists anything, or whether it depends on project state, which is a gap given 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?

The computation is front-loaded in a compact formula line, followed by one sentence of stage/relationship context and a default-value note. Little waste; the parenthetical credit note is slightly dense but 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?

An output schema exists, so return values need not be described, which the description correctly omits. But for a 6-parameter, zero-schema-coverage, annotation-free tool the definition is only partially complete: parameter meanings and side-effect/safety behavior are thin, and sibling differentiation from pricing_unit_economics 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?

Schema description coverage is 0% across 6 parameters, so the description must compensate. It explains apple_cut's default semantics and references the weekly/yearly credit inputs, but leaves weekly_price, yearly_price, ai_cost_per_credit, and yearly_monthly_credits entirely unexplained — no units, granularity, or accepted ranges.

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

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

The description states a concrete computation: 'credit count × AI cost vs subscription revenue → margin, break-even, warnings.' An agent can tell this is a unit-economics calculator rather than a mutating setup tool. However, it never distinguishes itself from the near-identical sibling 'pricing_unit_economics', which is the most likely source of misselection.

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 anchors usage to a phase: 'Grounds the price + credit decision in data at the idea/scaffold stage,' and ties it to app_scaffold via the credits it validates. That is implied when-to-use context, but there is no explicit when-not guidance and no routing away from the sibling pricing_unit_economics.

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 entire behavioral burden. It does not say what is validated, whether a failure is fatal, whether it mutates anything, or what errors look like. An output schema exists, which covers return structure, but the validation behavior itself is undisclosed.

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 padding, which is good. But it is terse to the point of under-specification given everything it leaves unaddressed.

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 an output schema the return values need no prose, but two undocumented required parameters, zero annotations, and a crowded sibling set of validators make this far too thin. An agent lacks enough to select or invoke 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 0% and neither of the two required parameters (app_name, base_dir) is documented anywhere. The path fragment "outputs/<App>" loosely hints that app_name slots into a directory, but base_dir's role and expected format are 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 ("Validate") and a concrete resource (the apple-metadata.md file), which is more than a tautology. However, it does nothing to distinguish itself from sibling validators like metadata_check, metadata_listing_check, or pipeline_validate, so an agent cannot tell which validator applies.

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 exclusions, and no mention of the many sibling validation tools. The agent must guess at the workflow position and prerequisites on its own.

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 well: it discloses that dry_run makes no calls, that live deployment requires human approval, that migrations are tracked, and that secret values are reported by name only rather than echoed. It stops short of covering idempotency, rollback, or permission requirements for live runs.

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 and resource, and the parenthetical lists are dense but each item earns its place by telling the agent what will actually be provisioned. The single run-on sentence is information-heavy but slightly unwieldy.

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 high-complexity deployment tool with 4 params, an output schema present, and no annotations, the description covers scope, safety gating, and dry-run behavior well. The unexplained app_dir/project_ref semantics are the main residual gap, but return values are correctly left to the 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 0% for 4 parameters, so the description must compensate. It explains dry_run's semantics and implies the approval/approval_id mechanism, but app_dir and project_ref receive no explanation in either place, leaving half the surface documented only by name.

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 (Deploy) plus a precise resource (the spec's Supabase backend), with an explicit enumeration of what is deployed: migrations, secrets, auth, legal build, and a named function set. An agent can distinguish this from siblings like supabase_create_project or supabase_run_sql 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?

Clear context: dry_run=true is the default and returns only a plan, while a live deploy requires human approval via the approval path. It does not explicitly name alternative tools or state when-not to use this versus supabase_* setup tools, so it falls short of the explicit-alternatives bar.

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 does well: 'offline' tells the agent no network or credentials are needed, and 'idempotent' signals it is safe to re-run. 'Prune supabase/' also discloses that files may be removed, which is important destructive context. It stops short of saying what happens on failure or whether existing files are overwritten.

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?

Purpose is front-loaded, then a compact colon-delimited list of side effects. It is one dense sentence, but every clause names a real artifact or trait, so there is little waste.

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

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

An output schema exists, so return values need not be described, and the description covers offline/idempotent behavior plus the concrete mutation set. The main gap is placement in the broader setup pipeline relative to siblings like app_scaffold and backend_deploy.

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 0% and the single app_dir parameter is never named or described. The file paths and the app.spec.json reference imply app_dir is the project root containing those artifacts, which gives some implicit semantic value, but the description never compensates fully for the undocumented parameter.

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

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

The description names a specific action (rendering the backend to match app.spec.json) and enumerates the concrete artifacts produced: pruned supabase/, functions/_shared/app.gen.ts, config.toml, the CONTRACT.md quota block, legal sources, and listing.json URLs. This is far more specific than a sibling like backend_deploy, though it never explicitly names the alternative it contrasts with.

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?

Calling it a step that makes 'the scaffolded backend' follow the spec implies it runs after app_scaffold, so prerequisite order is inferable. However, there is no explicit when/when-not guidance and no mention of how it relates to backend_deploy, app_inject_config, or app_sync_spec, so the agent must infer sequencing.

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 add the useful detail that it emits a .xcarchive artifact, but gives no information about required signing/credentials, execution time, where the archive is written, or whether the path directory is created. For a build mutation with zero annotation coverage this is a large gap.

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

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

It is short but this is under-specification rather than true conciseness. The single fragment is front-loaded, yet it omits information that would earn its place (prerequisites, artifact location). A one-line arrow notation is too sparse for a four-parameter build tool.

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

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

An output schema exists, so return values need not be explained. But given four undocumented parameters, no annotations, and a complex build operation, the description leaves out signing requirements, project/scheme expectations, and how the result feeds downstream shipping steps. Incomplete for the tool's 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 0% and there are four parameters, so the description must compensate but does not. 'archive_path' is only obliquely implied by '→ .xcarchive'; project, scheme, and the Release-defaulted configuration are entirely unaddressed. No format hints (workspace vs project) or path conventions are given.

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+resource (xcodebuild archive) and identifies the output artifact (.xcarchive), so the core action is inferable. However, it does not distinguish this from siblings like build_export_ipa or build_for_sim, and the '(generic iOS)' fragment is the only scoping hint. It states what happens but not how it differs from adjacent build 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?

There is no guidance whatsoever on when to use this tool versus the many other build/export siblings (build_for_sim, build_export_ipa, build_test). No prerequisites, no mention of needing a configured scheme or signing setup. The agent must guess where archive fits in the pipeline.

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 the UI side effect of opening Simulator.app, which is useful, but says nothing about state mutation (booting changes device state), whether an already-booted device errors, or any auth/permission 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 front-loaded sentence with zero filler. It is efficient, though its brevity contributes to the guidance gaps rather than being purely economical.

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?

An output schema exists, so return values need not be explained. However, for a state-changing tool with no annotations and a fully undocumented parameter, the description is thinner than ideal, leaving the udid semantics and prerequisites unaddressed.

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 0% for the single required parameter, so the description must compensate and it does not. It never mentions 'udid', its format, or where to obtain it; the only hint is the parameter name 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?

States a specific verb+resource ('Boot the simulator') and adds the side effect of opening Simulator.app. This distinguishes it from build_for_sim and build_list_simulators, though it never names a 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?

No when-to-use guidance, no alternatives, and no prerequisites. It does not mention that the udid must come from build_list_simulators or how this relates to build_for_sim, which are the natural adjacent 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?

No annotations are provided, so the description carries the full behavioral burden, and it discloses nothing: not that it shells out to xcodebuild, not the host/toolchain requirements, not that it writes files into export_dir, not what happens on failure or whether output is overwritten. A single command line is far short of adequate for a 3-required-parameter mutating build step.

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 undeniably front-loaded with zero filler, but the extreme brevity here reflects under-specification rather than disciplined conciseness. There is no wasted sentence simply because there are almost no 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?

An output schema exists, so return values need not be described, but for a tool with three required, undocumented parameters and no annotations, the description should at minimum explain the inputs and preconditions. It leaves an agent unable to call the tool correctly without outside knowledge.

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

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

Schema description coverage is 0% for three required parameters. The '-exportArchive' flag faintly implies archive_path and export_options_plist, and '.ipa' faintly implies export_dir, but no parameter is named or explained, and key facts (plist is a file path, expected plist keys, directory must exist) are absent from 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 maps the tool to a concrete command ('xcodebuild -exportArchive') and its output ('.ipa'), so an informed agent can infer it exports an existing Xcode archive into a signed .ipa. However, it never states this in plain terms and offers no differentiation from the sibling 'build_archive', which an agent could easily confuse with 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?

There is no guidance on when to use this versus 'build_archive' or any other build tool, no stated prerequisites (an archive must already exist, xcodebuild/macOS required), and no mention of ordering in a pipeline. The agent must guess entirely.

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 identifies the operation as a simulator build but does not disclose side effects, failure behavior, permission needs, or whether it installs/launches anything. Only the project path format is clarified.

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?

Very concise and front-loaded: the core action appears first, followed by a brief parameter hint. The second sentence is slightly fragmentary but still efficient and useful.

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, 0% schema description coverage, and two required parameters, the definition is missing key context about scheme semantics, device selection, and the build workflow. An output schema exists, so return values need not be explained, but the invocation context remains thin.

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

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

Schema description coverage is 0%, so the description must compensate for all parameters. It explains the 'project' parameter as a .xcodeproj/.xcworkspace path, but says nothing about the required 'scheme' parameter or the optional 'device_name' default.

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 action (build), target (project), and platform context (simulator verification). Clear enough for an agent to understand what the tool does, but it does not explicitly differentiate itself from sibling build tools such as build_test or build_archive.

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 '(verification)' hints that this is for simulator build verification, but there is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives like build_test or build_archive. Usage must be inferred.

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 only discloses one behavioral trait: iPhone simulators are ordered first. For a read-only enumeration that is mild but real added context; permissions, side effects, and whether only booted/installed devices appear are 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?

One sentence, front-loaded with the core action, and the parenthetical ordering note is the only supplementary content. Nothing extraneous.

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?

An output schema exists, so return values need not be explained, and a zero-parameter read-only tool requires little else. The only remaining gap is the unstated relationship to build_boot_sim/build_for_sim, which would help the agent sequence calls.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; no schema semantics are missing.

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 iOS simulators, with the extra detail that iPhones are surfaced first. It is clearly distinguishable from siblings like build_boot_sim or build_for_sim by name, but the description never explicitly contrasts itself with those tools, so it stops 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?

Usage is implied rather than stated: an agent can infer this is a discovery step before build_boot_sim, but the description never says when to call it or name the follow-up tool. No exclusions or alternatives are offered.

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 not disclose whether an existing file at out_path is overwritten, what permissions are needed, or what happens if no simulator is booted. For a file-writing tool with zero annotation coverage this is a real gap.

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

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

A single, front-loaded sentence with zero wasted words and the output target placed last for emphasis. It is arguably too terse, but nothing is 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?

An output schema exists, so return values need not be described. However, with no annotations and 0% schema coverage, the definition leaves overwrite behavior and UDID semantics unexplained for a two-required-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?

Schema description coverage is 0%, so the description must compensate for two undocumented parameters. It clarifies only that out_path is a PNG destination and implies udid identifies the simulator; it never explains the UDID format or confirms which simulator to target.

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 (Capture) and resource (screenshot), plus the source (booted simulator) and output (out_path, PNG). It is clearer than most siblings, though it never distinguishes itself from the nearby screenshot_capture sibling.

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

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

The phrase 'booted simulator' implies a prerequisite (a simulator must already be running, likely via build_boot_sim), but this is left implicit. There is no explicit when-to-use guidance and no mention of the screenshot_capture alternative.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it delivers almost nothing: no indication that test execution is long-running, whether a simulator must already be booted (a sibling `build_boot_sim` exists), how failures are reported, or whether artifacts/logs are produced. The only disclosed trait is the simulator environment.

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 front-loaded phrase with zero filler, so there is no verbosity problem. But it is a fragment rather than a structured sentence, and its brevity comes at the cost of under-specification rather than economy.

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?

An output schema exists, so return values need not be explained, but for a tool that spawns a test run the description omits everything else an agent needs: simulator prerequisites, expected runtime, and the meaning of the required project/scheme arguments. Given no annotations and 0% param coverage, the description is well below sufficient.

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

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

Schema description coverage is 0% for all three parameters with no annotations to compensate. The description never clarifies whether `project` is an .xcodeproj or .xcworkspace path or what form `scheme` takes; the phrase 'on the simulator' only loosely gestures at `device_name`. This is far short of compensating 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 description states a specific command and environment: it runs `xcodebuild test` against a simulator. That implicitly separates it from `build_for_sim` (build only), `maestro_test` (different runner), and `build_archive`, even though no sibling is named explicitly. It is a clear verb+resource, just extremely terse.

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 guidance at all: nothing says when to pick this over `maestro_test`, `build_for_sim`, or `cpp_build_all`, and no prerequisites (e.g. simulator boot, scheme/project format) are given. The single parenthetical is a runtime detail, 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?

No annotations are provided, so the description carries the full burden. 'Return the Xcode version' implies a harmless read with no side effects, but it does not disclose failure behaviour (e.g. what happens when Xcode is not installed) or whether it is read-only. The 'validation' framing adds some context about intent, keeping this above a 2.

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 sentence with no waste, front-loading the action and resource. Nothing could be removed 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?

An output schema exists, so the return value need not be explained, and there are no parameters to document. For a trivial version query the description is nearly sufficient, with only error/failure semantics left unaddressed.

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

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

The tool takes zero parameters, so there is no parameter syntax for the description to explain. The baseline of 4 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 states a specific verb+resource: 'Return the Xcode version.' The parenthetical 'the first validation tool of the build_* group' positions it within a family of tools, which aids recognition, though it does not explicitly name a sibling it should be chosen over.

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?

Calling it 'the first validation tool of the build_* group' implies it is a preliminary preflight check to run before other build_* tools, but there is no explicit when-to-use, when-not-to-use, or named alternative. Usage is inferable rather than stated.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses that secrets are masked (a real safety-relevant trait) and that output is a presence/absence report, but says nothing about permissions, whether it reads repo or runtime config, or whether it mutates anything.

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, front-loaded with the action and resource, with the masking caveat appended where it matters. 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?

An output schema exists, so the description needn't enumerate return values, and it still sketches the report's shape (present/missing keys, masked secrets). For a zero-parameter diagnostic this is close to complete, though a hint about which config source it inspects would help.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4; there is nothing for the description to disambiguate.

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 ('Report') plus resource ('config status') and concrete output content (present/missing keys). It is clear on its own, but it never distinguishes itself from related siblings like config_set, env_doctor, or setup_status.

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 diagnostic framing implies you run this to check config health, but there is no explicit when-to-use or when-not-to-use guidance, and no routing to alternatives such as env_doctor for environment issues or config_set for fixing the gaps it finds.

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 patch semantics ('Fields left empty are unchanged'), the file written and its 0600 mode, and a security constraint (secrets never pass through the model). It does not mention validation, error behavior, or that changes are immediate/persistent beyond the file write.

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 target file, with the security caveat following. No filler; 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?

An output schema exists, so return values need not be explained, and the behavioral essentials are present. The gap is parameter meaning for an 11-field tool with zero schema descriptions, which keeps it from being 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?

11 parameters with 0% schema description coverage, and the description documents none of them individually (team_id, apple_id, asc_key_id, etc. are never explained). The only parameter-level meaning added is the general 'empty = unchanged' rule, which is insufficient 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?

States a specific verb+resource: 'Write NON-secret settings to ~/.appfactory/config.toml (0600)'. It explicitly scopes itself against the secret-handling sibling by naming setup_credentials(), so an agent can distinguish it without opening the schema.

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

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

Gives a clear exclusion ('Secrets ... are refused here') and names the correct alternative (setup_credentials()), which is genuine when-not/when-to guidance. It does not, however, position itself against the other setup_* siblings, so routing among non-secret config tools 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?

With no annotations, the description carries the safety burden, and 'LIVE writes: human approval' is genuinely important disclosure about reversibility and gating. However, it does not explain what approval_id must contain, what happens if it is omitted, whether reruns duplicate CPPs, 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?

Very compact and front-loaded: the core action and the returned URLs come first, context and the approval constraint follow. The telegraphic fragment style is efficient though slightly clipped.

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?

An output schema exists, so return value detail is not required, and the key constraint (live write + approval) is present. Still missing the approval_id contract and any note on idempotency or partial failure, which matters for a multi-step live write tool.

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

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

Schema coverage is 0%, so the description must compensate, and it partially does by documenting the themes element shape as {name, locale?} where the schema only says 'array of objects'. bundle_id and especially approval_id (the human-approval token) remain unexplained, leaving a real 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?

States a specific verb and resource ('Create one CPP per Search Ads theme') and even sketches the internal sequence (create→version→localization) plus the side output (deep-link URLs). It does not name a sibling for contrast, so it falls short of a 5, but the operation is unmistakable.

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 the input-context hint that themes come from 'the theme/keyword clusters in the ASO output', which implies when to reach for this tool. It stops short of any when-not guidance or explicit alternatives (e.g. aso_scaffold_outputs), so 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 does disclose two useful traits — that it uses a direct API path and bypasses a known fastlane 'No data' bug — and hints at gating ('ASO-gated'), but it says nothing about permissions, what gets overwritten in the draft, failure modes, or reversibility.

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?

Extremely terse and front-loaded — the core action leads and the parenthetical rationale follows. It earns most of its words, though 'ASO-gated' is a compressed term that adds ambiguity rather than 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?

An output schema exists, so return values need not be documented. But for a write/gated operation with three undocumented parameters and no annotations, the description omits prerequisite conditions, parameter meaning, and error/side-effect behavior — substantial gaps remain.

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

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

Schema description coverage is 0% and the description explains none of the three parameters. 'approval_id' in particular is an opaque, non-obvious identifier whose role (which approval, issued where) is never clarified, and app_dir vs bundle_id precedence is left ambiguous. The description 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?

States a specific verb+resource ('Upload metadata to the ASC draft'), which is clear enough to distinguish from read-oriented siblings like metadata_check or metadata_export. However, it does not name or contrast with the many nearby metadata tools (metadata_render_listing, metadata_listing_check, aso_validate_metadata), and the trailing 'ASO-gated' is a cryptic qualifier rather than a clarifying one.

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 explicit when-to-use or when-not-to-use guidance. 'ASO-gated' hints at a prerequisite stage/approval but never states the condition or names an alternative tool. The agent must infer from the presence of an 'approval_id' parameter that some approval workflow precedes invocation.

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 does well: it discloses the checksum-based incremental strategy, the skip condition (local MD5 == ASC sourceFileChecksum), and what gets uploaded (missing/changed only). It lacks details on permissions, rate limits, or failure handling, but the core sync behavior is well explained.

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 core behavior and prerequisite are front-loaded, but the parenthetical about fastlane randomly dropping images is marketing-style justification that does not help invocation. Trimming that clause would make the description tighter without losing 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?

An output schema exists, so return values need not be described, and the behavior and prerequisite are covered. However, with zero annotation coverage and zero schema description coverage, the omission of any parameter explanation and lack of auth/permission context leave gaps for a mutation tool.

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

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

Schema description coverage is 0% across three parameters, so the description must compensate for parameter meaning but does not. It never explains what app_dir, bundle_id, or approval_id expect, leaving the agent to infer their formats and roles.

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 screenshots to the ASC draft') and specifies the sync mechanism (checksum-based incremental). It clearly distinguishes its behavior from fastlane, but does not differentiate itself from close siblings like screenshot_sync or deliver_screenshots_audit, leaving some ambiguity about which upload path to choose.

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 a prerequisite ('run screenshot_build_all first') and implies when not to use fastlane. It gives clear context for invocation but stops short of naming alternative tools or exclusions among siblings such as screenshot_sync.

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 the read-only nature ('No writes'), the comparison semantics (exactly the local files, in order, all COMPLETE, matching MD5), and that it lists preview sets. It does not detail auth needs or what happens on mismatch, but the behavioral profile is well described.

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 core purpose, but the middle clause is densely packed and requires parsing around escaped quotes and parenthetical mappings. Three sentences is appropriate, yet the second sentence is information-dense and not optimally readable.

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?

An output schema exists, so return values need not be explained. The description covers the comparison contract, sequencing, and read-only guarantee for a 2-param tool. Minor gaps: no note on failure behavior when the audit finds mismatches.

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

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

Schema description coverage is 0% for two required params (app_dir, bundle_id), so the description doesn't compensate. However, both parameter names are reasonably self-evident and the description's framing implies app_dir is the project directory whose local screenshots are compared. Baseline 3 given the shallow 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+resource: 'Read-only screenshot readiness audit' of the ASC screenshot set per locale/display type. It names exact display-type mappings (APP_IPHONE_67, APP_WATCH_ULTRA) and describes what it compares, distinguishing it clearly from deliver_screenshots (which writes) and screenshot_sync.

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 sequencing: 'Run after deliver_screenshots and before submission.' This tells the agent precisely where this tool sits in the pipeline relative to a named sibling, leaving no ambiguity about when to invoke 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 idempotency ('Idempotent by MD5'), the human-approval gate, the MISSING_METADATA blocking state, and the paywall-vs-offer variant logic. It omits permission/auth details and failure modes, so not a 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?

Dense but front-loaded: the action and source path come first, then the blocking consequence, idempotency and approval note. Every sentence carries information, though the paywall parenthetical is slightly heavy.

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?

An output schema exists so return values need no explanation, and the description covers the path convention, idempotency and blocking state for a mutation tool. The gap is parameter meaning, which is left entirely to the undescribed 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 0%, so the description must compensate for all three parameters. It only obliquely touches approval via 'Human approval' (hinting approval_id) and never defines app_dir or bundle_id formats, leaving two required parameters completely 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?

Specific verb (Upload) plus precise resource (App Review screenshot of every subscription) and the exact source path convention. An agent can distinguish it from deliver_screenshots and screenshot_capture without opening a schema.

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

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

States the consequence of not running it ('a subscription stays MISSING_METADATA'), which tells the agent when this step is required. It does not name explicit alternatives or exclusions, but the 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?

With no annotations, the description carries full behavioral burden and does disclose meaningful traits: rasterization uses local headless Chrome rather than Claude in Chrome, and serve_url is single-use and never persisted. However, it says nothing about failure modes, whether out_path is overwritten, permissions, or rendering side effects, leaving notable gaps for a file-writing 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?

Front-loads the core action and mechanism, then supplies concrete examples. Four compact sentences with no filler, though the mixed prose-plus-example formatting is slightly uneven rather than tight.

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?

Output schema exists so return values need no explanation, and the description covers the confusing inputs and the rendering mechanism. But with five parameters at 0% schema coverage and no annotations, an agent still lacks documented semantics for width/height and any guidance on output overwrite or error 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 0%, so the description must compensate, and it does for the two most ambiguous parameters: serve_url's origin/lifetime and scale's multiplicative behavior (440×956 at scale=3 → 1320×2868). out_path is illustrated via 'design/icon.png'. Only width/height are left merely implied by the example rather than stated.

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 ('Rasterize') and resource ('a Claude Design board') and explicitly disambiguates the mechanism from a similarly-named one ('with local headless Chrome (not Claude in Chrome)'). An agent can tell this apart from siblings like screenshot_capture or design_generate 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?

Concrete usage context is given: serve_url originates from mcp__claude-design__render_preview, implying this tool runs after a render step, and two example invocations (app icon, store layout check) show intended scenarios. No explicit when-not-to-use or named alternative tool is provided, so this is not 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?

With no annotations, the description carries the full burden and does well: it discloses side effects (writes scaffolds and project JSON to disk), refusal conditions, and a hard boundary ('this tool never uploads'). It omits idempotency/overwrite behavior for existing files in design/scaffold/ and design/project/, which matters for a file-writing 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?

Front-loaded with the core action and follows with the concrete outputs, so the agent gets the essentials in the first clause. The long parenthetical chains are dense and slow to parse, but every clause carries real 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?

An output schema exists, so return values need not be restated, and the description still adds the useful note that the return is claude-design MCP calls rather than an upload. Given the tool's complexity, the description covers inputs, outputs, and refusal conditions adequately, with only the app_dir contract left unaddressed.

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

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

Schema description coverage is 0% and the single parameter app_dir is never explained in the description (no format, whether it is relative/absolute, or what it must contain). For a tool whose behavior depends heavily on directory layout, the description should compensate and does not.

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 ('Prepare') plus a sharply bounded resource (the Claude Design project from brief/app.spec.json/design/screens.json), with the exact artifacts enumerated (design/scaffold/, design/project/canvas.json, store_layout.json, upload_plan.json). An agent can distinguish this from siblings like design_screens_skeleton or design_research_collect without opening a schema.

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

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

Preconditions are stated clearly ('Refuses without valid research/brief or when screens/tokens are not derived from the brief'), which tells the agent when this tool will succeed. It does not name the sibling alternatives (e.g., design_screens_skeleton, design_research_brief_template) or state which stage precedes it, so routing between near-neighbors 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.