Server Quality Checklist

Tool Scores

• cleanup_media_cacheA
  3.6/5.0
  Behavior3/5

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

  Annotations indicate readOnlyHint=false (a write/mutating operation) and the description expands on this by stating it cleans up files and frees disk space. However, it does not disclose whether the deletion is permanent, irreversible, or whether it affects only media files or also metadata. The description adds some context but not enough to fully understand the destructive nature beyond what annotations already imply.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness3/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is repetitive, using phrases like 'cleaning up old cached media files', 'clean up storage space', and 'cache becomes too large' multiple times. It is not overly long, but every sentence does not earn its place; the final sentence adds little. It is front-loaded with 'REQUIRED' which is somewhat bold but acceptable.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool's simplicity (one parameter) and lack of output schema, the description covers the basic purpose and usage. However, it lacks explanation of the max_age_days parameter, the permanence of deletion, and any side effects. It is adequate for basic understanding but leaves gaps for correct invocation, especially since schema coverage is 0%.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters2/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema has one parameter, max_age_days, with 0% coverage from the description. The description does not mention this parameter at all, nor explain how age is determined or the effect of changing the default. Since schema coverage is 0%, the description should compensate, but it fails to provide any parameter guidance.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's purpose with a specific verb ('cleaning up') and resource ('old cached media files'), and explicitly mentions images and videos. It distinguishes itself from sibling tools like get_cache_stats and search_cached_media by focusing on the deletion/cleanup action.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description provides clear usage context: use when users want to remove old cached media, clean up storage space, or when cache becomes too large. However, it does not explicitly state when not to use the tool or name alternatives, though siblings are obviously different. This is good but not fully explicit.

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

• search_cached_mediaA
  3.9/5.0
  Behavior3/5

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

  Annotations already indicate readOnlyHint=true and openWorldHint=true, so the description's additional behavioral context is limited but useful: it clarifies that the tool retrieves past analysis results and avoids re-downloading. It does not disclose pagination, return format, or cache freshness, which would add more transparency. With annotations covering the safety profile, a 3 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.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is three sentences, front-loaded with 'REQUIRED,' and every sentence adds distinct value: purpose, use cases, and benefit. There is no redundancy or filler, making it appropriately concise and well-structured.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The tool has 5 optional parameters, no output schema, and no enums, placing a burden on the description to explain behavior and results. The description covers purpose and use cases well but lacks information about what the tool returns (e.g., a list of media items, metadata, or full analysis results). Given the absence of an output schema, this is a notable gap.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  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 explains the intent of four parameters (brand_name, has_people, color_contains, media_type) via phrases like 'by brand name' and 'with people.' However, it omits the 'limit' parameter and does not clarify value formats (e.g., how colors should be specified). This partial compensation warrants a 3.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's purpose: 'finding previously analyzed ad media (images and videos) in cache.' It uses a specific verb ('search') and identifies the resource ('cached media') with a clear scope ('previously analyzed'). This distinguishes it from sibling tools like analyze_ad_video or search_tiktok_ads, which serve different purposes.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description provides explicit when-to-use guidance: 'Use this 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 also highlights a key advantage ('without re-downloading media'). However, it does not explicitly state when not to use or directly compare to alternatives like search_tiktok_ads, so it falls just short of a 5.

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

• analyze_ad_imageA
  4/5.0
  Behavior4/5

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

  The annotations already indicate read-only and non-destructive behavior. The description adds that it downloads and analyzes images, uses caching for cost-efficiency, and extracts specific content types. It doesn't contradict annotations and offers useful operational context beyond the structured metadata.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is compact and front-loaded with the 'REQUIRED' label and core purpose. It lists valuable details (caching, what to extract) without repetition. The structure is efficient and each sentence adds information.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple image-analysis tool, the description covers the main functionality, usage context, and caching behavior. It does not describe return format, but the list of extracted elements gives a strong hint. Combined with annotations and sibling context, it's reasonably complete, though a brief note on output or error handling would improve it.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters2/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema has no descriptions (0% coverage), and the tool description only indirectly refers to media_url as the image URL. It does not explain the purpose or effect of ad_id or brand_name parameters. Since the description fails to compensate for the missing schema information, the agent gets little additional meaning for these parameters.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly identifies the tool's function: downloading and analyzing ad images from TikTok ads. It lists specific extractable elements (visual, text, colors, people, brand, composition) and distinguishes from sibling tools by focusing on images rather than videos. It leaves no ambiguity about the resource and action.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description explicitly states 'REQUIRED for analyzing images from TikTok ads' and instructs to use it for every image URL from search_tiktok_ads. It provides strong when-to-use guidance, though it doesn't explicitly mention alternatives or when-not-to-use. The context is clear and compelling.

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

