tool4seller-mcp

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

Beyond annotations declaring a destructive write, the description discloses that a linked structure draft may automatically prepare a next preview without confirming or executing it, and that Review Sandbox simulates writes and skips continuation. It also highlights the one-time confirmation receipt and idempotency requirements, which are behaviorally important for safe 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?

The description is four focused sentences, front-loading the core constraint that only a confirmed plan is executed. Each sentence carries useful operational context about prerequisites, continuation behavior, or sandbox behavior.

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

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

For a complex destructive workflow tool with nested parameters and an output schema, the definition covers the key call prerequisites, continuation side effect, and sandbox distinction. Error and reconciliation guidance is supplied in the schema's planId description, so no critical agent guidance 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 schema already explains planId, confirmationReceipt, idempotencyKey, and applyContinuation in more detail than the tool description. The description adds only high-level requirements, 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?

The description states a specific verb and resource: executing a confirmed AD_AD_GROUP_CHANGE plan, and clarifies that it changes ad-group default bids, states, or names. This distinguishes it from prepare_* and from apply_* tools for other resource types without requiring 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 clearly states that only a confirmed plan may be executed and that a one-time confirmation receipt and idempotency key are required. It also notes Review Sandbox behavior, but it does not explicitly name prepare_ad_group_changes or confirm_workflow_plan as the preceding steps, leaving that routing to inference from sibling names and schema.

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/openWorld writes; the description adds genuine context beyond them — real writes to the authorized account, one-time receipt semantics, idempotency, and that a linked draft may auto-prepare a next preview without confirming or executing it. Sandbox simulation behavior is disclosed rather than left to inference.

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

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

Four front-loaded sentences with no filler: action and scope first, then prerequisites, then continuation behavior, then sandbox caveat. Dense but every clause carries operational meaning.

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

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

Return values are covered by the output schema, and the description handles the hard parts: continuation eligibility, automatic next-preview preparation, and sandbox divergence. Combined with the schema's retry/reconciliation notes, an agent has what it needs to call this safely.

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

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

Schema coverage is 100% and the parameter descriptions are far richer than the tool description (timeouts, INDETERMINATE reconciliation, key reuse rules). The description only restates that a confirmation receipt and idempotency key are required, adding little beyond the schema.

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

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

States a specific verb and resource ('Executes ... Creates advertising ad groups') scoped to AD_AD_GROUP_CREATE plans on the authorized Amazon Ads account. The plan-type scoping implicitly separates it from prepare_ad_group_creation and apply_ad_group_changes, though neither sibling is named.

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

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

Makes the prerequisite chain explicit: only a confirmed plan, requiring the one-time confirmation receipt and an idempotency key, so an agent knows it must come after confirm_workflow_plan. It also distinguishes the Review Sandbox case, but never states when to use apply_ad_group_changes instead.

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 (destructive=true, openWorld=true, readOnly=false), so the description's added value is workflow behavior: one-time receipt semantics, idempotency-key scoping, and the automatic linked-draft continuation that prepares but does not execute the next preview. The finer retry/INDETERMINATE guidance lives in the schema parameters rather than here, leaving a small gap against the destructive mutation.

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

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

Core purpose is front-loaded in the first sentence, followed by the mutation scope, then prerequisites, with edge behaviors (continuation, sandbox) last. It is slightly redundant with the schema-level description, which repeats the same next-stage-preview guidance, and the closing sandbox sentence is terse to the point of being cryptic.

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

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

For a destructive, multi-stage workflow tool with an output schema, the description covers the aspects an agent could not infer from structure: confirmation receipt requirements, idempotency across retries, automatic continuation, and sandbox behavior. Return values are properly left to the output schema, so nothing critical 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 parameter meaning is fully carried by the schema, including planId retry semantics, idempotency-key reuse rules, and the applyContinuation contract. The description only references the receipt and idempotency key in passing, which is the expected baseline when the schema does the work.

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

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

States a specific verb (executes/applies), the resource (an AD_CAMPAIGN_CHANGE plan), and the exact fields mutated (budgets, states, names), which separates it from prepare_campaign_changes and from apply_campaign_creation. It does not name any sibling explicitly, so the differentiation is inferred rather than stated.

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

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

The 'only a confirmed plan' constraint plus the required one-time confirmation receipt and idempotency key make the preconditions clear. It also notes the Review Sandbox variant skips continuation. It stops short of naming alternatives (e.g. confirm_workflow_plan, query_advertising_campaigns) or stating when not to use it.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, and the description adds real operational context beyond them: the one-time nature of the receipt, idempotency expectations, that a linked draft may silently prepare the next preview without confirming or executing it, and that Review Sandbox simulates writes and skips continuation. These are exactly the side effects an agent must know before invoking a destructive write.

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

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

Front-loaded with the gating condition and the effect, then the preconditions, then the continuation and sandbox caveats. Five sentences with no filler, though the final two caveats are dense enough that they read as schema-level detail rather than selection guidance.

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

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

For a destructive, open-world write tool with a nested continuation object, the description covers the prerequisite chain, the automatic continuation side effect, and the sandbox variant, while the output schema handles return values and the parameter descriptions handle timeout/indeterminate recovery. An agent has enough to invoke it correctly.

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

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

Schema coverage is 100% and each parameter already carries detailed guidance (idempotency reuse rules, continuation recovery, receipt scoping). The description only restates that a receipt and idempotency key are required, adding no syntax or semantics 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 (executes), a specific resource (an AD_CAMPAIGN_CREATE plan) and the concrete outcome (creates Sponsored Products campaigns). The 'only a confirmed ... plan' scoping plus the sibling set (apply_campaign_changes, prepare_campaign_creation) makes the boundary unambiguous 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?

Explicitly gates usage on a confirmed plan plus a one-time confirmation receipt and idempotency key, which tells the agent it must call confirm_workflow_plan first. It also carves out the Review Sandbox case. It does not explicitly name the alternative to use for a change vs. a creation, so it falls short of a full when/when-not matrix.

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 destructive/openWorld annotations, it discloses that an empty set clears all associations, that eligibility and quota are rechecked before applying, that Catalog relationships are revalidated, and that the receipt is one-time and single-plan. These are substantive behavioral facts an agent would otherwise have to guess.

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

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

It is front-loaded with the core action and scope, then the exclusions, then the preconditions. Sentences are dense but each carries distinct information; only the Sandbox sentence is tangential 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, full parameter coverage, and annotations covering safety, the description adds the mutation consequences, eligibility rechecks, and retry/uncertainty handling an agent needs. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, and each parameter already documents its role, retry semantics, and reuse rules in detail. The description only restates that the confirmation receipt and idempotency key are required, adding no syntax or format 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?

