Server Quality Checklist

Tool Scores

• get_video_evidenceA
  4.3/5.0
  Behavior4/5

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

  The description adds value beyond annotations by stating that the tool 'never invents detail beyond what was actually recorded', which is a behavioral guarantee. Annotations already provide readOnlyHint=trueتریidempotentHint=true and destructiveHint=false, but the description adds specific context about data fidelityesternity. It does not contradict annotations and accurately reflects a read-only lookup operation.

  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 concise, with two sentences. The first sentence clearly states the purpose and constraint, and the second provides a concrete use case. It is front-loaded with the core function and behavioral guarantee. It could be slightly more structured, but it is effective and does not waste words.

  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 moderate complexity, with 2 required parameters and an output schema, the description covers the essential aspects: what it does, when to use it, and behavioral guarantees. It mentions the ids needed and where they come from in the schema. The description is sufficient for an agent to understand when and how to use this tool correctly, especially with the output schema and annotations providing additional context.

  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 input schema fully describes both parameters (video_id and evidence_id) with explanations of where they come from. The description does not add additional parameter semantics beyond what the schema provides. Since schema description coverage is 100%, the baseline score of 3 is appropriate; the description does not need to repeat the parameter details.

  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: to look up evidence for a single Video Map fact by id. It uses a specific verb ('looks up') and the resource ('full evidence behind a single Video Map fact'). It differentiates itself from siblings by explicitly referencing get_video_map and get_video_entity, making it clear that this tool retrieves evidence details rather than the map or entity data itself.

  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 provides explicit guidance on when to use this tool: to double-check a specific claim before treating it as authoritative, such as confirming a reference's evidence_level. It also implies when not to use it (e.g., when you need the full map or entity, use the mentioned siblings). The mention of alternative tools (get_video_map, get_video_entity) provides clear routing, and the use case ('double-check a specific claim') is well-defined.

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

• get_video_timelineA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds meaningful behavioral context about the merged chronological view coming from a previously-processed video and the dependency on a prior understanding call.

  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 composed of three efficient sentences with no filler. The core return semantics are stated first, followed by the usage context and the required prerequisite.

  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 single-parameter read-only tool with an output schema present, the description gives the key return semantics, the prerequisite, and the relationship to sibling tools. An agent has enough information to decide when to invoke it and what it will receive.

  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 already has 100% coverage for the single required video_id parameter, including the prerequisite that it was returned by understand_video or transcribe_video. The description adds little beyond what the schema already provides, so baseline 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 states the exact resource and behavior: a full chronological, merged timeline of a previously-understood video, interleaving spoken segments and visual observations. It also distinguishes this tool from siblings by positioning it as the underlying structure that search_video and find_moment query.

  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 tool when the agent needs the complete picture rather than a single answer, and connects it to the search siblings. It also states the prerequisite that video_id must come from a prior understand_video or transcribe_video call.

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

