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

Even though annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds substantial behavioral context: synchronous execution, internal application state, not saving to Studio, and detailed response-handling instructions (use assistantSummary, never display raw JSON, suggest next action). This goes well beyond the annotations and orients the agent on how to handle results.

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 verbose and includes redundant meta-instructions (e.g., 'Classification: read-only' repeats annotations, 'Execution: synchronous' is not essential). It has a typo ('..') and repeats the title word-for-word at the start. While it front-loads the purpose, it spends several sentences on response formatting guidance that inflate length without adding tool-specific clarity.

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?

The tool has 7 parameters and a nested options object with 14 sub-properties, but the description provides no guidance on how to configure these settings. It does give high-level context (visual grounding for Studio builds, pre-build_ad usage, read-only nature) and points to output schema existence. However, for a tool of this complexity, the lack of any parameter-related context leaves the agent under-informed about how to tailor the collection 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?

Schema description coverage is 0%, so the description must compensate. It does not explicitly explain any of the 7 parameters (advertiserId, brandName, websiteUrl, seatId, seatName, options, storage). It only vaguely hints at the role of brand/website via 'brand logos, imagery, colours, fonts,' but this does not clarify parameter purpose or constraints. The description is largely silent on how to set options or interpret the required fields.

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 clearly states a specific verb+resource: 'Collect brand logos, imagery, colours, fonts, and visual previews for use in Studio creative builds.' It also differentiates from siblings by noting it is a deprecated alias for get_brand_visuals and by positioning it as a pre-step to build_ad, making its role unambiguous.

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?

It explicitly states when to use: 'Use this before build_ad when a campaign needs visual grounding.' It also provides a when-not via 'this read capability does not save to Studio,' and names an alternative (get_brand_visuals as the non-deprecated alias). The restriction 'Task support: forbidden' further clarifies agent usage boundaries.

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