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

With annotations already marking readOnlyHint and idempotentHint, the description adds meaningful behavioral detail: exact frames are extracted from existing local files, otherwise the nearest cached keyframe is returned and the caption notes this. It also discloses the transcript inclusion and approximate image size, going beyond what annotations capture.

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 compact and front-loaded, starting with the core purpose before covering fallback behavior and output details. Every sentence contributes useful information, though it is slightly longer than the minimum needed.

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 adequately explains what the agent receives: one image, approximate size, transcript paragraphs, and the keyframe caption caveat. It covers the important edge case of missing local files and gives enough context for a correct call, though it does not discuss failure modes or prerequisites at length.

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 67%, and the description mostly restates that the frame corresponds to a specific time rather than adding new parameter-level semantics. It does connect the default 960 px to the ~100 KB output, but it does not substantially enrich the meaning of video, time, or max_width beyond the schema.

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

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

The description states a specific action ('Look closely at one moment') with a clear resource ('already-watched video') and concrete use cases like reading code, slides, or UI. It also explicitly says it returns one image, distinguishing it from siblings like get_frames or watch_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 conveys a clear context for use: when you need a close, detailed look at a specific moment of a previously watched video. It does not explicitly name alternatives or give when-not-to-use guidance, so it stops 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.

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds substantial behavioral detail: tile labels with '#number mm:ss', the 3-image cap, downscaling to max_width, paging via start/count, and the absolute-file-path prefix. This goes well beyond the structured 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 dense but well organized: purpose first, then usage strategy, then limits and paging, then file-path behavior. Every sentence contributes actionable information, and there is no 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?

There is no output schema, so the description must carry the burden of explaining return values; it does so thoroughly, including image layout, labels, ordering, size limits, and host file access. The tool is simple enough that nothing needed for correct invocation is missing.

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 100%, so the baseline is 3, but the description adds real value by explaining the paging relationship between start/count, the meaning of kind ('grids' vs 'frames'), and the practical effect of max_width. This helps an agent use the parameters more correctly than the schema alone.

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

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

The description clearly states the verb ('Returns contact-sheet images... or individual keyframes') and the resource ('an already-watched video'), and it distinguishes the two output kinds, grids vs. frames. This makes the tool's purpose concrete and separates it from related frame-retrieval tools.

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

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

The description explicitly says to 'Read the contact sheets first... then request single frames only when you need to read code, slides or UI text,' which is strong when-to-use guidance within the tool. It also gives paging and count guidance, though it does not explicitly name sibling alternatives like get_frame_at for single-frame needs.

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

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

The description discloses truncation and pagination behavior: "Returns at most max_chars; when truncated the last line gives next_start so you can continue from there." It also notes cost behavior ("Paragraph format is the cheapest"). The readOnlyHint and idempotentHint annotations already cover safety, so the description adds meaningful behavioral detail beyond them.

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 dense sentences, each earning its place: purpose, use cases, and return/truncation behavior. The most important scope is front-loaded and there is no redundant restating of the parameter schema.

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 read-only transcript tool with no output schema, the description covers the key operational details: time-range reading, format options, truncation, continuation, and cost. It is slightly less explicit about the exact shape of the transcript lines, but enough 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?

Schema coverage is high and each parameter already has a description, so the baseline is 3. The description adds value beyond the schema by explaining the practical cost/format tradeoff and the continuation mechanism tied to max_chars and start/end usage.

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 a specific verb and resource: "Read part of an already-watched video's transcript with [mm:ss] timestamps." It clearly distinguishes this from the sibling tools by explicitly linking it to watch_video and by its time-range-focused scope rather than search or frame extraction.

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

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

The description gives explicit when-to-use conditions: "Use when the watch_video overview was truncated, when the user asks about a specific time range, or to export subtitles (format='srt')." This tells the agent exactly which scenario selects this tool versus alternatives.

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 and idempotentHint, so the safety profile is covered. The description adds value by specifying the scope ('on this machine') and mentions disk space usage, which is additional context beyond annotations. However, it doesn't detail behavior like live updates of running jobs or error cases, so 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.

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

The description is compact: it states what is listed, the fields, and the purpose in two sentences. It front-loads the core function and lists key return fields, then gives usage reasons. Every clause earns its place; no fluff.

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

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

