kadam_adv_set_creative_bids

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

Annotations only declare readOnlyHint=false; the description carries the real behavioral load: replace-not-merge semantics, fallback to campaign bid for omitted countries, same-campaign and targeting preconditions, duplicate-country restriction, and CPA rejection. This is exactly the destructive/irreversible context an agent needs before calling.

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, purpose front-loaded, then the crucial replace/fallback behavior, then validation constraints. Every sentence earns its place with no filler.

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

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

For a two-parameter write tool with no output schema, the description covers semantics, preconditions, and rejected cases completely. An agent has everything needed to invoke it correctly without opening the schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: the bids list fully replaces existing bids and unmapped countries fall back to the campaign bid. That semantics-of-the-list insight is not inferable from the schema alone.

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

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

States a specific verb and resource ('Set per-country bids on creatives') with scope clarified as per-country/creative. This clearly distinguishes it from siblings like kadam_adv_bulk_update_bids and kadam_adv_update_extended_bids.

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 operational guidance: 'send every country you want priced, not just the one you are changing' and an explicit exclusion ('CPA campaigns are rejected'). It does not, however, name an alternative tool for e.g. campaign-level bids, so it stops short of full when-vs-alternative routing.

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