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

The annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so "does not change anything" largely restates structured data. The genuinely additive content is the current configured value and the note about which tools set keys; the returned keys are duplicated from the existing output schema.

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

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

Three compact lines, front-loaded with the read-only nature of the call and the usage trigger. Slight waste in restating the annotation ("does not change anything") and repeating the output shape already covered by the output schema, but nothing bloats the definition.

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

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

For a no-required-param, read-only inspection tool with an output schema and full annotation coverage, the description supplies what is missing: the current model value and where configuration changes belong. Nothing essential for correct invocation 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?

There is a single optional parameter with 100% schema description coverage ("AI provider ids; default ['fal.ai']"), so the schema fully documents it. The description adds no syntax, format, or defaulting semantics beyond that, making 3 the appropriate baseline.

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

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

States a specific verb and resource (report the AI provider/model selection) and pins the current value (fal.ai Flux schnell). It also differentiates itself from the mutating alternatives by naming ai_deploy_proxy and backend_deploy, so an agent can tell why this is a read of state rather than a write.

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

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

"Use when: checking which image model the backend will use" gives an explicit trigger condition, and the pointer to ai_deploy_proxy/backend_deploy for setting keys routes the agent away from this tool for writes. It stops short of naming read-side alternatives such as config_doctor or setup_status, but the when-to-use guidance 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?

Annotations cover the safety profile (destructive, idempotent, open-world), but the description adds genuinely new behavior: credits mode is 'live, needs human approval', keys go only to server-side secrets, and the call can return an approval_required refusal. It does not explain what idempotency means here or the effect of re-deploying over an existing backend.

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, then 'Use when', then 'Returns' – three tight segments with no filler. Every sentence earns its place.

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

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

Output schema exists and the return shape is restated, and the approval workflow is covered. Remaining gap: nothing explains how the subscription vs. legacy mode is chosen or how daily_limit relates to mode, which is the key ambiguity for this 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 100%, including the detailed approval_id round-trip and the daily_limit default, so the schema carries the parameter burden. The description adds no per-parameter meaning beyond that, so a baseline 3 is appropriate.

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

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

States a specific verb+resource ('Deploy the AI backend') and explicitly splits it into two modes (spec-driven subscription mode vs. legacy ai-proxy in credits mode), which lets an agent tell it apart from backend_render and backend_deploy 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?

Gives a clear positive trigger ('Use when: the app has an AI feature') and routes dry-run planning to backend_deploy explicitly. It stops short of stating when NOT to use it (e.g. when a deployment already exists) or how the two modes are selected.

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

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

Annotations already declare idempotent, non-destructive, open-world behavior, so the bar is lower. The description adds real value beyond that: it discloses the external network fetch from LottieFiles, the build-time color mapping rule (dominant to primary, others to accent), and the write target. It doesn't explicitly state overwrite behavior for an existing slot file, which is the one 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?

Front-loaded purpose sentence, then clearly labeled 'Use when:' and 'Returns:' blocks. No filler, every sentence earns its place.

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

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

With an output schema present, the description needn't explain return values, yet it does. Combined with the usage and color-mapping context, an agent has nearly everything needed; only explicit overwrite/collision behavior for an existing slot file is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the slot values already enumerated in the schema and does not clarify the keyword override or the hex format handling, so it adds little meaning beyond structured data.

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 specific verbs (fetch, recolor) and the resource (Lottie animation from LottieFiles), plus the exact output destination (Resources/Animations/<slot>.json). This is clearly distinguishable from the many sibling setup/build/deliver 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?

The 'Use when:' clause gives concrete context — once per slot (loading, success, empty, onboarding_hero) for every app — and explains downstream rendering via lottie-spm. It stops short of naming an alternative tool or stating when not to use it, so it is clear but not fully routing-aware.

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

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

Annotations already declare the safety profile (not read-only, idempotent, non-destructive, closed-world). The description adds genuinely new constraints: credit-field defaults and the requirement that pack amounts match the server-side PACK_MAP. Missing auth/permission context, but the added constraint is meaningful.

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 purpose sentence followed by clearly labeled 'Use when', 'Not for', and 'Returns' segments. No filler; every clause carries actionable information.

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

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

For a 16-parameter write tool with full schema coverage and an output schema, the description covers purpose, preconditions, alternatives, key defaults, and the PACK_MAP constraint. Nothing material is missing.

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

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

Schema coverage is 100%, so per-field semantics are already documented (baseline 3). The description adds value by summarizing the credit defaults and flagging the cross-parameter PACK_MAP consistency requirement, which the schema cannot express.

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?

