Vendooly

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

Beyond readOnlyHint, it discloses that results are exhaustive with no sampling and that incomplete or stale data fail loudly rather than yielding false uncovered results. It also states required backend preconditions, though it does not discuss pagination or response shape.

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

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

The purpose and safety/scope constraints are front-loaded in a compact paragraph. Some repetition of READ-ONLY is redundant with annotations, but overall it is appropriately sized for a complex coverage check.

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

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

For a six-parameter read-only tool with no output schema, it describes the returned fields, cross-referencing behavior, error semantics, and prerequisites. The main remaining gaps are full parameter semantics and response structure, but it is largely complete for correct invocation.

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

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

Schema description coverage is only 50%, and the description adds meaning mainly for the only_with_sales/only_uncovered combination. It leaves lookback_days and only_in_stock without added semantic detail, while account_id and ignore_orphan_ads rely on their schema descriptions.

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

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

The opening states the exact resource and scope: all catalog ASINs plus recent outpost sales, one row per ASIN, including SKU, title, stock, sales, and live Sponsored Products coverage. It also says it cross-references Product Ads and campaign/group states, which distinguishes it from generic catalog or ads-listing 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 gives a concrete filter recipe for the 'sold without active SP' case (only_with_sales=true and only_uncovered=true) and states prerequisites such as a synced data-hub and linked Ads. However, it does not name alternative tools or explicit when-not conditions, so sibling routing remains implicit.

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=false, destructiveHint=false, openWorldHint=true), and the description adds real context on top: no portfolio-level budget cap and no extra authorization beyond campaign scope. It omits the two-step preview/confirm write flow that the confirm_id parameter implies, which an agent would only learn from the schema.

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

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

Two sentences with the purpose front-loaded and the budget-cap caveat placed immediately after. Denseness in the parentheticals is slightly high but nothing is wasted.

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

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

For a mutation tool with no output schema, the description never says what is returned (e.g., the new portfolio ID needed for campaign assignment) and does not surface the preview-then-confirm requirement. Annotations cover the mutation safety profile, but these operational gaps remain.

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

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

Schema description coverage is 67% (account_id and confirm_id documented, the required nested portfolio object not), and the description adds no parameter-level detail such as what profile_id means at the portfolio level. The schema does most of the work, so the baseline 3 holds.

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

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

States a specific verb and resource ("Create an Amazon Ads portfolio") plus its function ("to group campaigns"), which is enough to separate it from the list/update siblings that operate on campaigns. It does not explicitly name a sibling such as ads_list_portfolios, so it stops just short of a 5.

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

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

Usage is implied rather than stated: the agent can infer it should call this before assigning campaigns to a portfolio, and "campaigns can then be assigned to it" signals sequencing. There is no explicit when-not guidance and no named alternative for inspecting existing portfolios.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description adds non-obvious behavior beyond them: the default PAUSED state so the group can be populated before delivery, and the Amazon otherError rejection when mixing keyword and product targets. These are the kinds of domain constraints an agent cannot infer from structured fields.

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

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

Purpose is front-loaded, then the critical mutual-exclusion constraint, with no padding. The only friction is the abrupt switch into Italian for the most important paragraph, which costs a bit of readability for a general 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 create tool with no output schema, the description covers the essential creation semantics and the key failure mode. It stops short of saying what the call returns (e.g., the new ad group ID needed for follow-up populate calls), which would fully close the loop.

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 account_id and confirm_id already carry descriptions in the schema. The description mentions no field-level semantics (state, default_bid, campaign_id, profile_id) and does not even reference the two-step confirm_id flow, so it adds little beyond the schema. Baseline 3 for moderate coverage 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+scope: 'Create a SP ad group in an existing campaign.' An agent can immediately distinguish this from ads_create_sp_campaign or ads_update_sp_ad_group without opening any schema.

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

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

Explicitly explains when to create one vs two ad groups, names the alternatives (ads_create_sp_keywords, ads_create_sp_product_targets) and the condition that selects each, and clarifies that negative keywords/targets are exempt from the rule. This is exactly the when/when-not/alternatives guidance the dimension wants.

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 write-safety profile is covered. The description adds real behavioral detail the annotations lack: the MANUAL default, the 0-900% placement-bid bound, and the allowed strategy values. However it never mentions the preview/confirm two-step write flow that the confirm_id parameter implies, which is the most consequential behavioral fact for an agent calling 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?

Front-loaded with the one-line purpose, then a dense but single-topic paragraph of parameter guidance. Every clause carries information, but the run-on structure and mixed Italian/English phrasing make it slightly harder to scan than it needs to be.

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

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

For a mutation tool with no output schema and a nested campaign object, the description covers the branching workflow, placement bidding, strategy, and portfolio assignment well. Its notable omission is the preview-then-confirm write protocol, which is left entirely to the schema's confirm_id description; an agent reading only the description could miss 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?

Schema coverage is 67% and the description more than compensates: it supplies the placement enum values (PLACEMENT_TOP|PLACEMENT_PRODUCT_PAGE|PLACEMENT_REST_OF_SEARCH|SITE_AMAZON_BUSINESS) and the 0-900% range for percentage, plus the dynamic_bidding.strategy enum, none of which appear in the schema (dynamic_bidding is an untyped object and placement has no enum). It also states the MANUAL default for targeting_type, which the schema does not.

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

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

The opening sentence gives a specific verb+resource ('Create a SP campaign') that is immediately distinguishable from siblings like ads_create_sp_ad_group or ads_create_sp_keywords. The rest of the description stays scoped to creation and never drifts into update/delete territory.

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 routes the agent through the two targeting modes and names the follow-up tools for each (ads_create_sp_keywords for MANUAL keywords, ads_create_sp_product_targets for AUTO/ASIN), including the explicit exclusion 'NON aggiungere keyword/target manuali' under AUTO. It stops short of naming a true alternative to this tool (e.g., when to prefer ads_update_sp_campaign instead), so it is strong context rather than a full when/when-not matrix.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real behavioral value beyond that: the keyword-vs-product exclusivity rule per ad group and the specific otherError failure mode. It does not mention the two-step preview/confirm flow, but that lives in the confirm_id schema description.

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

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

