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

Annotations already declare readOnlyHint and openWorldHint, lowering the bar. The description adds caching behavior and cost-free repeated calls, giving useful context beyond annotations, though it doesn't detail download side effects or error 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?

Three sentences, front-loaded with 'REQUIRED', providing purpose, usage, and caching behavior with no redundant wording.

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?

Strong on purpose and usage, but lacks parameter explanation and output format description, especially given no output schema. The 3-param schema with 0% description coverage and no return value details leaves notable gaps.

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 has no parameter descriptions (0% coverage). The description only indirectly mentions media_url via 'image URL returned by get_google_ads' but leaves ad_id and brand_name unexplained, so it does not compensate for the schema gap.

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 the tool analyzes ad images and enumerates specific extraction targets (visual elements, text, colors, people, brand, composition), distinguishing it from siblings like analyze_ad_video.

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 mandates use for every image URL returned by get_google_ads during comprehensive analysis, providing strong when-to-use guidance and indirectly excluding video analysis.

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

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

Annotations provide readOnlyHint=true, indicating safe read-only behavior. The description adds behavioral context beyond that: it downloads videos, uses Gemini's video understanding, employs intelligent caching, and provides comprehensive analysis. It doesn't mention rate limits, failure modes, or output format, but with no mutation risk and moderate added context, a 4 is appropriate.

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 brief and front-loaded with 'REQUIRED', immediately conveying importance. It's composed of two sentences with minimal fluff. However, the final phrase 'includes comprehensive video analysis' is somewhat redundant given the previous list of insights, making it slightly less concise than it could be.

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 analyzes videos from Google, which is a complex task with no output schema and sparse annotations. The description gives a good overview of capabilities and insights but lacks details about input prerequisites (e.g., what form media_url should take) and what exactly the output consists of. It does mention caching and specific analysis dimensions, but misses edge cases and more concrete usage guidance. Overall, it's functional but not fully complete.

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?

The input schema has 0% description coverage, so the description must compensate by explaining the parameters. It only implicitly suggests that media_url is the video to download, but says nothing about ad_id or brand_name. The meanings of these optional parameters remain unclear, making it difficult for an agent to know what values to provide. This is a significant gap.

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 the tool's purpose: analyzing video ads from Google using Gemini. It lists specific extractable insights (visual storytelling, audio, pacing, etc.), which distinguishes it from sibling tools like analyze_ad_image (images vs. videos) and get_google_ads (listing vs. analyzing). The verb 'analyze' and resource 'video ads' are specific and 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?

The description explicitly states it is 'REQUIRED for analyzing video ads from Google', providing clear context for when to use this tool. It doesn't explicitly mention alternatives or when not to use it, but the strong 'REQUIRED' phrasing and the contrast with analyze_ad_image imply the appropriate use case. No exclusions or alternatives are named, so it's slightly below a perfect score.

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

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

Annotations already indicate readOnlyHint=false, so it is known to be a mutation. The description adds that it targets old cached media and frees disk space, but does not disclose irreversibility, whether files are permanently deleted, or any side effects beyond freeing space. This is minimal but not contradictory.

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 brief and front-loaded with the action. However, the closing phrase 'Essential for cache maintenance and storage management' is somewhat redundant and does not add meaningful value beyond the first sentence.

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 simple tool with one parameter, the description covers purpose and usage, but lacks information about return values or specific outcomes like the number of files deleted or space reclaimed. Since there is no output schema, the description should explain what the tool returns or what happens after cleanup.

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%, and the description does not mention the max_age_days parameter or explain how it affects cleanup. The parameter name and default are in the schema, but the description does not compensate for the lack of schema-level descriptions.

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 the tool cleans up old cached media files and frees disk space, using a specific verb and resource. It naturally distinguishes itself from sibling read-only tools like get_cache_stats and search_cached_media.

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 gives explicit context for when to use the tool: when users want to remove old cached media, clean storage space, or when cache becomes too large. It does not mention alternatives or when not to use it, but the primary use cases are clearly defined.

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

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

Annotations already declare readOnlyHint=true, covering the safety profile. The description adds meaningful behavioral context beyond annotations by specifying that the tool reports on media cache (images/videos), storage usage, and file counts. It does not contradict annotations, and it gives a clear picture of what the tool returns.

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 concise, consisting of three short sentences with no redundant information. It front-loads the purpose with 'REQUIRED for checking media cache status and storage usage' and then gives actionable guidance on when to use it. Every sentence earns its place.

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?

Given the tool is simple (0 params, no output schema), the description covers the essential usage scenarios and what the tool reports. It is complete enough for an agent to decide when to invoke it. It could mention potential limitations or whether stats are global, but these are not critical for basic usage.

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?