• get_cache_statsA
  4.3/5.0
  Behavior4/5

  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.

  Conciseness4/5

  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.

  Completeness4/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• analyze_ad_videoA
  4.4/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint and openWorldHint, and the description adds substantial behavioral context: it downloads and processes videos via Gemini, extracts specific narrative elements, notes that TikTok CDN URLs expire quickly, and explains the caching strategy for stability. This goes well beyond the annotations and gives the agent a clear model of what happens during invocation.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Three compact sentences, front-loaded with 'REQUIRED', efficiently convey purpose, extraction details, parameter guidance, and caching. Every sentence adds value with no redundancy or filler.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a tool with no output schema, the description covers the core functionality, critical parameter usage, processing details, and caching behavior. The only notable gap is the roles of media_url and brand_name, which leaves some cross-parameter scenarios ambiguous. Overall, it is reasonably complete for an agent to invoke successfully.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema has 0% description coverage, and the description compensates for only one of three parameters: ad_id is thoroughly explained with its signed-URL rationale. However, media_url and brand_name are left undefined, and the relationship between ad_id and media_url is not clarified. This partial coverage earns a mid-range score.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool analyzes TikTok video ads, with a specific verb ('analyzing') and resource ('video ads from TikTok'). It enumerates the specific aspects extracted (hook, scene-by-scene storytelling, on-screen text, audio/voiceover, pacing, brand messaging), which distinguishes it from sibling tools like analyze_ad_image.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The opening 'REQUIRED for analyzing video ads from TikTok' frames when to use the tool. It also gives a critical usage instruction ('ALWAYS pass ad_id') with a clear rationale. However, it does not explicitly mention when not to use it or name alternatives, though the scope restriction to video ads and the presence of analyze_ad_image imply the boundary.

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

• search_tiktok_adsA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds useful behavioral context beyond those annotations: exact case-sensitive matching, the public nature of the Ad Library, and that spend/impressions are returned as bands, not exact figures. No contradiction with annotations.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is three sentences, each earning its place: purpose, usage modes with an example, and return values plus required companion tools. It is front-loaded and contains no filler.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given no output schema, the description explicitly lists return fields (ad ids, run dates, spend/impression bands, media URLs) and directs to analyze tools for visual analysis. It could mention pagination behavior via cursor/limit, but the description is otherwise complete for a search tool with good annotations.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema has 0% description coverage, so the description must compensate. It provides critical semantics for the primary parameter 'query', explaining it can be an exact advertiser name or a keyword, and highlights case sensitivity. However, it doesn't explain 'limit' or 'cursor', but these are standard pagination parameters and the query guidance is the key missing piece.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states a specific verb and resource: 'Search TikTok's public Ad Library for the ads an advertiser is running.' It also lists the return fields (ad ids, run dates, spend/impression bands, media URLs), distinguishing it from siblings like analyze_ad_video and analyze_ad_image.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Explicitly instructs to use the exact registered advertiser name (case-sensitive) or a keyword, and names appropriate alternatives: 'For complete analysis ... you MUST also use analyze_ad_video (passing ad_id) or analyze_ad_image.' This gives clear context for when to use this tool versus others, though it doesn't explicitly state when not to use it.

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

• get_tiktok_ad_detailsA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint and openWorldHint, so the safety profile is clear. The description adds behavioral context by promising a 'fresh playable video URL' and detailing what information the response contains (creative, landing page, country targeting, engagement metrics). No contradictions found.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is two concise sentences: the first states the function and the returned data categories, the second provides usage context. There is no redundant wording or unnecessary detail, making it highly efficient.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple one-parameter read-only lookup, the description adequately sets expectations by listing the output content categories and linking to the appropriate sibling search tool. No output schema exists, but the enumerated detail fields are sufficient for an agent to understand what the tool provides.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema has zero description coverage for the single parameter ad_id, so the description must compensate. It does so by explaining the provenance ('from search_tiktok_ads') and the purpose (identifying a specific TikTok ad), which gives the agent enough context to provide a valid value.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses a specific verb ('Get detailed information') and identifies the exact resource ('a specific TikTok ad'), while enumerating concrete data categories (full creative, landing page, country targeting, engagement metrics, playable video URL). It clearly distinguishes itself from the sibling search_tiktok_ads by specifying that it operates on an ad_id rather than performing a search.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description explicitly states when to use this tool: 'Use this with an ad_id from search_tiktok_ads' and calls it 'Essential for analyzing ad content and extracting media URLs for visual analysis.' It does not explicitly mention alternatives or exclusions, but the context is clear enough for an agent to select it appropriately.

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