The description states a precise verb and resource: 'Replaces the full associated competitor set of one existing owned-product tracker', including the empty-set case. It distinguishes itself from the sibling prepare_keyword_rank_competitor_replacement and from apply_keyword_rank_tracking_changes by explicitly ruling out creating competitor tracking or changing keyword status.

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

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

It gives clear preconditions — only a confirmed plan matching this tool, with a one-time confirmation receipt and idempotency key, and it 'rejects other operation groups'. Exclusions ('does not create independent competitor tracking or change keyword status') further scope usage. It stops short of naming the exact prepare/confirm sibling sequence, so it is not a full 5.

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

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

Adds real value beyond the destructiveHint annotation: it specifies what archiving does to data ('remove while retaining ranking history'), discloses idempotency-key and one-time-receipt requirements, and notes eligibility/quota rechecks at apply time. The only gap is not stating explicitly that the ARCHIVED transition is the irreversible/removal path in the caller's own terms.

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

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

Front-loaded with the core action and its scope, then constraints, then exclusions. Dense but disciplined; a couple of the negative clauses ('Does not access Amazon Catalog') could be trimmed, but nothing is 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, full annotation coverage, and 100% schema coverage, the description supplies everything else an agent needs: confirmation/idempotency preconditions, rejection behavior, eligibility/quota rechecks, and a sandbox simulation path.

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 already documents its semantics in depth, so the description's mention of the receipt and idempotency key largely restates the schema. Baseline 3 is appropriate; no additional parameter meaning is introduced.

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 (executes a confirmed plan) plus the exact resource (keyword rank tracking status) and the two resulting states (ACTIVE resume, ARCHIVED with history retained). It proactively differentiates from siblings by declaring 'Does not create tracking or change competitor associations', which rules out apply_keyword_rank_tracking_creation and apply_keyword_rank_competitor_replacement.

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?

Clearly gates usage on a confirmed plan, and explicitly excludes other operation groups and creation/competitor operations. It also mentions the Sandbox simulation path for review. It stops short of naming the sibling tools (prepare_*/confirm_workflow_plan) as the explicit alternative workflow, leaving that routing to be inferred.

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

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

Adds real behavior beyond the annotations: rejects mismatched operation groups, rechecks eligibility and quota at apply time, and revalidates competitor Catalog relationships before applying. Does not spell out what happens to partially-failed applications or the shape of a rejection/quota error, which keeps it 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-group gate and the core action, then layers constraints in short sentences. It is dense with domain jargon and the retry guidance is duplicated between the description and the planId/idempotencyKey schema text, but no sentence is 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 and annotations cover safety and open-world behavior, so the description needn't explain return values. It still supplies the full lifecycle context an agent needs: confirmation prerequisite, idempotency retry rule, eligibility/quota recheck, and sandbox simulation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description ties the parameters to workflow semantics: the plan must already be confirmed, the receipt is one-time and plan-bound, and retries must reuse the same idempotency key. This reinforces intended sequencing rather than restating types.

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

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

States a specific verb and resource ('Creates keyword tracking for owned products or independent competitors') and scopes it to a confirmed plan matching this tool, explicitly rejecting other operation groups. This clearly separates it from prepare_keyword_rank_tracking_creation (prepares) and apply_keyword_rank_tracking_changes (modifies existing).

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 when-not guidance: existing active tracking is unchanged and paused tracking must use the status changes tool. Also names prerequisites (one-time confirmation receipt plus idempotency key) and the sandbox simulation path for review.

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

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

Annotations already declare destructive=true and openWorld=true, so the safety profile is covered; the description adds genuinely new traits beyond them: one-time confirmation receipts, idempotency semantics, and the fact that a linked draft may silently prepare (but not execute) the next preview, plus that Review Sandbox simulates writes. It never explains what a rejected/INDETERMINATE outcome looks like at the description level, but that is pushed into the parameter docs.

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 tool-level description is four short sentences that front-load the core action and the confirmation dependency, with the sandbox caveat last. The only weak spot is 'Review Sandbox simulates advertising writes and skips continuation,' which is terse to the point of being cryptic without prior context.

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, idempotent write tool with an output schema and full annotation coverage, the description supplies the confirmation gate, retry/idempotency model, continuation side effect, and sandbox behavior — enough to call it correctly. Residual gaps (retry-on-timeout and INDETERMINATE reconciliation) are handled in the parameter schema rather than here.

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 nested applyContinuation object is thoroughly documented in the schema, so the schema already carries parameter meaning. The description only restates that a receipt and idempotency key are required, adding no syntax or format detail beyond the structured fields. 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?

The first sentence names a concrete verb (Executes) and resource (a confirmed AD_AD_CHANGE plan on the Amazon Ads account), and the second narrows scope to ad states and supported Sponsored Brands ad names. That distinguishes it from apply_product_ad_creation and the other apply_* siblings in the fleet, though it never names an alternative explicitly.

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

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

'Executes only a confirmed ... plan' plus the receipt and idempotency-key requirements implicitly set the precondition (confirm_workflow_plan must have run first) and the continuation/sandbox exceptions carve out when behavior differs. It gives clear context but stops short of naming the prepare/confirm siblings or stating explicit when-not conditions at the description level.

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 declare a destructive open-world write, and the description adds real context beyond that: the confirmation-receipt requirement, idempotency-key requirement, automatic draft continuation that stops short of executing, and that Review Sandbox simulates writes and skips continuation. It does not spell out rollback/irreversibility of a completed ad write, which is the main remaining gap for a destructiveHint=true 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?

Four front-loaded sentences that each carry content: purpose, scope, continuation caveat, sandbox caveat. Some of it duplicates the applyContinuation schema description, but nothing is padded or buried.

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

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

With an output schema present and full parameter documentation, the description fills the remaining gaps an agent needs: the confirm-then-apply gate, idempotent retry framing, the automatic continuation behavior, and the sandbox exception. Nothing material about invoking this destructive write is missing.

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

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

Schema description coverage is 100%, so the schema already documents planId, idempotencyKey, confirmationReceipt, and the applyContinuation internals in detail. The description adds only the high-level statement that a receipt and idempotency key are required, which is a restatement rather than new semantic detail. 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 ('Executes only a confirmed AD_AD_CREATE plan') and the resource created ('Sponsored Products product ads or Sponsored Display product ads'). The 'only a confirmed ... plan' qualifier plus the creation framing distinguishes it from apply_product_ad_changes and the prepare_* siblings without needing to open any schema.

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

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