Front-loaded with the action, then the constraint, then the payload shape - a sensible ordering with little waste. Mixing English and Italian in one description is slightly jarring for an agent parsing instruction text, but every sentence carries operative 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, the definition covers the crucial rejection case and the full keyword object contract. It omits what the call returns (created keyword identifiers/status) and does not spell out bid currency or keyword_text constraints, minor gaps against otherwise solid coverage.

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 declares 'keywords' only as an untyped array with no item schema, so the description carries the entire payload contract: campaign_id, ad_group_id, keyword_text, match_type with the BROAD|PHRASE|EXACT enum, and bid. This is essential information found nowhere else and directly compensates for the opaque required parameter.

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

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

States a specific verb and resource ('Create SP keywords') and immediately disambiguates from sibling tools by scope, since ads_create_sp_negative_keywords and ads_create_sp_product_targets exist. An agent can tell this creates positive keyword targets without opening the schema.

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

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

Gives a concrete when-not condition: if the target ad group already has product targets, Amazon rejects with otherError, and the agent should instead create a keyword-dedicated ad group. It stops short of naming the sibling tool (ads_create_sp_ad_group) to perform that fallback, but the routing condition is explicit.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the basic write/safety profile is covered. The description adds nothing on top: it doesn't explain that this is a staging-plus-confirm write, that the confirm_id is required to actually persist the change, or what happens to the inactive negatives. With annotations carrying the safety signal, the description still contributes zero behavioral context.

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

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

Four words with no waste in a literal sense, but the single sentence is pure redundancy and therefore earns no place. Brevity here reflects under-specification rather than disciplined concision.

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 mutation tool with three parameters, a required undocumented array, no output schema, and an implicit preview/confirm protocol. The description covers none of the operational context an agent needs to invoke it correctly, leaving it well short of what the tool's complexity demands.

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 sits at 67%, and the description supplies no parameter meaning at all. The required 'negatives' array has no schema description and no item structure, and the description does not compensate by explaining its shape (keyword text, match type, ad group scope). The two documented params (account_id, confirm_id) are only described 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?

The description 'Create SP negative keywords' is a verbatim restatement of the tool name and annotation title, with no added scope, target entity, or differentiation from siblings such as ads_create_sp_negative_targets or ads_create_sp_keywords. An agent cannot tell from the text which of the near-identical 'create' siblings this is beyond the name itself.

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 mention of prerequisites, and no reference to alternatives like ads_create_sp_negative_targets. The critical two-step flow implied by the confirm_id parameter (preview, then re-submit the same payload) is never surfaced as usage guidance.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so the safety profile is known. The description adds the payload item shape but omits the two-step confirm_id workflow, which is a meaningful behavioral trait only relayed via the schema.

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

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

Two compact sentences, front-loaded with the action, and every clause carries information (the item structure is not repeatable elsewhere). 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 write tool with no output schema, the description covers the array payload but leaves the confirmation workflow and idempotency/scope expectations unstated. Annotations and schema cover safety and confirm_id, so the omissions are noticeable but not crippling.

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 required 'targets' array carries no schema description, and the description fills that gap by specifying the per-element shape: { campaign_id, ad_group_id, asin (or raw expression) }. This meaningfully compensates for the 67% coverage gap, though account_id and confirm_id 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?

States a specific verb+resource: 'Create SP negative product targets.' This is clearly distinguishable from ads_create_sp_negative_keywords (keyword vs product) and ads_create_sp_product_targets (positive vs negative) by resource noun, even though no sibling is named explicitly.

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

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

No guidance on when to use this versus the positive-target or negative-keyword siblings, and no mention of prerequisites even though the schema implies a preview-then-confirm workflow. The agent must infer all routing and precondition rules.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true, destructiveHint=false, so the write/safety profile is covered externally. The description adds nothing, and it omits the significant behavioral detail the schema hints at: a preview-then-confirm flow (a confirm_id must be re-supplied to actually perform the write). It does not contradict the annotations, but it leaves the agent unaware this is a two-step, non-idempotent operation.

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 four-word sentence: nothing is wasted, but this is under-specification rather than effective conciseness. It is front-loaded and readable, yet too thin to guide invocation on its own.

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

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

For a mutation tool with no output schema, an undocumented required array parameter, and no mention of the preview/confirm token flow or any permission/marketplace requirements, the description is materially incomplete. An agent could not safely call this pattern from the description alone.

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

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

Schema coverage is only 67% (account_id and confirm_id are described in Italian; the required `ads` array has no description and no item structure). The description supplies no parameter information at all, so the most important argument — the array of ads to create — is undocumented in both places.

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

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

States a specific verb and resource ("Create SP product ads"), which is enough to separate it from list_sp_product_ads and the update/delete variants. However, it adds nothing beyond the tool name — there is no explanation of what an SP product ad is, or how it relates to the sibling create_sp_campaign / create_sp_ad_group / create_sp_product_targets 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?

No when-to-use guidance, no prerequisites (e.g., does it require an existing campaign and ad group, a SKU/ASIN, a profile?), and no mention of alternatives among the ~10 sibling create tools. The agent must infer everything from the name and schema.

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

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

Annotations already declare destructiveHint=true/openWorldHint=true, but the description goes further by disclosing a concrete failure mode (INVALID_ARGUMENT when AUTO groups already exist because Amazon pre-created them) and the precondition that AUTO groups are immutable via this tool. That is meaningful behavioral context beyond the annotations.

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

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

