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

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

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

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

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

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

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

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

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

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

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

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

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

States a specific verb (aggiorna/update) and resource (BID of SB product targets), plus scope (single vs batch). It explicitly positions itself against ads_update_sb_keyword_bid and ads_update_sb_campaign, so an agent can distinguish it from sibling bid/state/campaign tools without opening their schemas.

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

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

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

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