Uses a specific verb ('Fill in') against a named resource ('scaffolded app's AppConfig and StoreKit tokens') and enumerates the exact token categories covered. An agent can distinguish it from siblings like app_sync_spec 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?

Explicit 'Use when: after backend and RevenueCat values exist' gives the precondition, and 'Not for: spec-driven changes (edit app.spec.json, then app_sync_spec)' names both the exclusion and the correct alternative. This is the gold standard for 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?

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuine side-effect context beyond the annotations: it initializes a pipeline manifest and a local git repo, and notes the spec drives StoreKit, locales, onboarding and monetization/backend modes. It does not state failure behavior on re-run or auth prerequisites, so not a full 5.

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

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

Three front-loaded blocks (action, use-when/not-for, returns) with no filler. The returns line is brief and, although an output schema exists, it costs little and improves scanability.

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 present, return values need not be explained, and the description still summarizes them. Purpose, trigger, alternative and side effects are all covered, leaving only minor gaps such as behavior when the destination already exists.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes further by enumerating what the 'spec' parameter drives (products, StoreKit file, locales, onboarding length, monetization and backend mode), which the schema does not explain, adding real meaning to the most important 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?

States a specific verb and resource ('Scaffold a new SwiftUI app from app.spec.json') plus the concrete mechanisms involved (xcodegen, pipeline manifest, local git repo). It also names the sibling it is not (app_sync_spec), so an agent can distinguish it from adjacent tools 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?

Explicit 'Use when: starting a new app after idea validation' gives the trigger, and 'Not for: editing an existing app (use app_sync_spec after changing the spec)' names both the exclusion and the correct alternative. This is exactly the when/when-not/alternative structure.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=false. The description adds real value on top: it discloses that String Catalogs are destructively pruned to locales.app, and that writes are local-only — details the annotations do not express.

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 lines with the action front-loaded and the usage condition immediately after. 'Returns: {ok, files}' is mildly redundant given an output schema exists, which is the only thing keeping it from 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?

For a single-parameter, idempotent local-write tool with an output schema and full annotation coverage, the description supplies the trigger, the scope, and the destructive pruning caveat. Nothing essential for correct invocation is missing; naming an alternative sibling would make it complete.

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

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

There is a single required parameter with 100% schema description coverage, including a format example (/Users/me/Apps/MyApp), so the schema carries the full burden. The description adds no path or format guidance beyond it, making the baseline 3 appropriate.

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

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

The description names a specific verb (Regenerate) plus the exact artifacts produced (AppSpec.swift, PaywallSource.swift, Configuration.storekit) and an additional pruning action, so the agent knows precisely what the tool does. It does not, however, distinguish itself from nearby siblings such as storekit_generate, which an agent might reasonably confuse with the Configuration.storekit output.

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

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

'Use when: after editing app.spec.json' gives an explicit trigger condition, and 'Local writes only' scopes the operation. It stops short of naming when NOT to use it or pointing at a sibling (e.g. storekit_generate) as the alternative, so it is clear context without 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?

Annotations already declare destructiveHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds genuinely new context beyond that: it is a 'live write' requiring human approval, the MISSING_METADATA prerequisite, and the return/refusal shape. It does not, however, explain the destructive nature flagged by annotations or how the idempotency interacts with approval retries.

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 labeled lines (purpose, when, returns), front-loaded with the scope and the sibling routing before the return shape. No filler 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?

Covers the approval-required flow, the MISSING_METADATA motivation, and the return/refusal contract, and an output schema exists so return values need no expansion. The only gap is the destructive behavior implied by annotations, which the description never addresses.

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

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

Schema description coverage is 100%, so all four parameters including the approval_id workflow are already documented in the schema. The description adds only an implicit hint that locale granularity is per-call, not new syntax or format detail, so baseline 3 applies.

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

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

States a specific verb and resource ('Add one display-name localization to a subscription group') and explicitly distinguishes itself from the plural sibling ('For many languages use asc_localize_group'). An agent can route between the two without opening either schema.

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

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

Gives an explicit use condition ('when: a single locale is needed') and names the alternative plus the condition that selects it ('For many languages use asc_localize_group'). Nothing is left to inference.

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

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

Annotations cover safety flags (destructiveHint, idempotentHint, openWorldHint), but the description adds context beyond them: it is a live write requiring human approval, idempotency works by skipping when the marker is present, output is truncated to 4000 characters, and it can return an approval_required refusal. That approval workflow and truncation constraint are genuinely new information for the caller.

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, then uses compact labeled clauses ('Use when:', 'Not for:', 'Returns:') that each carry distinct information. No sentence is redundant or 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?

With an output schema present, return values need no expansion, yet the description still summarizes them. Combined with annotations and full schema coverage, an agent has everything needed: trigger, exclusion, write/approval behavior, idempotency, and truncation limit.

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

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

Schema description coverage is 100%, so bundle_id, terms_url, approval_id, privacy_url and disclosure_by_locale are already fully documented in the schema. The description alludes to the approval_id round-trip via the 'approval_required refusal' mention but adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb (append) and resource (subscription disclosure, Terms/EULA and Privacy links to the app description, in every language) with the Apple 3.1.2 rationale. It also explicitly names the sibling it is not (deliver_metadata), so an agent can separate it from other metadata tools 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?

Provides an explicit 'Use when: preparing a subscription app for review' trigger and a 'Not for: uploading other metadata (use deliver_metadata)' exclusion with a named alternative. Nothing about when to select this versus siblings 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?

Annotations already declare destructiveHint=true, idempotentHint=false, openWorldHint=true, but the description adds critical behavior they cannot: this is a live write gated by human approval, the first call may return an approval_required refusal, and a re-call with approval_id is needed. That two-phase approval protocol is genuinely new information.

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, then explicit Use when / Not for / Returns sections. Dense and skimmable with no filler sentences; every clause carries routing or behavioral 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?

Covers the destructive-write risk, the approval prerequisite, and the refusal outcome well, and an output schema exists so return values need not be detailed further. Minor gap: it doesn't state that the bundle_id must already exist (create_bundle_id ordering), though the 'Not for' clause implies the relationship.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema, including candidate_names first-available semantics and approval_id's retry role. The description adds only a restatement ('pass candidate_names and the first available is used'), so the 3 baseline applies.

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

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

States a specific verb+resource ('Create an app shell in App Store Connect') and names the underlying mechanism (fastlane produce). The 'Not for' clause explicitly distinguishes it from asc_create_bundle_id and deliver_metadata, so an agent can route without opening another schema.

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

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

Gives an explicit precondition ('after aso_check_name confirms a free name'), the key argument to pass (candidate_names, with first-available semantics), and explicit exclusions naming the sibling tools that cover bundle ids and metadata. Full when/when-not/alternative coverage.

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

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

Annotations already declare destructive=true, openWorld=true, and idempotent=false, so the mutation/risk profile is covered. The description adds genuinely new behavioral context beyond that: the live-write-needs-human-approval requirement and the approval_required refusal path. It stops short of disclosing what a partial capability failure does or how retries interact with the created bundle id, so it falls just under full marks.

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 tightly structured blocks (purpose, Use when / Not for, Returns) with zero filler. The action and its routing constraint are front-loaded ahead of the return-shape detail.

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

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

For a destructive, approval-gated mutation this covers everything the agent needs: prerequisites (capabilities before signing), the sibling to use instead, the approval loop, and a return shape. An output schema exists, so the brief 'Returns' line is appropriately terse rather than duplicative.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents all five parameters including approval_id and apply_capabilities. The description adds value by naming the concrete capabilities acted on (IN_APP_PURCHASE, Sign in with Apple, HEALTHKIT if enabled), which the boolean apply_capabilities does not convey.

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') plus the secondary action (check or apply App ID capabilities). It explicitly distinguishes itself from the sibling asc_create_app, so an agent can route correctly without opening either schema.

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

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

Has an explicit 'Use when' (first ASC step for a new app; capabilities must exist before signing) and an explicit 'Not for' that names the alternative tool (asc_create_app). Both the positive and negative selection conditions are 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?

Annotations already disclose destructive=true, idempotent=false, openWorld=true, so the safety profile is covered. The description adds real value beyond them: 'live write, needs human approval' and the 'approval_required refusal' outcome, which explain the human-in-the-loop gate the agent must expect. It stops short of detailing reversibility or timing, hence a 4 rather than 5.

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

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

Three short lines, each earning its place: purpose, routing rule, return contract, all front-loaded with no filler.

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

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

An output schema exists, so the return-value line is a helpful bonus rather than a necessity, and it flags the non-obvious approval_required refusal path. Combined with the approval flow documented in the schema, an agent has everything needed to call 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 100%, so every parameter (including the approval_id retry flow) is fully documented in the schema. The description adds no parameter-level meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('Create a subscription product inside a subscription group'), which cleanly distinguishes it from siblings like asc_create_subscription_group and asc_finalize_subscription. The parenthetical scope '(live write, needs human approval)' sharpens it further.

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

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

Explicitly names the use condition ('Use when: hand-building a single product') and the preferred alternative ('Prefer store_setup for the whole spec'), routing the agent without 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?

Annotations already declare write/destructive/non-idempotent, and the description corroborates plus adds the crucial out-of-band approval requirement and the refusal shape ('or an approval_required refusal'). It stops short of detailing what the live write mutates downstream, so a 4.

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 'Use when' and 'Returns' labels; the approval caveat is front-loaded in the first line. No filler.

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

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

With an output schema present and full schema coverage, the description covers what an agent needs: purpose, alternative, approval workflow, and refusal case. Minor gap is the absence of success/error nuance beyond the refusal, but nothing essential is missing.

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

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

Schema coverage is 100%, so the schema already documents app_id, reference_name, and the approval_id flow in detail. The description adds no parameter-level syntax or constraints beyond it, so baseline 3 applies.

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

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

States a specific verb and resource ('Create a subscription group for an app') and immediately scopes it as a live write requiring approval. It is clearly distinguishable from siblings like asc_create_subscription and store_setup.

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 gives the when ('hand-building the subscription tree') and names the preferred alternative with the reason ('store_setup, which does groups, products, prices and offers idempotently from app.spec.json'). This is textbook 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?

Adds substantial behavior beyond the annotations: a live write requiring human approval, an out-of-band approval flow via approval_required refusal, and skip semantics ('Idempotent: priced subscriptions are skipped'). Annotations already declare destructiveHint and idempotentHint, but the description supplies the approval workflow and exact return shape that an agent needs.

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

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

Three tight sentences, front-loaded with the action, followed by the trigger condition and return shape. Every sentence carries unique information and there is no redundancy.

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

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

Covers purpose, when-to-use, idempotency, approval requirement, and return/refusal outcomes. With an output schema present and annotations covering safety, the description is complete enough for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so all four parameters including the approval_id workflow are already documented in the schema. The description adds no parameter-level syntax or format detail beyond what the schema provides, making the baseline 3 appropriate.

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

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

States a specific verb and resource: 'Set a price on every subscription of the app that has none'. The MISSING_METADATA condition makes the scope distinctive, but no sibling tool is named as an alternative, so it stops short of full sibling differentiation.

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

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

Gives an explicit trigger: 'Use when: subscriptions are stuck in MISSING_METADATA for price.' This is clear context for invocation, though it does not state when not to use the tool or name an alternative for other pricing scenarios.

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

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

Adds real value beyond annotations: it discloses that this is a 'live write, needs human approval', describes the approval_required refusal path, and states fallback behavior for missing copyright and contact_email. However, annotations flag destructiveHint=true and the description never explains what existing listing values this overwrite or what 'destructive' means here, leaving one meaningful 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?

Front-loads the core purpose, then uses tight 'Use when:' and 'Returns:' labeled clauses. Zero filler and every sentence carries operational information.

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

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

An output schema exists, so the brief Returns summary is sufficient, and the description covers the approval refusal mode and the App Privacy caveat. It is largely complete, with only the unexplained destructive semantics of the write left out.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including the copyright/support_email fallbacks that the description repeats. The description adds no format or constraint detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Fill the submit-blocking app-level fields in one call') and enumerates the concrete fields it writes (content rights, copyright, age rating, price, review contact/notes). It distinguishes itself from the sibling asc_submit_for_review by positioning as the prerequisite step.

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

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

'Use when: once per app before asc_submit_for_review' gives explicit timing and routing. It also states an exclusion condition (App Privacy must be set in the ASC web UI because it is not in Apple's API) and describes the approval-gated retry flow.

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

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

Annotations already declare destructive/idempotent/openWorld hints, but the description adds material context beyond them: 'live write, needs human approval', the approval_required refusal, availability excluding CHN, and the per-step return shape. It stops short of detailing exactly what the live write mutates, but the approval workflow is a meaningful disclosure.

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

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

Front-loads the operation and its ordered steps, then 'Use when' guidance, then the return contract. Every sentence carries distinct 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?

Given an output schema exists, return values need not be explained, yet the description still gives the shape and the approval refusal path. Combined with rich annotations and full schema coverage, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so all 7 parameters including approval_id and intro are already documented in the schema. The description only restates the intro example ('P3D') and offer-product rule, adding marginal value over the schema.

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

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

States a specific verb+resource ('Finalize one subscription') and even enumerates the ordered sub-steps (localization, availability, price, intro offer). It distinguishes itself from sibling store_setup by scoping to a single product.

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 'Use when: fixing a single product by hand' and names the preferred alternative store_setup with the reason (does every product idempotently). Clear when-to-use and routing to the better tool is fully specified.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds 'live, read-only' and a return shape, but these are largely redundant with the annotations or output schema. It does not disclose auth requirements or error/rate-limit behavior, so it adds only modest behavioral context.

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

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

The description is short, front-loaded, and structured as purpose, usage, exclusion, and return shape. Every sentence earns its place with no filler or repetition.

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

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

For a simple one-parameter, read-only lookup tool with full schema coverage, annotations, and an output schema, the definition is complete. It covers what the tool does, when to use it, when not to use it, and the alternative, so an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, and the single required parameter bundle_id is fully documented in the schema with reverse-DNS format guidance. The description mentions bundle id as the lookup key but adds no syntax or format meaning beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb and resource: find one App Store Connect app by bundle id. It explicitly distinguishes itself from the sibling listing tool asc_list_apps, so an agent can select it correctly 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?

Includes explicit when-to-use guidance ('you need the numeric app id for a known bundle id') and a clear when-not-to-use exclusion ('Not for: listing all apps (use asc_list_apps)'). The alternative is named directly.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds that results are 'live' (not cached), which is genuinely beyond the annotations, though it does not discuss pagination 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?

Three short, front-loaded lines: purpose, usage, returns. No filler; the scoping and routing information comes before any detail.

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?

Despite the output schema already existing, the description stays complete for a zero-parameter list tool: purpose, when to use, alternative, and return shape are all present. Nothing an agent needs to call it correctly is missing.

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

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

The tool takes no parameters, so there is nothing to disambiguate; baseline 4 applies. No parameter-level guidance is possible or needed.

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

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

States a specific verb ('List') and resource ('apps in App Store Connect') and immediately scopes it as live and read-only. It is clearly distinguishable from asc_get_app, which retrieves a single app.

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 'Use when: you need app ids or want to see what exists' plus direct routing to the alternative 'To find one app by bundle id use asc_get_app'. Both the when and the when-not are stated.

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

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

Beyond the annotations (which already declare destructive, idempotent, open-world, and non-read-only), the description adds the critical behavioral trait that this is a live write requiring human approval, and it describes the approval-refusal outcome. This goes well beyond what the structured annotations provide.

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 three tight sentences: purpose first, usage condition and alternative second, return shape third. Every sentence earns its place and the most important information is front-loaded.

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

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

Given the output schema already exists, the description need not explain return values in detail, yet it still does briefly. Together with the rich annotations and the explicit alternative for single-locale use, an agent has everything needed to call this tool correctly.

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

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

Schema description coverage is 100%, so the schema already fully documents group_id, approval_id, and name_by_locale. The description adds no additional syntax or format details for the parameters, so the baseline of 3 applies when the schema does the heavy lifting.

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

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

The description states a specific verb and resource ('Localize a subscription group's display name') and scope ('in many languages at once'). It also distinguishes itself from the sibling asc_add_subscription_group_localization for the single-locale case, so an agent can select it correctly without opening schemas.

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

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

It gives explicit when-to-use guidance ('Use when: several locales are needed') and an explicit alternative ('for one locale use asc_add_subscription_group_localization'). The condition that selects the alternative is clear, leaving no inference needed.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the safety profile is covered structurally. The description adds genuinely non-redundant context: it is a live write requiring human approval, unsupported locales are silently skipped, and the result/refusal shapes are named.

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 front-loaded lines: action, when-to-use, and return contract. No filler, and the approval caveat is placed where an agent will read it before invoking.

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 re-explained at length, and annotations cover safety. The description still supplies the approval_required refusal path and locale-skipping behavior, leaving little an agent needs missing.

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

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

Schema description coverage is 100%, including the approval_id round-trip protocol, so the schema carries parameter meaning. The description adds little beyond reinforcing the batch-locale semantics, which is baseline-3 territory when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Localize a subscription's name and description in many languages at once'), which cleanly separates it from the group-level localization siblings such as asc_localize_group. It never names an alternative explicitly, but the resource qualifier does the differentiation work.

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

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

'Use when: filling per-locale product copy' gives clear context for invocation. It does not name alternative tools (e.g., asc_localize_group vs asc_add_subscription_group_localization) or state exclusions, so it stops short of the 5 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?

Annotations already declare readOnlyHint/idempotentHint/openWorldHint, so the safety bar is lower. The description adds real value beyond them: required Finance-role credentials (asc_finance_key_id, asc_finance_key_filepath, asc_vendor_number) and the 403 error behavior, which an agent needs to pre-flight the call.

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 purpose, then clearly delimited 'Use when' and 'Returns' sections. Every sentence carries information: the ratio heuristic, the auth requirement, the failure behavior, and the return shape.

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 and the description still summarizes the shape ({ok, ratio, program, report_date}). With auth prerequisites, error behavior, and usage trigger all present, nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so days_back and report_date are fully documented in the schema. The description only implies 'latest report' semantics and adds no syntax or format detail beyond that, which matches the baseline 3 for schema-covered parameters.

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

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

States a specific verb and resource ('Prove Small Business Program status from the latest subscription sales report') plus the discriminating detail (0.85 SBP vs 0.70 standard ratio). An agent can distinguish it from the other asc_* siblings such as asc_token_check or asc_list_apps at a glance.

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

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

'Use when: confirming the 15% commission' gives an explicit trigger condition, and the description states the Finance-role key prerequisites and the 403 failure mode. It does not name an alternative tool, but no obvious sibling competes for this purpose, so the guidance is clear without 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?

Annotations already flag destructive/non-idempotent/openWorld, but the description adds non-obvious behavior: it ALWAYS requires out-of-band human approval even with approvals disabled, and it discloses the failure modes (approval_required refusal, {ok:false, blockers, next}). This is exactly the kind of gating and refusal semantics an agent cannot infer from structured fields.

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 labeled blocks (purpose, Use when/Not for, Returns) with the critical write/approval warning front-loaded. Every sentence carries routing or behavioral information; 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?

The tool is a high-stakes irreversible write with only two params and an output schema; the description covers the approval gate, the alternative tool, and a return-shape summary. Nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description nudges higher by stating the consequence of a missing/invalid approval_id ('nothing is submitted') and reinforcing the re-call flow. It does not add much beyond the already-detailed schema text for approval_id.

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

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

States a specific verb+resource ('Submit the app to App Store review') and immediately qualifies it as a live write. It explicitly contrasts with the nearest sibling ('Not for: uploading a TestFlight build (use testflight_ship)'), so the agent can route correctly 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?

Provides an explicit 'Use when' precondition (everything ready + human approved) and an explicit 'Not for' exclusion naming the alternative tool. Nothing about when to select this tool 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuinely new context: the call is live, it validates key id/issuer/.p8, and it returns auth_source/keychain_profiles diagnostics, which annotations alone would not convey.

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, then when/not-for and returns on their own lines. The returns block enumerates fields that the output schema already covers, so a small amount of it is redundant, but the structure remains 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?

For a parameterless diagnostic with a full output schema, the description supplies trigger, exclusion, and mechanism. An agent has everything needed to decide when to run it before the asc_* family.

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 beyond the no-arg nature that the empty schema already implies.

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 ('Verify App Store Connect authentication through the asc CLI') with the mechanism (one live read-only call). It explicitly names the sibling it is not: listing apps (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?

Gives an explicit 'Use when' trigger (before any asc_* tool, to confirm key id, issuer and .p8 work) and an explicit 'Not for' exclusion routing to asc_list_apps. Nothing is left to inference.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, open-world), so the bar is lower; the description still adds real signal by disclosing the exact-match-only methodology, which tells the agent this will not surface near-collisions or fuzzy matches. It also names the response keys, though those live in the output schema.

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

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

Three short, front-loaded lines: purpose first, then a labelled 'Use when:' routing clause, then returns. Zero 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 two-parameter read-only lookup with an output schema, the description supplies purpose, the one sibling fallback, and the matching method — nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description adds nothing about the 'country' storefront scoping or default 'us', so the baseline 3 applies.

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

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

States a specific verb ('Check whether ... is free'), the exact resource (App Store app name), and even the mechanism ('exact-name collision in iTunes Search'). It is immediately distinguishable from the sibling aso_find_available_name, which it names.

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

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

The 'Use when:' clause gives a concrete trigger ('testing one name before asc_create_app') and an explicit alternative with its selecting condition ('For several names use aso_find_available_name'). No inference required.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, openWorld), but the description adds high-value context beyond them: the source is flagged 'fragile, undocumented', failure semantics are spelled out (ok:false and prices null mean unknown, not free), and the return payload is tagged untrusted_content. These are exactly the behavioral facts an agent needs and cannot get from structured fields.

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, front-loaded sentences with zero filler: purpose first, then when-to-use plus the id source, then the failure/return contract. Every sentence carries distinct information.

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

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

For a 2-param read tool with a declared output schema and rich annotations, the description covers the remaining gaps: the unreliability of the upstream source, the meaning of a null prices result, and the untrusted nature of the data. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so both app_id and country are already documented in the input schema, including the note that app_id is the iTunes trackId for this tool. The description restates that same fact, adding little beyond the schema – baseline 3 applies.

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

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

States a specific verb and resource ('Fetch a competitor's subscription/IAP price ladder from its App Store product page') with clear scope limited to competitors, which cleanly separates it from the account-side pricing tools (asc_ensure_subscription_prices, pricing_unit_economics). 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?

'Use when: setting our pricing' gives explicit context, and it names aso_fetch_competitors as the upstream source of the required app_id. It stops short of stating when NOT to use it or naming any alternative competitor-pricing tool, so it is clear but not fully exhaustive.

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

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

Annotations already cover idempotency and non-destructiveness, so the bar is lower; the description adds genuinely new behavioral context by disclosing the gate-opening side effect and the refusal-with-missing-items outcome on failure. It does not clarify whether validation failure leaves any partial state, which is the one remaining ambiguity for a mutating 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?

Three short, front-loaded clauses: action, usage routing, and return shape. Every sentence carries information and nothing is repeated from the annotations or schema.

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

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

For a single-parameter mutation tool with an output schema, the description covers the action, the routing rule, and the side effect on the pipeline gate. Return values are already captured by the output schema, so nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and there is only one parameter, so the schema already documents app_dir fully. The description adds no format or path semantics beyond what the schema provides, which matches the baseline 3 for a fully-covered single parameter.

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

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

The description names a specific verb+resource pair ('Validate the ASO output') and goes further by stating the state transition it performs ('mark the 'aso' stage done, opening the metadata/deliver gate'). It explicitly contrasts itself with the sibling pipeline_mark, so an agent can distinguish them without opening either schema.

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

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

It gives an explicit trigger ('Use when: ASO files are written') and an explicit exclusion with an alternative ('Not for: other stages (use pipeline_mark)'). This is the full when/when-not/alternative pattern.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds genuinely new context: it is a live call to iTunes Search, and the response is tagged untrusted_content, which is security-relevant and not visible in annotations.

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

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

Three short, front-loaded sentences — purpose, usage/alternatives, then return shape. No filler and the key routing information is not buried.

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

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

For a read-only fetch with an output schema (so return values need not be spelled out), the description still summarizes the payload and flags untrusted_content. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so term, limit and country are fully documented in the schema. The description adds no syntax or format details beyond that, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource ('Fetch competitor apps for a search term') and names the underlying source ('through iTunes Search'), which lets an agent distinguish it from aso_niche_score and aso_competitor_iap.

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 'Use when' clause (sizing up a niche, gathering trackIds for aso_competitor_iap) and routes the agent to a named alternative ('For a scored go/no-go use aso_niche_score'), covering both when and when-not.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds genuinely useful behavior beyond them: it selects the FIRST available name (ordering semantics) and discloses the failure mode ({ok: false} if none is free). It does not restate the return shape much beyond the output schema, so it stops short of 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?

Three tight lines with the action front-loaded, followed by usage and return. Every sentence earns its place with zero filler.

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

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

With an output schema present and full schema coverage, the description covers purpose, usage, alternative, and the none-free fallback. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so both the country and candidates parameters are already documented in the schema. The description adds no syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Pick the first available App Store name from a candidate list') and names the sibling it differs from ('For one name use aso_check_name'). An agent can distinguish it from aso_check_name without opening either schema.

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

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

Explicit 'Use when' clause gives the triggering condition (ordered name options, avoiding rejection of taken names) and routes the single-name case to the alternative aso_check_name. Nothing is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), but the description adds real behavioral value the annotations cannot: the verdict thresholds (GO >=60, MAYBE >=40, WEAK, REJECT conditions) and the untrusted_content flag on output. It omits any latency/cost or source-of-data context, so it is strong rather than complete.

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, front-loaded chunks: what it does, when to use it vs the sibling, and the verdict logic. Every sentence 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, yet the description still restates the return shape, which is mildly redundant but harmless. The verdict thresholds and untrusted-content warning are useful additions that make the definition callable with confidence; only minor gaps (e.g., what 'demand'/'competitors' contain) 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 100%, so the schema fully documents term, genre, and country. The description only implicitly echoes the 'idea' input and adds no syntax, format, or default guidance beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Score an idea 0-100') plus the exact scoring dimensions (demand, competitor weakness, saturation, monetization) and a verdict output. It explicitly differentiates itself from the sibling idea_evaluate, so an agent can pick it without opening either schema.

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

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

'Use when: ranking one idea quickly. For the full evidence bundle use idea_evaluate' gives both the condition for use and the named alternative with its selecting condition. Nothing is left to inference.

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

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

Annotations already declare the mutation/safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the description only needs to add context. It usefully notes the side effect of creating an outputs skeleton and that skill instructions are returned, but it does not say what happens to pre-existing outputs on a re-run, despite claiming idempotency.

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, front-loaded sentences with the action, trigger, and follow-up in priority order. The trailing 'Returns: {ok, outputs_dir, instructions}' is mild redundancy given a declared output schema, but it is compact.

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 annotations, a 100%-covered schema, and an output schema, the description only needs to supply purpose and sequencing, which it does. The main missing piece is disambiguation from aso_scaffold_outputs and behavior on repeat invocation.

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

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

Schema description coverage is 100% and the single app_dir parameter is fully documented in the schema, so the description adds nothing beyond it. Baseline 3 is appropriate when the schema carries all parameter meaning.

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

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

States a specific verb and resource: 'Start the mandatory ASO stage: create the outputs skeleton and return the skill instructions.' An agent can tell this is the ASO stage entry point rather than a completion or validation step. It does not, however, distinguish itself from the closely named sibling aso_scaffold_outputs, which the phrase 'create the outputs skeleton' would otherwise suggest.

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

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

Gives explicit activation context ('Use when: the pipeline reaches ASO') and names the terminating counterpart ('Finish with aso_complete'), which is genuine routing information. It stops short of exclusions, e.g. when to prefer aso_scaffold_outputs over this tool or what to do if the stage was already started.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false, covering the safety/mutation profile. The description adds the default 32-language scope, but says nothing about what happens to pre-existing files on a repeat call (idempotency semantics) and its 'Returns' line merely restates the output schema.

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

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

Three short, front-loaded sentences with clear 'Use when' and 'Returns' labels and no filler. The Returns sentence is redundant given the output schema, which is the only wasted line.

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 annotations, a 100%-covered schema, and an output schema present, the description covers purpose, routing, and return shape adequately. Only the idempotent-overwrite behavior on existing files is left unstated, a minor gap for this scaffolding 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 100%, so app_name, base_dir, and locales are fully documented in the schema. The description's '32 languages' note loosely reinforces the locales default but adds no syntax or format detail beyond what the schema already provides; baseline 3 applies.

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

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

Specific verb (Create) plus concrete resource (outputs/<App>/ ASO skeleton with apple-metadata.md in 32 languages). It explicitly distinguishes itself from the sibling aso_run, so an agent can choose between them without opening schemas.

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

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

Explicit 'Use when: standalone ASO work' paired with 'Inside the pipeline use aso_run' gives both the positive condition and the named alternative, which is exactly the routing guidance an agent needs.

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

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

Adds important behavior beyond the annotations: 0 suggestions for a real term is treated as no demand, and endpoint errors return ok:false rather than an empty list. It also notes the response contains untrusted_content, which is valuable safety context for an open-world read 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 purpose, follows with usage guidance, then error/return behavior in three compact sentences. Every sentence carries useful 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?

Given the rich annotations, full schema coverage, and an output schema, the description is complete enough. It adds the interpretive hard-gate rule and error behavior without unnecessarily restating return fields.

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

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

Schema description coverage is 100%, so the schema already documents term, expand, and country. The description repeats that expand=true appends a-z but adds no further parameter syntax or default semantics beyond the schema.

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

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

States a specific verb and resource: query App Store autocomplete for real search demand. The 'idea-stage hard gate' framing makes the function clear, but it does not explicitly differentiate itself from sibling ASO/idea-validation tools such as aso_niche_score or idea_evaluate.

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

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

Provides clear usage context: use when validating an idea or expanding keywords, with expand=true for a-z expansion. It does not name alternatives or state when-not to use it, so it falls short of explicit sibling 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description goes beyond that by disclosing failure semantics ('an unknown genre returns ok:false, never the overall chart') and the return envelope, which are real behavioral traits not encoded in the structured fields.

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 lines, purpose first, then routing guidance, then return/error behavior. Every sentence carries information and none is redundant.

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

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

An output schema exists, so the description need not explain return values in depth, yet it still summarizes the envelope and the error path. Combined with the annotations and full schema coverage, an agent has enough to call this correctly; only minor depth (e.g. ranking or pagination semantics) 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 100%, so genre, limit, and country are fully documented in the schema itself. The description adds a little framing ('optional category', 'storefront') but no syntax or format detail beyond what is already there, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List the top-grossing apps') and pins down the scope ('of a storefront and optional category'), plus the purpose ('as a revenue proxy'). The sibling it is not (idea_harvest) is named, so an agent can route 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?

'Use when: hunting proven ideas in one category' gives an explicit triggering context, and the next sentence names the alternative (idea_harvest) with the condition that selects it ('sweep all categories and storefronts'). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so safety is covered; the description reinforces this with 'pure calculation, no network'. It also surfaces the domain rule that apple_cut is 0.15 for Small Business else 0.30, which is genuine behavioral context beyond the annotations.

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

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

Front-loaded with the core purpose, then compact 'Use when / Not for / Returns' segments; every sentence carries information and there is no filler despite covering purpose, routing and output shape.

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

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

For a no-required-param, pure-calculation tool with full schema coverage and an output schema, the description supplies the missing routing context and the domain-specific apple_cut rule. An agent has everything needed to select and 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 100%, so every parameter (including defaults and the Small Business cut) is already documented in the schema. The description only summarizes the input domain as 'prices, credits and AI cost' and largely repeats the apple_cut rule, adding little beyond the structured field text.

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

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

States a specific verb (Compute) plus the exact outputs (margin, break-even, warnings) and inputs (prices, credits, AI cost), and adds a scoping qualifier ('pure calculation, no network'). It explicitly names the sibling it is not (pricing_unit_economics), so an agent can discriminate it from the large tool list.

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?

Contains explicit 'Use when: idea/scaffold stage pricing decisions' and 'Not for: measured-cost economics for a built app (use pricing_unit_economics)', giving both the trigger condition and the named alternative. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so safety is covered. The description adds real value beyond that by specifying the validation scope (fields and character limits) and the failure payload shape {ok, problems: [...]}, which tells the agent this can return a non-fatal negative result rather than throwing.

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 labeled blocks (action, Use when, Returns) with the artifact path front-loaded. Every sentence carries routing or contract information; 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?

For a two-parameter read-only validator with a full output schema, the agent has the target file, the required inputs, the sibling alternatives, and the result contract. Nothing needed to invoke or interpret the call correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already fully documented in the schema. The description only restates them at a high level ('by app name and base dir') without adding format, path-resolution, or default semantics, so the baseline 3 applies.

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

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

States a specific verb (validate) plus the exact artifact it operates on (outputs/<App>/02-metadata/apple-metadata.md) and the validation dimension (fields and character limits). This is distinguishable from metadata_check and aso_complete without opening any schema.

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

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

Explicitly names the 'when' condition ('checking ASO output by app name and base dir') and routes to two alternatives with their selecting conditions: metadata_check for an arbitrary file, aso_complete to mark the stage done. Nothing is left to inference.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is partly covered. The description goes further by disclosing the human-approval gate and the approval_required refusal path and the two-call choreography, which are not in the annotations. It stops short of stating what a live run irreversibly changes (e.g. migration/data impact), so not a full 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?

Front-loaded verb+resource, then structured "Use when / Not for / Returns" segments that are scannable. Slightly dense with parentheticals, but every sentence carries actionable information and nothing is padding.

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

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

For a destructive, open-world deploy tool with an output schema present, the description covers purpose, sequencing, exclusions, dry-run default, approval flow and refusal shape. Since the return schema exists, the brief "Returns" line is sufficient rather than duplicative.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning the schema does not fully convey: that dry_run=true performs "no call" and that approval_id is threaded from a prior approval_required refusal on a repeat call. That approval round-trip semantics is genuinely beyond the property descriptions.

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

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

States a specific verb (Deploy) and resource (the spec's Supabase backend) and enumerates the components involved (migrations, secrets, auth, legal build, edge functions). It explicitly distinguishes itself from the SQL and secret siblings by name, so an agent can select it without opening another 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?

Provides explicit sequencing ("Use when: after backend_render"), an explicit exclusion list with named alternatives (supabase_run_sql, supabase_set_secret), and clarifies the dry_run default path. Nothing about when to pick this tool 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?

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds genuinely useful context beyond them: it is offline, it mutates the workspace by pruning supabase/ to the monetization mode, and nothing is deployed. It stops short of saying what pruning destroys or how failures are surfaced.

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 lines: purpose with parenthetical qualifiers first, then when-to-use, then return shape. Every sentence carries information and the most important scoping fact (offline, nothing deployed) is front-loaded.

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

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

For a single-parameter, annotated mutation tool with an output schema, the description covers purpose, timing, side-effect scope, and return fields. The returns line is largely redundant with the existing output schema, and error behavior (ok=false cases) is not touched.

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

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

Only one parameter exists and schema description coverage is 100%, so the schema already documents app_dir fully. The description's reference to app.spec.json adds modest context (the spec file drives the render) but no syntax or format detail beyond the schema.

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

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

The description names a specific verb and resource ('Render the scaffolded backend from app.spec.json') and enumerates the concrete operations performed (prune supabase/, generate shared config, legal sources, listing locales). This is clearly distinguishable from siblings like backend_deploy or legal_render.

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

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

It gives explicit sequencing ('after editing the spec, before backend_deploy') and names the sibling it precedes, plus the key negative constraint 'Nothing is deployed'. The agent knows exactly when this tool is the right choice versus the deploy tool.

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

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

Annotations already declare the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=false). The description adds that it invokes xcodebuild against a generic iOS device, which is useful behavioral context, but says nothing about side effects like archive_path overwrite behavior or signing requirements. Adequate but not rich.

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, front-loaded lines: purpose, when-to-use/alternative, and return shape. No filler and everything 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, and the description even summarizes the return shape, so an agent knows what to expect. Combined with annotations covering safety, the only mild gap is that mutation side effects on archive_path are unstated.

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

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

Schema description coverage is 100%, so all four parameters (scheme, project, archive_path, configuration) are already documented with examples and a default. The description adds no parameter-level meaning beyond the schema, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific command (xcodebuild archive), its scope (generic iOS device) and its concrete output artifact (.xcarchive). An agent can immediately distinguish it from sibling build tools like build_for_sim or build_export_ipa.

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

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

Explicitly names the context ('manual signing pipeline steps') and the alternative for the full flow (testflight_ship). The condition for choosing this tool is stated, though the boundary of 'manual signing pipeline steps' is a touch loose rather than crisply defined.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, and the description reinforces idempotency with the concrete '{ok, note: already booted}' outcome, which is useful behavioral context. The return-value detail is partially redundant given an output schema exists, so it stops short of 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?

Three tight lines: action, when-to-use, and return shape, each front-loaded with no filler.

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

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

For a single-parameter, non-destructive boot tool with an output schema, the description covers purpose, prerequisites, and idempotency; nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the sole udid parameter is already documented with its source tool and format, so the description adds nothing beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Boot an iOS simulator and open Simulator.app'), which cleanly separates it from siblings such as build_list_simulators, build_for_sim, and build_test.

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

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

Explicitly names the triggering conditions ('before capturing screenshots or running maestro_test'), routing the agent to the downstream tools that depend on a booted simulator, and adds the idempotency caveat so repeat calls are understood.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, and idempotentHint=false. The description adds useful behavioral context beyond annotations by identifying the underlying command (xcodebuild -exportArchive) and the raw return shape ({ok, exit_code, stdout, stderr}). It does not mention file overwrite behavior or whether an existing .ipa would be replaced, but the annotation set covers the main safety and mutability profile.

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

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

Three short sentences, front-loaded with the core action, then usage guidance, then return shape. Every sentence earns its place 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?

For a narrowly scoped build step, the description covers purpose, when to use it, prerequisite, broader alternative, and return format. An output schema exists, so it is not required to explain return values exhaustively, and the annotations already communicate the safety profile.

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

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

Schema description coverage is 100%, and all three required parameters have clear schema descriptions. The description does not add syntax, path formats, or constraints beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Run xcodebuild -exportArchive to turn a .xcarchive into an .ipa.' It also names sibling tools build_archive (prerequisite) and testflight_ship (full flow alternative), so an agent can distinguish this tool 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?

It gives an explicit when-to-use condition: 'after build_archive with an ExportOptions.plist', and an explicit alternative for the broader workflow: 'For the whole flow use testflight_ship.' This is exactly the routing guidance an agent needs.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the safety profile is covered. The description adds the compile-verification intent and a return shape, but says nothing about prerequisites (e.g. a booted simulator) or build artifact side effects; with annotations doing the heavy lifting, a 3 is appropriate.

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 lines, front-loaded with the core action, followed by routing and return info. No filler 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 and annotations cover the safety profile, so the description need not explain return values; combined with the usage routing it gives the agent everything required 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 100% and each parameter (scheme, project, device_name) is documented in the schema itself. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Build the Xcode project for the simulator') plus the intent ('to verify it compiles'). It also names the sibling tools it is not (build_archive, testflight_ship), so an agent can route without opening any schema.

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

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

Gives explicit 'Use when: verifying code changes' and 'Not for: signed/release builds (use build_archive or testflight_ship)'. This is exactly the when/when-not/alternative structure that removes routing ambiguity.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context with the 'iPhones first' ordering guarantee. It does restate the return shape, which is redundant given the output schema, keeping it below 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?

Three tight lines: what it does, when to use it, what it returns. No filler, and the scoping and routing information is front-loaded.

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

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

For a no-arg, read-only listing tool with an output schema present, everything an agent needs to select and call it is covered. Downstream tool references make the workflow 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?

Zero parameters, so the baseline is 4. There is nothing for the description to clarify beyond confirming the tool takes no input, which it implicitly does.

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 ('List') plus resource ('available iOS simulators') with an added ordering qualifier ('iPhones first'). Clearly distinguishable from mutation siblings like build_boot_sim or build_for_sim.

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 'Use when' clause names the exact prerequisite: needing a udid for build_boot_sim, build_screenshot, or screenshot_capture. Routes the agent to the correct downstream tools without 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?

Annotations already cover safety (readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=false), so the burden is lighter. The description still adds real context: it requires an already-booted simulator and documents the return payload shape, which annotations do not convey. It stops short of noting failure modes or overwrite behavior on out_path, so not a full 5.

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

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

Three short labeled fragments — action, use-when, returns — with zero filler and the core action front-loaded in the first sentence. Every sentence earns its place.

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

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

For a two-parameter read-and-write-artifact tool, the description covers the action, the selection condition against siblings, the precondition (booted simulator), and the return shape. With an output schema present, further return-value detail is unnecessary, so nothing an agent needs is missing.

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

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

Schema description coverage is 100%, with both udid (tied to build_list_simulators and an example format) and out_path documented in the schema itself. The description only restates out_path and adds no syntax or format meaning beyond it, so the baseline 3 is correct.

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

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

States a specific verb and resource ('Capture a PNG screenshot of the booted simulator') plus the output destination, so the agent knows exactly what this produces. It is clearly distinguishable from screenshot_capture and screenshot_build_all, which are named as the localized-store alternatives.

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 scopes usage to 'an ad-hoc check' and routes localized store screenshots to screenshot_capture / screenshot_build_all. When-to-use and when-to-use-something-else are both stated, leaving nothing 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?

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false, idempotentHint=false), so the agent knows this is a non-destructive local execution. The description adds the return shape, but since an output schema exists that is largely redundant. It does not mention side effects (build artifacts written, simulator state changes) or any precondition such as a booted simulator.

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

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

