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

Annotations only declare readOnlyHint and openWorldHint, so the description carries the rest: text-only by default, includeFrame costs roughly 1,900 vision tokens for one image, transcript precedence (subtitles > transcriptFile > ASR via MMGREP_ASR_PROVIDER), graceful failure rather than guessing, and the caveat that ASR-sourced matches may misquote names and numbers. The only missing piece is a fuller account of the per-match record fields.

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 purpose and return format, then usage, cost, and prerequisites in short paragraph blocks. It runs longer than most definitions, but nearly every sentence carries decision-relevant information (token cost, transcript requirement, ASR caveat); the bilingual restatements add length without adding much for an English-reading agent.

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 tool with no output schema, the description covers the critical unknowns: what is returned (position units, source tag), what it costs, what prerequisites must hold, and how failure is surfaced. It stops short of enumerating all result fields (snippet text, match metadata), leaving some return-shape uncertainty.

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 baseline is 3; the description adds genuine meaning on top — matching ignores punctuation, spacing and case, works in Chinese and English, and long phrases match better than single characters — which the schema's query field does not say. It also ties the transcript/transcriptFile parameters to the ASR fallback logic.

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 — find where a given text appears in a local media file — and specifies the return shape (timestamp in ms/seconds for video/audio, page number for documents). It also names the sibling it is not (media_overview for visuals only), so an agent can choose without opening 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 use case ("you know roughly what was said but not when") plus an explicit alternative ("Use media_overview if you only need the visuals"). It also warns when the tool cannot work (no transcript available), which is a real when-not condition.

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 only declare readOnlyHint and closed-world, and the description is fully consistent while adding substantial behavior: a four-step text-source precedence order, per-segment source tags, a strong warning not to quote ASR verbatim, and the fact that full text is written to disk (content.md, segments.jsonl, manifest.json) rather than inlined. It also discloses the key failure mode — storyboard cells are too small to read — that annotations cannot express.

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?

Structure is strong — scoping sentence, per-media output list, source-precedence block, then caveats and return-value paths — and the most important warnings are front-loaded or visually separated. It is nonetheless verbose (bilingual restatement plus some overlap between the output list and the file-path paragraph) where a tighter version would lose nothing.

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?

Eleven parameters with no output schema make this a complex tool, and the description covers what an agent needs: what is produced per media type, that text lives at returned disk paths and should be read section by section, how to page through long media, and the quoting caveat for ASR. Nothing material is left for the agent to guess.

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 schema already carries parameter mechanics and the baseline would be 3. The description still adds motive that guides parameter choice: why windows must be used (illegible cells, spoilers), that start/end are video/audio-only while documents use pages, and the subtitle-vs-ASR consequence of transcript="auto" vs "off" via the source order. It stops short of adding format specifics beyond what the schema states.

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?

Opening sentence names a specific verb and resource ("build an overview of a local media file") and immediately enumerates the three media types with the exact artifact produced for each. It also disambiguates the outputs from the sibling tools by naming media_zoom for reading text and media_probe for probing, so an agent can place this tool in the workflow without opening a 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?

Explicit sequencing and exclusions: "Always call media_probe first", "To read text on screen, call media_zoom on that moment", and long media "must be narrowed with start/end or pages". It also tells the agent to follow the continuation hint rather than re-requesting the same range, which is precisely the kind of when/when-not guidance that prevents bad calls.

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 only declare readOnlyHint and openWorldHint=false; the description adds substantial context beyond that: it costs no image tokens, decodes nothing, never downloads, never calls an LLM, and requires a local absolute path. It also discloses the silent-recording gate (silent audio is never sent to ASR, preventing hallucinated transcripts), which is behavior an agent could not predict from the 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?

Well front-loaded: purpose first, routing second, behavioral caveats last. Nearly every sentence earns its place, though the parenthetical Chinese restatement of the purpose line is pure duplication and the routing list is somewhat verbose.

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 carries the return-value burden and does so thoroughly: metadata fields, track list, ASR/OCR readiness, and the audio health check (average level, speech ratio, silence ratio). It also covers the operational constraints (local path only, no downloads, no LLM) that an agent needs 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 description coverage is 100%, so the schema already documents path, transcript enum, and transcriptFile. The description reinforces the local-absolute-path constraint and mentions the ASR judgment, but adds no syntax, default, or interaction detail for the transcript/transcriptFile parameters beyond what the schema states. Baseline 3 applies.

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 (inspect/probe) and resource (local media file) and enumerates the concrete outputs it reports: duration, resolution, page count, codec, tracks, ASR/OCR availability. It also names each sibling routing target (media_overview, media_zoom, media_locate), so an agent can distinguish it from all of them without opening a 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?

"Call this FIRST on any file you have not inspected yet" gives an unambiguous trigger condition, followed by explicit if/then routing to each sibling for video/audio, documents, specific moments, and 'where was X said' queries. Both when-to-use and which-alternative are stated, not inferred.

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?

Beyond the readOnly and closed-world annotations, the description discloses cost (~1,900 vision tokens), output nature (single image, source 'visual'), and an important interpretive limitation: reading pixels is an observation, not a transcript or quotation. It also explains that for video windows the sharpest frame is returned and the exact timestamp is reported back.

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 English portion is front-loaded, clearly structured, and every sentence carries useful guidance about purpose, routing, cost, and interpretive caveats. The main inefficiency is the full bilingual duplication, which roughly doubles the description size without adding new semantic content for an agent.

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 7-parameter tool with no output schema, the description is nearly complete: it explains the returned image, its visual source, the video/document modes, and the read-after-overview workflow. One gap is that the schema accepts audio paths and start/end for audio, while the description only frames the tool around video and documents.

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. The description still adds meaningful semantics beyond the schema: at versus start/end behavior, the sharpest-frame-inside-window rule, exact timestamp reporting, and crop as fractional coordinates with top-left origin.

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 and resource: get a close-up of one moment in a local video or one page of a local document, returned as a single image. It explicitly distinguishes itself from media_overview by saying the image is meant for reading, not just navigation, and by noting storyboard cells are too small to read.

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 routes the agent explicitly: use this after media_overview when one cell or page needs a closer look, with concrete questions like 'what exactly is on screen at 01:12?' and 'what does line 3 of page 7 say?'. It also warns to keep it to one frame and zoom only the parts that matter rather than re-scanning the whole file.

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 mark this read-only and closed-world, and the description adds real context beyond them: the three-tier source fallback, the guarantee that source and exact path are always reported and 'never silently' resolved, and the cost note that no images/pixels are spent. That is exactly the kind of disclosure an agent needs for a fallback-laden 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 core statement, then source order, then cost, then siblings — a clean information hierarchy. Slightly longer than necessary because of the mirrored Chinese parentheticals that duplicate the English content without adding 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?

With no output schema, the description picks up the slack by characterizing the return value (text with millisecond/second timestamps) and the metadata echoed back (source and exact path). Nothing an agent needs to invoke this correctly appears to be 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 schema carries the mechanical burden (start/end/pages/transcriptFile all documented). The description still adds semantic value by explaining that transcriptFile takes precedence over the embedded track and that format support is limited to .srt/.vtt/.ass/.ssa, though it says nothing about how pages interacts for document media.

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?

Opens with a specific verb+resource+output shape ('Read subtitles for a local media file and return them as timestamped segments'), which is unambiguous and clearly distinct from siblings like media_probe or media_overview. An agent knows exactly what it gets back.

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 routes the agent: use media_locate to search inside subtitles, use media_overview to also see on-screen content. It also defines the source resolution order (transcriptFile > embedded track > auto-discovered sibling), which is the key invocation decision.

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