Explicitly gates use on a confirmed plan with a one-time confirmation receipt and an idempotency key, which functions as a when-to-use prerequisite. It also describes the follow-on scenario ('A linked structure draft may automatically prepare the next preview without confirming or executing it') and how Review Sandbox differs, so the agent knows both the entry condition and the post-call behavior.

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 and openWorld=true, and the description adds substantial context beyond that: 'archiving is irreversible,' negative targeting has no bid actions, a one-time confirmation receipt and idempotency key are required, and sandbox mode skips continuation. These are exactly the operational traits an agent needs before invoking a destructive write.

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

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

The preconditions and irreversibility warning are front-loaded, but the run-on sentence about continuation and the schema-level prose about nextActions/presenting previews add density that could be tightened. Still, every clause carries operational meaning.

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

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

With an output schema present, return values needn't be explained; the description still covers the critical edge cases (irreversible archive, idempotency/retry posture, continuation behavior, sandbox simulation), leaving nothing an agent needs to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents planId, idempotencyKey, confirmationReceipt, and the applyContinuation nested object in detail. The description only restates that a receipt and idempotency key are required, adding no syntax or semantics 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 ('executes') on a specific resource ('confirmed AD_TARGETING_CHANGE plan') and enumerates the exact operations covered (positive bid/state changes, re-enable/archive negative targeting). This clearly differentiates it from siblings like prepare_targeting_changes and apply_targeting_creation.

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

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

The description establishes the precondition (only a confirmed plan) and explains downstream behavior (auto-prepared next-stage preview, sandbox skipping continuation), which tells the agent when this tool applies. It doesn't explicitly name alternatives for the non-confirmed case, but the gating condition is unambiguous.

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

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

Annotations already declare non-read-only, destructive, and open-world. The description adds real value beyond them by disclosing batch semantics, the automatic next-stage preview preparation, and sandbox write simulation that skips continuation. It does not address partial-failure or reconciliation behavior in the description proper (that lives only in the planId schema text).

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 operation and only six sentences, each carrying a distinct constraint (scope, entity types, batch, receipt/key, continuation, sandbox). One or two clauses are dense but nothing is 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 fully documented parameters, the description only needs to cover invocation preconditions and side effects, which it does: confirmation requirement, idempotency, continuation behavior, and sandbox divergence. The remaining gap is guidance on reconciling INDETERMINATE outcomes, which is delegated to the schema text.

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 carries the semantics for planId, idempotencyKey, confirmationReceipt, and applyContinuation. The description only mentions that a receipt and idempotency key are required, adding no syntax or format detail. 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: executes a confirmed AD_TARGETING_CREATE plan and enumerates the entity types it creates (positive/negative keyword and ASIN targeting). The plan-type qualifier distinguishes it cleanly from apply_targeting_changes and from the prepare_* siblings.

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

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

Explicitly restricts use to plans that are already confirmed, and names the required receipt and idempotency key. It also flags the sandbox variant and the continuation side-effect. It does not explicitly route the agent to confirm_workflow_plan or prepare_targeting_creation as the preceding steps, which keeps it from 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 destructiveHint=true and readOnlyHint=false. The description adds useful stage context (only prepared or confirmed plans, and no business changes have been applied yet), but is silent on whether cancellation deletes the plan, whether it is idempotent, and what happens if the plan was already applied.

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

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

A single front-loaded sentence with no filler; the verb and the state constraint appear immediately. Nothing is repeated or padded.

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

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

An output schema and annotations exist, so return values and safety profile are covered. However, for a destructive single-action tool, the description omits post-cancellation state and behavior for plans past the confirm stage, which an agent would need before invoking it.

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

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

Only one parameter with 100% schema description coverage, so the baseline is 3. The description merely echoes the schema's 'prepared or confirmed workflow plan ID' qualifier and adds no format, lookup, or sourcing guidance (e.g., where to obtain the planId).

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 (cancels) and resource (prepared or confirmed workflow plan) plus the stage constraint 'before business changes are applied', which implicitly separates it from the apply_* and confirm_workflow_plan siblings. It does not name those siblings explicitly, so differentiation is inferential rather than stated.

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

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

The phrase 'before business changes are applied' hints at the appropriate moment to use it (prior to apply/confirm), but there is no explicit when-to-use statement, no exclusion for plans already applied, and no pointer to confirm_workflow_plan or apply_* as the alternative path.

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

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

The description adds a human-approval gate and the immutability property ('exact immutable plan') that annotations cannot express, which is meaningful context for a destructiveHint=true tool. It omits what actually happens on confirm — whether changes execute immediately or a separate apply_* call is still required — and gives no guidance for hash/version mismatch.

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

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

Two sentences, zero filler, with the identity constraint front-loaded and the precondition second. Every clause earns its place.

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

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

An output schema exists, so return values needn't be explained, and the safety profile is carried by annotations. However, for a destructive commit step in a multi-tool workflow, the description leaves the critical question open: whether confirming itself applies changes or merely locks the plan for a later apply_* call. That ambiguity is material to correct invocation.

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

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

Schema coverage is 75%, so most parameters are already documented (planId, planHash, expectedItemCount); planVersion has no description. The phrase 'exact immutable plan' hints that all four params together pin plan identity, but the description adds no meaning about what a version or hash mismatch implies. Baseline 3 is warranted.

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

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

Names a specific verb ('Confirms') and a specific resource ('the exact immutable plan the customer reviewed'), which places it clearly in the prepare/confirm/apply lifecycle. It does not explicitly name the sibling it is *not* (get_workflow_plan, cancel_workflow_plan, apply_*), so an agent must infer the distinction from the lifecycle vocabulary.

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?

'Call only after explicit customer approval of old/new values' is a concrete, actionable precondition that tells the agent when to invoke it. It stops short of naming alternatives (e.g. cancel_workflow_plan when approval is withheld, get_workflow_plan to re-review), so the routing is implied rather than explicit.

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

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

Beyond the annotations, the description discloses substantial behavioral details: it queries Amazon Ads, persists workflow progress and decisions, reconciles the last atomic plan, retains successful IDs, and prepares only the next atomic plan. It also describes partial-write retry behavior, 429 suggestion-read evidence, ambiguous create-result reconciliation, and the rule that ambiguous creates are never retried. The destructive/open-world annotations are not contradicted; this tool mutates draft/workflow state while explicitly not applying Amazon Ads writes.

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

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

