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

Annotations already declare readOnlyHint and openWorldHint, so the description only needs to add extra context. It discloses the caching behavior ('intelligent caching... efficient and cost-free') and implies network access via downloading, which adds value beyond annotations.

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, front-loaded with 'REQUIRED' and immediately conveys the core action. Every sentence adds value, including the caching note and usage rule, with no fluff or repetition.

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 with a simple schema and no output schema, the description is quite complete. It explains what types of images are handled, lists the extracted elements (giving a sense of output), and provides caching and usage context. Minor gaps such as error handling or prerequisites are not critical.

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 schema has 3 parameters with 0% description coverage, so the description should compensate. It references media_url by mentioning 'image URL' but does not explain ad_id or brand_name, leaving their purpose unclear. The required parameter is implicitly covered, but optional parameters lack guidance.

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 function: downloading and analyzing ad images to extract visual elements, text content, colors, people, brand elements, and composition details. It distinguishes itself from sibling tool analyze_ad_video by explicitly focusing on images and listing supported image types.

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 context: 'should be used for EVERY image URL returned by search_linkedin_ads when doing comprehensive analysis.' It clearly indicates when to use the tool, but does not mention specific alternatives or exclusions, though the sibling tool list implicitly differentiates 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?

Discloses meaningful behavioral context beyond annotations: downloads and analyzes video via Gemini, uses caching per ad rather than CDN URL, and mentions intelligent caching. This aligns with readOnlyHint while adding practical details.

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', followed by function, analysis details, and caching guidance. No redundant phrases or filler.

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 no output schema and minimal param descriptions, the description covers purpose, cached behavior, and analysis dimensions well. Missing brand_name semantics and explicit return format, but the extracted-elements list implies output structure.

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%, and the description adds meaning for media_url (required video URL) and ad_id (caching key), but brand_name is entirely unexplained. This leaves one parameter without semantic clarity.

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 function: 'analyzing video ads from LinkedIn' with specific outputs (hook, storytelling, on-screen text, voiceover, etc.). It distinguishes from sibling tools like analyze_ad_image by explicitly focusing on 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?

The description gives a strong usage signal with 'REQUIRED for analyzing video ads' and advises passing ad_id for correct caching. It doesn't explicitly name alternative tools but the sibling context makes the differentiation obvious.

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 (a mutating operation), and the description confirms by mentioning 'cleaning up' and 'freeing disk space.' However, it doesn't disclose that files are permanently deleted, potential irreversibility, or any side effects beyond space freeing. The description adds some context but could be richer.

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 but contains redundancy: 'freeing disk space,' 'clean up storage space,' and 'storage management' all express the same idea. The leading 'REQUIRED' is unnecessary and adds noise. It is front-loaded but could be more concise.

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 no output schema, the description should hint at what the tool returns (e.g., number of files deleted, space freed). It also doesn't mention irreversibility or any confirmation flow. For a destructive tool with annotations indicating mutation, this is a notable gap, but the core purpose and trigger conditions are covered.

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 only parameter 'max_age_days' at all. The parameter name is somewhat self-explanatory, but the description fails to clarify its role (e.g., cutoff age for deletion), leaving the agent without additional guidance beyond the schema's default value.

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 action ('cleaning up old cached media files') and resource ('images and videos'), distinguishing it from sibling tools like get_cache_stats or search_cached_media. The verb 'cleanup' is unambiguous and tied to a concrete outcome (freeing disk space).

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?

Explicitly states when to use the tool: 'when users want to remove old cached media, clean up storage space, or when cache becomes too large.' It doesn't explicitly mention when not to use it, but the context and sibling tools make that implicit, which is sufficient.

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, so the safety profile is clear. The description adds useful behavioral context about what statistics are provided (storage usage, file counts) and positions it as essential for monitoring. It does not introduce any side effects or contradictions.

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 front-loaded with the essential purpose ('REQUIRED for checking media cache status') and followed by usage cues. It is efficient overall, but the final sentence 'Essential for cache management and monitoring' adds little beyond the earlier text, making it slightly redundant.

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's simplicity (no params, read-only, no output schema), the description covers the core purpose and user intents. It does not describe return format or how it relates to cleanup decisions, but these are not critical given the annotations and simplicity. The description is sufficient for accurate selection and invocation.

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 is inherently 100% covered. No parameter explanation is needed, and the description appropriately omits any. This aligns with the baseline of 4 for zero-parameter tools.

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 function: checking media cache status and storage usage. It lists specific outputs (storage space used by cached media, number of files analyzed/cached) and distinguishes it from siblings like cleanup_media_cache (mutation) and search_cached_media (search).

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 when to use: 'when users ask about cache statistics, storage space used by cached media, or how many files have been analyzed and cached.' It provides strong contextual guidance, though it does not explicitly mention when not to use it or name alternative tools for 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?

