Locate

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.