Server Quality Checklist

Tool Scores

• get_channel_metadataA
  4/5.0
  Behavior3/5

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

  No annotations exist, so description carries the burden. It implies read-only operation ('fetch') and specifies the channel_id constraint. However, it omits error handling, rate limits, and authentication requirements. Behavior is partially disclosed but lacks depth.

  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?

  Two short paragraphs: first gives core purpose and usage, second details args/returns. Every sentence is necessary, no fluff. Front-loaded with the key action.

  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 single-parameter read tool, it covers purpose, usage context, parameter constraint, and return fields. Lacks error/edge-case details, but given low complexity, it is reasonably complete.

  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% (no parameter descriptions), so the description's 'channel_id: YouTube channel ID (must start with UC)' adds needed format constraint. But the parameter is simple and essentially named; the addition is helpful but not extensive.

  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 'fetch full metadata for a known channel_id' with clear verb and resource. It distinctly positions itself as an enrichment step after search_youtube_channels, differentiating from siblings that search or analyze videos.

  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?

  It provides explicit usage context: 'Use after search_youtube_channels to enrich a candidate... before presenting to the user.' This guides when to invoke, though it does not explicitly mention when not to use or alternatives beyond the sibling hint.

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

• get_video_infoA
  4.2/5.0
  Behavior3/5

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

  No annotations are provided, so the description must carry the burden. It mentions the tool is 'cheap' (1 API unit) and metadata-only, implying read-only behavior. It does not mention error handling, rate limits, or what happens on failure, but for a simple lookup this is acceptable.

  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 short sentences with an extra 'Args' section for clarity. No redundant words, every sentence adds value.

  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 simple parameters and lack of output schema, the description covers what the tool returns, how to pass parameters, and the cost implication. It could mention the return format, but the purpose is clear enough.

  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?

  Schema coverage is 0%, but the description adds meaning beyond the schema: video_url can be a full URL or just the video ID, and min_duration_seconds has a default of 600 and is a threshold for an 'excluded_from_analysis' flag. This helps the agent understand usage.

  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 it is a 'cheap metadata-only lookup for a single YouTube video' and lists the specific fields returned (title, duration, channel, publish date). It distinguishes itself from sibling tools that perform analysis or batch operations.

  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?

  It explicitly tells when to use this tool: to inspect metadata without burning Gemini tokens. It also explains the purpose of min_duration_seconds as a threshold for a flag. However, it does not explicitly mention alternatives or when not to use it, though sibling tools provide context.

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

• get_stateA
  4.4/5.0
  Behavior4/5

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

  Despite no annotations, the description discloses read-only nature, return fields, and the fact that data is cached (avoiding API calls). This covers key behavioral traits.

  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?

  Two short paragraphs, each sentence earns its place. No fluff, front-loaded with purpose and key details.

  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?

  With one optional parameter and no output schema, the description adequately explains input semantics and output content. Could mention potential size of results, but not necessary for this single-param tool.

  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 sole parameter channel_ids is clearly explained: if provided, filter to those channels; otherwise return all. Schema only has type info, so description adds essential meaning.

  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 'read-only view of the discovery state file' and specifies the returned fields (video_id, published_at, analyzed_at). It distinguishes from sibling tools like list_tracked_channels by focusing on state per channel.

  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 mentions it is useful for answering 'what's the latest video I've seen from channel X?' without re-hitting YouTube, providing clear context. Does not explicitly mention when not to use, but the purpose is well-scoped.

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

• analyze_videos_batch_resultA
  4.5/5.0
  Behavior4/5

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

  Describes possible statuses (SUCCEEDED, FAILED, CANCELLED, EXPIRED) and return structure including results and error. Without annotations, it provides sufficient behavioral context for a simple poll operation.

  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?

  Concise yet comprehensive: one initial sentence for purpose, followed by usage instructions, parameter description, and return shape. No wasteful content.

  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?

  Covers all necessary aspects: polling behavior, argument source, return shape, terminal statuses, and error handling. For a tool with one parameter and no output schema, this is fully complete.

  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 description adds valuable context for 'batch_job_name' by specifying it is the name returned by 'analyze_videos_batch_start', which is not evident from the schema alone (coverage 0%).

  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 it polls the Gemini Batch API once to check for results, and distinguishes itself from sibling tools like 'analyze_videos_batch_start' (which starts the batch) by specifying its polling nature and return of per-video results upon completion.

  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 call repeatedly until a terminal status, with recommended cadence of 30-60s. It also references the start tool for the argument but does not explicitly state when not to use (e.g., before starting a batch).

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