Beyond the readOnlyHint and openWorldHint annotations, the description discloses input variations (ad id or full URL) and enumerates the returned data fields (targeting, per-country impressions, creative, destination URL). It also highlights the ability to extract media URLs for visual analysis, adding useful behavioral 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?

Two tightly packed sentences with zero fluff. First sentence lists the output details; second sentence states the input source and purpose. Highly concise and well-structured.

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 one-parameter tool with no output schema, the description is remarkably complete. It covers the input source, the returned information categories, and the practical use case (visual analysis and ad targeting understanding). No missing pieces for an agent to invoke it correctly.

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 schema only lists ad_id as a string, but the description explains that it can be an ad id from search_linkedin_ads or a linkedin.com/ad-library/detail/ URL. This thoroughly compensates for the schema's 0% description coverage.

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: get detailed information about a specific LinkedIn ad. It lists specific content (targeting, per-country impressions, creative, URL) and distinguishes from the sibling search_linkedin_ads by focusing on detailed lookup for a single ad.

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?

Explicitly instructs when to use: with an ad id from search_linkedin_ads or a LinkedIn ad library detail URL. It also states it's essential for understanding targeting and extracting media URLs, providing clear context and alternative guidance.

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 cover readOnlyHint and openWorldHint, and the description adds useful context like 'previously analyzed' and 'without re-downloading media.' However, it does not disclose details about return formatting, ordering, or behavior when no results are found. The added context is helpful but not extensive.

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, front-loaded with 'REQUIRED,' and uses three short sentences that each add value. It captures the purpose, use cases, and benefit without extraneous information.

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 five optional parameters and no output schema, the description covers the main search dimensions and conveys the tool's purpose and typical use cases. It doesn't explain the return structure, but it implies the retrieval of prior analysis results, which is sufficient for an annotated read-only search tool.

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 names the searchable filters (brand_name, has_people, color_contains, media_type) and maps them to user intents, adding meaning beyond the raw schema. However, it does not explain value formats or the meaning of the limit parameter, leaving some gaps.

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 finds 'previously analyzed ad media (images and videos) in cache' with a specific verb and resource. It distinguishes itself from siblings by emphasizing 'cached media' and the search use cases (brand name, people, colors, media type).

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 when-to-use guidance: 'REQUIRED for finding previously analyzed ad media' and lists specific user intents (search by brand, find media with people, search by colors, filter by media type). It lacks explicit when-not-to-use or alternative tool references, but 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 provide readOnlyHint=true, and the description adds useful behavioral context: it lists the returned fields (headline, description, CTA, destination URL, targeting, impressions, media URLs) and notes media URLs are meant for downstream analysis. This goes beyond the annotation, but it doesn't address pagination behavior, result ordering, or potential incompleteness of the Ad Library data.

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 five sentences, each adding distinct value: purpose, search methods, filter support, returned fields, and cross-tool directive. There is no filler or redundant phrasing, and the most critical information is front-loaded in 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?

Given no output schema and sparse annotations, the description covers the essential return fields and provides clear pointers for further analysis. However, it omits pagination (pagination_token) and the meaning of `limit`, which are relevant for handling large result sets. A fully complete description would mention these to help agents use the tool effectively at scale.

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 no per-parameter descriptions (0% coverage), so the description must compensate. It explains company, keyword, company_id, countries, and date-range filters, but leaves `limit` and `pagination_token` entirely unexplained. It also does not specify date or country formats, so the parameter guidance is helpful but incomplete.

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 'Search LinkedIn's Ad Library for the ads a company is running,' which precisely identifies the verb (search), resource (Ad Library), and scope (ads of a company). It distinguishes itself from siblings by explicitly directing visual analysis to analyze_ad_image/analyze_ad_video, making its own search-and-return purpose clear.

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 clearly states multiple search strategies (by company name, keyword, or LinkedIn company ID) and even highlights company_id as 'most precise.' It explicitly instructs using analyze_ad_image or analyze_ad_video for visual analysis, which serves as a when-not-to-use this tool guidance. However, it does not mention when to use get_linkedin_ad_details compared to this search tool.

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