bilibili-info-gathering

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

With no annotations present, the description carries the burden well: it discloses that one call may hit upstream multiple times (cost.calls), that frames requires ffmpeg and only runs when frames_at is supplied, which channel is cheapest, and that degraded[] reports per-channel failures. Missing richer detail on failure modes or permissions, but the behavioral picture is above average.

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 channel breakdown is front-loaded and scannable, with the cost warning placed at the end for emphasis. The '为什么要有它' paragraph adds some narrative padding and an external DSH comparison that an agent doesn't strictly need, but structure remains tight enough.

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 10-parameter aggregator with an output schema, the description covers the mechanics an agent needs: channel selection, per-channel knobs, degradation handling and cost. The unexplained page and quality parameters are the notable gap, since the output schema does not cover request-side semantics.

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

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

Schema coverage is 0%, so the description must compensate, and it does map most controls to their channels: transcript_query/transcript_head_ratio/transcript_max_chars for transcript, comment_n/comment_detail for comments, frames_at for frames. However it leaves page and quality entirely unexplained and gives no value semantics for comment_detail beyond the raw default.

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 gives a specific verb-and-resource statement (aggregating transcript, comments, danmaku, cover and optional frames in a single call) and explicitly positions it against the single-channel siblings by saying results are structurally identical to them. An agent can distinguish it from get_transcript/get_comments/get_danmaku without opening any schema.

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?

It explains the selection rationale clearly: use it to cut round trips and obtain a unified degradation signal rather than orchestrating the five channels separately. It also names a concrete cost-avoidance recommendation (supply transcript_query or transcript_head_ratio). It stops short of an explicit 'use X instead when' rule for the lightweight single-channel case.

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?

No annotations are provided, so the description carries the full disclosure burden. It does so well by disclosing the threshold-based auto-download logic, the skip behavior below 5%, the contact-sheet composition, and the caveat that thumbnails are only for locating and not for citing numbers or conclusions. It does not cover permissions, rate limits, or error 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?

The text is front-loaded with the purpose, then the threshold rules, then the usage workflow and the thumbnail caveat. It is compact and nearly every sentence carries useful information, though the formatting is slightly dense.

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 three-parameter tool with an output schema and no annotations, the description covers the core workflow, the output shape at a conceptual level, and the key caveat about using original images. Its main omission is that bvid and comments remain semantically undocumented.

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

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

Schema description coverage is 0%, so the description must compensate. It explains top_n=0 and its threshold-based behavior in detail, including the 15% and 5% rules. However, it does not explain bvid or the comments parameter, and it leaves positive top_n values unexplained.

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 that this tool handles comment-section images: it judges them against a threshold, downloads them in parallel, creates a numbered contact sheet, and returns a grid-number list. That is a specific verb-and-resource purpose, but it does not explicitly distinguish this tool from siblings such as get_comments or grab_frames.

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?

It gives clear context for when to use the tool and how to use it: check the contact sheet first, then read the original images by #number. It also explains the automatic threshold behavior when top_n=0. It does not explicitly state when not to use it or name a competing alternative.

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?

With no annotations, the description carries the full behavioral burden and does so well: it discloses token costs, body truncation, returned field sets, default sanitize behavior, injection-risk marking semantics, and the privacy warning for locations. It also warns that keyword injection hits are only hints and not evidence.

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 long but front-loads the core purpose and structures the cost/field tradeoffs as bullets. Every major section carries operational value: mode selection, stats semantics, privacy handling, and injection caveats.

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?

Although there is an output schema, the description still supplies essential context for interpreting the modes, stats metrics, n limitation, and sanitize behavior. For a complex comment-reading tool with four parameters and zero schema coverage, it is complete enough to call 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 0%, so the description must compensate; it explains n as a top-level comment cap that excludes nested replies, and it defines the detail and sanitize modes despite no enums in the schema. However, the required bvid parameter is not explained at all.

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 opening states a specific verb and resource: it retrieves top-level comments plus structural metrics for the comment section. The three detail modes are clearly differentiated, but the description does not explicitly distinguish this tool from siblings such as get_comment_images or scan_untrusted_text.

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?

It gives clear when-to-use guidance for each detail mode, including 'brief' for broad scanning, 'opinion' for opinion distribution, and 'full' only for quoting originals or reading nested replies. It also explains the n<100 limitation and sanitize='off', but does not name sibling alternatives for overlapping 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?