• remove_tracked_channelA
  4.6/5.0
  Behavior5/5

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

  With no annotations, the description fully bears the responsibility. It discloses no-op behavior, persistence of last-seen state, and details of the return value including the 'user_facing_message' field, which is essential for correct agent behavior.

  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 well-structured with clear sections for Args and Returns, and the critical usage instruction is front-loaded. It is somewhat verbose but each part adds value, earning a high score.

  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?

  Despite the tool's simplicity, the description covers all relevant aspects: what the tool does, when it is a no-op, what happens to state, and the exact return format including the 'user_facing_message' for agent usage. No output schema exists, but the description compensates fully.

  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 single parameter 'channel_id' is described as 'YouTube channel ID', adding minimal context beyond the schema's type and title. Since schema description coverage is 0%, the description compensates only slightly; the parameter is straightforward, so a score of 3 is appropriate.

  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 removes a channel from the registry, using a specific verb and resource. It distinguishes itself from the sibling tool 'add_tracked_channel' which performs the opposite action.

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

  Usage Guidelines5/5

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

  The description explicitly warns that the tool must be called to avoid silently wrong state, and explains that it is a no-op if the channel was not tracked. It also clarifies that it does not clear last-seen state, guiding appropriate usage.

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

• add_tracked_channelA
  4.7/5.0
  Behavior5/5

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

  Discloses idempotency behavior, constraint that channel_id must start with 'UC', and the return structure including user_facing_message. Since no annotations are provided, the description carries full burden and does so thoroughly.

  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 structured but somewhat lengthy; however, each sentence provides essential information. It could be slightly more concise but remains effective.

  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?

  Given zero annotations and no output schema, the description covers behavioral details, parameter semantics, and return structure comprehensively. It even instructs the agent on how to present results.

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

  Parameters5/5

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

  Schema description coverage is 0%, but the description details each parameter's purpose and constraints, such as channel_id format, handle being optional '@handle', and tags being arbitrary grouping strings. This adds significant value beyond the schema.

  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?

  Clearly states 'Add a channel to the registry' and emphasizes that the tool must be invoked, distinguishing it from sibling tools like list_tracked_channels and remove_tracked_channel.

  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 tells the agent to call this tool when adding a channel and warns against claiming addition without invocation. However, it does not provide explicit when-not-to-use or alternatives beyond the sibling context.

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

• resolve_youtube_channelA
  4.7/5.0
  Behavior4/5

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

  No annotations provided, so description carries full burden. It describes return value on success and failure, and mentions that it returns None/error for certain inputs. Missing details like rate limits or authentication, but reads well for a simple resolution tool.

  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?

  Well-structured with bullet points and examples, but slightly verbose. Could trim some repetition (e.g., 'Returns None / error' and then later 'Returns:' block). Still effective and front-loaded.

  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?

  Tool is simple with one parameter and no output schema, but description covers input constraints, return fields, and error format. Complete enough for an agent to use correctly without additional context.

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

  Parameters5/5

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

  Despite 0% schema description coverage, the description provides multiple concrete examples and explains the expected format. This fully compensates for the sparse schema, making the parameter semantics crystal clear.

  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?

  Clearly states it resolves a YouTube handle or channel URL to metadata. Distinguishes from sibling tools like search_youtube_channels by noting it skips the search step. Explicitly lists what inputs it does not handle.

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

  Usage Guidelines5/5

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

  Explicitly says 'Use this when the user gives an exact handle or URL — skips the search step.' Also warns about invalid inputs (video URLs, free-text strings). Provides clear context for when to use versus alternatives.

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

• analyze_videos_batch_startA
  4.8/5.0
  Behavior5/5

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

  With no annotations, the description carries full burden and delivers: it reveals async nature, cost implications ('50% cheaper'), SLA ('up to 24 hours, typically 15-60 min'), and return structure. It fully discloses behavioral traits beyond the input schema.

  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 well-structured with clear sections (use case, args, returns). It is concise but could be slightly trimmed (e.g., the detailed prompt override explanation is useful but slightly verbose). Still, it earns its keeping.

  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 has 2 parameters, no output schema, and no annotations, the description is very complete. It covers purpose, usage, behavioral details, and return format. However, it lacks explicit error conditions or failure handling, which is minor.

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

  Parameters5/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 add meaning. It explains `video_urls` as 'List of full YouTube URLs (https://www.youtube.com/watch?v=...)' and `prompt` as optional override with default behavior and per-batch override mechanism. This adds significant semantic context.

  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 'Submit a batch of YouTube videos to Gemini Batch API for async analysis.' It distinguishes from `analyze_video_start` by noting it is async and cheaper. The verb 'submit' and resource 'batch of YouTube videos' are specific, and the context signals show sibling tools with similar names, but the description effectively differentiates.

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

  Usage Guidelines5/5

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

  Explicitly states 'Use this ONLY when the user explicitly says "no rush", "overnight", "do it later", or for scheduled cron digests.' It contrasts with `analyze_video_start` for interactive requests, providing clear when-to-use and when-not-to-use guidance. This is exemplary.

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