• understand_videoA
  4.6/5.0
  Behavior5/5

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

  While annotations already declare readOnly, idempotent, and openWorld hints, the description adds behavioral detail beyond those: it clarifies the output includes both transcript and visual analysis, explains that the returned video_id is reusable across other tools without reprocessing, and explicitly states it does not answer free-form questions. This contextualizes the tool's behavior without contradicting any annotation.

  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 longer than average but well-structured: purpose and entry-point guidance are front-loaded, followed by downstream usage and a dedicated 'WHAT IT DOES NOT DO' section. Every sentence contributes useful information, though it could be tightened slightly without losing clarity.

  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 the tool's multimodal complexity and integration with multiple siblings, the description is remarkably complete. It covers what it does, what it does not do, the limitations, and how the output (video_id) connects to other tools. Since an output schema exists, omitting return structure details is acceptable. Nothing an agent needs to decide when and how to call it is missing.

  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 already provides full coverage (100%) for the single 'url' parameter, describing it as a public video URL with platform restrictions and login requirements. The description reiterates these constraints in the 'DOES NOT DO' section but does not add new parameter-level meaning beyond what the schema already conveys, keeping it at the baseline for high 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?

  The description states a specific verb ('watches') and resource ('public video') and clearly defines the output as both transcript and visual information. It explicitly differentiates itself from transcribe_video by noting that visual analysis is always included versus opt-in for its sibling, making its purpose unambiguous.

  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 gives explicit entry-point guidance ('Use this as the entry point for any question that isn't purely what was said'), states what it does NOT do (does not answer free-form questions), and names the exact sibling tools to use for downstream tasks (search_video, find_moment, get_video_timeline). It also lists platform and access limitations, leaving no inference required.

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

• find_momentA
  4.7/5.0
  Behavior4/5

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

  Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful behavioral detail about the interaction field: it is present only when a visual entity is strongly resolved, absent when evidence is weak, and never fabricated. This goes beyond the annotations and adds trust-indicating transparency.

  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 a compact set of four sentences, each carrying distinct information: purpose/differentiation, dependency, usage guidance/example, and interaction field reliability. No filler or redundancy. The most essential info is front-loaded in the opening sentence.

  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?

  The tool has only two parameters, a 100% schema-described input schema, and an output schema to describe return values. The description sufficiently explains prerequisites, intended use cases, and edge-case behavior (weak evidence), making it equally complete. No critical operational element needing explanation is missing.

  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?

  With 100% schema description coverage, the baseline is 3. The description adds extra value by explaining the query parameter's semantic role (specific things to find, with examples like 'pricing') and stating that video_id must come from prior understand_video or transcribe_video output. This contextual relationship is not in the schema and helps agents compose calls correctly.

  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 ('Returns') and a precise resource ('single best timestamped piece of evidence'), and explicitly contrasts itself with the sibling search_video ('unlike search_video which returns every match'). An agent can clearly distinguish this tool from its siblings without inspecting the schema.

  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?

  It explicitly states a prerequisite (requires a video_id from prior understand_video or transcribe_video), provides usage examples, and gives a clear selection criterion: 'use this when you need one authoritative answer with proof rather than a list of every mention'. The 'when not to use' is implied by the contrast with search_video, giving an exclusionary signal.

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

• get_video_entityA
  4.7/5.0
  Behavior5/5

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

  Annotations already establish that the tool is read-only, idempotent, and non-destructive, so there is no contradiction. The description adds meaningful behavioral detail beyond those annotations: results include every interaction and every linguistic reference resolved to the entity, returned in chronological order. This tells the agent what kind of data to expect and how it is organized.

  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 compact sentences with no repetition or fluff. It front-loads the core function, then provides usage context and a concrete example in parentheses. Every sentence earns its place.

  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 two-parameter lookup tool with comprehensive annotations and an output schema, the description is complete: it defines what the tool returns, the prerequisites, the input IDs, the output scope, and the ordering. An agent has everything it needs to call this tool correctly and understand the result.

  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 100%, and both parameters already have clear descriptions explaining where the IDs come from (understand_video/transcribe_video for video_id; get_video_map or search_video/find_moment for entity_id). The tool description reinforces this relationship but does not add new parameter-level semantics beyond the schema, so the baseline 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 uses a specific verb and resource: it 'Returns everything the Video Map knows about one specific entity' and clarifies that entity means 'a person/product/object'. It also differentiates itself from siblings like get_video_map and search_video/find_moment by emphasizing the full chronological history rather than an isolated moment.

  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?

  It explicitly states when to use the tool: 'Use this after get_video_map or search_video/find_moment surfaces an entity id.' It further clarifies the use case—full history across the video—and contrasts it with seeing 'one isolated moment,' which helps the agent choose between this and more narrowly scoped tools.

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

• transcribe_videoA
  4.8/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds substantial behavioral context beyond annotations: it explains that visual analysis is server-side gated, that 'visual' is not a frame-by-frame caption, that low_confidence is set rather than guessing, that on-screen text is preserved exactly as read, and that longer/larger videos are rejected rather than partially processed. This is rich, honest behavioral disclosure.

  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 long but well-structured with clear section headers (WHAT IT DOES, WHAT IT DOES NOT DO, SUPPORTED INPUT, LIMITATIONS). The most important information is front-loaded in the first sentence. Every section earns its place, though the length is at the upper bound of what is reasonable for a tool description.

  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 the tool's complexity (3 parameters, output schema, multiple supported platforms, server-side feature gating), the description is remarkably complete. It covers supported inputs, unsupported inputs, error behavior, limitations, confidence semantics, and the meaning of absent 'visual' data. The output schema exists, so return values don't need to be re-explained. Nothing an agent needs to call this correctly is missing.

  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 description coverage is 100%, so the schema already documents all three parameters well. The description adds value by explaining the semantics of the visual output ('visual' is only meaningful observations, not every frame) and by clarifying that includeVideoMap only enriches the same sampled frames. However, the description doesn't add much beyond the schema for the url parameter, which is already thoroughly described in 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?

  The description opens with a specific verb ('Retrieves... and returns') and names the exact resources (public Instagram Reel, TikTok video, YouTube video/Short) and outputs (timestamped transcript, visual info). It clearly distinguishes itself from siblings like understand_video, search_video, and find_moment by focusing on transcription of spoken audio plus optional visual observations.

  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 states when to use the tool ('when you need the words spoken in a public video... and optionally what it visually showed') and provides extensive what-it-does-not-do guidance, including unsupported platforms, private content, and unsupported URL shapes. It also names the error type (UNSUPPORTED_SOURCE) for invalid inputs, which helps an agent decide before calling.

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

• get_video_mapA
  4.9/5.0
  Behavior5/5

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

  Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false. The description adds critical behavioral detail: evidence_level ('observed/inferred/uncertain'), the meaning of absent target_entity_id (expected, not failure), and the empty-array vs error contract. These go far beyond the structured annotations and reduce deployment surprises.

  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 packed with purpose, usage, semantics, and edge cases, and every sentence earns its place. It front-loads what the tool does, then gives context and fallback guidance, ending with the clearest routing alternative. No fluff or 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?

  For a read-only look-up tool with a single parameter and a deep output schema, the description covers the only input prerequisite, the meaning of key output fields, the edge case for un-resolved references, and the fallback behavior when data is absent. Nothing an agent needs to safely invoke and interpret this tool is missing.

  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 already describes video_id ('A video id previously returned by understand_video or transcribe_video'), providing full coverage of the single parameter. The description adds one valuable nuance: 'with visual mapping enabled', which is not in the schema and is essential for determining when the tool will return meaningful results.

  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 ('Returns') and names a concrete resource ('the Video Map: the semantic layer') and explains what it connects (speech, visible entities, interactions, references). It clearly distinguishes itself from siblings like search_video or find_moment by stating it resolves speech-to-reference mappings, not raw search.

  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 gives explicit preconditions ('Requires a video_id from a prior understand_video call with visual analysis enabled'), explicit fallback behavior ('Returns empty arrays when the feature wasn't enabled or found nothing'), and explicit alternatives ('use search_video/find_moment for the underlying speech/visual search either way').

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

• search_videoA
  4.9/5.0
  Behavior5/5

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

  The description discloses that the operation is read-only (consistent with annotations), returns every match with timestamp and modality, and ranks by relevance. It also notes the dependency on prior video understanding, which annotations do not cover. This adds meaningful behavioral context beyond the readOnlyHint and idempotentHint 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 two paragraphs: the first clearly defines function and output; the second gives usage guidance with examples. It is front-loaded with the core purpose, and every sentence adds 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?

  Given the presence of an output schema (not shown) and the straightforward nature of a read-only search, the description covers all necessary context: what it searches, what it returns, prerequisites, and when to use it. No critical information appears missing.

  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 descriptions already cover both parameters (100% coverage), so baseline is 3. The description adds extra meaning: video_id must come from specific prior calls (understand_video or transcribe_video), and query can be a word, phrase, name, number, or topic. This exceeds the level of the input 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?

  The description states a specific verb ('searches') and resource ('every information channel of a previously-understood video, including spoken transcript, on-screen text, and visual context'), and specifies the return of matches with timestamps and modality. It clearly distinguishes from siblings like transcribe_video and understand_video by focusing on search rather than extraction or summarization.

  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 states when to use the tool ('when you already know what you're looking for'), the prerequisite ('video_id from a prior understand_video or transcribe_video call'), and names the alternative behavior it replaces ('re-reading a whole transcript'). This gives clear routing guidance relative to siblings.

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