The purpose is front-loaded in the first sentence, which is good. However, the description is a very long, dense paragraph covering many edge cases, sequencing rules, and retry semantics without internal structure. Much of the content is substantive for this complex workflow, but the overall presentation is over-verbose rather than concise.

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

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

Given the tool's orchestration complexity and the presence of an output schema, the description is comprehensive. It explains the workflow stages, AUTO vs MANUAL branching, retry/reconciliation behavior, candidate limits, and how to continue into execution tools. An agent has enough context to invoke and route 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 documents all four parameters and their nested structures. The description still adds useful workflow-level meaning: candidateRef-based selection, customCandidates as a fallback, the 100-candidate cap, one targeting family per ad group, and bid-mode behavior for AUTO and MANUAL decisions. It stops short of fully explaining every parameter interaction because the schema itself is already very detailed.

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: it resumes a READY AD_STRUCTURE_CREATE draft from persisted server state. It also explicitly distinguishes this orchestration/preparation tool from execution tools by saying it never confirms or applies a write plan. The scope and sequencing are detailed enough that an agent can identify this as the draft-continuation tool rather than a get, prepare, or apply sibling.

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

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

The precondition is explicit: the draft must be READY and AD_STRUCTURE_CREATE. The description also gives strong routing guidance for the next step by telling the agent to pass applyContinuation unchanged to the matching execution tool. It does not explicitly name when to use get_workflow_draft or prepare_workflow_draft instead, so it falls short of full when/when-not/alternatives 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?

Goes well beyond annotations with concrete rate limits (95-day range), splitting rules, and aggregation caveats (do not average ratios), plus exceptions for write plans and keyword ranking trends. Annotations already confirm read-only, but this description adds critical operational constraints.

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 purpose but then includes lengthy, off-topic instructions about advertising write plans and keyword ranking trends that are irrelevant to this read-only diagnosis tool. These repeated and extraneous sentences dilute the core message.

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 calling requirements well (date formats, range limits, splitting), and the output schema handles return values. However, it omits guidance on when to select this vs sibling diagnostic/query tools and contains irrelevant limits that could mislead, leaving a gap for correct tool selection.

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

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

Schema coverage is 100% and schema descriptions already document each parameter, including independent 95-day limits for comparison ranges. The description adds no parameter-specific meaning beyond what the schema provides, so baseline 3.

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

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

States a specific verb 'Diagnoses' and resource 'advertising efficiency' with scope 'one store and business date range'. It does not explicitly differentiate from sibling tools like query_advertising or diagnose_sales_change, so it misses the top mark.

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 extensive procedural guidance on date-range splitting and aggregation but never states when to choose this tool over query_advertising or other diagnose_* siblings. Usage is implied by 'read-only advertising metrics' but alternatives are not named.

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, the description discloses meaningful behavior: read-only signals, a 95-day inclusive range limit, window-splitting rules, ratio recomputation guidance, separate keyword-ranking limits, and a campaign-scheduling exception. These details help an agent avoid incorrect reporting behavior, though they are broad and somewhat generic across reporting tools.

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

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

The description is front-loaded with the core purpose, but it is long and includes guidance about keyword ranking trends and campaign scheduling that is not clearly relevant to diagnosing profit anomalies. Much of the later text could be trimmed or moved to a shared reporting guide.

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 annotations and output schema, the description covers the main operational constraints an agent needs: store/date scope, read-only nature, range limits, comparison handling, and ratio recomputation. It lacks explicit sibling-tool routing, but is otherwise sufficiently complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters, including date formats and range limits. The description adds context about splitting long ranges and comparison ranges, but does not substantially extend parameter semantics beyond what the schema provides.

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

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

The description clearly states a specific verb and resource: it diagnoses profit anomalies using read-only profit, sales, and advertising signals for one store and date range. It does not explicitly contrast with sibling diagnostic tools, which keeps it below a 5.

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

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

The description gives detailed operational constraints for date ranges and splitting windows, but it does not say when to use this tool versus alternatives such as diagnose_sales_change, diagnose_ad_efficiency, or query_profit. Usage is therefore implied rather than fully routed.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces read-only while adding genuinely useful context: the 95-day cap, the keyword-ranking interval limits (90 DAILY / 31 RAW), the ratio-recomputation rule, and the exclusion for campaign scheduling dates. These are non-obvious behavioral constraints an agent would otherwise get wrong.

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

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

The purpose is front-loaded correctly, but the body is a long block of date-splitting boilerplate that reads like shared policy text rather than tool-specific guidance, plus a keyword-ranking digression that this tool's schema doesn't even expose as parameters. Roughly half the text does not earn its place for calling this specific tool.

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

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

Safety and date-window behavior are well covered, and an output schema exists so return values needn't be described. However, for a multi-signal diagnostic tool with an optional 'focus' param, the description never explains what kind of diagnosis is produced (drivers, attribution, anomaly breakdown) or how it differs from the two sibling diagnose_* tools.

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

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

Schema description coverage is 100%, so the schema already documents storeId format and the per-date-range limits. The description adds the independent-limit rule for comparison ranges and the windowing formula (endDate = startDate + 94 days), which is somewhat more than the schema, but it says nothing about what the optional 'focus' parameter actually changes in the diagnosis.

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 opening sentence gives a specific verb (diagnoses), resource (sales changes), and names the signal sources (sales, traffic, advertising, inventory) and scope (one store, business date range). It implicitly distinguishes itself from the query_* siblings by being a diagnosis rather than a raw data pull, though it never names a sibling to contrast with.

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

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

It gives real constraint guidance — split windows for longer ranges, don't average ratios, don't split advertising write plans, get a supported window from the user — but these are mostly operational rules for the date parameters rather than when-to-use-this-tool guidance. It never says when to pick this over diagnose_ad_efficiency, diagnose_profit_anomaly, or the query_* tools.

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

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