• list_tracked_channelsA
  4.8/5.0
  Behavior4/5

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

  Describes return format and a key behavioral instruction (use user_facing_message verbatim). Does not explicitly state read-only, but it's implied for a listing tool. No annotations, so description carries the burden well.

  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?

  Front-loaded with purpose, strong usage guideline, then parameter and return details. Every sentence adds value; no waste.

  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?

  Despite no output schema, the description outlines the return structure (channels array with fields, count, tag, user_facing_message). Complete for a simple filtered list tool.

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

  Parameters5/5

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

  Schema has 0% coverage, but description explains the tag parameter: 'If provided, return only channels carrying this tag.' Fully compensates for missing schema descriptions.

  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?

  Clear verb+resource: 'List all channels currently in the registry.' Distinguishes from siblings by referencing the registry and providing a specific use case.

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

  Usage Guidelines5/5

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

  Explicitly states when to call: 'Always call this tool when the user asks "what am I tracking"...' and instructs not to answer from memory, highlighting registry mutability.

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

• analyze_video_resultA
  4.9/5.0
  Behavior5/5

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

  No annotations provided, but description fully discloses blocking behavior, clamping of wait_seconds to [0,55], all possible return statuses, and job TTL of 6 hours. No 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?

  Well-structured with paragraphs and bullet points, front-loaded core purpose. Slightly verbose due to recommended pattern details but every sentence adds value.

  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 polling tool with 2 params and no output schema, description covers all needed context: return format, error handling, timeouts, polling limits, and job lifecycle. Very complete.

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

  Parameters5/5

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

  Schema coverage 0%, but description adds full meaning: job_id defined as id from analyze_video_start, wait_seconds explained with default and clamping range. Significantly adds beyond schema.

  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?

  Clearly states it polls for an analyze_video_start result. Distinguishes from siblings (analyze_video_start, analyze_videos_batch_result) by focusing on polling behavior.

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

  Usage Guidelines5/5

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

  Provides explicit recommended pattern: call with wait_seconds=10, cap polling at ~90 iterations, re-poll on transport errors. Rationale for default wait_seconds given.

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

• analyze_video_startA
  4.9/5.0
  Behavior5/5

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

  No annotations, but the description fully discloses behavior: background job, returns immediately, does not update discovery state, and explains concurrency for multiple videos and timeouts.

  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?

  Well-structured with sections, but slightly verbose. Could be trimmed while retaining all necessary information.

  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?

  Given no output schema and moderate complexity, the description covers behavior, parameters, usage, and next steps (polling). It also explains the rationale for background processing due to timeouts.

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

  Parameters5/5

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

  Schema coverage is 0%, so the description must explain parameters. It does so thoroughly: video_url as required, max_retries default 3, prompt optional with explanation of default and environment variable override.

  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 it launches Gemini video analysis as a background job, returning quickly with a job_id. It distinguishes from siblings like analyze_videos_batch_start and analyze_video_result, making the purpose clear.

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

  Usage Guidelines5/5

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

  Explicitly says to use this for single or multi-video requests as the default, and to use analyze_videos_batch_start only when the user says 'no rush' or for scheduled tasks. Also mentions polling for results.

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

• discover_new_videosA
  5/5.0
  Behavior5/5

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

  No annotations present, but description fully discloses state tracking, filters (skip livestreams, short videos, old videos), and first-run behavior. No contradictions.

  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?

  Well-organized with sections for modes, state, filters, args, and returns. Each sentence adds value; no redundancy. Front-loaded with core purpose.

  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?

  Complex tool with 4 params, state management, filtering, and two modes. Description covers all aspects: inputs, behavior, output fields. Sufficient without output schema.

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

  Parameters5/5

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

  Schema coverage is 0%, but description explains all 4 parameters: channel_ids, tag, max_per_channel, min_duration_seconds, including defaults and conditional behaviors.

  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?

  Clearly states the tool discovers new videos from YouTube channels since last seen, with two modes and filtering. Distinguishes from siblings like search_youtube_channels or get_video_info 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 Guidelines5/5

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

  Explicitly explains two modes: explicit channel_ids vs registry-based, and tag filter. Also describes first-call behavior and mentions related tools for registry management.

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

• search_youtube_channelsA
  5/5.0
  Behavior5/5

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

  Discloses that no YouTube API key is required, uses yt-dlp scraping, and specifies what data is not populated in the results.

  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?

  Well-structured, concise paragraphs with Args section; every sentence adds unique value without redundancy.

  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?

  Includes return format with field names, empty list case, and references get_channel_metadata for missing data, compensating for lack of output schema.

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

  Parameters5/5

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

  Adds meaningful context to both parameters: query with example values, max_results with description of ranking and default, despite schema having 0% coverage.

  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?

  Description clearly states 'Search YouTube for channels matching a free-text query' with specific examples of use cases, and distinguishes from sibling tools like get_channel_metadata.

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

  Usage Guidelines5/5

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

  Explicitly says when to use (when user names or describes a channel before adding to registry) and what not to expect (subscriber count, recent videos) with pointer to sibling tool.

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