Three short sentences, zero filler, and the core action is front-loaded ahead of the routing guidance. Every sentence carries distinct information (action, when, alternative, return shape).

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 present and annotations covering the safety profile, the description need not explain return values, and it correctly covers routing. The one omission is preconditions — siblings like build_boot_sim suggest a booted simulator may be required, and that dependency is unstated.

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

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

Schema description coverage is 100%, so 'scheme', 'project', and 'device_name' are all fully documented in the schema with examples. The description only alludes to 'the scheme' and 'a simulator', adding no format or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and mechanism ('Run xcodebuild test'), names the resource ('the scheme on a simulator'), and explicitly distinguishes itself from the sibling maestro_test. An agent can differentiate it from build_for_sim and maestro_test 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?

'Use when: running unit/UI tests' gives the trigger condition, and 'For end-to-end Maestro flows use maestro_test' names the alternative and the condition that routes there. Both when-to-use and when-not-to-use are 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?

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds value by disclosing the return envelope {ok, exit_code, stdout, stderr} and noting that stdout carries the version lines, which annotations cannot express.

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, front-loaded lines: purpose, when, returns. No sentence is filler and the most decision-relevant information (what it does, when to call it) comes first.

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

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

For a no-argument read-only probe, the description covers purpose, trigger condition, and the shape of the result. An output schema exists, but the extra note about stdout holding the version lines is a useful pointer, and nothing needed to call it correctly is missing.

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

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

