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

Rich disclosure well beyond the annotations: it states writes to Studio, billable AI usage, synchronous execution, forbidden task support, the three mutation modes, and a partial-failure policy (completed_items_not_rolled_back). It also documents deterministic idempotency-key derivation and the requirement to pass seatId/seatName on a write when more than one seat is authorised. This is exactly the extra behavioral 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 description uses labelled fields (Classification, Execution, Task support, Mutation modes, Partial failure policy) that are front-loaded and scannable. It is somewhat long, with a boilerplate block about response formatting and assistantSummary, but every section is labeled and purposeful rather than rambling.

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 an output schema present, return values need not be explained, and the behavioral sections are thorough. However, for a complex tool with nested objects the description still omits the most fundamental question - what 'refresh' retrieves or changes about brand visuals - so an agent knows the mechanics and safety profile but not the effect.

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 0%, so the description must carry parameter meaning, yet it only explains idempotencyKey and the seatId/seatName rule. The five business arguments (advertiserId, brandName, websiteUrl, accountId) and the large nested options/storage objects receive no explanation, leaving most parameters 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?

The description opens by restating the name ('refresh brand visuals') and only adds 'writes to Studio, creates billable AI usage,' which classifies the operation but never explains what a refresh actually does (re-scrape the website for logos, fonts, colours, images?). It does not distinguish itself from siblings like get_brand_visuals or refresh_brand_profile. An agent can infer a mutation, but the core resource/action relationship is left vague.

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 choose this tool over alternatives such as get_brand_visuals (the read counterpart) or refresh_brand_profile. The mutation modes (validate_only, preview_only, execute) hint at execution style but not at selection criteria or prerequisites. Usage must be inferred entirely from context.

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