No annotations exist, so this carries the full load, and it does disclose meaningful operational traits: space endpoints require WBI signing, unsigned calls return -799 'too many requests', and the correct seasons_series_list path. It omits pagination behavior, upper limits, and whether calls are purely read-only.

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 section list is front-loaded and useful, but the '为什么需要这条通道' motivation paragraph and emoji-heavy formatting consume space without helping invocation. The endpoint-path caveat is valuable but buried at the end.

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?

An output schema exists, so return values need no explanation, and the section enumeration adequately covers what the agent will get back. Remaining gaps are the pagination contract (page/page_size interaction) and what mid actually identifies.

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% with 5 parameters, so the description must compensate. It does well on section (five named values with meanings) and order (pubdate / click / dm), but says nothing about mid identity, page, or page_size semantics.

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?

States a specific verb+resource (fetch an UP creator's profile/works/posts) and enumerates the five section values with a short gloss for each. It also distinguishes itself from search_videos by explaining that search recalls by content and cannot retrieve 'what a given person posted later'.

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?

Gives an explicit use case (after narrowing a topic to 2-3 core creators, ask what they posted next) and names the alternative (search_videos) plus why it fails there. No when-not-to-use or prerequisite/rate-limit guidance beyond the endpoint warning.

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?

No annotations exist, so the description carries the burden. It usefully discloses one behavioral trait beyond the schema — out-of-range page raises an explicit error rather than silently falling back to P1 — and states that output is a compressed summary, not raw danmaku. However it says nothing about volume, rate limits, or what happens with empty danmaku streams, and an output schema already covers the return shape.

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?

Front-loaded with the action and output, then rationale, then constraints. The rationale section is somewhat editorial and could be tightened, but every paragraph maps to a decision the caller must make.

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?

Return values are covered by the output schema, and the description adds scope restrictions and error behavior, which is what an agent most needs for a focused analysis tool. The gap is that 'top' is undocumented, leaving one of three parameters opaque.

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

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

Schema coverage is 0% and there are 3 parameters, so the description must compensate. It does well for page (multi-P selector, default 1, hard error on out-of-range), but 'top' (default 5) is never explained and bvid is left implicit. Partial compensation only.

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?

Names a specific verb and resource (get danmaku) and immediately enumerates the derived outputs: density curve, densest segment with samples, high-repetition lines, disclosure keywords. It also explicitly contrasts itself with get_comments (second-level timestamps vs publish time), so an agent can tell them apart without opening the schema.

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?

Gives an explicit two-item allowlist of use cases (extension divergence, comment-section structural bias) plus two explicit prohibitions: don't create a dedicated chapter, don't treat danmaku as majority opinion. That is when-to-use, when-not-to-use, and the alternative (get_comments) in one place.

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?

No annotations, so the description carries the load and does disclose a real behavioral trap: for multi-part videos (n_pages > 1) downstream tools read only part 1 unless page= is passed explicitly. It doesn't mention batch-size limits, failure modes for invalid BV ids, or rate/cost constraints, which keeps it short of a 5.

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?

Front-loaded with the core purpose, then warnings, then field semantics — good ordering. Some internal jargon ("批次 C3 放回来的", "最便宜的一手形态信息") is noise, and emoji-heavy emphasis inflates length slightly, but no sentence is purely redundant.

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

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

Output schema exists, yet the description still usefully explains the most consequential return fields (n_pages vs pages, per-page cid). Combined with the usage routing, an agent has what it needs; only batch-size/error behavior 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 0% for the single required 'bvids' parameter, and the description only indirectly reveals it takes BV ids ("你只有一个 BV 号"). It adds no detail on array size limits, ID format, or whether non-BV ids are accepted, leaving a real gap for the only input.

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?

Starts with a specific verb+resource: batch-fetch complete metadata (cid/pages, tags, full description). It explicitly contrasts itself with the broad-scan path (search results already carry metadata), so an agent can distinguish it from search_videos/scan_topic without reading schemas.

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?

Gives an explicit when-not (broad scanning doesn't need it) followed by two enumerated when-to-use conditions: you have only a BV id, or you need a cid — and it even notes that get_transcript/get_danmaku handle cid internally. That is the strongest form of routing 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?

With no annotations, the description carries the full burden and does so well: it discloses the default compression behavior, the citation-safety distinction between 'subtitle' and 'ai_subtitle', and explicitly states that an out-of-range page raises an error rather than silently falling back to P1. The 'degraded' field for multi-part videos is also disclosed. It stops short of covering permissions or rate limits, which keeps it from a 5.

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 cost ordering is front-loaded and the three usage modes are laid out as a scannable list. Heavy bold/emphasis markup and the opening warning take up space that could be tighter, but every section conveys actionable information rather than 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?

An output schema exists, so the description needn't document return shape, yet it usefully explains the two highest-stakes return fields (data_source and degraded). Combined with the mode guidance, an agent has nearly everything needed — the unmentioned max_chars is the one remaining hole in a 5-parameter tool.

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

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

Schema description coverage is 0%, so the description must compensate, and it explains query, head_ratio, and page with real semantics (query = hit sentence ±2 context; page = which part of a multi-P video). However, max_chars (default 8000) is never mentioned at all, despite being the parameter that governs the cost tradeoff the description is built around — a notable gap.

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 verb plus resource ('取字幕' — fetch the transcript) and immediately flags its default behavior (compression on). It implicitly distinguishes itself from transcribe_audio by framing itself as retrieval of existing subtitles with a data_source provenance field, but it never names that sibling or explicitly contrasts the two.

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?

It enumerates three usage modes in ascending cost order, gives a concrete value for each (head_ratio=0.2, query="关键词"), and states which one to prefer ('优先用这个'). It also warns when not to use the full-fetch mode ('长视频会非常贵，慎用'), which is exactly the when/when-not guidance an agent 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?

With no annotations, the description carries the full behavioral burden and does so well: it discloses the ffmpeg dependency, non-silent failure behavior, page-cache separation for multi-part videos, quality limitations for reading numbers, and the returned {sheet, grid[]} structure.

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 content is front-loaded and organized with clear sections, and most sentences earn their place. Some warnings and emphasis are repeated, making it slightly longer than necessary.

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 frame-extraction tool with no annotations and an output schema present, the definition provides enough context to call it correctly: trigger conditions, quality guidance, multi-part handling, dependency behavior, and return-value interpretation.

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

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

Schema description coverage is 0%, so the description must compensate. It richly explains quality and page semantics, including practical consequences, and implies at_seconds usage around the error timestamp, but bvid and the exact array format of at_seconds are not explained.

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 — extracting frames on demand — and sharply scopes it to cases where subtitle/transcript errors affect understanding. It also distinguishes the tool from the anti-pattern of extracting frames for the whole 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?

It gives explicit when-to-use criteria (numbers, proper nouns, parameter names whose misreading changes the conclusion) and a clear when-not-to-use warning against full-video extraction. It does not explicitly name an alternative sibling tool, so it falls short of a full 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?

With no annotations, the description carries the full burden and largely meets it: it explains that `staging` is the write-side gate (the formal library is untouched before commit) and that `cost` with `window="run"` requires a prior `registry_upsert(kind="run-start")` marker, plus `closed=true` semantics. It also disclaims that `est_output_tokens` is a rough output-side estimate, not a billing figure. It does not state size/volume limits for the list modes.

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 most important instruction (query the registry at task start) is front-loaded before the long `kind` enumeration, and the enumeration is formatted so an agent can scan for the mode it needs. It is long, but the length is justified by 13 modes; the trailing `est_output_tokens` caveat is the one part that reads as extra.

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 six-parameter multi-mode reader with no annotations, the description supplies mode semantics, param prerequisites, the write-gate distinction, and the run-marker dependency. An output schema exists, so return-value explanation is correctly omitted. Minor residual gaps are list-mode volume/pagination behavior.

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

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

Schema description coverage is 0%, so the description must compensate, and it effectively does: every parameter's role is covered — `mid` ("需 mid"), `bvid` ("需 bvid"), `topic` ("需 topic 名"), `domain` ("可按 domain 过滤"), `window` (`"run"` vs default). It does not state that `kind` defaults to `stats`, nor spell out the valid value set as an enum, but the mode list supplies the semantics.

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 opening verb+resource ("读资产库") is followed by a complete enumeration of the 13 `kind` modes, each with a one-line scope note, so an agent knows exactly which sub-resource each call retrieves. It is clearly the read side of the registry, distinguishable from the sibling `registry_upsert` which is named explicitly in the `cost` and `staging` notes.

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?

Gives explicit timing guidance ("每次任务开始前先查一遍——已有评级的 UP 主直接沿用") and a concrete motivation for `video`/`sources` lookups (avoid re-analyzing key_findings). It also states the prerequisite for `cost` (`window="run"` requires a run-start marker). It stops short of saying when to prefer sibling tools like `deep_read` or `scan_topic` over a registry read.

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?

With no annotations, the description carries the full burden and discloses the key behavioral traits: all writes go to staging and the formal registry is untouched until kind='commit'; commit can be previewed and rolled back; duplicate writes with changed grades append conflicts; protocol writes preserve user-modified copies as protocol.md.new; insight writes are scanned and rejected on injection signals; and records are normalized before persistence. These are meaningful behaviors beyond anything in the schema.

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 definition is front-loaded with purpose and the critical staging/commit gate, then uses kind-based bullets so an agent can scan to the relevant mode. It is long, but the length is largely justified by ten distinct record kinds and two cross-cutting warnings; a few rhetorical or emphatic phrases could be trimmed without losing information.

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

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

Given the tool's complexity, ten modes, absent schema descriptions, and no annotations, the description is complete enough to call correctly: it covers staging semantics, commit/discard lifecycle, run-start bookkeeping, per-kind payloads, normalization behavior, injection handling, and readback paths. An output schema exists, so the description reasonably does not need to enumerate return values in detail.

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

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

Schema description coverage is 0% and the schema exposes only kind, topic, and records, so the description must compensate, and it does: it defines all ten kind values and gives the expected record shape for source, video, insight, topic, protocol, cluster, rejected, commit, discard, and run-start records. It also clarifies when topic is required, that records are not needed for run-start, and that malformed topics/domains/key_findings will error rather than be silently written.

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, '写资产库', and enumerates ten record kinds, so the agent knows this is the write/upsert path for the registry. It refers to the readback sibling registry_get and to scan_topic, but never gives a single explicit contrast sentence such as 'use registry_get to read; use this to write staging records', leaving sibling differentiation partly implied.

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?

Usage conditions are unusually explicit: call at the end of every task, call kind='run-start' once at phase 0 end, call kind='commit' once at wrap-up in the fixed commit → paste final_cost → render order, and use kind='discard' to throw away staging. It also states that rejected candidates must be recorded through this tool and names registry_get(kind='rejected')/scan_topic(exclude_bvids=...) as the downstream read/use path, so alternatives and timing are clear.

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?

With no annotations, the description carries the full burden and does so thoroughly: it discloses the returned buckets (candidates, digest, images, coverage, degraded/ok/cost), that degradation signals are surfaced, that a sample-bias declaration is included, that digest images are low-resolution 160px thumbnails unfit for reading numbers, and how ranking changes when families are supplied. Defaults come with rationale (e.g. 12 comment budget, 15 comments per candidate).

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?

Front-loaded with the one-line purpose and call-replacement claim, then organized into return-value, parameter, offset, exclusion and ranking sections. It is long and occasionally restates what the output schema already defines, plus it leans on internal jargon (批次 D2/D3) — but for a 14-parameter orchestration tool nearly every line carries decision-relevant information.

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

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

Covers the full lifecycle an agent needs: what the call does, how to tune cost versus coverage, how to paginate via coverage.next_offset and rest_preview, how to avoid re-scanning already-analyzed videos, and how the ranking differs with and without families. Even though an output schema exists, the extra explanation of degraded/cost/coverage makes the tool safe to invoke blind.

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% across 14 parameters, so the description must compensate, and it does: it explains keywords (4–6, five semantic categories), per_query, comment_budget, comment_n, image_policy with its three values, image_top, families with its structure and consequence (kw_families returns null if omitted), pages_per_keyword, min_play, published_after format, offset, exclude_topic and exclude_bvids. Only max_candidates goes unmentioned.

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?

States a specific composite action — multi-keyword search → dedupe → rank → pull comments for top candidates — and explicitly positions itself as the single entry point for broad Phase-1 scanning, replacing N searches + M metadata + M comment calls. This clearly separates it from siblings like search_videos, get_metadata and get_comments, which are single-step operations.

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?

Gives rich usage guidance: when to use offset (recall/return gap), when to use exclude_topic (second round on the same topic, stackable with exclude_bvids), and when a filter narrows vs. widens the pool. It does not name sibling tools or a Phase-2 counterpart as explicit alternatives, so the routing information is implied rather than stated.

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?

With no annotations, the description carries the burden and does well: it discloses the detection method (pure keyword matching), the known false-positive mode and a fixed example, the degraded flag, and the return shape. It omits anything about size limits, cost, or performance for large batches, which is the remaining gap for a batch tool.

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?

Front-loaded with the action and the trust-boundary rationale before the motivation section. Some redundancy in restating that other channels sanitize, and the prose is longer than needed, but every block contributes actionable context rather than 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?

An output schema exists, yet the description still explains the result fields and their caveats, which is helpful for interpreting flagged results. For a one-parameter read-only scanner the coverage is nearly complete; only batch sizing and the meaning of the risk field's scale are unspecified.

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

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

Schema coverage is 0% for the single 'texts' array parameter, so the schema adds nothing. The description only indirectly conveys batch semantics via the return shape ({n, flagged:[{index, ...}]}), showing each input is scanned independently with per-item indices. It never states format, limits, or how previews are truncated.

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?

States a specific verb+resource: scan arbitrary external text for injection. It explicitly contrasts itself with the fetch-time sanitization done by get_comments, so an agent can tell which channel handles which text without opening the schema.

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?

Enumerates concrete trigger scenarios (text from upstream bilibili-mcp, user-pasted pages/excerpts, self-copied passages) and explains that these bypass get_comments sanitization, so they will not be flagged otherwise. It also sets an interpretation boundary: a hit is a 'look again' hint, not evidence, and false positives are real (with a dated example).

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?

No annotations, so the description carries the load, and it adds real operational context: one-keyword restriction, the observed limit cap of 50, and the warning that numResults is a fixed ceiling of 1000 rather than a true total. It does not mention pagination behavior or how page interacts with limit, which is the remaining gap.

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?

Short, front-loaded, and each line carries a distinct instruction (what it returns, when to use, caps, what not to do). The numResults note is slightly opaque out of context and could be tightened.

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?

An output schema exists so return values need not be described; the description still adds the useful ceiling caveat. Coverage is nearly complete for a 3-parameter search tool, with only page semantics 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 0%, so the description must compensate. It explains keyword (single keyword only) and limit (hard cap 50), but the page parameter is entirely undocumented in both schema and description.

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?

States a specific verb and resource (search videos with exactly one keyword) and immediately scopes the return payload as full metadata that needs no follow-up calls. It also distinguishes itself from siblings get_metadata/scan_topic by naming the alternative explicitly.

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?

Gives explicit when-to-use cases (probe an unfamiliar word family's coverage, or supplement after scan_topic) and explicit when-not-to-use (don't loop-call this for broad scanning; use scan_topic). Nothing is left to inference.

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?

With no annotations, the description carries the full load: it discloses the backend must be user-supplied, the two setup paths, and that a missing backend yields status="no_backend" with install guidance rather than a silent failure. It also states the return structure matches get_transcript with data_source="asr" and that ASR output inherits the same verification caveats — leaving only minor gaps like latency/cost of a 3 GB model download beyond what's implied.

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?

Front-loaded with a bold one-line summary, then headed sections with bullets — good structure for a complex tool. The narrative about page previously being a no-op is somewhat verbose, though it does justify trusting the parameter now.

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?

An output schema exists, so return values needn't be spelled out, and the description still links its output to get_transcript compatibly. Coverage of failure modes, backend prerequisites, login preconditions, and per-part caching is sufficient for an agent to invoke this correctly and interpret failures.

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

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

Schema coverage is 0%, so the description must compensate. It does an excellent job on 'page' (multi-P selection, per-part audio caching so P2 doesn't silently reuse P1) but never explains 'bvid' at all. Half the parameters are documented, half are not.

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?

States the operation precisely (download audio track → local ASR transcription) and positions it explicitly as the third path relative to get_transcript. An agent can distinguish this tool from get_transcript and grab_frames without opening either schema.

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?

Gives explicit trigger conditions: get_transcript returns transcript: null, or the subtitle is ai_subtitle with unacceptable error rates. Also adds a necessary precondition (must be logged in, otherwise the subtitle list is falsely empty) which prevents a whole class of misdiagnosis.

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