Vendooly

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

Adds substantial behavior beyond the readOnlyHint annotations: no sampling, and incomplete or stale data raise an error rather than producing false negatives (an explicit anti-false-negative guarantee). The prerequisites (synced data-hub, linked Ads) tell the agent when the call will fail. This is genuinely useful context an agent can act on.

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?

Opens with the READ-ONLY guarantee and follows with output scope, behavior, parameter guidance and prerequisites in a logical order. Dense with parenthetical clauses but every sentence carries information; no filler.

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

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

For a five-parameter tool with no output schema, the description covers the returned fields (SKU, title, stock, sales, coverage), the failure mode, and prerequisites. The gap is the undocumented lookback_days and only_in_stock parameters, but overall an agent has enough to call it correctly.

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

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

Schema coverage is only 40%, so the description must compensate. It does explain the only_with_sales + only_uncovered interaction, but lookback_days and only_in_stock are undocumented in both schema and description, leaving half the parameters ambiguous. Partial compensation only.

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

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

States a specific verb and resource: enumerating every ASIN in an outpost's catalog and recent sales with SKU, title, stock, sales and live Sponsored Products coverage. The scope (coverage audit, one row per ASIN, cross-referencing Product Ads and campaign/group state) differentiates it from siblings like ads_list_sp_product_ads, though it never names an alternative directly.

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 conditional guidance: use only_with_sales=true combined with only_uncovered=true for sold products lacking active SP, and lists prerequisites (synced data-hub, connected Ads). It stops short of naming a sibling alternative or stating when NOT to use this tool.

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

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

Annotations declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds genuinely useful context beyond them: no portfolio-level budget cap and no extra authorization required. It omits the two-step preview/confirm_id write flow, which is only visible in the schema.

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

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

A single front-loaded sentence with two tight parentheticals; nothing is wasted. It could be marginally cleaner but is well structured.

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 create tool with annotations covering the safety profile and no output schema, the description covers purpose, constraints, and auth. The only meaningful omission is the confirm_id two-step behavior, which the schema does document.

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

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

Schema coverage is 67%, and the schema documents the notable confirm_id preview/confirm mechanism and account_id. The description adds no parameter-level meaning, so it neither compensates for the gap nor enhances what the schema provides — 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?

Specific verb+resource ('Create an Amazon Ads portfolio') with a clarifying parenthetical that defines what a portfolio is (a grouping of campaigns). This clearly separates it from ads_list_portfolios and the ads_create_sp_* tools, though it does not name a sibling explicitly.

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

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

Usage is implied ('to group campaigns') rather than stated as when-to-use, and there are no exclusions or alternative paths given. The note about scope/authorization offers some context but does not route the agent between options.

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 non-destructive write (readOnlyHint false, destructiveHint false), and the description adds two traits beyond them: the new ad group defaults to PAUSED, and Amazon will reject mixed targeting with an otherError. It does not cover the confirm_id preview-then-write flow in prose, but the schema documents that token.

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

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

Front-loads the core action and default state, then the critical constraint. The bulk of the payload is a dense but earned domain warning; the only real structural cost is the mid-description language switch to Italian, which is jarring in an otherwise English toolset.

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

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

For a mutation tool with no output schema and a private (openWorldHint false) backend, the description covers the default state, the key failure mode, and the correct workaround involving two sibling create tools. It omits sequencing with ads_create_sp_campaign, but the essential call-time context is present.

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

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

Schema description coverage is 67% and the required nested fields (name, campaign_id, default_bid) are self-evident from the schema. The description's targeting-type rule is behavioural rather than parameter-level, so it adds little parameter meaning beyond what the schema already carries.

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

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

States a specific verb and resource (create a SP ad group) and scopes it to an existing campaign, which cleanly separates it from the ads_update_sp_ad_group and ads_list_sp_ad_groups siblings. An agent knows exactly what this produces without opening the schema.

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

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

Gives unusually specific domain guidance: an ad group must be keyword-targeted OR product-targeted, never both, and it routes the agent to ads_create_sp_keywords and ads_create_sp_product_targets for the two separate ad groups. It stops short of stating prerequisites such as creating the campaign first or previewing via confirm_id, but the when-to-use routing is strong.

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

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

Annotations only declare readOnlyHint=false, destructiveHint=false and openWorldHint=false. The description adds genuine domain behavior beyond that: the AUTO mode forbids manual keywords/targets and requires ads_create_sp_product_targets with auto_match to modulate bids, the placement percentage range (0-900%), and the allowed strategy values. It does not surface that this write is gated behind a confirm_id preview flow, which the schema carries instead.

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

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

It is a single dense run-on paragraph that packs purpose, mode branching, follow-up tools, placement syntax and strategy enums into sentence fragments, with Italian/English mixing. Content is mostly load-bearing and front-loaded, but the lack of bullet/line separation for the many enum lists hurts scanability.

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

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

For a 3-parameter nested write tool with no output schema, the description covers the decisions that matter: which targeting mode, how to format placement bidding, which strategy to choose, and which tools continue the workflow. The remaining gap is the required confirmation step, which an agent must rely on the schema's confirm_id description to discover.

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

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

Schema coverage is 67% and the nested fields (dynamic_bidding, placement_bidding items) carry no schema descriptions at all, so the description does real work: it supplies the targeting_type default and behavior, the placement enum values and 0-900% range, the dynamic_bidding.strategy enum, and the meaning of portfolio_id. It leaves name, state, daily_budget and the date fields unexplained, so it does not fully compensate for the coverage gap.

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

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

Opens with a specific verb+resource ('Create a SP campaign') and immediately differentiates the two creation modes (AUTO vs MANUAL), which is the key branch point. It also routes the agent to the correct sibling tools for the follow-up work (ads_create_sp_keywords, ads_create_sp_product_targets), so an agent can place it among the many ads_* tools without opening a schema.

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

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

Explicitly states when to pick AUTO ('NON aggiungere keyword/target manuali') versus MANUAL ('default; poi attacchi keyword via ... o ASIN via ...'), and names the alternative tools for each path. It omits any mention of the preview/confirm two-step requirement and the account_id prerequisite (both only in the schema), so it falls short of full when/when-not guidance.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false), the description adds important behavioral context: Amazon will reject the request with otherError if the ad group already contains a product target, and an ad group cannot mix keyword and product targeting. This is useful mutation-specific transparency.

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

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

The description is front-loaded with purpose and then provides the critical constraint and payload shape without unnecessary filler. However, the mix of Italian and English may reduce immediate readability for some agents, and the middle sentence is dense.

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

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

For a create tool with no output schema, the description covers the key operational constraint, mutation behavior, and keyword payload structure. It does not describe return values or the two-step preview/confirm flow, but the schema's confirm_id description covers the latter adequately.

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

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

Schema coverage is 67%, and the keywords parameter is an untyped array in the schema. The description compensates by specifying each keyword object's fields: campaign_id, ad_group_id, keyword_text, match_type (BROAD|PHRASE|EXACT), and bid. This adds critical meaning beyond the structured 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 opens with a specific verb and resource: 'Create SP keywords.' It also implicitly distinguishes itself from sibling tools like ads_create_sp_product_targets and ads_create_sp_negative_keywords by specifying that the target ad group must be keyword-targeted and that an ad group is keyword OR product, never both.

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

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

It gives a clear prerequisite and fallback: the target ad group must be keyword-targeted; if it already has a product target, Amazon rejects the call with otherError, so a dedicated keyword ad group should be created. It does not explicitly name alternative sibling tools or cover the preview/confirm workflow, leaving some guidance implied.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, and the description adds nothing on top. Critically, it omits the two-step behavior implied by confirm_id (a preview call returning a token, then a repeat call with the same payload to actually write), which is exactly the kind of trait the description should surface.

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 words, front-loaded, no waste — but the brevity is under-specification rather than efficiency. It cannot be called verbose, yet it also fails to earn its place with any useful content.

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

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

For a mutation tool with no output schema, an undocumented required array parameter, and a non-obvious confirmation flow, this description is far too thin. It provides no permissions, side-effect, or workflow context.

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

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

Schema coverage is only 67%, and the description contributes zero parameter meaning. The required 'negatives' array has no description in either the schema or the description, leaving the agent without the shape or syntax of the core input.

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 merely restates the tool name and the annotation title: 'Create SP negative keywords'. It states a verb and resource, but adds no distinguishing detail versus siblings such as ads_create_sp_negative_targets or ads_create_sp_keywords, which are functionally adjacent.

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

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

