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

The description discloses a wealth of behavioral details beyond the annotations: writes to Studio, synchronous execution, task support forbidden, mutation modes (validate_only, preview_only, execute), partial failure policy (completed_items_not_rolled_back), deterministic retry key derivation, and the explicit seat requirement for writes. This far exceeds the minimal annotation hints and provides actionable 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?

The description is well-structured with clear labels (Classification, Execution, etc.), but it is overly long. The final paragraph about response formatting and user interaction is generic boilerplate that applies to any tool and adds bulk without tool-specific value. It could be tightened by moving the generic style instructions to a shared location.

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?

Despite the rich behavioral metadata, the description omits the core operational semantics: what inputs are required for a resolve vs. a provision, what the output represents, and how the parameters interact. An agent cannot confidently invoke this tool based on the description alone, especially given the nested brand object and 11 loosely-typed parameters. The output schema helps, but the description does not tie parameters to behavior.

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 11 parameters and 0% schema description coverage, the description carries a heavy burden. It does explain idempotencyKey behavior and the seatId/seatName requirement, but it leaves the core parameters (brand, dryRun, billing, sandbox, operator, accountId, advertiserId, createIfMissing) completely undocumented. The mention of 'mutation modes' is not mapped to any parameter (e.g., dryRun), so an agent cannot correctly set up a call without additional information.

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 begins with 'resolve or provision advertiser,' which simply restates the tool name/title without explaining what 'resolve' or 'provision' actually does. It does not clarify the conditions under which it resolves vs. provisions, nor does it distinguish this tool from siblings like create_advertiser or get_advertiser. The added detail 'Classification: writes to Studio' is a property, not a purpose.

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 explicitly states 'Deprecated alias for resolve_or_provision_advertiser,' which clearly instructs the agent to prefer the canonical tool. It also provides relevant usage constraints: 'Task support: forbidden' and the seat requirement for writes. However, it does not elaborate on when to use resolve vs. provision or when to choose this over sibling tools, so it is not a full 5.

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