Given the tool's simplicity, the rich sibling context, and clear schema, the description covers everything needed for correct invocation. It specifies what is returned, ordering, usage cases, and even performance characteristics (instant, read-only). No gaps for an agent to make mistakes.

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%, but the parameter is simple (limit with default, min, max). The description does not explain the limit semantics, but since it's a common parameter with schema constraints, baseline 3 is given; the description could add 'Use limit to control result count' but doesn't need much.

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 lists videos already processed by yueying, plus running jobs, with a specific set of fields returned, and notes ordering (newest first). It distinguishes itself from siblings by focusing on already-processed videos and running jobs, not on watching, transcript retrieval, or frame lookup.

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: when user refers to a video watched earlier, to fetch video_id for other tools, or to check disk space. It also implicitly guides away from siblings by mentioning the video_id is for the other tools, and characterizes the tool as instant and read-only, reinforcing usage context.

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 establish readOnlyHint and idempotentHint. The description adds meaningful context on top: the 'already-watched' prerequisite and the exact per-hit result shape (time, surrounding sentences, keyframe number, contact-sheet number). It does not contradict annotations, though it leaves out result ordering and empty-result behavior.

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

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

Two sentences, front-loaded with purpose, then result contents, then usage guidance. Every clause earns its place and no information is repeated from the schema or annotations.

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?

Despite no output schema, the description tells the agent exactly what each hit returns and how to follow up with get_frame_at or get_transcript. Combined with the well-described parameters and annotations, the description gives the agent everything needed to select and invoke the tool 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?

Schema description coverage is 75% and the schema itself gives rich descriptions for video, query, and context_seconds. The tool description does not add parameter-level semantics and does not explain the undocumented limit parameter. This is a fair baseline score because the schema carries the semantic burden.

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 states a specific action ('Find where something is said') targeting a specific resource ('an already-watched video' transcript) and describes the result contents. It clearly differentiates itself from get_transcript by framing itself as the targeted-search alternative to paging the full transcript.

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

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

The description explicitly says to use this tool instead of paging the whole transcript when the user asks a specific mention question, with concrete example phrasing ('when does he mention X'). It also names follow-up tools, giving clear routing context. This is strong, actionable when-to-use 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?

The description goes well beyond the annotations. It discloses that the tool is fully offline, uses platform subtitles when available otherwise local Whisper, caches results per video, has specific time expectations (5–60s short subtitled, minutes for long unsubtitled), downloads a model on first run (~480MB CPU / ~1.6GB GPU), and explains the RUNNING reply behavior. It also states the reply format (English overview with metadata, chapters, contact sheets, file paths, transcript with [mm:ss] timestamps). This is rich behavioral context that annotations alone (readOnlyHint=false, idempotentHint=true, destructiveHint=false) do not provide.

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 dense but well-organized, front-loading the core purpose and then covering input types, offline behavior, caching, timing, the RUNNING protocol, reply format, and exclusions. Every sentence carries useful information. It loses a point for being somewhat long and for burying the 'Not for live streams or images' exclusion at the end, which is important routing information that could be more prominent.

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 complex tool with 10 parameters, no output schema, and no sibling differentiation in the schema, the description is remarkably complete. It covers input types, platform support, offline behavior, caching, timing, model download, the RUNNING retry protocol, reply format, timestamp citation format, and exclusions. It also references sibling tools (get_frames, get_transcript) for follow-up actions. Nothing an agent needs to call this tool correctly is missing.

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 100%, so the baseline is 3. The description adds value beyond the schema by explaining the video parameter's accepted URL platforms (YouTube, Bilibili, Douyin, Xiaohongshu, TikTok, Vimeo) and clarifying that results are cached per video, which gives meaning to the refresh parameter. It also explains the max_chars truncation behavior and its relationship to get_transcript. However, it doesn't add much detail on mode, model, language, or output_dir beyond what the schema already documents, so a 4 rather than 5.

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 a specific verb and resource: 'Turn a video into a timestamped transcript plus a keyframe overview' and immediately lists downstream uses (summarize, answer questions, extract steps/commands/code, write notes). It also names the input types (local file or specific platforms) and explicitly excludes live streams and images, which distinguishes it from sibling tools like get_frames or get_transcript.

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

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

The description gives explicit when-to-use context: use it to summarize, answer questions, extract steps/commands/code, or write notes. It also states when NOT to use it ('Not for live streams or images') and references sibling tools for follow-up actions ('see them with get_frames', 'start time for get_transcript'). It even provides operational guidance about the RUNNING reply and not starting other videos meanwhile.

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