The tool has zero parameters, so the schema Description coverage is fully satisfied. The description adds no parameter-specific semantics, but with no parameters required, no additional explanation is necessary. Baseline for 0 params is 4, and the description does not introduce confusion about inputs.

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: 'checking media cache status and storage usage' and elaborates on what is measured ('how many files have been analyzed and cached'). This distinguishes it from sibling tools like search_cached_media and cleanup_media_cache, which focus on searching or deleting cached media.

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 provides explicit usage scenarios: 'Use this tool when users ask about cache statistics, storage space used by cached media, or how many files have been analyzed and cached.' It is marked as 'REQUIRED' for these cases. However, it does not explicitly mention when not to use it or name alternative tools such as search_cached_media or cleanup_media_cache for other cache-related tasks.

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

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

The description expands beyond the readOnlyHint annotation by detailing the returned data (text variations, image URLs, headlines, descriptions). This adds valuable context about the tool's scope and output, though it doesn't address edge cases or response structure.

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?

Three well-structured sentences front-load the purpose, then provide usage guidance and rationale. Each sentence adds value with no redundancy or filler, making it concise and easy to parse.

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?

Given a single parameter, read-only annotations, and no output schema, the description adequately covers what the tool does, where the input comes from, and expected data content. It also mentions practical use cases like media extraction and visual analysis, leaving little ambiguity for typical usage.

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 ad_url having no schema description (0% coverage), the description compensates by specifying the parameter's source ('adUrl from get_google_ads') and its role in identifying a specific ad. This provides meaningful semantic context, though exact formatting or validation rules are not mentioned.

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 uses the specific verb 'Get' and resource 'detailed information about a specific Google ad,' listing concrete data types like variations, regional stats, and impressions. This clearly distinguishes it from siblings like get_google_ads (which lists ads) and analyze_ad_image (which analyzes images).

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 instructs to use this tool with the adUrl from get_google_ads, providing a clear integration path and use case ('analyzing ad content and extracting media URLs'). While it doesn't explicitly state when not to use alternatives, the context is clear and actionable.

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

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

Annotations already include readOnlyHint: true, so the description needs to add behavioral context beyond that. It does add useful details: the tool filters by topic and region, returns 'currently running ads' (implying real-time data), and each ad includes an imageUrl that can be passed to analyze_ad_image. However, it doesn't describe pagination behavior (cursor) or limits, and it doesn't mention any potential caveats like missing advertisers or incomplete data from the external source.

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 three sentences, each earning its place: purpose, usage, and cross-reference to a sibling tool. It is front-loaded with a clear verb and resource, and contains no fluff. This is a model of efficient, structured tool description.

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 6 optional parameters, no output schema, and no required params, the description covers the core scope well: what it retrieves, how to identify the company, and how to filter. It references imageUrl from details, which hints at the return shape. It doesn't explicitly mention pagination or result limits, but the presence of cursor and limit parameters and the lack of an output schema make that less critical. The description is complete enough for typical invocation, though a brief note about pagination would improve it.

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 coverage is 0%, so the description must compensate. It explains domain and advertiser_id ('using their domain (e.g., 'nike.com') or advertiser ID'), and it explains topic and region ('filter by topic (including political ads) and region'). However, it does not mention limit or cursor, which have no schema descriptions. Given that 4 of 6 parameters are semantically explained, it provides substantial value beyond 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 clearly states the tool's purpose: 'Retrieve currently running ads for a company from Google Ads Transparency Center.' This specifies the verb (retrieve), resource (ads), and scope (currently running ads for a company), distinguishing it from siblings like analyze_ad_image and get_google_ad_details. The example 'e.g., 'nike.com'' further clarifies the intended input.

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 instructs when to use this tool: 'Use this tool to get ads for a company using their domain ... or advertiser ID.' It also provides a clear directive for an alternative tool: 'For complete analysis of visual elements ... you MUST also use analyze_ad_image on the imageUrl from each ad's details.' This gives the agent explicit guidance on complementary usage and when to invoke a different tool.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description's burden is reduced. It adds useful context that this searches the cache and avoids re-downloading media, but does not disclose return format, pagination behavior, or matching semantics.

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 concise and front-loaded, conveying the tool's necessity and usage in three short sentences. Some redundancy exists between 'REQUIRED' and 'Essential', but overall it is well-organized and free of fluff.

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?

Given the moderate complexity of a filtered search tool with no output schema, the description adequately communicates what the tool searches and why it matters. It does not explain the returned data structure, but the phrase 'past analysis results' gives a reasonable expectation.

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 descriptions are absent, but the description maps four of the five parameters to concrete user intents: brand_name, has_people, color_contains, and media_type. The limit parameter is not described, though it has a default value in 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 clearly states the verb 'search' and the resource 'cached media', specifying that it finds previously analyzed ad media (images and videos). It differentiates from sibling tools like analyze_ad_image/video and cleanup_media_cache by emphasizing retrieval of cached analysis results.

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 says when to use the tool: 'when users want to search for cached media by brand name, find media with people, search by colors, or filter by media type.' It provides practical context but does not mention when not to use it or explicitly name alternative tools.

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