Annotations already cover safety (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description adds genuinely new behavioral context: navigation/guidance-only output, no execution side effects, and that it surfaces reporting date limits and range-splitting guidance. This affects how an agent should consume the result, going beyond the annotations.

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

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

Three tight sentences, front-loaded with purpose then boundaries then return content, with no filler. The opening sentence is slightly dense ('for diagnosis, advertising draft collection, and individual advertising operations'), but nothing is wasted.

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

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

For a read-only, one-optional-param discovery tool with an output schema and full annotation coverage, this is close to complete: purpose, boundaries, and key return content are all stated. The only minor gap is no guidance on whether the query filter is recommended for first-time discovery versus omitted for a full listing.

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 'query' parameter is fully documented in the schema with example search texts. The description adds no syntax, format, or required/optional detail beyond that, so this is the baseline case where the schema carries the burden.

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 ('Lists supported business workflows and their already-exposed MCP tools') and scopes it to diagnosis, advertising draft collection, and individual ad operations. It sharply distinguishes itself from the many prepare_*/apply_*/query_* siblings by declaring it returns navigation and input guidance only.

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

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

The negative framing ('does not prepare plans, execute queries, or apply advertising changes') tells the agent when not to use it and routes mutation work to the prepare/apply siblings. It does not explicitly say 'call this first' or name a specific alternative to use instead, so usage is clear but not fully prescriptive.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds meaningful behavioral context beyond annotations: it identifies the exact profile fields returned and states that only authenticated basic access is required, with no business OAuth scope. This helps the agent understand auth requirements that annotations do not cover.

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

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

Two sentences, front-loaded with the return value and followed by the authentication context. Every sentence adds useful information, with no repetition of the schema or annotations.

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

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

The output schema handles the return shape, annotations cover the safety profile, and the description supplies the remaining critical context: the returned fields and the authentication requirement. For a zero-parameter read-only profile tool, 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?

There are zero parameters, and schema coverage is 100%, so no parameter semantics need explanation. The description does not invent or misdescribe parameters. Baseline for a zero-parameter tool is 4.

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

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

The description states a specific verb and resource (returns the current user's profile details) and enumerates the exact fields returned. It is clear and concrete, though it does not explicitly differentiate itself from siblings—largely because no sibling is similarly named or scoped.

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

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

Usage is implied by the tool's name and the description's field list, but there is no explicit guidance on when to call it versus alternatives. It does not state prerequisites beyond authentication or exclusion conditions, leaving the agent to infer that this is the canonical way to retrieve the current user's profile.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that the draft is 'owned' and lists returned state such as expiry, lock version, missing inputs, validation errors, and continuation state, but much of that overlaps with the output schema and does not disclose auth or failure behavior.

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

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

The description is a single front-loaded sentence with no unnecessary preamble. It is somewhat dense due to the long list of returned fields, and the phrase 'without modifying it' is redundant with readOnlyHint, but overall it is efficient.

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 tool with annotations and an output schema, the description provides sufficient scope and return context. The main omissions are sibling differentiation and explicit usage guidance rather than missing operational details.

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

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

There is only one parameter, draftId, and schema description coverage is 100%. The schema already documents it as the workflow draft ID, and the description adds no further parameter-specific semantics. Baseline 3 is appropriate when schema coverage is complete.

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: it returns the current owned workflow draft. It also names the draft scope and return content, so the operation is clear. However, it does not explicitly distinguish itself from related siblings such as get_workflow_plan, prepare_workflow_draft, or continue_workflow_draft.

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

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

The description explains what is returned but gives no explicit guidance about when to use this tool versus alternatives like continue_workflow_draft or get_workflow_plan. It also provides no exclusions or prerequisite conditions.

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

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

Annotations already declare readOnlyHint and non-destructive, but the description adds valuable behavior context: what state is returned and the reconciliation/idempotency semantics that govern recovery after ambiguous apply outcomes. It does not cover error cases such as a missing or expired plan ID, but for a read-only query tool the disclosure is 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?

Two tightly packed sentences with no filler; the read-only scope and return contents come first, and the recovery guidance follows. Every clause earns its place.

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

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

The tool is simple (one required param, output schema exists) and the description covers what an agent needs: that it is a safe read, what it returns, and exactly when to use it versus retrying apply or creating a new plan.

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 planId parameter is already fully documented in the schema, and the description adds only the reinforcement that it must be 'this exact plan' rather than a newly created one. Baseline 3 is appropriate when the schema carries the parameter detail.

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 (Gets) and resource (a workflow plan) and explicitly declares it is non-modifying, which differentiates it from the apply/cancel/confirm siblings. It also enumerates what the returned state includes (expiry state, execution status, item errors, diagnostics, old/new values), so the agent knows exactly what it retrieves.

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 triggering scenario ('After a timeout or disconnected apply call') and names the two correct recovery paths: query this exact plan or retry apply with the same idempotency key. It also states a hard prohibition: never create a replacement plan until the outcome is terminal and INDETERMINATE items are reconciled.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds genuine behavioral constraints on top: a hard 95-calendar-day cap per range, a prescribed window-splitting algorithm, and a warning not to average ratios across windows. However, several paragraphs (keyword ranking limits, advertising write plans) do not apply to this tool and dilute the 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?

The purpose is front-loaded well, but the bulk of the text is generic boilerplate about keyword ranking trend limits and advertising write plans that is irrelevant to an inventory risk review. Every sentence is supposed to earn its place; here several paragraphs do not.

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 and full annotations exist, so return values and safety need not be explained. What remains missing is how the optional 'focus' value changes the review and why an agent would choose this tool over the raw query_inventory / query_inventory_alerts siblings — a real gap given a crowded sibling namespace.

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 documented storeId/startDate/endDate/compare* semantics are already covered and the baseline is 3. The description adds real meaning beyond the schema by specifying the exact non-overlapping split procedure (endDate = startDate + 94) and that the comparison range is limited independently. The 'focus' parameter is never mentioned in the description, leaving that gap unaddressed.

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 opening sentence names a specific verb and resource ('Reviews inventory risk') plus the scope ('for one store') and the signals consumed ('inventory and inventory alert signals'). This implicitly distinguishes it from the raw siblings query_inventory and query_inventory_alerts, though it never names them explicitly.

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

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

Usage is only implied: a 'review' that combines two signal sources suggests a synthesis tool rather than a raw query, and 'read-only' signals safety. There is no explicit statement of when to pick this over query_inventory, query_inventory_alerts, or the diagnose_* tools, and no exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds 'paginated' and the 100-shipment-ID cap, which is genuine extra context, but says nothing about behavior with invalid or unknown shipment IDs or what happens past the cap.

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

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

One front-loaded sentence with no filler, stating resource and scope immediately. It is efficient but so terse that the sibling relationship and pagination contract are left entirely implicit.

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 shape needn't be explained, and annotations handle the safety profile. However, for a tool with a near-identical sibling, the description omits the disambiguation an agent needs to select correctly, which is the main remaining gap.

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

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

Schema description coverage is 100%, so limit, offset, sellerIds, and shipmentIds are fully documented in the schema itself. The description only restates the shipmentIds cap, adding no meaning beyond structured fields — 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 ('Returns') plus precise resource ('FBA inbound shipment items') and a scoping constraint (up to 100 shipment IDs). The noun differs from sibling list_inbound_shipments, but the description never states that distinction explicitly, so an agent must infer it.

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

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

No statement of when to use this versus list_inbound_shipments, no prerequisites, and no exclusions. The only guidance is the implicit constraint that it takes shipment IDs, which an agent could derive from the required parameter anyway.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that results are paginated and scoped to authorized sellers, but does not add detail on rate limits, ordering, or output behavior.

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

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

The description is a single front-loaded sentence with no wasted words. It is appropriately sized for a simple list tool.

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

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

For a simple read-only list tool with a full input schema, output schema, and safety annotations, the description covers the essential resource and scope. It is slightly incomplete because it does not explain its relationship to list_inbound_shipment_items.

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 limit, offset, and sellerIds are already fully documented in the schema. The description only implies pagination and seller scoping; it adds no parameter semantics beyond the schema.

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

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

States a specific verb and resource: returns paginated FBA inbound shipments. It is clear what the tool does, but it does not explicitly distinguish itself from the sibling list_inbound_shipment_items tool.

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

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

Provides only a vague scope ('for authorized sellers') and no when-to-use guidance. It does not explain when to choose this over list_inbound_shipment_items or inventory-related siblings.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the useful scoping fact that results are limited to the current user's authorized sellers/marketplaces, but says nothing about result size or pagination behaviour for a listing call, and an output schema exists so return shape is not its job.

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

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

A single front-loaded sentence listing the returned entities with no filler. It is appropriately sized, though the space saved is not spent on the missing usage routing.

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 a full output schema and complete annotations, most of the burden is already handled elsewhere. What remains missing is the operational context an agent needs: that this is the discovery entry point for seller and marketplace identifiers used by the query_* 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?

Schema coverage is 100% and the five optional filters are documented in unusual detail in the schema itself. The description restates none of them and adds nothing beyond the implicit 'all sellers for the current user' default, which the sellerId schema text already states. Baseline 3 is the correct ceiling.

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 the resource concretely (sellers, marketplaces, and the SP/Advertising/active status fields returned) and scopes it to the current user, so an agent knows exactly what this returns. It does not, however, distinguish itself from near-neighbours like get_current_user or discover_capabilities, which an agent could easily confuse it with.

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

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

There is no guidance on when to call this versus alternatives such as get_current_user or discover_capabilities. The most useful fact — that this is the tool to resolve sellerId/marketplaceId before calling query_* tools — is absent entirely.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false; the description usefully reconciles this by clarifying that it persists an internal plan while leaving advertising entities untouched, which is non-obvious for a non-readonly tool. What is missing is the plan lifecycle (expiry, validity window, what makes a plan confirmable).

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: purpose first, scope second, side-effect clarification last. No filler and no repetition of the title.

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

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

Output schema exists, so return values needn't be explained, and annotations plus a rich nested schema cover the mechanics. The remaining gap is workflow positioning — which tool consumes the prepared plan and under what conditions — which an agent must infer from sibling names alone.

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

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

Schema coverage is 100% and the nested schema already documents operation limits, action types, selector semantics, and even the 'state goes in value, not action.state' gotcha. The description only restates the changeable fields (bids, states, names), so it adds 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 (Prepares) and resource (an immutable, separately confirmable Amazon Ads plan) and scopes it to ad-group default bids, states, and names. The clause 'without changing advertising entities' implicitly separates it from apply_ad_group_changes, though that sibling is never named.

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

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

Usage is implied by 'immutable, separately confirmable plan' — an agent infers this is the pre-apply step — but no explicit when-to-use/when-not or next-step guidance is given. The description never points to confirm_workflow_plan or apply_ad_group_changes, which matters in a family of ~10 prepare_*/apply_* pairs.

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

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

With annotations only saying readOnlyHint=false and destructiveHint=false, the description adds genuinely useful context: it persists a plan but does not modify advertising entities, and the plan is immutable. It does not state plan lifetime, what confirmation consumes it, or any failure/rate-limit behavior, which keeps it from 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 short sentences, front-loaded with the plan concept and no filler. The middle sentence 'Creates advertising ad groups' slightly risks being read as immediate execution, requiring the third sentence to disambiguate.

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?

Complete for a plan-preparation tool: schema is exhaustive and an output schema exists, so return values need no explanation. The one remaining gap is that the description never points to the confirming tool or describes the confirm step the plan is prepared for.

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 nested adGroups/defaultBid/automaticTargetBidding semantics are already documented in the schema. The description restates defaultBid and server-side adProduct resolution, adding little 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?

The description states a specific verb and resource ('Prepares an immutable, separately confirmable Amazon Ads plan. Creates advertising ad groups') and clarifies the scope boundary by saying it persists an internal plan without changing advertising entities. It implicitly contrasts with the apply_ad_group_creation sibling, though it never names it.

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

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

'Separately confirmable' implies a prepare-then-confirm workflow, but the description never says explicitly to use this instead of apply_ad_group_creation or that a follow-up confirmation step is required. The selection logic must be inferred from sibling names alone.

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

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

Annotations already declare readOnlyHint=false with destructiveHint=false; the description adds the crucial nuance that the only side effect is persisting an internal immutable plan, not mutating ads. It stops short of describing plan lifetime, staleness/expiry, or the confirm step needed before execution.

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, no filler, with the nature of the tool and its non-mutating guarantee front-loaded. Every clause carries information.

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

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

For a tool with a deeply nested schema, a 20-operation cap, action-scoped snapshot staleness, and a large prepare/apply/confirm sibling family, the description omits the lifecycle (what to call next to confirm or apply) and any mention of plan invalidation. An output schema exists, so return-value detail is not required, but the workflow context is thin.

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

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

Schema description coverage is 100% and the nested schema itself documents operations, selectors, action/value shapes, date ranges, and staleness semantics in detail. The description only restates the field domain ('budget, ENABLED/PAUSED state, or name changes'), adding nothing beyond what the schema already provides.

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: prepares an immutable plan that changes campaign budgets, states, or names, and explicitly says advertising entities are not modified. That distinguishes it from apply_campaign_changes, but it never names the sibling nor distinguishes itself from prepare_campaign_creation or prepare_workflow_draft.

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?

'Separately confirmable' hints at the prepare-then-confirm flow, and 'persists an internal plan without changing advertising entities' implies it is the non-executing counterpart to apply_campaign_changes. But no alternative is named and no explicit 'use this when / not when' guidance is given, so an agent must infer the workflow.

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 declare non-read-only, non-destructive, closed-world, and the description adds real context beyond them: the plan is immutable, persisted internally, and has no effect on live advertising entities until separately confirmed. It does not quantify plan lifetime or confirm permissions, 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 short sentences, each carrying distinct information – what it does, its scope, and its side-effect profile – with the key differentiator (immutable, confirmable plan) 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?

An output schema exists and the nested schema carries the heavy parameter documentation, so return values and field semantics are covered. What remains missing for a multi-step workflow tool is the explicit next action (confirm_workflow_plan / apply_campaign_creation), though 'separately confirmable' points in that direction.

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

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

Schema coverage is 100% and the nested schema already documents every field, so the baseline is 3; the description adds meaning by explaining adProduct is reserved for future Sponsored Brands/Display, that targetingType controls automatic target creation on execution, and that the server derives marketplace fields. It does not add field-level syntax beyond that.

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

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

Names a specific verb and resource (prepare an Amazon Ads campaign plan for Sponsored Products) and distinguishes planning from execution with 'without changing advertising entities.' The middle sentence 'Creates Sponsored Products campaigns' is momentarily misleading for a prepare tool, but the surrounding sentences scope it to a plan.

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?

Implies the two-step flow via 'immutable, separately confirmable plan,' but never names apply_campaign_creation or confirm_workflow_plan as the follow-up, nor states when to use this instead of apply_campaign_creation. Usage must be inferred from the sibling naming 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 declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, but the description adds substantial context beyond them: the plan is immutable and requires explicit customer approval, an empty set clears associations, competitor validation may read fresh Amazon Catalog relationships, and changed relationships require a new plan with no silent cached fallback. These are real behavioral traits 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?

Front-loaded with the core action and scope, then the exclusions. Mostly every sentence earns its place, though the 'Does not apply tracking changes' point is partially redundant with the workflow note in the schema description.

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 rich annotations, an output schema, and a fully described nested input schema, the description covers everything else needed: immutability, approval requirement, clearing semantics, fresh-validation caveats, and the follow-on execution step. 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 description coverage is 100% and the nested fields already document critical semantics — competitorAsins is a 'Complete replacement set, not an append,' empty array clears, PARENT vs CHILD ASIN rules, max 10. The description's 'Replaces the full associated competitor set' and 'An empty set clears associations' merely echo what the schema already states, 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 — 'Prepares and persists an immutable keyword-rank tracking change plan' — and scopes it precisely to replacing 'the full associated competitor set of one existing owned-product tracker.' This clearly separates it from apply_keyword_rank_competitor_replacement (execution) and prepare_keyword_rank_tracking_changes (keyword changes).

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 what it does NOT do — 'Does not create independent competitor tracking or change keyword status. Does not apply tracking changes' — and the schema description lays out the prepare → review → approve → confirm → execute workflow and says to query capabilities and quotas first. It stops short of naming the specific alternative siblings (e.g., prepare_keyword_rank_tracking_changes) for other change types.

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

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

Goes well past the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false) by disclosing that the plan is immutable and persisted, that ARCHIVED preserves ranking history and the resulting state is NOT_TRACKED rather than an ARCHIVED state, that removing the last keyword drops the target from its tracking list, and that ACTIVE only resumes system-paused collection after package and quota checks. It also disclaims Amazon Catalog access, which matters for a non-open-world tool.

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

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

Front-loaded with the core action and scope, then bounded by a compact set of 'does not' exclusions that each remove a real ambiguity. It is dense and mostly waste-free, though the repeated negation clauses read as somewhat clipped and could be merged into one boundary sentence.

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, full annotation coverage, and a fully described nested schema, the description supplies exactly the missing layer: the prepare/review/confirm/execute lifecycle, the prerequisite capability and quota check, and the state semantics of the two allowed changes. Nothing needed to select or invoke the tool 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 single top-level parameter is a deeply documented nested object, so the baseline is 3. The description adds semantics the schema does not: the operation only mutates already-existing tracking entries and works against the account's existing tracking, which tells the agent items must reference tracked keywords rather than new ones.

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

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

States a precise verb+resource ('Prepares and persists an immutable keyword-rank tracking change plan') and immediately bounds the operation to status updates ACTIVE/ARCHIVED on existing tracking. Explicitly negates the neighboring capabilities ('Does not create tracking', 'Does not apply tracking changes'), so an agent can separate it from prepare_keyword_rank_tracking_creation and apply_keyword_rank_tracking_changes without consulting 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?

The flow is spelled out: prepare -> explicit customer review -> approval -> confirm -> matching execution tool, plus the precondition to query capabilities and quotas first. Exclusions route the agent away from creation and application. Slight deduction because the alternative tools are described by negation ('matching execution tool') rather than named outright.

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 declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true; the description earns credit by explaining that open-world behavior concretely ('Competitor validation may read fresh Amazon Catalog product relationships') and by clarifying that the persisted plan is immutable and non-applying. It stops short of stating auth/scope prerequisites (e.g. required capability for competitor tracking), which would push it higher.

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

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

Four compact sentences, front-loaded with the core action and the immutability guarantee, followed by scope and non-goals. Minor redundancy between 'Does not apply tracking changes' and the review framing, but no wasted bulk.

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, full schema coverage, and annotations present, the description supplies exactly the missing behavioral context: immutability of the plan, non-application, competitor Catalog reads, and routing for excluded cases. Nothing an agent needs to select or 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 nested, so the schema already carries parameter meaning (trackingScope, productType, asin vs parentAsin, keyword limits). The description only adds a light gloss on owned-vs-competitor tracking, so baseline 3 is appropriate.

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

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

Names a specific verb and resource ('Prepares and persists an immutable keyword-rank tracking change plan') and immediately delineates scope: owned products vs independent competitors. It distinguishes itself from apply_keyword_rank_tracking_creation ('Does not apply tracking changes') and from prepare_keyword_rank_tracking_changes ('paused tracking must use the status changes tool').

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

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

Gives explicit exclusions and routing: existing active tracking is untouched, paused tracking belongs to the status-changes tool, and this tool does not apply changes. It implies the prepare→review→apply flow via 'explicit customer review' but never names the execution sibling (apply_keyword_rank_tracking_creation) or the confirm step, which the agent must infer.

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

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

Annotations only declare readOnlyHint=false, destructiveHint=false and openWorldHint=false; the description adds the meaningful context that the plan is immutable, is separately confirmable, and does not mutate advertising entities. It stops short of disclosing plan lifetime/expiry or what happens to a plan that is never confirmed.

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 plan concept and the non-mutation guarantee. No restatement of the tool name or filler.

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

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

With an output schema, full annotation coverage and a richly described nested input schema, the description carries enough for correct invocation. The remaining gap is workflow-level: it never names the confirm/cancel tools or states that the plan must be confirmed before any ad state actually changes.

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

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

Schema coverage is 100% and the nested schema already explains storeId format, selector fields, the SET_STATE/SET_NAME action shape, and the 1-20 operation limit. The description only echoes the change types, adding little beyond the schema (it does not, for example, clarify how selector combinations are scoped), so baseline 3 is appropriate.

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

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

The description names a specific verb (prepares) and a precise resource (an immutable, separately confirmable Amazon Ads plan for product ads), and states exactly what the plan covers: ad state changes and supported Sponsored Brands ad names. The phrase 'persists an internal plan without changing advertising entities' cleanly separates it from the apply_* siblings.

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

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

It makes clear this is the staging step (prepare then separately confirm) and that nothing is applied yet, which is the key usage decision against apply_product_ad_changes. It does not explicitly name confirm_workflow_plan/apply_product_ad_changes as the next step, nor does it state exclusions such as when a direct apply is preferable.

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 and destructiveHint=false, and the description adds meaningful context: the plan is immutable, must be separately confirmed, and does not change advertising entities. This clarifies the write-to-plan versus write-to-account distinction, which is not captured by annotations alone.

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

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

Three compact sentences with no filler. The key constraints—immutable plan, separately confirmable, no entity changes—are front-loaded before the lower-level 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?

Given an output schema exists and annotations cover the safety profile, the description supplies the essential behavioral context: it creates a plan rather than changing entities and requires separate confirmation. A slightly clearer pointer to the confirm/apply workflow would make it fully complete for an agent navigating this sibling set.

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 nested schema already documents storeId, skus/asins precedence, adGroupId, adGroups, and campaignId in detail. The top-level description adds little parameter-specific meaning beyond saying the tool creates SP or SD product ads, so the schema remains the primary source of parameter semantics.

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

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

The description states a specific verb and resource: it prepares an immutable Amazon Ads plan and creates Sponsored Products or Sponsored Display product ads. It also distinguishes itself from mutation siblings by noting it persists an internal plan 'without changing advertising entities,' though it stops short of naming apply_product_ad_creation explicitly.

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

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

The phrases 'immutable, separately confirmable' and 'persists an internal plan' imply this is a prepare step before confirmation/apply, but the description never states when to use this tool versus apply_product_ad_creation or confirm_workflow_plan. The usage context is inferable but not 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?

Adds real context beyond the annotations: the plan is immutable and separately confirmable, it writes a plan rather than mutating ad entities, negative targeting accepts no bid actions, and archiving is irreversible. Those are non-obvious traits that annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false) do not convey. It stops short of describing the confirmation lifecycle or what the persisted plan record contains.

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

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

