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

Annotations provide only readOnlyHint=false, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial non-obvious behavior: 'creates billable AI usage', 'Execution: synchronous', 'Partial failure policy: completed_items_not_rolled_back', explicit mutation modes (validate_only, preview_only, execute), deterministic retry-key derivation when idempotencyKey is omitted, and the seat-supplied-on-exact-call rule. It also discloses that the returned JSON is 'internal application state for LeanrIQ and ChatGPT orchestration'. These materially affect how an agent should call the tool and what to expect. No contradiction with annotations - readOnlyHint=false aligns with 'writes to Studio' and idempotentHint=true aligns with the retry-key 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?

The description is dense but organized: purpose first, then classification, execution mode, task support, failure policy, and then response-format guidance. Every operational sentence carries distinct information. The response-format section ('Never display raw JSON... Prefer concise, human language') is somewhat generic chat-SOP material that could be trimmed, but it remains actionable. Front-loading is good - the most decision-relevant traits (billable write, synchronous, partial failure) appear early.

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 tool of this complexity - 9 params, 5 required, nested options and storage objects, billable side effects, partial failure without rollback - the operational coverage is strong: sync execution, mutation modes, failure policy, idempotency, and seat rules are all disclosed. But the description omits the domain semantics: what refreshing brand visuals does, what data is updated, and any prerequisites (e.g., must an advertiser exist first, is a prior get_brand_visuals needed). The output schema exists, so return-value explanation is not required, but the purpose-generation gap remains significant for such a complex mutation.

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 carries full responsibility for parameter meaning. It does add value for idempotencyKey (deterministic retry if omitted) and seatId/seatName (mandatory on the exact call when multiple seats are authorized). But it says nothing about advertiserId, accountId, brandName, websiteUrl, or - critically - the large nested options object (17 properties controlling fonts, logos, images, videos, screenshots, AI images) and the storage object. An agent cannot understand what configurations it is choosing without opening 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 opens with a clear verb+resource ('refresh brand visuals'), which distinguishes it from read-only siblings like get_brand_visuals and leanriq_get_brand_visuals. However, it never explains what a refresh operation actually entails operationally - e.g., that it re-scrapes the website to update fonts, logos, colors, images, or videos. The core semantics are left to inference from the options schema, which the agent would have to reverse-engineer.

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 refresh_brand_profile, get_brand_visuals, or leanriq_get_brand_visuals. The description gives operational constraints - 'Task support: forbidden' and the seat requirement for mutations ('seatId or seatName must be supplied on that exact tool call') - but these are invocation rules, not tool-selection guidance. An agent has no stated basis for deciding between refreshing visuals and refreshing a brand profile.

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