Zero parameters, so there is nothing to document and the baseline is 4. The description correctly spends no words on argument 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 and resource ('Return the installed Xcode version') with no ambiguity, and the context of use ('before build_* tools') cleanly separates it from the build_* siblings. An agent can pick this out without opening the schema.

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

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

Explicitly names the when ('a quick check that xcodebuild works before build_* tools'), which is genuinely actionable routing guidance. It does not name a when-not or an alternative diagnostic tool (e.g., env_doctor, config_doctor) that an agent might otherwise consider.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds a genuinely useful behavioral detail the annotations do not carry: secrets are masked in the output, plus the exact return field set. It stops short of full depth (no notes on partial-config handling), so a 4 rather than 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?

Three labeled, front-loaded segments with no filler; the purpose sentence leads. The 'Returns' enumeration is somewhat redundant given an output schema exists, which slightly dilutes conciseness.

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

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

For a zero-parameter, read-only diagnostic with an output schema already present, the description covers purpose, routing, privacy behavior, and expected output. Nothing an agent needs to invoke it correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate, and it correctly does not invent parameter details.

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

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

The description states a specific verb (Report) and resource (config keys in ~/.appfactory/config.toml) with precise scope (present/missing, secrets masked). An agent can distinguish it from the many sibling setup_*, env_doctor, and pipeline tools 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?

