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

readOnlyHint=true already establishes that this is a safe read, and the description adds genuinely useful behavior beyond that: results are grouped by episode, speech matches carry the exact second (exact_sec derived from word timings), and the index only covers episodes that were analysed or transcribed. It does not mention ranking, pagination, or empty-result behavior, which leaves a modest 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?

The core purpose, return shape, and coverage prerequisites are front-loaded in the first three sentences, and the per-argument block is easy to scan. The Arabic restatement of the opening sentence is duplicated content for most agents and adds length without adding routing 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 three params, an existing output schema, and a read-only annotation, the definition covers what is searched, which corpora are indexed, what the matches look like, and every argument. The only substantive omission is not distinguishing this tool from search_videos, which matters in a fourteen-tool sibling set.

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 the description fully compensates: query is described as a name, topic, or phrase in Arabic or English; kind enumerates all ten accepted values with glosses (people = guests + mentions, transcript_en = English translation); limit's default of 40 is restated. This is exactly the information the empty schema lacks.

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 with scope: searching *inside* analysed episodes for appearances, topics, speech and on-screen content. This distinguishes it in substance from the sibling search_videos, but it never names or contrasts that sibling explicitly, so the boundary is implied rather than declared.

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 line 'Covers episodes saved with save_video_analysis or transcribed with listen_to_video / transcribe_audio' effectively tells the agent when this tool will return results, which is real contextual guidance. However, it offers no when-not condition and never routes the agent to an alternative such as search_videos, so the choice among siblings 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.