Front-loaded with the core action, then branches cleanly into MANUAL/AUTO, then a warning, then an alternative. Each clause earns its place, though the inline enum glosses and the final reroute sentence make it dense for a single description.

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

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

For a mutation tool with no output schema, it covers payload shapes, error semantics, and the bid-change alternative well. It does not spell out the preview/confirm_id write flow (delegated to the schema description) or the return shape, leaving a small gap for a write operation.

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

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

The schema defines 'targets' only as a bare array with no item schema, so the description carries the real burden and delivers it: exact field shapes for MANUAL targets ({campaign_id, ad_group_id, bid, one of asin/category_id/expression}) and AUTO targets (auto_match enum with all four values defined). This adds substantial meaning the schema does not provide.

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

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

States a specific verb+resource ('Create SP targets') and then disambiguates the two campaign modes (MANUAL vs AUTO) that produce different target shapes, which no sibling tool covers. An agent can distinguish it from ads_create_sp_keywords, ads_create_sp_negative_targets, and ads_update_sp_target_bid from the text 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 (MANUAL campaigns with asin/category_id/expression; AUTO campaigns with auto_match groups) and when NOT to: re-creating the 4 AUTO groups on an existing campaign yields INVALID_ARGUMENT, and bid-only changes should route to ads_list_sp_targets + ads_update_sp_target_bid. 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 destructiveHint=true, but the description goes further by disclosing the specific irreversibility ('una campagna archiviata non si riattiva, va ricreata') and the underlying API constraint. This is exactly the extra context the annotations cannot convey.

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

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

Three sentences, front-loaded with the action, then the exclusivity rule, then the critical irreversibility warning. No filler; every sentence carries actionable weight.

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 archive operation with no output schema, the description covers what is destroyed, that it is irreversible, and why no alternative exists. Remaining details (account_id optionality, confirm_id two-phase flow) live in the schema, so nothing critical is missing.

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

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

Schema coverage is 75%, so the schema already documents account_id, confirm_id and campaign_ids; profile_id is undocumented in both. The description only echoes the campaign_ids array shape ('[id, ...]'), adding minimal meaning beyond the structured fields.

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 ('Archivia (elimina) una o più campagne SP') and explicitly distinguishes itself from the sibling ads_update_sp_campaign, explaining that this is the ONLY way to archive. An agent can differentiate it from the update tool without opening either schema.

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

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

Gives explicit when-to-use guidance by naming the alternative (ads_update_sp_campaign only accepts ENABLED|PAUSED) and the technical reason Amazon rejects ARCHIVED on PUT. This is a textbook 'use this, not that, because' routing statement.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is covered externally. The description adds nothing beyond that — no note on irreversibility, permission requirements, or the required preview-confirm step that the confirm_id parameter implies.

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 with no padding, which is structurally clean. But it is under-specified rather than genuinely concise, leaving the reader with no actionable 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 with four parameters, no output schema, and an implied two-step confirmation flow, the description omits prerequisites, the preview requirement, and the scope of deletion. It is far from complete enough for an agent 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 coverage is only 50%, and the required parameter keyword_ids has no description in either the schema or the tool description. The description contributes zero parameter meaning, 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?

The description states a specific verb+resource ('Delete SP negative keywords'), so the core action is identifiable. However, 'SP' is unexplained jargon and there is no differentiation from the very similar sibling ads_delete_sp_negative_targets, which an agent could easily confuse it with.

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

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

There is no guidance on when to use this tool versus ads_delete_sp_negative_targets or ads_delete_sp_campaign, and no mention that a preview/confirm workflow is required. The only hint at that workflow lives in the schema's confirm_id field, not the description.

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 destructive, non-readOnly, and openWorld, so the safety profile is declared. The description adds only the '(archive)' nuance and otherwise adds no behavioral context: it doesn't explain that deletion is soft/archival, what happens to associated entities, or the preview-confirm requirement hinted at by confirm_id.

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 that front-loads the action and resource. It is concise but also under-informative; the parenthetical '(archive)' is the only extra 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 half the parameters undocumented, the description is far too sparse. It omits the confirm_id two-step flow, the archive-not-hard-delete semantics, and any prerequisites or consequences, leaving the agent without enough information 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 50% and the required target_ids parameter has no schema description. The description does not compensate by clarifying the ID format, cardinality, or the meaning of the optional account_id/profile_id. It mentions 'targets' only at the resource level, adding essentially no 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 clear verb and resource: 'Delete (archive) SP negative product targets'. It reveals that deletion is really archiving, which is helpful. It's less specific than it could be — 'negative product targets' in Sponsored Products are the negative targeting entities, and the archive semantics should be made explicit as a non-permanent state rather than packed into parentheses.

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 on when to use this tool versus alternatives like ads_delete_sp_negative_keywords, ads_delete_sp_targets, or ads_update_sp_target_state. There is also no mention of the two-step confirmation flow that the confirm_id parameter 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, readOnlyHint=false and openWorldHint=true, so the risk profile is covered structurally. The description adds genuine value by revealing that 'delete' means archive (soft delete, likely reversible), but it omits the required preview-then-confirm sequence and any note on auth/scope requirements 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?

Extremely short and front-loaded with no wasted words, but it is a bare fragment rather than a structured definition; the brevity comes at the cost of the workflow detail this destructive tool needs.

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

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

For a destructive mutation with no output schema and only half its parameters documented, the description should explain the preview/confirm requirement and the scope of target_ids. Nothing about the return value or the safety workflow is conveyed.

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%, and the description adds no parameter meaning at all. It never mentions target_ids (the sole required parameter), profile_id, or the confirm_id confirmation flow, leaving the agent to reconstruct the write protocol from partial Italian-language schema notes.

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 clarifies with '(archive)' that the operation is a soft delete rather than permanent removal. However, it does nothing to distinguish itself from close siblings like ads_delete_sp_negative_targets or ads_delete_sp_campaign beyond the resource noun.

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

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