No guidance on when to use this versus the negative-targets or positive-keyword creation tools, and no mention of the preview/confirmation workflow implied by confirm_id. The agent is left to infer everything from the name.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the agent knows this is a destructive write. The description adds no behavioral context beyond that — it does not mention the preview/confirm two-step flow (only hinted at by the schema's confirm_id), any limits, or what effect negative targets have.

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 terse sentences, front-loaded with the action and then the payload contract. No filler, every clause carries information.

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

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

For a destructive, no-output-schema mutation tool the description covers purpose and payload, but omits the confirmation workflow, validation constraints, and error behavior. The destructiveHint annotation carries the safety profile, so this is adequate but not complete.

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

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

The schema leaves the required `targets` array with no item schema, and the description fills that gap by specifying each element's fields: campaign_id, ad_group_id, and asin (or raw expression). This is genuine added meaning for the one required parameter, though the optional account_id/confirm_id semantics are covered only in the schema.

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

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

"Create SP negative product targets" gives a clear verb (create) and specific resource (SP negative product targets), which distinguishes it from the sibling ads_create_sp_negative_keywords and ads_create_sp_product_targets. It is a clear statement of purpose, though it does not explicitly name the alternatives it differs from.

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 no when-to-use context, no when-not-to-use, and no mention of alternatives such as ads_create_sp_negative_keywords (keyword-level negatives) or the corresponding delete/list tools. It only explains the payload shape, leaving the agent to infer when this tool is appropriate.

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, so the basic safety profile is covered. However, the schema reveals a non-obvious two-phase behavior (a confirm_id token returned by an 'anteprima'/preview that must be replayed with the identical payload to actually write), and the description says nothing about this preview-confirm flow, nor about account scoping or side effects.

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

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

At four words there is no filler, but this is under-specification rather than conciseness. The single phrase is a duplicate of the title and earns no additional place in the agent's decision process.

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 write tool with an untyped required array, no output schema, and a hidden preview/confirm workflow, the description is far too thin. Nothing tells the agent what a valid ads payload looks like, what happens on success, or that a preview step precedes the real write.

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 a middling 67%: account_id and confirm_id carry Italian-language descriptions while the required 'ads' array is a bare array with no element shape documented. The description adds zero parameter meaning on top of the schema, so it fails to compensate for the undocumented required payload.

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 is a verbatim restatement of the tool title and name ('Create SP product ads'), which is the textbook tautology case. It conveys a create verb on an SP product-ads resource, but it gives no scope, no distinguishing detail, and no contrast with siblings such as ads_create_sp_product_targets, ads_create_sp_keywords, or ads_create_sp_campaign.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives within the large ads_* family. An agent must infer from the name alone when this belongs in a campaign-creation workflow versus a keyword or target creation call.

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

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

Annotations already flag this as a destructive write (destructiveHint=true, readOnlyHint=false). The description adds real behavioral value: it warns that re-creating the 4 AUTO matching groups on an existing campaign yields INVALID_ARGUMENT, preventing a likely failure. It does not cover auth/prerequisites beyond what the schema's confirm_id implies, hence not a 5.

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

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

Front-loaded with the core action, and every subsequent sentence carries decision-relevant detail (mode payloads, error pitfall, alternative tool). It is dense rather than padded, though the bilingual phrasing and long parentheticals make it slightly heavier than necessary.

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

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

For a destructive write tool with no output schema, the description equips an agent to call it correctly: it defines both payload variants, the enum meanings, and the key failure mode. It leaves the confirm_id two-step flow to the schema, which is acceptable since the schema documents it.

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

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

The schema types 'targets' only as an untyped array at 67% coverage, so it carries little meaning. The description compensates strongly by spelling out the exact object fields for both MANUAL (campaign_id, ad_group_id, bid, asin/category_id/expression) and AUTO (auto_match) targets, including the semantics of each auto_match enum value.

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

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

States a specific verb and resource ('Create SP targets') and then clearly distinguishes the two operating modes (MANUAL vs AUTO) with distinct payload shapes. An agent can immediately tell what this creates and how it differs from sibling list/update/delete target tools.

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

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

Explicitly covers when to use it, when NOT to use it (existing AUTO campaigns already have the 4 groups), and names the correct alternative path (ads_list_sp_targets + ads_update_sp_target_bid) for the bid-only case. This is textbook routing guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds meaningful context beyond them: the operation is irreversible, an archived campaign cannot be reactivated, and it must be recreated. It stops short of explaining the confirm_id preview/double-submit flow described in the schema, which is a notable behavioral requirement for 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 action, followed by the key differentiator and the irreversibility warning, then the payload hint. No wasted sentences; 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?

For a destructive tool with no output schema and 75% param coverage, the description covers the critical safety information (irreversibility, no reactivation). The one gap is that it never mentions the confirm_id preview-then-execute step that the schema implies, leaving the agent to discover the confirmation flow elsewhere.

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

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

Schema coverage is 75%, so the schema already documents account_id and confirm_id in detail plus campaign_ids. The description only restates the campaign_ids array shape (no syntax/format detail) and adds nothing about the two-phase confirm_id pattern, so it does not meaningfully exceed the schema.

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

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

The description names a specific verb+resource ('Archivia (elimina) una o più campagne SP') and explicitly distinguishes itself from the sibling ads_update_sp_campaign, stating why that tool cannot do this. An agent can select this tool without opening any schema.

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

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

It states this is the ONLY way to archive an SP campaign and explains the alternative's limitation (ads_update_sp_campaign only accepts ENABLED|PAUSED because Amazon rejects ARCHIVED on PUT). This is explicit when-to-use and when-not-to-use 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds nothing beyond that: it does not say the deletion is permanent/irreversible, whether it cascades, or that a two-step confirmation (evidenced by the confirm_id param) is required.

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

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

It is a single four-word phrase with no wasted sentences, but this is under-specification rather than effective conciseness — the brevity carries no front-loaded operational detail.

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

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

For a destructive mutation tool with no output schema and only 50% parameter documentation, the description should carry far more load. Instead it delegates all meaning to a sparse schema and the annotations, leaving the confirmation flow and ID sourcing unexplained.

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

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

With 50% schema description coverage, the description is expected to compensate, but it adds zero parameter meaning. keyword_ids (the required array) has no description, profile_id is undocumented, and the two-step confirm_id/account_id semantics are only discoverable by reading the Italian schema text.

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

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

The description is essentially the title/name restated: 'Delete SP negative keywords' adds no scope, no effect, and no differentiation from the many sibling delete tools (ads_delete_sp_negative_targets, ads_delete_sp_targets, ads_delete_sp_campaign). An agent learns nothing about what 'SP negative keywords' means operationally beyond the name.

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

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

No when-to-use guidance, no exclusions, and no pointer to alternatives such as ads_list_sp_negative_keywords (to find IDs) or the sibling delete variants. The agent must infer the workflow entirely from the name.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description does add one real behavioral fact beyond annotations — '(archive)' signals a soft/reversible delete rather than a hard purge. However, it omits the confirmation workflow implied by confirm_id, idempotency, and the effect on live campaigns, which matters for 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?

A single front-loaded sentence with zero wasted words; the resource and operation lead. It is terse to the point of under-specification, but as a conciseness measure 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 destructive 4-parameter mutation with no output schema, the description should explain the preview/confirm requirement and expected outcome; it does neither, and the required target_ids parameter is undocumented in both description and schema. Only the destructive annotation carries context.

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

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

Schema description coverage is only 50%: account_id and confirm_id are documented, but profile_id and the required target_ids have no description anywhere. The description adds no parameter-level meaning at all, so it fails to compensate for the coverage gap on the one required field.

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 ('Delete SP negative product targets') with the clarifying parenthetical '(archive)'. An agent can distinguish it from ads_delete_sp_targets (positive targets) and ads_delete_sp_negative_keywords, though the description never names those siblings explicitly.

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

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

There is no when-to-use guidance, no prerequisite (e.g. needing a preview first), and no mention of alternatives such as ads_delete_sp_targets. The schema exposes a confirm_id preview/confirm flow, but the description never tells the agent that deletion is a two-step operation.

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, so the safety profile is covered. The description adds a genuinely useful nuance by equating delete with archive (soft delete), but it omits the two-step confirm_id write workflow and any statement of what happens to the archived targets.

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 terse phrase with zero waste and the essential action front-loaded. It is efficient, though its brevity borders on under-specification for a destructive operation.

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 mutation with no output schema, an undocumented required parameter, and a confirm_id confirmation flow, the description is far too thin. It does not tell the agent that confirmation is required or what the operation returns on success.

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

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

Schema coverage is only 50%: account_id and confirm_id are documented, but profile_id and the required target_ids have no descriptions anywhere. The description adds no parameter information to compensate for this gap, leaving the key required parameter unexplained.

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

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

States a specific verb and resource ("Delete SP product targets") and usefully clarifies that delete means archive, which disambiguates the semantics. It does not distinguish itself from sibling tools like ads_delete_sp_negative_targets or ads_delete_sp_campaign, so it stops short of a 5.

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

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

There is no guidance on when to use this tool, no prerequisites, and no mention of alternatives. The agent must infer from the name alone that this is the target-deletion counterpart to ads_create_sp_product_targets.

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, but the description adds substantial behavioral context: intraday refresh cadence (~10-15 min), the consequence at 100% (campaign exits the auction until midnight), and the auto-discovery scope when campaign_ids is omitted (all ENABLED campaigns of the ad product). This is well beyond the annotation surface.

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 "READ-ONLY, LIVE" and the core fact, then the question it answers, then routing guidance. Slightly dense with several parenthetical asides, but each sentence carries distinct information (cadence, 100% behavior, exclusion, auto-discovery default).

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

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

For a 6-param, no-output-schema read tool, the description covers scope (intraday vs daily), cadence, the critical 100% threshold behavior, and default discovery behavior. It does not describe the return shape (per-campaign percentage plus the at_risk list implied by threshold_percent), which is the only notable gap.

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

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

Schema coverage is high (83%), so the schema already documents most parameters; the description still adds the default value for ad_product (SP) and the semantics of omitting campaign_ids, which reinforces rather than duplicates the schema. The threshold_percent/at_risk relationship is left to 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 — how much of each campaign's DAILY budget is consumed today, in percent — and immediately contrasts itself with the sibling data sources (execute_sql for history/ACoS, fact_campaign_daily as daily-only). An agent can distinguish it from every other ads_* tool at a glance.

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

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

Explicit when-to-use ("quali campagne stanno per restare senza budget adesso") and when-not ("Per storico, ACoS, spesa e trend usa execute_sql, NON questo tool"), plus the exclusivity claim that it is the UNICA fonte of today's data. Routing 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 readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds no behavioral context beyond that — no pagination/result-size behavior, no hints about needing a valid account/profile scope, and no indication of what happens when no portfolios exist.

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

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

A single, front-loaded sentence with the verb and resource first. It is efficient and wastes no words, though the parenthetical explanation is slightly redundant for a domain-savvy agent.

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 annotations covering the safety profile and no output schema, the definition is minimally viable. However, with one of two parameters undocumented and no scoping or return-shape context, an agent still lacks what it needs to call this reliably in a multi-account environment.

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

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

Schema description coverage is only 50%: account_id has an (Italian-language) description, but profile_id has none. The tool description says nothing about either parameter, so it fails to compensate for the uncovered parameter and adds no meaning beyond the partial schema documentation.

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

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

States a specific verb and resource ('List Amazon Ads portfolios') and even explains what a portfolio is ('groups of campaigns with optional shared budget'), which helps an agent understand the domain object. It doesn't name or differentiate against any sibling, but there is no competing list_portfolios tool, so ambiguity is low.

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 tool versus alternatives such as ads_list_profiles, ads_list_sp_campaigns, or ads_catalog_coverage. No prerequisites or conditions (e.g., needing an account context first) are stated, leaving routing entirely to inference from the name.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds only the loose scoping hint 'for this account' and says nothing about what a profile is, whether results are paginated, or how the account/token binding affects the call.

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

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

One short front-loaded sentence with zero filler, which is structurally clean. It is arguably under-specified for a list tool, but nothing in the text 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?

Complexity is low (one optional parameter, annotations present), so the definition is nearly complete. However, with no output schema, the description should at least hint at what a 'profile' record contains or how many are returned, and it does not.

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 account_id parameter is fully documented in the schema, including its optionality when the token is bound to one outpost. The description's 'for this account' adds no syntax or semantics beyond that, 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 ('List Amazon Ads profiles'), so an agent knows the operation type. However, it does nothing to distinguish itself from siblings such as ads_list_portfolios or list_clients, which is a meaningful gap in a family of 60+ ads/list tools.

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

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

There is no when-to-use or when-not-to-use guidance and no mention of alternatives or prerequisites. The only scoping note ('for this account') is not framed as a usage condition, leaving the agent to infer when this tool is the right pick.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the 'Read-only' prefix is redundant. The description adds value beyond annotations by naming the returned fields (id, nome, stato, campagna) and the status enum values (ENABLED|PAUSED|ARCHIVED), though it omits pagination or rate-limit behavior.

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

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

A single sentence that front-loads the read-only nature and the resource, then lists return fields and the filter. No words are wasted and the structure is easy to scan.

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

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

For a list tool with annotations covering safety and no output schema, the description does reasonably well by naming returned fields. However, it leaves profile_id undocumented and gives no pagination or filtering syntax details, so it is only minimally complete given the schema 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 only 33%, so the description must compensate. It mentions campaign_id_filter only by name without explaining its format (array of strings) and never addresses profile_id, leaving two of three parameters with no real semantic detail beyond the schema's bare types.

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

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

States a specific verb (elenco = list) and resource (ad group Sponsored Brands SB), and lists returned fields. It implicitly distinguishes itself from siblings like ads_list_sp_ad_groups and ads_list_sd_ad_groups via the 'SB' qualifier, so an agent can tell it apart without opening schemas.

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

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

The only usage guidance is 'Filtra con campaign_id_filter' (filter with campaign_id_filter), which tells how to narrow results but not when to choose this tool over the SP/SD ad group list tools. No explicit alternatives or when-not-to-use conditions are given.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false. The description adds meaningful context beyond that: it returns live/current data, covers only existing campaigns, and explicitly does not return performance metrics. It does not contradict 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?

The description is front-loaded and compact, with the core purpose stated first. The parenthetical about SB creation support is slightly verbose but earns its place by preventing misuse.

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

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

With no output schema and sparse input schema descriptions, the description usefully lists key returned fields and the non-performance scope. However, it leaves the filtering parameters undocumented, which is a notable gap for a list tool that supports filters.

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

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

Schema description coverage is only 25%, and the description does not explain the input parameters account_id, profile_id, state_filter, or campaign_id_filter. The field names it lists are output fields, not input filter semantics, so it does little to compensate for the schema gap.

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

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

States a specific verb and resource: listing the current state of existing Sponsored Brands campaigns. It distinguishes the tool from SB creation (not implemented) and from performance reporting (execute_sql), so an agent can identify its purpose without ambiguity.

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

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

Explicitly routes performance questions (ACoS, spend, sales) to execute_sql on fact_campaign_daily, and clarifies that this tool does not create new SB campaigns. However, it does not explain when to use the state_filter or campaign_id_filter parameters.

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

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

Annotations already establish readOnly/openWorld=false/destructive=false, so safety is covered. The description adds genuinely non-structured behavior: it returns live bid+state values, it deliberately omits performance metrics, and — most valuably — it defines what an empty result means and instructs the agent not to fabricate keywords.

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 identity ('LIVE: ... BID e stato ATTUALI'), followed by usage, exclusion, and edge-case handling in tight sequence. Slightly dense but each sentence carries distinct information.

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

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

No output schema, so the description usefully covers the return shape (current bid/state, not performance) and the empty-result semantics. What remains unaddressed, pagination behavior and the meaning of state_filter, are minor for a read-only list tool whose safety profile is already given by annotations.

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

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

Schema coverage is only 20%, so the description must compensate and does so only partially: it names campaign_id and ad_group_id as filters, but leaves state_filter and profile_id unexplained. account_id is documented in the schema itself. With the two primary filters covered, baseline-adequate but incomplete.

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

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

States a specific verb and resource ('keyword Sponsored Brands con BID e stato ATTUALI') and immediately frames it as the pre-rebid read. Explicitly distinguishes itself from the alternative (execute_sql for performance), so an agent can route correctly without opening the schema.

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

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

Names both when to use ('la lettura da fare prima di riofferire su SB') and when not to ('NON ritorna performance: per spesa/vendite/ACoS usa execute_sql su fact_keyword_daily'), and gives the exact filtering conditions (campaign_id/ad_group_id). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds meaningful behavioral context beyond that: the data is LIVE/current, it deliberately excludes performance metrics, and an empty result is a valid answer that must not be fabricated.

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 telegraphic sentences, front-loaded with the LIVE nature and return contents, then routing, then the anti-hallucination rule. Every clause carries distinct information with no padding.

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

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

With no output schema, the description usefully explains what is returned (bid, state) and the empty-list meaning. However, the filtering parameters that determine which targets appear are left entirely undocumented, so an agent cannot confidently construct filtered calls.

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

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

Schema description coverage is only 20% (only account_id is documented) across 5 parameters. The description hints that results are scoped to 'questo profilo' but never explains state_filter, campaign_id, ad_group_id, or profile_id semantics, so it fails to compensate for the coverage gap.

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

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

States a specific verb+resource ('LIVE ... product target Sponsored Brands') and enumerates the target kinds (ASIN/categoria/brand) plus the fields returned (BID e stato ATTUALI). It clearly distinguishes itself from sibling list tools such as ads_list_sp_targets and ads_list_sb_keywords.

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

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

Explicitly routes the agent: the returned target_id feeds ads_update_sb_target_bid, and performance questions belong to execute_sql on the data-hub. It also instructs how to handle the empty-list case, which is real when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so 'Read-only' merely repeats structured data. It does add a useful nuance by framing defaultBid as the SD optimization lever, but says nothing about pagination, result limits, or auth requirements beyond the account_id hint in the schema.

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

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

A single dense sentence that front-loads the read-only nature and resource before the field list and filter hint. No padding, though the mixed Italian/English phrasing slightly hurts scannability.

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

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

For a read-only list tool with no output schema, enumerating returned fields is helpful, but the under-documented parameters (75% undocumented) and absent pagination/volume guidance leave gaps an agent must guess at.

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

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

Schema coverage is only 25% and three of four parameters (profile_id, state_filter, campaign_id_filter) have no schema description. The description names campaign_id_filter but gives no value format or behavior, and ignores state_filter and profile_id entirely, so it does not compensate for the coverage gap.

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

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

Clear verb (list/read) plus specific resource (Sponsored Display ad groups), with the returned fields enumerated (id, nome, stato, campagna, defaultBid). An agent can distinguish it from ads_list_sp_ad_groups and ads_list_sb_ad_groups purely from the name and description.

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 sentence 'Filtra con campaign_id_filter' implies the filtering use case but never states when to use this tool versus the SP/SB ad-group siblings or when not to. Usage is inferable 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds useful behavioral context by listing the exact fields returned (name, campaignId, state, budget, tactic, costType, bidOptimization) and stating that performance is not returned. It does not disclose pagination or result limits, 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?

The description is front-loaded with the resource and its live/existing scope, then quickly enumerates return fields and exclusions. Each sentence earns its place by clarifying scope, preventing misuse for creation or performance queries, and naming the alternative. There is no redundant or filler content.

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

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

With no output schema, the description usefully explains the main return fields and states that performance data is absent. However, it gives no guidance on how to use the filter parameters or what results look like beyond the field list. For a list tool with four parameters and low schema coverage, this is adequate but incomplete.

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

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

Schema description coverage is only 25%, and the description does not explain the input parameters account_id, profile_id, state_filter, or campaign_id_filter. It mentions state values (enabled|paused|archived) as returned fields, but does not connect them to filtering behavior. With four parameters and low schema coverage, the description fails to compensate for missing 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: listing LIVE existing Sponsored Display (SD) campaigns. It enumerates returned fields and distinguishes this tool from Sponsored Products/Sponsored Brands siblings by explicitly scoping to SD. It also clarifies that Vendooly does not create SD campaigns, preventing confusion with creation tools.

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

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

The description gives explicit when-not guidance: Vendooly does not create SD campaigns, and this tool does not return performance data. It names the correct alternative for performance analysis, instructing the agent to use execute_sql on fact_campaign_daily with ad_product='SD'. This clearly routes the agent away from using this list tool for metrics.

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 and openWorldHint, so the description's 'Read-only' phrasing is largely redundant. Its one genuine contribution is naming the returned fields, which partials compensate for the absent output schema, but no pagination or filtering behavior is disclosed.

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

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

A single compact sentence with the resource scoping front-loaded; nothing is wasted. It is arguably under-specified rather than padded, which is the better failure mode.

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 list tool with three filter parameters, no output schema, and low schema coverage, the description omits how to scope results (e.g., by campaign_id or account) and what pagination or volume to expect. An agent can guess the call but not use it well.

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

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

Schema description coverage is only 33%: account_id has a (non-English) description, while profile_id and campaign_id have none. The description never mentions the parameters at all, so it fails to compensate for the undocumented campaign_id scoping, which is critical for a list tool.

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 ('Read-only list of Sponsored Products ad groups') and even enumerates returned fields (id, name, state, default bid). The 'Sponsored Products' qualifier implicitly distinguishes it from the SB and SD ad group siblings, but it never names those alternatives explicitly.

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

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

There is no guidance on when to use this list versus ads_list_sp_campaigns, ads_list_sp_targets, or the SB/SD equivalents, and no prerequisite or filtering context. An agent must infer usage entirely from the tool name.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the bar is lower; the description still adds the return shape (audience_id, name, description, source), the IT/DE/FR/ES/UK availability, and an anti-hallucination warning about not inventing audience_id. The redundant 'READ-ONLY' opener adds nothing over the annotation.

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 scope and packs source semantics, return fields and routing into a compact block; every sentence carries information. It is dense and slightly run-on, but there is no padding.

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

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

No output schema exists, and the description compensates by naming the returned fields plus the downstream tool that consumes them. For a zero-required-parameter list tool with a clear follow-up path, this is close to complete; only the non-documented locale/profile_id parameters remain unexplained.

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

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

With 60% schema coverage the description usefully expands the source enum ('amazon' = Amazon-built audiences with concrete examples, 'amc' = Amazon Marketing Cloud, 'all') and confirms search as an optional text filter, adding meaning beyond the bare enum. locale, account_id and profile_id are left to the schema, which only partly compensates.

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 ('Elenca i SEGMENTI DI PUBBLICO ... per i moltiplicatori di bid delle campagne Sponsored Products') and scopes it to audience bid adjustments. It is immediately distinguishable from sibling list tools like ads_list_sp_campaigns and ads_list_sp_targets.

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

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

Explicitly routes the agent: returned audience_id must be passed to ads_update_sp_audience_bidding, and segments already set on a campaign are read via ads_list_sp_campaigns. It lacks an explicit 'do not use this when...' clause, but the routing context is unusually clear.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower; the description still adds real context by flagging LIVE data, clarifying that daily_budget is numeric in marketplace currency and that no campaign-level bid exists, and describing the shape of placement_adjustments and audience_adjustments. It does not describe pagination or result limits, which keeps it out of 5 territory.

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 LIVE scope, then fields, then exclusions/alternatives; each clause carries information an agent needs. It is dense but long, and a few field enumerations (e.g., placement keys) could arguably be trimmed, so not a clean 5.

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

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

No output schema exists, and the description compensates well by naming the returned fields, what is absent (performance metrics, campaign-level bid), and where to get each missing thing. The one real gap is the undocumented state_filter/profile_id behavior, which leaves a filter-capable list tool partially under-specified.

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

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

Schema coverage is only 33%: account_id is documented in the schema, but profile_id and state_filter have no descriptions. The description makes no attempt to compensate — it never mentions state_filter's accepted values or profile_id's role, so the filter parameter's semantics are left to inference from its name.

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

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

States a specific verb and resource (live current state of SP campaigns) and enumerates the exact returned fields (name, campaignId, state, targetingType, daily_budget, bidding_strategy, placement_adjustments, audience_adjustments). An agent can distinguish this from ads_list_sb_campaigns/ads_list_sd_campaigns and from the update/create siblings without opening a schema.

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

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

Explicit when-to-use ('Usa per VERIFICARE prima di agire o per avere nomi/ID') and explicit when-not with named alternatives ('NON ritorna performance: per ACoS/spesa/ROAS/vendite/click usa execute_sql su fact_campaign_daily', and fact_campaign_placement_daily for placement performance). Routing to ads_list_sp_audiences and ads_update_sp_audience_bidding is also given.

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

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

Annotations already declare readOnlyHint/openWorldHint/destructiveHint, so safety is covered. The description adds non-obvious behavior: the data is LIVE/current (not cached/aggregated) and deliberately excludes performance metrics, which is real value beyond the annotations. It does not, however, mention pagination or scope limits of the returned set.

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

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

Two front-loaded sentences, no filler. The scope/boundary statement is stated first and the redirect to the alternative second, so no token 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 list tool with no output schema, the description does convey the essential return content (bid + state) and the absence of performance fields. However, it leaves the meaning of three of four filter parameters unexplained, which matters for correctly narrowing the query.

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

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

Schema description coverage is only 25% — only account_id is documented, and profile_id, ad_group_id, and campaign_id are bare strings. The description says nothing about what these filters do or whether they combine, so it fails to compensate for the coverage gap that the low-coverage rule requires.

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

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

States a specific verb and resource (list live SP keywords) plus the exact scope: current bid and state. An agent can distinguish it from ads_list_sb_keywords, ads_list_sp_targets, and the create/update siblings from the name and first clause alone.

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

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

Explicitly states when to use it ('per agire o verificare' — for bidding/acting or verifying) and when not to (no performance data), naming the concrete alternative `execute_sql` on `fact_keyword_daily` for spend/sales/ACoS/wasted-keyword questions. This is a textbook when/when-not/alternative routing.

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

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

Annotations already declare this is a read-only, non-destructive, closed-world operation, so the safety profile is covered. The description adds no further behavioral context such as pagination, scope of results, or filtering behavior, which would be valuable for a list tool.

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

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

The description is a single four-word phrase, front-loaded and free of waste. It is arguably under-specified, but that is a completeness concern rather than a structural flaw.

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 list tool with four optional filter parameters, no output schema, and sparse parameter documentation, the description is far too thin. It does not explain what is returned, how results are filtered, or how to use the optional IDs.

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

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

The description mentions no parameters at all. With only 25% schema description coverage, the description is expected to compensate for undocumented parameters (profile_id, ad_group_id, campaign_id), but it provides zero 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 (List) and resource (SP negative keywords), making the tool's basic purpose clear. However, it does not differentiate this tool from closely named siblings like ads_list_sp_keywords or ads_list_sp_negative_targets, so an agent must still infer which list is appropriate.

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

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

There is no guidance on when to use this tool versus alternatives, nor any prerequisites or filtering conditions. The agent is left to infer usage from the name alone.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds no further behavioral context such as pagination, return format, or filtering behavior, so it does not enrich what the annotations already provide.

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

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

The description is a single, front-loaded sentence with no wasted words. However, it is so sparse that it fails to earn its place as useful context, making it concise but under-specified rather than optimally structured.

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 list tool with four optional parameters and no output schema, the description is incomplete. It does not clarify what is returned, how to filter by campaign/ad group, or what 'SP' refers to, leaving the agent with insufficient information to call the tool correctly in context.

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

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

Schema description coverage is only 25%, and the description mentions none of the four parameters (account_id, profile_id, ad_group_id, campaign_id). With low coverage, the description should compensate by explaining parameter meaning or filtering behavior, but it provides no parameter semantics at all.

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

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

States a specific verb (List) and resource (SP negative product targets), which is enough to distinguish it from sibling list tools like ads_list_sp_targets or ads_list_sp_negative_keywords. However, it does not explicitly differentiate from those siblings or explain what 'SP' means, leaving some ambiguity for an agent unfamiliar with the domain.

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 no guidance on when to use this tool versus alternatives, nor any prerequisites or context. The name implies it lists negative product targets, but the description does not say when an agent should choose this over ads_list_sp_targets or ads_list_sp_negative_keywords.

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's 'READ-ONLY LIVE' is consistent with that. It adds useful behavioral detail beyond annotations: default all_pages=true, one-page Amazon reads when false, and next_token behavior after ASIN/SKU filtering.

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

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

The description is short, front-loaded with the read-only nature, and every sentence contributes operational guidance. It avoids redundant restatement of the tool name and schema fields.

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

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

For a 10-parameter listing tool with no output schema, it describes both pagination behavior and returned fields (ASIN/SKU, state, campaign/group names and states). It still omits some optional ID and paging parameters, but the core call behavior and alternative route are covered.

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

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

Schema description coverage is only 20%, so the description must carry more parameter meaning. It adds useful semantics for all_pages, next_token, and exact ASIN/SKU filters, but many parameters such as page_size, profile_id, ad_group_id, campaign_id, and state_filter are left largely to 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: listing SP product ads, with ASIN/SKU, state, campaign and ad-group names/states. It also distinguishes itself from ads_catalog_coverage for uncovered ASINs, so an agent can identify the tool's scope without opening the schema.

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

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

Provides explicit context for the default full-list mode and for all_pages=false, including the next_token continuation rule even when a filtered page is empty. It also routes uncovered-ASIN discovery to ads_catalog_coverage, though it does not explicitly compare against other SP list siblings.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is clear. The description adds valuable behavioral context beyond annotations: it specifies the returned fields (targetId, state, and bid if set) and provides a mapping from expression.type to UI group names. It does not mention pagination or rate limits, but the added return and mapping details are substantial.

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 dense but front-loads the core purpose and then provides necessary details like the AUTO group mapping and bid-change workflow. Some sentences are long and could be structured more clearly, but every part appears to serve a purpose and nothing is obviously redundant.

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

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

For a read-only list tool with no output schema, the description does a good job explaining the return fields (targetId, state, bid) and how to use the result for a subsequent bid update. It also warns against creating AUTO targets. However, it leaves some contextual gaps around filtering parameters and pagination, which are not covered by the schema or annotations.

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

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

Schema coverage is only 20% (only account_id has a description), so the description must compensate for the other four parameters. It partially explains campaign_id by implying it is used to retrieve AUTO groups, but profile_id, ad_group_id, and state_filter are completely unexplained, leaving significant gaps for an agent trying to invoke the tool correctly.

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 it lists SP targeting clauses and distinguishes between MANUAL targets (ASIN/category) and the 4 AUTO groups. It also names the sibling update tool and warns against using create tools for AUTO, making it easy to tell apart from siblings like ads_create_sp_product_targets or ads_update_sp_target_bid.

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

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

It explicitly says when to use this tool (to get targetId for an AUTO group bid change) and when not to use alternatives (do not use ads_create_* on AUTO because targets already exist). It also provides a concrete workflow: call this tool with campaign_id, take targetId, then call ads_update_sp_target_bid.

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, so the bar is lower, yet the description adds value by disclosing a behavioral trait annotations cannot: the metric relies on a 30-day cached velocity, which warns the agent that the stock-out signal is lagging, not real-time. It omits permission requirements or response-shape 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?

Front-loads 'READ-ONLY', then the operation, then the user questions. Three compact sentences with minimal waste, though the two quoted example phrasings are somewhat redundant with the preceding clause.

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

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

There is no output schema, so the description must carry more of the return-value burden; it hints at a list of at-risk ad-product overlaps but does not describe the shape, fields, or pagination. For a diagnostic tool it is adequate but leaves the agent guessing about the result format.

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

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

Schema coverage is 67%, and the description adds no parameter-level meaning. days_threshold's default and intent are already in the schema, account_id is documented inline, but profile_id is undocumented in both schema and description. Baseline 3 is appropriate since the description does not compensate for the partial coverage gap.

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

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

States a specific verb (cross-references) over two named resources (catalog days of cover and active SP product ads) and delivers the analytical output ('finds where you are paying for clicks on products close to stock-out'). This is clearly distinguishable from sibling list/CRUD tools like ads_list_sp_product_ads or ads_get_budget_usage.

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 concrete triggering questions ('am I wasting ads budget?', 'are ads pushing products that are running out?') that map well to the tool's purpose. It gives clear context for use but names no alternatives or explicit when-not conditions (e.g., no mention of ads_catalog_coverage as a related diagnostic).

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, so the safety profile is covered. The description adds that it mutates an existing entity's state (ENABLED|PAUSED), but omits meaningful behavioral context such as whether changes are reversible, permission requirements, or that a confirm_id round-trip is needed to actually commit the write.

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

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

Two tight sentences, front-loaded with the core action and its constraint; the exclusion is stated second. No filler.

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

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

For a destructive mutation with a nested, undocumented patches payload and no output schema, the description should say more about what can be patched and how the confirm step works. The schema covers account_id and confirm_id, but the core write payload is left unexplained by both.

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 50%, with the critical nested 'patches' object and 'ad_group_id' undocumented in the schema. The description partially compensates by hinting at patch content (state ENABLED|PAUSED), but does not explain the patches structure or the confirm_id two-step, leaving a real gap.

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

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

States a specific verb ('Aggiorna') and resource (SB ad group), and explicitly distinguishes it from a create operation ('NON crea ad group nuovi'). However it never names the analogous siblings (ads_update_sp_ad_group, ads_update_sd_ad_group), so differentiation relies on the tool name rather than the description.

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 'ESISTENTE'/'NON crea' phrasing gives an implicit exclusion (do not use to create), which is useful routing guidance. But it offers no positive when-to-use context and does not mention the preview/confirm workflow or when to prefer the SP/SD variants.

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 destructiveHint=true, but the description adds crucial behavioral detail beyond that: Amazon rejects negative SB multipliers as of 15/6/2026 and the tool rejects them before calling Amazon; passing multipliers forces bid_optimization=false per Amazon's requirement; verified per-id and per-placement read-after-write; max 25 batch items. This is exactly the kind of enforcement/policy context annotations cannot provide.

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

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

The description is dense and information-packed, front-loaded with the core action and scope. Some clauses are long and could be split for readability, but every sentence carries operational value. Slightly overstuffed for a one-pass read, preventing a perfect score.

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

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

For a mutation tool with no output schema, the description covers every behavioral burden: destructive nature, two invocation modes, batch limit, Amazon policy constraints, confirmation flow implied by confirm_id schema, and the read-after-write verification. An agent has everything needed to invoke correctly. Neither schema nor annotations carry this load.

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 50%, so the schema documents some parameters (bid_optimization, placement, percentage, account_id, confirm_id, items). The description adds the enum of placement values with aliases (top, detail_page, home, other) and the positive-only constraint on percentage, plus the interplay between bid_optimization and multipliers. However, several parameters (daily_budget, state, campaign_id, patches structure) receive no extra semantic detail 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: updates one or more EXISTING Sponsored Brands campaigns, covering budget, state, and bid optimization. Explicitly says it does NOT create new campaigns, distinguishing it from ads_create_sp_campaign and the S-family create tools.

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

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

Rich when-to-use guidance: single mode (campaign_id + patches) vs batch mode (items, max 25). Explains the bid optimization workflow (multipliers vs keywords): to reduce spend on a placement, lower keyword/target bids and raise other placements. Names the sibling tools ads_update_sb_keyword_bid and ads_update_sb_target_bid 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?

Annotations already declare destructiveHint=true and the write nature. The description adds useful context: batch limit of MAX 25 and per-id read-after-write verification. However, it omits the preview/confirm (confirm_id) two-step execution flow visible in the schema, which is a notable behavioral trait for 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 purpose, then usage rationale, then the two invocation shapes and the batch cap. Dense and efficient, though the ALL-CAPS emphasis on multiple terms is slightly noisy rather than informative.

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

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

For a 6-parameter, zero-required, destructive write tool with no output schema, the description covers modes and verification but leaves the confirm_id preview-execute contract unexplained, which an agent needs 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 50%. The description meaningfully explains keyword_id (source: ads_list_sb_keywords), bid, and the items batch shape with a max, but says nothing about account_id, profile_id, or the confirm_id preview token covered only in the schema.

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

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

States a specific verb (Aggiorna il BID) and resource (keyword Sponsored Brands), and explicitly covers both single and batch modes. It distinguishes itself from the many sibling bid/state tools by naming the SB keyword resource and its scope.

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

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

Explains when to reach for it (the lever to optimize an underperforming SB campaign 'instead of turning it off or throttling budget'), implying the alternative of ads_update_sb_keyword_state. It also routes the agent to ads_list_sb_keywords for obtaining keyword_id, but does not name the state-update sibling explicitly.

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, so the mutation risk is covered. The description usefully adds the per-id outcome-verification and the 25-item batch cap, but omits the two-step confirm_id preview/execute workflow, which is the most consequential behavior for a destructive write here.

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

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

Extremely dense and front-loaded: purpose first, then SINGLE, then BATCH with the cap, then the outcome note. No filler sentences; 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?

For a destructive, zero-required-parameter tool with no output schema and a confirm-token flow, the description covers modes and limits but leaves the preview/confirm requirement and the account/profile scoping unexplained in prose.

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

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

Schema coverage is 50%. The description documents the mode-specific parameters (keyword_id, state, items shape) and the batch limit, but says nothing about account_id, profile_id, or the critical confirm_id confirmation token, which the schema alone must carry.

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: updating the state of one or more Sponsored Brands keywords, listing the three valid states. The 'SB' in the name and description distinguishes it from ads_update_sp_keyword_state, though it never names the sibling explicitly.

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

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

Clearly describes the two invocation modes — SINGLE (keyword_id + state) and BATCH (items array, MAX 25) — so the agent knows how to structure a call. It does not, however, state when to prefer one over the other or any prerequisites.

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

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

Annotations already declare write/destructive and non-open-world semantics. The description adds value beyond them: batch cap of 25 items, the SINGLE vs BATCH invocation forms, and per-id verified results. It does not restate irreversibility or the confirm-preview flow, which is left to the schema.

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

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

Dense but front-loaded: purpose first, then strategic context, then operational modes and limits. Every sentence carries information, though the capitalization and mixed single/batch notation add slight reading overhead.

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 write tool with no output schema and safety already covered by annotations, the description supplies the invocation forms, the batch limit, the ID source, and per-id result reporting. The only real gaps are profile_id semantics and the confirm_id write-confirmation flow, which the schema partially covers.

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

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

With 50% schema coverage, the description compensates by explaining the two mutually exclusive payload shapes (target_id + bid, or items=[{target_id, bid}] max 25) and the origin of target_id. account_id/confirm_id are documented in the schema; profile_id remains undocumented in either place.

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 (aggiorna/update) and resource (BID of SB product targets), plus scope (single vs batch). It explicitly positions itself against ads_update_sb_keyword_bid and ads_update_sb_campaign, so an agent can distinguish it from sibling bid/state/campaign tools without opening their 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?

Provides clear context: it is one of the levers for optimizing SB versus merely pausing or cutting budget, and it names the sibling tools that complete that picture. It also tells where target_id comes from (ads_list_sb_targets). It stops short of explicit when-not guidance, but the routing signal is strong.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation risk is covered. The description adds only two behavioral facts beyond that: the hard batch cap of 25 and per-id result verification ('Esito verificato per-id'). It is silent on the preview/confirm_id write gating and on the effective irreversibility of ARCHIVED.

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?

Telegraphic and front-loaded: purpose first, then the two calling modes, then the batch cap and the verification note. No filler sentences, though the shorthand style trades some readability for density.

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 write tool with 6 parameters and 0 required ones, the omission of the preview -> confirm_id workflow is a meaningful gap in the description itself, and the optional account_id/profile_id scoping is left to the schema. No output schema exists, so the per-id result note is a helpful partial substitute.

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

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

Schema coverage is 50%, so half the parameters carry their own documentation. The description's real added value is the single-vs-batch parameter pairing, which the flat schema cannot express. It says nothing about account_id, profile_id, or the confirm_id confirmation token.

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 (Aggiorna stato) and a precise resource (SB product target), and the enum of resulting states makes the effect unambiguous. It implicitly separates itself from ads_update_sb_target_bid and ads_update_sp_target_state by naming 'stato' and 'Sponsored Brands', but never explicitly names those 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 clearly tells the agent which shapes select which mode: SINGOLA = target_id + state, BATCH = items=[{target_id, state}] with MAX 25, so parameter selection is unambiguous. It stops short of saying when to prefer this over ads_delete_sp_targets or the bid-update sibling, and gives 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 destructiveHint=true and readOnlyHint=false, so the mutation profile is covered. The description adds useful behavior (max 25 per batch, 'Esito verificato per-id' implying per-item partial success), but omits the two-step preview/confirm flow for writes, which is the most important behavioral trait of this 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?

Dense and front-loaded: single vs batch is stated immediately after the purpose, with hard limits (MAX 25) called out. The telegraphic style is efficient, though a couple of clauses read more like notes than prose.

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 mutation with no output schema and 43% schema coverage, the definition covers the core update path but does not surface the mandatory confirm_id/preview step in the description, relying entirely on the schema field comment for a behavior the agent must get right.

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

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

Schema coverage is only 43%, yet the description covers only bid, state, ad_group_id and the items shape, leaving account_id, profile_id and confirm_id to the schema. It also says state is enabled|paused while the schema enum adds 'archived', a minor mismatch that could mislead.

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

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

States a specific verb and resource ('Aggiorna ... ad group Sponsored Display') plus the exact updatable fields (defaultBid, enabled|paused). It is unambiguously distinguishable from ads_update_sd_campaign and ads_update_sp_ad_group by naming the SD ad-group scope.

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

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

Explicitly routes the agent between SINGOLA (ad_group_id + bid/state) and BATCH (items, MAX 25) modes, and notes that bid is the primary optimization lever on SD. It does not, however, name an alternative tool or state when-not-to-use, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the mutation risk is covered. The description adds genuinely new behavioral facts: per-id read-after-write verification of the outcome and the batch cap of 25. It omits any mention of the preview/confirm_id write gate, which is the most safety-relevant behavior for this 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?

Densely packed and front-loaded: purpose, single form, batch form, limit, verification, exclusion — each in its own short clause with no filler. The all-caps emphasis is slightly heavy but the information ordering is correct.

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 batch mutation with no output schema and 43% schema coverage, the description covers the core write semantics but leaves out the confirm_id two-step flow and the account_id/profile_id targeting context. An agent could call it correctly in the common case but would miss prerequisite mechanics.

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

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

Schema coverage is only 43%, so the description must compensate: it does well for campaign_id, daily_budget, state and the items[] shape. However account_id and profile_id are not explained in the description (account_id is partly covered by the schema, profile_id nowhere), leaving a real gap for a 7-parameter tool.

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

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

Specific verb+resource ('Aggiorna ... campagne Sponsored Display ESISTENTI') with explicit scope: budget and/or state only. It distinguishes single vs batch forms and explicitly negates creation ('NON crea campagne SD'), which cleanly separates it from ads_create_sp_campaign and from ads_update_sd_ad_group.

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

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

Tells the agent the two calling modes (SINGOLA: campaign_id + daily_budget/state; BATCH: items[] with MAX 25) and that only existing campaigns are targeted. It stops short of naming an alternative sibling or stating exclusion conditions beyond 'does not create', so it is strong context rather than full when/when-not routing.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, so the agent knows this is a mutating operation, but the description adds nothing on top: no mention of what is overwritten, whether changes are reversible, or that a confirmation token is required. For a destructive write with annotations carrying only the safety flag, the description should disclose far more.

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?

Single short phrase, front-loaded and free of filler, but its brevity comes from omission rather than efficiency—it conveys no actionable detail beyond the name and title.

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

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

For a destructive mutation tool with no output schema, an opaque nested 'patches' object, and a two-step confirmation flow, the description is far too thin to let an agent call it correctly without guessing. Critical information about valid patch contents and the confirm workflow is missing.

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

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

Schema coverage is only 50% and the key parameter 'patches' is an undocumented nested object with no schema description, so the description must compensate and does not. It never explains what fields belong in 'patches' or how the preview/confirm_id handshake works.

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

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

The description gives a clear verb+resource ('Update a SP ad group') and the 'SP' qualifier does distinguish it from the SB/SD ad-group siblings. However, it says nothing about what aspects of the ad group can be updated, and the scope is so thin that it borders on restating the title.

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

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

There is no guidance on when to use this tool versus ads_update_sp_campaign or the SB/SD update siblings, and no mention of the preview-then-confirm write flow that the schema implies. The agent must infer usage entirely from the name.

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

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

With annotations already declaring readOnlyHint=false and destructiveHint=true, the description adds rich behavioral context: audience segments can only raise bids, max 10 segments, placement multipliers are reread and preserved, preview writes nothing, confirm writes and is verified by rereading. This goes well beyond the safety profile that annotations provide.

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

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

The description is front-loaded with purpose, then options, constraints, and flow. It is dense but justified by the complexity of a mutation tool with a preview-confirm workflow. Some all-caps emphasis and repetition of confirm details slightly reduce conciseness.

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

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

For a complex destructive mutation tool with no output schema, the description covers the confirmation flow, merge behavior, bid constraints, and practical preconditions. It misses an explanation of profile_id and campaign_id, but otherwise provides enough context to invoke the 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 coverage is 75%, and the description adds substantial meaning beyond the schema: percentage is an integer 0–900 that only increases bids, set adds/modifies, remove deletes, clear_all zeroes all, and confirm triggers the actual write. However, parameters such as profile_id and campaign_id remain unexplained in both the schema and the description.

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

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

The description names a specific verb (imposta/moltiplicatori) and resource (segmenti di pubblico di una campagna Sponsored Products), and explicitly identifies the underlying API path dynamicBidding.shopperCohortBidding. It distinguishes the four operations (set, remove, clear_all) and clarifies that it is not a generic campaign update, unlike siblings such as ads_update_sp_campaign.

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

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

It gives a clear usage flow (preview without confirm, then confirm=true) and a practical when-to-use rule (only on campaigns with ACoS within target, over 14–30 days). It also points to ads_list_sp_audiences for audience_id, but it does not name alternative sibling tools for related bidding changes, 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds real behavioral context beyond them: the preview/confirm_id write flow, read-after-write verification per placement or per id, the MAX 25 batch limit, and the guarantee that existing audience segments are preserved. It stops short of stating irreversible effects or rollback semantics, so it is strong but not exhaustive.

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

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

Front-loaded with the core action and packed with genuinely useful detail, but it is delivered as one long run-on paragraph with no sentence breaks, mixing single-path syntax, batch shape, limits and workflow into a single block. Information density is high but parseability suffers.

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

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

For a 6-parameter, nested-object mutation tool with no output schema and 50% schema coverage, the description covers everything an agent needs: the two invocation modes, parameter syntax, enum vocabularies, batch cap, confirmation handshake, and the scope boundary against the audience-bidding sibling.

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

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

Schema coverage is only 50%, and the description compensates heavily: it supplies the placement enum values and their aliases (top/rest_of_search/product_page/business), the 0-900 percentage range, and the daily_budget→v3 budget{budgetType:DAILY,budget} conversion that the schema does not express. account_id/profile_id/confirm_id semantics are left to 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?

Opens with a specific verb+resource ('Aggiorna una o PIÙ campagne SP') and immediately distinguishes the single-campaign path from the batch path. It also explicitly names the sibling it must not be confused with ('usa ads_update_sp_audience_bidding') and the excluded concern (audience segments).

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 end-to-end flow (execute_sql on fact_campaign_placement_daily → ads_list_sp_campaigns → before/after preview → confirm → this tool), states when to prefer BATCH ('consigliato per agire su più campagne'), and states what NOT to use it for. Routing 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 declare destructiveHint=true and readOnlyHint=false, so the safety profile is already covered. The description adds genuinely useful behavior beyond that: batch size limit, per-keyword independent bids, and PER-ID read-after-write verification of the outcome. It stops short of disclosing the preview/confirm flow that the schema hints at.

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

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

Front-loads the core action, then splits single vs batch cleanly with a bracketed rationale. Dense but every clause carries information; no filler sentences.

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

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

For a destructive mutation with no output schema, the description covers scope, batch limits, and result verification (read-after-write). The main omission is any mention of the confirm_id preview-then-execute workflow, which an agent would only discover from the schema.

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

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

With only 50% schema coverage, the description compensates by explaining the keyword_id+bid pairing, the items element shape, per-item bid independence, and the max-25 cap. account_id/confirm_id carry schema descriptions; only profile_id remains undocumented in both places.

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

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

States a specific verb (aggiorna) and resource (bid di keyword SP), immediately distinguishing it from sibling tools like ads_update_sp_keyword_state (state) and ads_update_sp_target_bid (targets). An agent can route to it without opening the schema.

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

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

Explicitly lays out the two invocation modes (single: keyword_id+bid; batch: items array) and recommends batch for multi-keyword work with a rationale (fewer calls, no burst), plus the MAX 25 constraint. It does not mention the confirm_id preview/execute two-step, which is a usage gap for a mutation tool.

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

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

Annotations already declare this as a non-read-only, destructive write. The description adds two useful behavioral details: batch operations cap at 25 items and results are verified per-ID. It does not mention the confirmation step needed to actually execute the write, nor any permission or account-scoping requirements beyond what the schema says.

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

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

Three tight sentences, front-loaded with the core action and scope, then mode details, then verification note. Every sentence carries information; no filler or redundancy.

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

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

For a destructive, multi-parameter write with no required top-level fields and no output schema, the description covers purpose, modes, and batch limit. It leaves out the two-step preview/confirm requirement that is critical for correct invocation (only hinted at in the confirm_id schema description), says nothing about profile_id, and gives only minimal output expectation ('esito verificato PER-ID').

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

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

With only 50% schema description coverage, the description adds meaningful semantics: it resolves the ambiguity between single-mode (keyword_id + state) and batch-mode (items array) usage, states the ENABLED/PAUSED values, and imposes the max 25 batch limit. It does not explain profile_id, which lacks any description in the schema.

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

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

States a specific verb and resource: update the state (ENABLED/PAUSED) of one or more SP keywords. The single vs batch modes further clarify scope. It doesn't explicitly name a sibling tool it is not, but the combination of 'SP' and 'keyword' distinguishes it from the SB keyword, SP target, and bid-update 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?

Explains how to call it in single mode (keyword_id + state) and batch mode (items array, max 25), which is useful in-tool guidance. However, it gives no guidance on when to use this tool versus alternatives (e.g., ads_update_sp_keyword_bid) and omits any mention of the preview/confirm flow implied by the confirm_id parameter.

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=true, so the mutation profile is known. The description adds concrete behavioral detail beyond that: a MAX 25 batch cap and per-id verification of the outcome ('Esito verificato per-id'). It does not explicitly say the previous bid is overwritten, though 'Aggiorna il bid' plus the destructive annotation makes that clear enough.

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 target scope, then modes, then constraints; every sentence carries information (source of id, mode selection, batch limit). The heavy capitalization for emphasis is slightly noisy but not wasteful.

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

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

For a destructive batch-mutation tool with no output schema and six partial-coverage params, the description supplies the id source, the two modes, the batch cap, and the per-id result check. Remaining gaps are a note on the confirm_id two-step write flow and profile_id, but it is otherwise complete enough to invoke correctly.

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

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

With only 50% schema coverage, the description does real work: it pairs target_id+bid for the single case, defines items=[{target_id, bid}] with per-item distinct bids and the 25 limit. It leaves profile_id and bid value semantics/units undocumented in both places.

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

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

States a specific verb (Aggiorna) and resource (bid of SP targets), and enumerates the exact target families it applies to (MANUAL ASIN/categoria, AUTO close/loose/substitutes/complements). It also distinguishes itself from ads_create_* and points to ads_list_sp_targets as the source of target_id, so an agent can place it precisely among 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?

Gives explicit prerequisites (target_id from ads_list_sp_targets), a clear alternative to rule out ('è QUESTA, non ads_create_*'), and two invocation modes (SINGOLA vs BATCH with a recommendation for many targets). It stops short of naming the closely-related state-update sibling (ads_update_sp_target_state) as the non-alternative for state changes.

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, so the safety profile is covered. The description adds the batch cap (MAX 25) and the per-id verification note (Esito verificato per-id), which is useful post-write context, but it does not disclose reversibility or that the schema's confirm_id preview flow governs the actual 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?

A single dense sentence, front-loaded with the verb and resource, then the two modes and the limit. No filler; every clause carries information.

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

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

For a destructive state-mutation tool with no output schema, the description covers the valid states, the two call shapes, the batch limit, and post-write verification. Gaps are minor: the confirm_id preview flow and multi-outpost account_id handling live only in the schema.

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

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

Schema coverage is 50%. The description compensates for the core target_id/state/items parameters by spelling out the single and batch shapes and the max-25 limit. It adds nothing about account_id, confirm_id, or profile_id, leaving part of the parameter surface to the schema only.

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

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

States a specific verb (Aggiorna) and resource (stato di target SP), and enumerates the valid states (ENABLED/PAUSED). The single-vs-batch framing distinguishes it from sibling state tools like ads_update_sp_keyword_state. It does not explicitly name alternatives, but the resource is unambiguous.

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

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

Clearly delineates the two invocation modes (SINGOLA: target_id + state; BATCH: items array) so the agent knows how to call it in either scenario. However, it gives no when-not guidance or explicit routing to sibling tools such as ads_update_sp_target_bid or ads_delete_sp_targets.

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

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

Annotations already declare readOnly/destructive=false, but the description adds critical operational context beyond them: it reports REJECTED documents (work done but never live, fastest recovery) and DRAFT/SUBMITTED states, and mandates declaring two limits to the user — that it only measures THIS seller's A+ documents and that A+ is per-marketplace. These constraints materially affect how results should be interpreted.

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?

Content is front-loaded with the core purpose, but the description is a dense, single-paragraph block with parentheticals and multiple caveats packed together, reducing scannability. Every sentence carries substantive information (no filler), but structure could be improved for readability.

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 four optional parameters, no output schema, and a read-only audit of non-trivial scope, the description covers: what is returned (coverage with gaps ordered by commercial weight, plus REJECTED/DRAFT/SUBMITTED flags), the seller-scoped and per-marketplace limitations that must be disclosed, and the absence of write support. This is complete for an agent to call and interpret it correctly.

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

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

Schema description coverage is 100%, so each of the four parameters (top_n, account_id, max_catalog, max_documents) is already documented. The description adds contextual meaning for account_id by explaining the outpost/marketplace model, but does not elaborate on top_n, max_catalog, or max_documents beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb+resource: audits A+ Content coverage across the catalog, distinguishing ASINs with APPROVED (customer-visible) A+ documents from those without. It further differentiates from siblings like list_aplus_documents (raw listing) and get_aplus_document (single doc) by framing this as a coverage/gap audit ordered by commercial weight.

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

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

Explicitly states when to use it (to find which selling pages lack A+, prioritizing by 30-day units sold), and gives clear when-not/caveat guidance: the A+ is per-marketplace (IT/DE/FR/ES are distinct documents, audit one outpost at a time), and creation/modification via API is NOT implemented — corrections must be made in Seller Central. This routes the agent away from expecting write capability.

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 structurally. The description adds nothing beyond that — no mention of scope, runtime (the wait_timeout_sec parameter hints at async behavior that goes unexplained), or what the audit inspects.

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

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

A single short sentence, so there is no waste or burying of information. It is terse to the point of under-specification, but that deficiency is penalized under other dimensions rather than here.

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

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

With no output schema, no required parameters, and two of three parameters undocumented, the description should carry more weight. As written, an agent cannot tell what the audit covers, how long it runs, or how to interpret top_n.

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?

Three parameters with only 33% schema description coverage; top_n and wait_timeout_sec are undocumented anywhere. The description provides zero parameter guidance, so it fails to compensate for the coverage gap.

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

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

States a verb and resource ('Run catalog quality audit'), so the general intent is legible. However, 'quality' is undefined — it doesn't say which checks run (titles, images, attributes, compliance) and does not distinguish itself from siblings like audit_compliance or audit_title_compliance.

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 run this audit versus the three sibling audit tools, nor on prerequisites, frequency, or what to do with the results. Usage is left entirely to inference.

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

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

Annotations already declare readOnlyHint/openWorldHint=false/destructiveHint=false, and the description reinforces READ-ONLY while adding context annotations cannot express: that it only flags 'mancante' when the product type truly requires the attribute, priority logic (alta = Amazon ERROR or missing GPSR), and the EPR-account-level caveat (SP-API reads the alert but does not set it).

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

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

Purpose and scope are front-loaded, then detail follows. It is dense and long with many parentheticals (Italian/English mix), and some content arguably belongs in the schema, but nearly every sentence carries operative information rather than filler.

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

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

For a read-only audit tool with no output schema, the description fully describes the return payload (SKUs with gaps, priority, per-attribute counts, most frequent gaps) and the full-vs-standard scope, leaving nothing an agent needs to call it correctly unstated.

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

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

Schema coverage is 100%, so parameters are already documented, but the description elaborates the mode semantics (what standard vs full actually scan) beyond the terse schema enum description, adding real meaning. max_pages and account_id gain no extra detail beyond the schema.

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

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

States a specific verb and resource (audit compliance/GPSR of the catalog, EU/IT) and enumerates exactly which attributes are checked per SKU. It clearly distinguishes itself from siblings like audit_title_compliance, audit_aplus_coverage, and audit_catalog_quality by scoping to compliance/GPSR attributes and Amazon compliance issues.

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 contrasts mode='full' vs the standard default and names the triggering condition ('quando l'utente chiede di verificare "tutti i requisiti di conformità"'). It also routes the agent to update_listing for corrections and warns about EPR being account-level rather than listing attributes, which prevents a common misuse.

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 read-only, non-destructive, closed-world behavior, and the description adds substantial behavioral context beyond that: return fields (excess character count, bullet/highlight counts per SKU), an at_risk band of 73–75 chars, Amazon's AI rewrite enforcement, and the fact that Item Highlights do not make a long title compliant and are not writable on some marketplaces. This is unusually rich 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 core purpose is front-loaded, and most sentences carry useful information. However, the description is long, mixes English and Italian mid-sentence, and blends return behavior, usage, and caveats without clear structure. This reduces conciseness despite the informational density.

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

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

There is no output schema, but the description explains what is returned (over-limit titles, excess counts, at_risk band) and how to act on findings. Annotations cover the safety profile, and parameter documentation is complete via schema. It is largely complete for a two-parameter, read-only audit, though pagination behavior beyond max_pages is not elaborated.

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

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

Schema description coverage is 100%, so both max_pages and account_id are already documented in the input schema. The description adds no additional parameter-level meaning, such as default behavior, pagination limits, or account_id optionality. Baseline 3 is appropriate.

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

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

States a specific verb and resource: audit all listings for the Amazon 75-character title limit. The scope is clear from the title-limit focus, but it does not explicitly distinguish itself from siblings such as audit_compliance or get_listing_issues, so a 4 rather than 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?

Provides contextual usage hints: the fix for an over-limit title is TRIM_TITLE, and prioritization should use execute_sql on sales data. However, it never states when to choose this tool over alternative audit tools or when not to use it. Usage is implied rather than explicit.

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

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

Annotations already mark this destructive and non-read-only, but the description adds substantial context beyond them: irreversibility ('LA CANCELLAZIONE È IRREVERSIBILE'), the two-phase plan_id/confirm flow, feed batching at 20,000 records, channel side effects (FBM default leaves FBA intact), and the note that SKUs never appear in the conversation. It also points to check_feed_status as the follow-up step.

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

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

It is long, but every clause carries operational weight (threshold, rate-limit rationale, phase ordering, channel semantics, irreversibility, next step) and the critical scoping constraint is front-loaded. Dense rather than bloated, though slightly tighter phrasing could trim a few redundancies.

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, six-parameter, no-output-schema tool, the description covers the full lifecycle: when to use it, the two mandatory phases, what phase 1 returns (counts, FBA/FBM split), the confirmation requirement, irreversibility, and post-execution follow-up. No output schema exists, but the description describes the meaningful return artifact (the plan with counts) without duplicating a schema.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema cannot: skus bypasses the report and ignores channel, channel='FBM'/'ALL' have asymmetric deletion effects, plan_id comes only from phase 1, and confirm must accompany plan_id to actually execute. This clarifying workflow context justifies a bump over baseline.

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

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

States a specific verb+resource (bulk-delete listings on an account) and explicitly distinguishes itself from the sibling delete_listing ('USA QUESTO, non delete_listing in ciclo'). The scope is further pinned down by the channel filter and the two-phase flow, so an agent can separate it from all siblings at a glance.

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

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

Gives an explicit selection threshold ('più di qualche decina'), names the alternative to avoid and why (delete_listing is SKU-by-SKU and hits Amazon rate limits), and lays out the mandatory two-phase procedure with the user-confirmation gate between phases. Nothing about when to use it is left to inference.

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

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

Goes well beyond the annotations: discloses the 5,000-SKU-per-call limit, one feed per call, the JSON_LISTINGS_FEED mechanism, the non-destructive dry-run path, that only FBM offers are affected while FBA ignores the template, and that results are checked via check_feed_status(feed_id). This complements destructiveHint=true with concrete operational context.

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

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

Dense but well front-loaded: the bulk-assign purpose and the feed mechanism come first, then the validate-then-submit workflow, then the exclusions. Every sentence carries information, though the run-on packing of parentheticals makes it slightly heavy.

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

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

No output schema exists, and the description closes the loop by telling the agent to verify the outcome with check_feed_status(feed_id). For a destructive bulk mutation with 5 parameters, the workflow, limits, scope restrictions, and verification step are all covered.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds real meaning: shipping_template is an ID or name as shown in Seller Central, discoverable via get_product_types with product_type="PRODUCT" → shipping_templates, and validate_only's 3-test-SKU behavior is spelled out. It stops short of clarifying account_id or the full confirm_id round-trip 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 (assign the SAME shipping template to many SKUs at once) and explicitly contrasts the mechanism with update_listing SKU-per-SKU. An agent can distinguish it from siblings like bulk_update_listings without opening the schema.

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

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

Gives an explicit two-step workflow: first call with validate_only:true to validate on 3 test SKUs without writing, show the user the template and SKU count, then call again without validate_only to submit. It also names the alternative (update_listing per SKU) and excludes out-of-scope actions (does not create or modify templates).

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, so the description's failure to restate mutability is not fatal. However, it adds no behavioral context at all: it omits the preview/confirm two-phase flow implied by confirm_id, batch limits, or what happens to existing inventory values.

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

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

Three words is not conciseness but under-specification. There is no front-loaded detail to earn the space because no meaningful information is provided at all.

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?

This is a destructive bulk mutation with a mandatory array parameter, partial schema coverage, no output schema, and an implied preview/confirm workflow. A three-word description is completely inadequate for an agent to call it safely or 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 67%, and the required 'updates' array has no description in either schema or description. The description does not explain the shape of the array items or add any meaning beyond the schema's Italian-language descriptions of account_id and confirm_id.

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

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

"Bulk inventory updates" essentially restates the tool name and adds no differentiating detail. It does not specify what inventory (FBA vs MFN), which fields are updated, or how it differs from siblings like bulk_update_listings, bulk_update_prices, or update_mfn_quantity.

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

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

No guidance on when to use this versus the many sibling bulk/update tools (bulk_update_listings, bulk_update_prices, update_mfn_quantity). There are no prerequisites or exclusions stated, leaving the agent to infer selection criteria.

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, but the description adds real context beyond them: the two-step preview-then-confirm safety protocol, the return shape, and the existence of a validate_only dry-run. It doesn't state auth/rate-limit constraints, but for a destructive write the confirm flow is the key disclosure.

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

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

Front-loads purpose, then schema hint, then when-to-use, then return shape, then safety — a sensible priority order. The telegraphic fragments ('Bulk listing attribute updates', 'updates: [...]') are dense but each sentence carries distinct information.

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

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

For a destructive bulk write with no output schema, the description supplies the return summary ({total, ok, errors, results[]}), the confirm gate, and the dry-run option — enough for an agent to call it correctly. It could note multi-SKU failure semantics (partial success) but is otherwise complete.

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

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

The description spells out the nested 'updates' item shape (sku, title, bullets, patches, product_type, validate_only), mapping directly to the array schema. account_id and confirm_id are documented in the schema itself (67% coverage), including the Italian-language confirm_id note, so the remaining gap is minor.

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 (bulk listing attribute updates) and enumerates the covered fields (title, bullet_point, patches). It explicitly contrasts itself with the update_listing sibling, so an agent can route without inspecting either schema.

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

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

Gives an explicit when-to-use condition ('update titles or bullets on multiple SKUs at once') and names the alternative it replaces ('instead of calling update_listing one by one'). It also states the required preview/confirm workflow, which governs invocation order.

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 this as a destructive, non-read-only write, and the description adds nothing beyond that. Critically, it omits the two-step behavior visible only in the schema: a preview call returns a confirm_id that must be passed back with the identical payload to actually write. For a destructive bulk mutation this is a serious disclosure gap.

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

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

Three words are technically concise but amount to under-specification rather than economical writing; there is no front-loaded scope, precondition, or caution for a destructive bulk operation.

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, bulk, open-world-false write with no output schema, an unclear required array payload, and an implicit confirm flow, the description is inadequate on every dimension an agent needs to call it safely.

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

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

Schema description coverage is a moderate 67%, and the description contributes no parameter information at all. The most consequential gap, the 'updates' array (required, untyped inner items, no description), is left entirely undocumented, and the confirm_id workflow is never explained in prose.

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 restates the tool name almost verbatim ('Bulk price updates') without specifying what is being updated, which entity/scope is affected, or how it differs from siblings like update_price, bulk_update_listings or bulk_update_inventory. It is essentially a tautology of the title.

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

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

No guidance is given about when to use bulk updating versus the single-item update_price tool, nor when to prefer bulk_update_listings/inventory. There is also no mention of the required preview-then-confirm flow that the schema's confirm_id implies.

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, but the description adds real value beyond them: the plan must not yet be shipped, the outcome is a VOIDED state, and explicit user confirmation is required first. It does not discuss irreversibility or permission requirements, so it is not exhaustive.

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

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

Front-loaded ACTION marker, then three tight sentences covering purpose, use case, and confirmation requirement. No filler, no repetition of schema content, and the most important constraints come first.

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

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

For a destructive mutation with annotations and no output schema, the description covers purpose, precondition, outcome state, and the confirmation guardrail. It stops short of explaining the confirm_id preview/execute flow or failure cases, but the essentials are present.

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

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

Schema coverage is 67% and the description adds no parameter meaning at all: it never mentions inbound_plan_id as the target, account_id scoping, or the confirm_id two-step token flow. With a non-trivial mutation flow and an undocumented required parameter, the description fails to compensate for the schema gap.

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

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

States a specific verb (annulla/cancel) plus resource (piano inbound FBA v2024), the precondition (non ancora spedito), and the resulting state (torna VOIDED). An agent can distinguish this from read siblings like get_inbound_plan or creation siblings like create_inbound_plan without opening the schema.

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

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

Explicitly says when to use it: reconsiderations on a plan created by mistake or no longer needed, plus a required explicit user confirmation before calling. It does not name a when-not case or point to an alternative sibling, so it falls just short of 5.

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