Four short sentences, each carrying distinct information, with the core identity (immutable confirmable plan) front-loaded and the constraints (no negative bids, irreversible archive, no entity mutation) following. No filler or restatement of the title.

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

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

Given an output schema exists and annotations cover the safety profile, the description supplies the essential decision information: what the tool does, that it does not mutate entities, and the irreversibility constraint. Slightly incomplete because it does not hint at the follow-up confirmation/apply step that a prepare tool necessarily requires.

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

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

Schema description coverage is 100%, so the baseline would be 3, but the description still adds branch-level meaning: the positive branch handles bids/states while the negative branch is state-only with an irreversible ARCHIVED terminal value. It does not map the oneOf branch structure to targetType values (KEYWORD/TARGET vs NEGATIVE_KEYWORD/NEGATIVE_TARGET) as explicitly as 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 (prepares) plus the exact resource (an immutable, separately confirmable Amazon Ads targeting plan) and enumerates both supported branches: positive keyword/ASIN bid or state changes and negative re-enable/archive. The phrase 'persists an internal plan without changing advertising entities' functionally separates it from apply_targeting_changes, and the positive-vs-negative scope separates it from prepare_targeting_creation.

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

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

'Separately confirmable' and 'Persists an internal plan without changing advertising entities' imply the prepare-then-confirm/apply workflow, which is useful implied guidance. However, it never names the alternative calls (apply_targeting_changes, confirm_workflow_plan) or states an explicit when-to-use/when-not condition, leaving the agent to infer the 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?