No when-to-use guidance, no prerequisites, and no mention of the two-phase preview/confirm workflow that the schema's confirm_id parameter clearly implies. An agent must infer the workflow entirely from the schema.

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

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

Annotations already declare 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 cover the safety profile (readOnlyHint=true, destructiveHint=false), and the description adds materially beyond them: determinism ('SEMPRE uguali a parità di dati'), fixed windows closed three days before the last data point because Amazon attribution is still incomplete, and where the ACoS target is sourced from (cockpit ORC-058 or `acos_max`). It also states org-scope behavior, which is exactly the kind of context annotations cannot carry.

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

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

The purpose and the routing instruction are front-loaded, which is good, but the middle is a single dense paragraph cataloguing roughly fifteen action codes with no formatting, and it is written in Italian while the schema and sibling names are English. Much of it earns its place as reference for the returned `action` column, but the structure makes it harder to scan than it needs to be.

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

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

There is no output schema, and the description compensates well: it names the metric set (ACoS/CTR/CVR/CPC/RPC/AOV), the previous-period comparison, and defines every value of the `action` column, so an agent can interpret results. The main gap is the phantom `account_id` scope parameter and the unexplained shape of the period-over-period comparison, otherwise it is complete for a 7-parameter read-only report.

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 does add real value for `action` (a free-form string in the schema whose valid codes are only defined here) and for the `acos_max` fallback to the cockpit. However, it describes an `account_id` parameter ('senza account_id copre tutti gli outpost autorizzati; con account_id filtra quell'outpost') that does not exist in the input schema, which will mislead an agent into trying to pass it.

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

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

The opening line names a specific resource and behavior: ads performance from the data hub with server-computed, deterministic numbers. The closing line fixes the grain ('Livelli: campaign (default) | keyword | search_term'), and the description explicitly distinguishes it from `execute_sql` and from the `ads_list_*` / `ads_update_*` action loop, so an agent can separate it from 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?

It gives an explicit use-this-instead rule: 'USALO al posto di execute_sql per QUALSIASI domanda su ACoS/spesa/keyword... non riscrivere le formule', plus the follow-up path 'rileggi lo stato live con ads_list_* e proponi la scrittura con ads_update_*'. Both the when and the what-next are stated rather than 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/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 readOnlyHint=false, destructiveHint=true, and openWorldHint=true, so the agent knows this is a destructive write. The description adds the meaningful existing-only constraint, but says nothing about the confirm-token preview flow, reversibility, or what a successful write returns.

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

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

Two compact clauses, front-loaded with the verb+resource and immediately followed by the scope restriction. Nothing is wasted, though it is arguably too terse given the mutation's complexity.

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

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

For a destructive mutation with a nested, undocumented 'patches' parameter and no output schema, the description leaves real gaps. account_id and confirm_id are covered by schema descriptions, but the agent gets no meaningful picture of what it can actually change or how confirmation works.

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 two undocumented parameters are the important ones: 'patches' (an untyped nested object) and 'ad_group_id'. The description partially compensates by hinting patches accepts status (ENABLED|PAUSED), but leaves the rest of the patch structure opaque.

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

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

The description names a specific verb (Aggiorna) and resource (ad group Sponsored Brands), and adds a scope qualifier (ESISTENTE) plus an explicit negative (NON crea ad group nuovi) that separates it from the create siblings. It is clear what the tool does, though it does not name a specific alternative tool the way the strongest examples do.

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

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

It implies usage ('update an EXISTING ad group') and rules out creation, which is useful. But there is no explicit when-to-use guidance beyond that negative, and the critical two-step preview/confirm workflow is not surfaced in the description at all.

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/openWorldHint, and the description goes well beyond them: passing multipliers forces bid_optimization=false, positive-only percentages enforced since 15/6/2026, batch capped at 25, and per-id/per-placement read-after-write verification. This is exactly the operational context an agent needs for an irreversible mutation.

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

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

Purpose is front-loaded and every sentence carries operational value, but the single dense paragraph is run-on and some clauses (e.g. the placement alias list) restate schema content. Information-dense yet slightly overpacked for 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 complex nested mutation tool with no output schema, the description covers modes, limits, side effects, the optimization trade-off, and read-after-write verification. An agent has enough to call it correctly without guessing.

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

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

With only 50% schema coverage, the description compensates strongly: it documents the single (campaign_id + patches) vs batch (items) shapes, the bid_optimization interplay, placement enum values with aliases, percentage semantics, and the 25-item cap. This adds meaning well beyond what the schema descriptors provide.

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 (campagne Sponsored Brands ESISTENTI) plus the fields it mutates (budget, stato, ottimizzazione dell'offerta). Explicitly rules out the create case ("NON crea campagne nuove"), which cleanly separates it from the ads_create_* 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 when-to-use and when-not-to rules: to optimize without cutting volume use placement multipliers, and to spend less on a placement lower keyword/target bids via ads_update_sb_keyword_bid/ads_update_sb_target_bid instead. Names the alternative tools directly and explains the single vs batch invocation paths.

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 safety is covered. The description adds genuinely useful behavioral context beyond that: per-id read-after-write verification and a MAX 25 batch limit. It does not itself explain the preview/confirm token 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?

Front-loaded with the verb+resource, then prerequisites, then mode usage, then verification. Dense 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 destructive mutation with no output schema, the description is largely sufficient: it covers the modes, limits, keyword_id source, and result verification. The confirm_id preview/confirm requirement is only explained inside the schema rather than the description, a minor 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?

With 50% schema coverage, the description compensates: it tells the agent where keyword_id comes from (ads_list_sb_keywords), explains the single-mode pairing (keyword_id + bid) and the batch shape (items=[{keyword_id, bid}], max 25). account_id/confirm_id are handled by schema descriptions; only profile_id remains unexplained anywhere.

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

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

States a specific verb (update) and resource (the bid of one or more Sponsored Brands keywords), and the 'Sponsored Brands' qualifier distinguishes it from the SP/SD bid siblings without needing to open the schema. The optimization framing ('la leva per OTTIMIZZARE una campagna SB') reinforces the intent.

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 optimizing bid price against the alternatives of pausing the campaign or choking its budget, and gives the single vs. batch mode selection with a recommendation for batch. It does not name a sibling tool as the explicit alternative (e.g. ads_update_sb_keyword_state), so it stops short of full 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 already flag destructiveHint=true and openWorldHint=true, so the safety profile is covered structurally. The description adds real behavioral context beyond that: the batch cap of 25 and the fact that the outcome is verified per-id ('Esito verificato per-id'), which tells the agent partial failures are reported individually.

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

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

Four terse, front-loaded fragments with zero filler: purpose first, then each invocation mode, then the outcome guarantee. Every clause carries information an agent needs, and nothing is repeated from the schema.

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

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

For a destructive mutation with no output schema, the description covers the value domain, the single/batch duality, the batch limit, and the per-id result semantics. The two-step preview/confirm workflow is only discoverable from the schema's confirm_id description, not the tool description, and reversibility of ARCHIVED is unstated.

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

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

Schema coverage is only 50%, so the description must compensate, and it does for the core parameters: it documents keyword_id, state values, and the items batch structure with its max size. Critically, it clarifies that keyword_id+state and items are alternative modes rather than co-required, which the flat schema leaves ambiguous. It does not cover profile_id at all and leaves confirm_id/account_id 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 ('aggiorna lo stato'), resource ('keyword Sponsored Brands') and the exact value domain (ENABLED|PAUSED|ARCHIVED). The 'Sponsored Brands' scoping implicitly separates it from ads_update_sp_keyword_state and the state-vs-bid siblings (ads_update_sb_keyword_bid), but no sibling is named explicitly, so it falls short of a 5.

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

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

The description lays out the two invocation shapes (SINGOLA: keyword_id + state; BATCH: items=[...], MAX 25), which tells the agent how to call it but not when to prefer this tool over ads_update_sp_keyword_state or ads_update_sb_keyword_bid. No prerequisites or when-not-to-use guidance 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=false, destructiveHint=true, openWorldHint=true, so the write/destructive profile is covered. The description adds substantive context beyond that: the batch cap (MAX 25) and that outcomes are verified per-id, which tells the agent the call can partially succeed. It omits mention of the preview/confirm (confirm_id) two-step write flow, but the schema documents that.

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

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

Front-loaded with the action, then the alternatives, then the identifier source, then the single vs batch calling convention. Dense and mostly waste-free, though the heavy capitalization and mid-sentence abbreviation ('SB') add mild parsing friction.

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 the calling modes, batch limit, and per-id result semantics, which substitutes for the missing return documentation. The main gap is that the preview/confirm write protocol is only implicit via the schema's confirm_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?

Schema description coverage is 50%, so the description must carry the mutual-exclusion logic, and it does: SINGOLA = target_id + bid, BATCH = items=[{target_id, bid}] with MAX 25, plus the origin of target_id. account_id, confirm_id, and profile_id are left to the schema, which does describe 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?

States a precise verb+resource ('Aggiorna il BID di uno o PIÙ product target Sponsored Brands') and explicitly distinguishes itself from the sibling ads_update_sb_keyword_bid and from the placement multipliers in ads_update_sb_campaign, as well as implicitly from the SP counterpart ads_update_sp_target_bid. An agent can route correctly without opening any schema.

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

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

Explicitly names the alternatives (keyword bid tool, campaign placement multipliers) and gives the strategic condition for choosing this tool over pausing/cutting budget. It also names the prerequisite source for the identifier ('target_id da ads_list_sb_targets'), so the agent knows the required upstream 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 declare readOnlyHint=false, destructiveHint=true and openWorldHint=true, so the mutation risk is covered structurally. The description adds the batch cap (MAX 25) and 'Esito verificato per-id' partial-failure semantics, but omits the confirm_id preview/confirm workflow and what ARCHIVED irreversibly does.

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

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

Front-loaded verb+resource, then two labelled clauses (SINGOLA/BATCH) with the constraint inline. No wasted words and 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?

Covers the core operation and batch limits, but for a destructive mutation with no output schema it omits the confirmation flow and account/profile scoping an agent needs to invoke it safely. Adequate but with clear gaps.

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

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

Schema coverage is 50%; the description explains the items=[{target_id, state}] shape and the single-mode pairing, which reinforces the key params. It adds nothing for account_id, confirm_id or profile_id, leaving those to the schema, so it sits at the baseline.

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

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

States a specific verb (Aggiorna) plus resource (stato di product target Sponsored Brands) and enumerates the exact states ENABLED|PAUSED|ARCHIVED. The 'SB' scope distinguishes it from siblings like ads_update_sp_target_state and ads_update_sb_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?

Clearly documents the two invocation modes (SINGOLA: target_id + state; BATCH: items=[...], MAX 25), which is useful selection context. However it never states when to prefer this tool over sibling update tools or the prerequisites/authorization needed, leaving usage implicit.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, openWorldHint=true, so the write/safety profile is covered. The description adds the batch cap (25) and per-id verified outcome, but it silently omits the preview/confirm two-step write flow that confirm_id implies, and it lists only enabled|paused while the schema enum also allows 'archived' — a partial mismatch that could mislead.

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 keeps to a few dense clauses; the SINGOLA/BATCH block is scannable. Minor redundancy between the opening sentence and the 'SINGOLA: ad_group_id + bid/state' line, but nothing is wasted.

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

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

No output schema exists, and the description does mention per-id verified outcome for the result. For a 7-param mutation tool it covers modes, limits, and outcomes adequately, though the confirmation workflow is only discoverable through the schema rather than the description.

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 43% schema description coverage, the description carries real weight: it spells out the single-form (ad_group_id + bid/state), the batch items shape [{ad_group_id, bid?, state?}], and the 25-item limit. It does not clarify account_id/profile_id/confirm_id, but those are documented in the schema itself.

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

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

States a specific verb and resource ('Aggiorna uno o PIÙ ad group Sponsored Display') plus the exact fields it touches (bid/defaultBid, state). The SD qualifier and the field list let an agent separate it from ads_update_sp_ad_group and ads_update_sb_ad_group without opening the schema.

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

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

Gives clear operating context: single mode (ad_group_id + bid/state) vs batch mode (items, MAX 25), and notes the SD ad-group bid is the primary optimization lever. It does not name when to prefer this over a sibling such as ads_update_sd_campaign, so there are no exclusions, but the mode selection guidance is concrete.

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 genuinely new behavior: a hard 25-item batch cap and per-id read-after-write outcome verification. It omits that writes only take effect when the same payload is resent with the confirm_id preview token, which is the most consequential operational detail 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?

Front-loaded and dense with zero filler – verb/scope first, then SINGOLA/BATCH variants, then the outcome guarantee and the negative scope. The telegraphic labeling is efficient, though the parenthetical (enabled|paused) is imprecise enough to cost a point.

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 7-parameter mutation with no output schema, the description covers the core operation but leaves gaps: profile_id is undocumented anywhere, the preview/confirm two-step is not mentioned, and the enum mismatch on state could cause a wrong-value call. Adequate but not complete for the risk level.

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 43% (below 50%), so the description must compensate and it partly does: it explains the single-vs-batch alternation, the items shape, and the max size. However it never mentions account_id or profile_id, and it lists state as (enabled|paused) while the schema enum also allows "archived", leaving one parameter's real domain misrepresented.

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 ("Aggiorna una o PIÙ campagne Sponsored Display ESISTENTI") plus the mutable fields (daily_budget, state), and explicitly rules out the nearest sibling behavior with "NON crea campagne SD." An agent can distinguish it from ads_create_sp_campaign / ads_create_sp_ad_group without opening any schema.

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

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

Gives concrete mode-selection guidance (SINGOLA: campaign_id + daily_budget/state; BATCH: items=[...], MAX 25), so the agent knows which parameter shape to pick. It does not name alternative tools (e.g., ads_update_sb_campaign or ads_update_sd_ad_group) or state prerequisites, so it stops short of 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 already disclose readOnlyHint=false, destructiveHint=true, and openWorldHint=true. The description adds no behavioral context such as the preview/confirm workflow, reversibility, permission requirements, or which fields the patch can change. It is consistent with annotations but uninformative.

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 short phrase with no front-loaded actionable detail beyond the verb and resource. This is under-specification rather than useful 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 destructive update tool with a required confirmation token, a nested patch object, no output schema, and half-documented parameters, the description omits call prerequisites, patch structure, and execution semantics. It is not complete enough for reliable invocation.

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

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

Schema coverage is only 50%: account_id and confirm_id have descriptions, but the required nested 'patches' object and ad_group_id have none. The description supplies no parameter meaning at all, 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 and resource: 'Update a SP ad group.' This distinguishes it from SB/SD ad group siblings and from create/list/delete variants. However, it adds no scope or effect detail beyond the name/title, so it is clear but minimal.

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 when-to-use guidance, no alternatives, and no prerequisites. With dozens of sibling tools including create/list/update variants, the description does not help an agent choose this tool over another.

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 the write/destructive/open-world nature, but the description adds critical behavior: multipliers can only increase bids (never decrease), the 10-segment cap, the stacking semantics on top of placement multipliers with a worked example, live re-read + merge behavior, and the preview-then-confirm write cycle. This goes well beyond what annotations convey.

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

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

Despite mixed Italian/English and dense parentheticals, the text is front-loaded with the core purpose, then mechanics, then flow, then policy. Every sentence earns its place, though the packing of many concepts into run-on sentences slightly hurts 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?

With no output schema and a destructive write tool, the description covers mode semantics, the confirmation workflow, side effects (placement multipliers preserved), constraints, and a usage policy. An agent has everything needed to call it safely and 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%, but the description adds semantics the schema does not: percentage is an integer 0-900 that can only raise bids, the set/remove/clear_all interaction, and where audience_id comes from. It meaningfully enriches parameter understanding beyond the schema descriptions.

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

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

The description names a specific verb and resource (set audience bid multipliers on a Sponsored Products campaign) and pinpoints the underlying field (dynamicBidding.shopperCohortBidding). It is clearly distinguishable from siblings like ads_update_sp_target_bid or 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 spells out operational modes (set / remove / clear_all), the two-step confirm flow with an explicit 'when-not-to-write' preview rule, and a practical policy rule (only on campaigns with ACoS within target, measured over 14-30 days). It also names the sibling that supplies audience_id (ads_list_sp_audiences).

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 destructive/openWorld/readOnly=false, but the description adds substantial behavior: a confirm_id preview-then-write flow, read-after-write verification per placement and per id, a hard MAX 25 batch limit, the internal daily_budget → v3 budget{budgetType:DAILY} conversion, and the guarantee that existing audience segments are preserved. This is the kind of operational context annotations cannot express.

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

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

Content is largely earned and the subject is front-loaded, but the entire definition is one dense uninterrupted paragraph mixing mode selection, flow, limits, aliases, and exclusions. It is readable but hard to scan, and a few clauses (the alias list) could be tightened.

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

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

For a zero-required-parameter, six-parameter mutation tool with nested objects and no output schema, the description covers single vs batch invocation, the confirmation prerequisite, the batch size ceiling, the verification guarantee, and the audience-tool boundary. Nothing an agent needs to call it correctly appears 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?

With only 50% schema coverage and nested objects, the description carries real weight: it documents patches.daily_budget conversion, placement multiplier range 0-900, and placement aliases (top/rest_of_search/product_page/business) that appear nowhere in the schema. It is not fully exhaustive — profile_id and account_id handling are left to the schema — so a 4 rather than a 5.

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 precise verb+resource in Italian ('Aggiorna una o PIÙ campagne SP') and immediately splits the SINGOLA and BATCH modes, so an agent can distinguish this from ads_update_sp_ad_group or ads_update_sb_campaign at a glance. It also names the sibling it is not (ads_update_sp_audience_bidding).

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

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

It gives explicit when-to-use guidance: BATCH is 'consigliato per agire su più campagne in una volta, es. "sistema 10 campagne"', and the placement flow is spelled out step-by-step (execute_sql → ads_list_sp_campaigns → anteprima → conferma → questo tool). It also states a clear exclusion: audience segments are not touched here, use ads_update_sp_audience_bidding instead.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: a hard MAX 25 items per call and read-after-write per-ID verification of the outcome, which the agent would not otherwise know.

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, then the single-vs-batch pattern and the limit. Dense but every clause 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 destructive mutation with no output schema, the description covers modes, the batch cap, and result verification. The one notable omission is that the two-step confirm_id write flow is left entirely to the schema, but overall an agent has enough to invoke it correctly.

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

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

Schema coverage is only 50%. The description does clarify the two core parameter patterns (keyword_id+bid vs items=[{keyword_id,bid}]) and the 25-item cap, but it omits the preview/confirm flow driven by confirm_id and leaves profile_id/account_id to the schema, so it only partially 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 and resource: updating the bid of one or more SP keywords. It clearly scopes to SP (Sponsored Products) keywords, but does not explicitly route away from the near siblings ads_update_sb_keyword_bid or ads_update_sp_target_bid, so the agent must infer the SP/keyword distinction.

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 strong internal usage guidance: SINGLE mode uses keyword_id + bid, BATCH mode is recommended for many keywords at once and avoids call bursts. It does not, however, state when to prefer a sibling tool or any preconditions/exclusions relative to them.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true, so the write/irreversibility profile is covered. The description adds meaningful behavior beyond the annotations: batch is capped at 25 items and the result is reported per-ID, which tells the agent partial failures are possible. It does not explain the confirm_id two-step write flow, though the schema does.

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, followed by terse SINGLE/BATCH usage lines and the cap. Every clause earns its place; no filler despite covering multiple modes.

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 per-ID verification note partially compensates by signaling result granularity. Missing pieces (the confirm_id two-step flow, profile_id meaning) are documented in the schema rather than the description, so the definition is adequate but not fully self-contained for a destructive 6-param tool.

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

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

Schema coverage is 50%. The description clarifies how keyword_id, state, and items compose for single vs. batch calls, which adds value. It says nothing about account_id, profile_id, or the confirm_id confirmation token, so the remaining half of parameters are covered only by schema descriptions (or not at all for profile_id).

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

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

States a specific verb+resource (update keyword state) and names the exact valid values (ENABLED/PAUSED), and distinguishes the single-item form from the batch form. An agent can tell this apart from the sibling ads_update_sp_keyword_bid, which changes bids rather than state.

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

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

Clearly explains the two invocation modes (single: keyword_id + state; batch: items array) and the batch cap of 25 per call, which is real operational guidance. It doesn't explicitly name alternatives or state when NOT to use it, but the mode framing gives clear selection context.

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 openWorldHint=true; the description adds non-derivable context: ARCHIVED is irreversible and forbidden, batch is capped at 25, and outcomes are reported per-id rather than as a single success flag. It omits the preview/confirm_id two-phase write behavior, which only surfaces in the schema, keeping it short of a 5.

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

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

Front-loaded with purpose, then constraints, then mode syntax — dense and waste-free. The telegraphic all-caps style ('SINGOLA', 'BATCH', 'PER-ID') is efficient but requires a small inference step, so it is not maximally clear.

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 6-parameter tool with no output schema, the description covers scope, limits, exclusions and granularity of results. The missing pieces are the confirm_id confirmation flow and the effect on already-ARCHIVED or non-existent ads, both of which an agent would want before writing.

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% and all parameters are optional, so mode selection is genuinely ambiguous from the schema alone; the description resolves it by pairing ad_id+state (single) vs items (batch, max 25). It says nothing about profile_id, and account_id/confirm_id meaning lives only in the schema.

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

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

States a specific verb pair (pause/reactivate ENABLED/PAUSED) and an exact resource (SP product ad = single sponsored ASIN/SKU inside an ad group), and explicitly scopes out campaign/ad group state changes, which is precisely how it differs from siblings ads_update_sp_campaign and ads_update_sp_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?

Gives the prerequisite for identifiers (ad_id from ads_list_sp_product_ads), an explicit exclusion (ARCHIVED not permitted), and the two invocation modes (single: ad_id+state; batch: items array, max 25). An agent knows both when to call it and how to shape the 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 declare readOnlyHint=false, destructiveHint=true and openWorldHint=true, so the mutation risk is covered. The description adds the 25-item batch cap and 'Esito verificato per-id', but never discloses the two-step preview/confirm write flow that the confirm_id parameter implies, nor rate/limit behavior beyond the batch cap. Useful, but not rich 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 core action, then the sibling routing, then the two usage modes with their payload shapes. Capitalized keywords (SINGOLA/BATCH/MAX 25) make it scannable. Slightly telegraphic with abbreviations, but no sentence 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 6-param destructive mutation with no output schema, it covers the essentials: what is changed, how to source target_id, single vs batch limits, and per-id result verification. The preview/confirm contract and the account_id/profile_id scoping are left entirely to schema field descriptions, which is a minor 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 only 50% (bid, target_id and profile_id are undocumented in the schema), and the description compensates: it explains that target_id comes from ads_list_sp_targets, that batch items each carry their own bid, and that bid applies to MANUAL targets or AUTO groups. It does not clarify the optionality/role of account_id, profile_id or the single-vs-batch mutual exclusion.

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: updates the bid for one or more SP targets, and explicitly enumerates the target kinds covered (MANUAL ASIN/category and the four AUTO groups). It also names the sibling it is NOT (ads_create_*) and the sibling that supplies target_id (ads_list_sp_targets), so an agent can distinguish it from ads_update_sp_target_state and the create family 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?

States both execution modes and when to pick each: single (target_id + bid) vs BATCH (recommended when many targets, each with a different bid, MAX 25). It routes the agent to ads_list_sp_targets for target_id and explicitly rules out ads_create_* for modulating auto-group bids on an existing AUTO campaign.

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 write/non-read nature is covered. The description adds 'Esito verificato per-id' (per-item result verification), but omits the significant confirm_id two-phase preview/execute workflow that governs this mutation.

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

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

Three terse clauses, single/batch modes front-loaded, all-caps markers for the mode switch and limit. No filler whatsoever.

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?

Adequate for a mutation tool whose annotations cover the safety profile and whose schema documents account_id/confirm_id. The only real gap is the absence of the preview-then-confirm flow in the description, which would help an agent sequence the calls 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?

At 50% schema coverage the description carries extra weight and delivers the ENABLED/PAUSED value set, which the schema leaves as an unconstrained string with no enum. It maps target_id/state to single and items to batch, but says nothing about account_id, confirm_id, or profile_id.

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

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

States a specific verb+resource ('Aggiorna lo stato di uno o PIÙ target SP') and enumerates the permitted values (ENABLED/PAUSED). It is clearly distinct from bid-update and keyword-state siblings, though it never names an alternative explicitly.

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

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

Explains the two invocation modes (SINGOLA: target_id + state; BATCH: items, MAX 25), which implies when to use each, but gives no guidance on when to prefer this tool over ads_update_sp_target_bid or ads_update_sp_keyword_state, and no 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?

Goes well beyond the annotations: it discloses that every SKU is re-read live and skipped if the listing changed since the preview, that a batch halts if the prior batch is not confirmed applied, and that the prior value is persisted to a registry for title_seo_rollback. These are exactly the write-safety and reversibility facts an agent needs before invoking a destructiveHint=true tool.

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

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

Three sentences, front-loaded with the tool's role and write nature, then the batching rules, then the live-verification and rollback guarantees. No filler and no repetition of the schema.

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

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

For a destructive batch-write tool with no output schema, the description covers prerequisites, size limits, abort conditions and rollback. What it omits is what a partial or halted batch returns to the caller (per-SKU success/failure, which SKUs were skipped), which matters for a batch operation.

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

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

Schema coverage is 100%, so the baseline is 3; the description nonetheless adds operational meaning by tying the batch-size ceilings (2 then 50) to the skus parameter and clarifying that the batch is drawn from the plan's ready set. It adds real constraint information rather than restating field descriptions.

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

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

States a specific verb and resource — applies a batch of a title-SEO plan, write step, ready SKUs only — and labels itself 'passo 2', which positions it against the planning/preview and rollback siblings. It never names plan_title_seo_fix, title_seo_rollback or title_seo_status directly, so the routing is inferable rather than explicit.

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

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

Gives a clear precondition (a plan must exist, SKUs must be 'ready') and sequencing rules: first batch per outpost is capped at 2 SKUs, later ones at 50, and the previous batch is re-read before continuing. It does not explicitly state 'do not use this to create a plan — use plan_title_seo_fix', leaving the alternative to inference from 'passo 2' and the schema note.

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 but the description adds substantial context beyond them: it discloses the seller-scoped measurement limitation (brand-owner A+ may masquerade as coverage), per-marketplace document separation, the non-implemented write path, and the specific catalog_not_ready response with alternatives rather than a silent error. These are genuine behavioral traits an agent needs.

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

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

The single-dense-paragraph format front-loads the core purpose well, but it crams purpose, output shape, error handling, disclosure obligations, marketplace caveats, and API limitations into one block. It is information-rich but not well structured for scanning, and several clauses are longer than needed.

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 a read-only audit with no output schema, the description covers scope, limitations, and failure modes thoroughly. It could still be clearer about the pagination/truncation behavior implied by top_n, max_catalog, and max_documents, which materially affect what the agent reports.

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

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

Schema description coverage is 100%, so the schema already documents top_n, account_id, max_catalog, and max_documents with defaults. The description adds no syntax or interpretation beyond the schema, which sets the baseline at 3 per the rubric.

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 (audit) and resource (A+ Content coverage) and defines exactly what is produced: which ASINs have an APPROVED A+ document and which do not, ordered by commercial weight. It is clearly distinguishable from siblings like get_aplus_document or list_aplus_documents (single document vs. catalog-wide audit).

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

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

Gives explicit when-to-use framing ('which pages that actually sell are missing A+'), names alternatives for the failure case (list_aplus_documents / get_aplus_document when catalog_not_ready), and states the mandatory user disclosure limit and the per-marketplace restriction. It also explicitly states what the tool cannot do (creation/editing via API).

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.