It gives explicit 'Use when' conditions (ASC/Finance key paths, session state, CLI availability) and explicit 'Not for' exclusions that route to named alternatives (setup_status, env_doctor). This is exactly the when/when-not/alternatives structure a strong definition needs.

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

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

Annotations already cover safety (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds real context on top: empty fields are left unchanged, and a secret key passed yields {ok:false, error}. It does not mention whether the file is created if missing or permissions required, but the key mutation semantics are disclosed.

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

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

Three short lines: what it writes, when/when-not, and return behavior. Front-loaded with the action and target path, zero 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 multi-field config mutation with an output schema present, the description supplies usage routing, partial-update semantics, and the error case. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so parameter meaning is already carried by the schema; the description still adds the non-obvious patch semantics that null/empty fields are unchanged rather than cleared, which the schema's default:null does not make explicit. It names a few representative fields but does not enumerate all 11, which is acceptable given the schema does.

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 (write settings to ~/.appfactory/config.toml), scopes it to NON-secret fields, and names the two sibling tools it is not (setup_credentials, setup_set). An agent can place it correctly without reading any schema.

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

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

Explicit 'Use when' (setting multiple ASC/identity fields together) and 'Not for' clauses route to the alternatives setup_credentials and setup_set by name. The empty-field behavior is also stated, leaving nothing 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?

Annotations already flag a destructive, non-idempotent, open-world write, but the description adds crucial workflow context beyond them: it is a live write requiring human approval, and a call may return an approval_required refusal that must be resolved out-of-band before retrying.

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 lines: what it does, when to use it, what it returns. The write/approval caveat is front-loaded in the first sentence, and 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?

For a destructive multi-page write with a two-step approval handshake, the description covers the trigger condition, the human-approval requirement, the refusal path, and the returned shape. With an output schema present, no further return-value detail is required.

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

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

Schema description coverage is 100% – bundle_id, themes and the approval_id retry flow are all documented in the schema itself. The description adds little parameter-level detail beyond restating the one-page-per-theme mapping, so the baseline 3 is appropriate.

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

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

Specific verb (Create one Custom Product Page per theme), precise scope (page, version, localization) and the concrete artifact produced (deep-link URLs). Clearly distinguishable from sibling build_all tools such as screenshot_build_all or growth_build_slideshows.

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 when-to-use: 'after ASO produced theme clusters; the URLs feed Ad Ops', which pins it to a pipeline stage. It does not name when-not to use it or a direct alternative, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true and openWorldHint=true. The description adds genuinely non-obvious context beyond that: it is a live write, it requires human approval, and it is ASO-gated, plus it names the refusal outcome ('gate / approval_required'). It does not reconcile the destructive-vs-idempotent tension explicitly, keeping it just short of 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?

Front-loads the operation and its gating in the first sentence, then uses tight labelled clauses ('Use when:', 'Not for:', 'Returns:'). No filler sentences; every element carries routing or behavioral information.

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

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

For a gated write tool with an output schema, full param coverage, and rich annotations, the description supplies the missing pieces: the approval gate workflow, the ASO prerequisite, the sibling boundaries, and the refusal shape. Nothing an agent needs to invoke it correctly 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 100%, and the schema itself documents app_dir, bundle_id and the approval_id approval-loop semantics in detail. The description mentions the approval requirement but adds no parameter syntax beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb and resource (upload metadata to the App Store Connect draft version) and explicitly names the two sibling tools it is not (deliver_screenshots, asc_submit_for_review). An agent can distinguish it from the ~100 siblings 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?

Uses explicit 'Use when' (metadata files are exported via metadata_export) and 'Not for' clauses naming the alternatives and the boundary conditions. The routing decision is fully determined.

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?

Discloses live write requiring human approval, describes the gate/approval_required refusal pattern, and notes checksum-based skipping. This adds context beyond annotations (destructiveHint=true, idempotentHint=true). Could mention what gets destroyed or permissions needed, but the approval gate 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?

Three sentences with zero waste, front-loaded with the action and key mechanism, then conditions, then return. Every sentence earns its place.

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

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

Covers purpose, usage, behavior, and return values well. With output schema present, the return description is supplementary. The approval flow is clearly explained, though minor details like error handling beyond gate refusals could be added.

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

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

Schema coverage is 100%, so all parameters are documented in the schema. The description mentions approval_id implicitly via the refusal pattern but doesn't add syntax or format details beyond what's in the schema descriptions. Baseline 3 is appropriate.

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

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

States a specific verb (upload) and resource (screenshots) with precise destination (App Store Connect draft) and mechanism (checksum-based incremental sync). Differentiates from siblings by naming the precondition screenshot_build_all and the audit tool deliver_screenshots_audit.

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

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

Explicitly states when to use (after screenshot_build_all is done), the skip behavior (unchanged files with MD5 match are skipped), and names the verification alternative (deliver_screenshots_audit). Provides clear routing.

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