Beyond the annotations, the description discloses that the plan is immutable, separately confirmable, and persisted internally without changing advertising entities. This is valuable behavioral context for an agent deciding whether this tool has side effects, though it omits workflow sequencing and error/permission details.

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

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

Four sentences, front-loaded with the core action and plan semantics, with no filler. Each sentence contributes either purpose, supported entity types, batch scope, or side-effect clarification.

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 and rich nested parameter descriptions are present, so the description need not explain return values in detail. It sufficiently covers the prepare-plan semantics and targeting types, though it could more explicitly connect this tool to the subsequent confirm/apply workflow.

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 the nested parameters thoroughly. The description adds only the high-level notion that a batch may contain multiple targeting groups and lists the four targeting types, which is marginal 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 the specific action: preparing an immutable, separately confirmable Amazon Ads plan for targeting creation, and lists the four supported targeting families. It is clearly distinguishable from query or apply siblings, though it does not explicitly name apply_targeting_creation.

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

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

It implies use before a separate confirmation/apply step by saying the plan is 'separately confirmable' and does not change advertising entities, but it never explicitly states when to use this versus apply_targeting_creation or prepare_targeting_changes. No exclusions or alternatives are named.

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 destructiveHint=true annotation: merge-by-clientRef semantics, deletion only via removeClientRefs, optimistic locking with draftId/expectedDraftVersion, server-side persistence and safe resume, and recoverable 429 responses that create no write plan. Nothing contradicts the annotations (omission never deletes, consistent with explicit removal), but the exact effect of a merge on previously supplied nested arrays could be stated more sharply.

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

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

A single dense paragraph of roughly 350 words mixing purpose, collection rules, continuation sequencing, error handling, and validation policy. Nearly every sentence carries information, but the lack of structure or grouping makes it hard to scan, and several points (AUTO negative support, family exclusivity) duplicate schema text.

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

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

Covers the full lifecycle an agent needs: draft creation, incremental update with version locking, the multi-stage continuation ordering, AUTO bid mode decisions, recommendation handling, and the final confirm-and-apply path. With an output schema present, no return-value detail is owed.

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