batch_search

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

No annotations are provided, so the description carries the full burden. It discloses that the search runs 'in parallel' and 'Returns aggregated results with file paths,' which gives some behavioral insight. However, it does not mention potential resource intensity from parallel workers, model download behavior, or whether files are modified (though 'search' implies read-only). It is not completely vague but lacks deeper behavioral context.

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 three sentences: the first states the core function, the second provides a use case, and the third describes the return value. There is no fluff or repetition. Every sentence earns its place, and the key information is front-loaded.

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 tool with 4 parameters, no output schema, and no annotations, the description gives the essential purpose, use case, and return format. It does not explain the aggregation format in detail or mention any constraints, but given the simplicity of the tool (search and return results), it is largely sufficient. The lack of output schema is partially mitigated by saying 'aggregated results with file paths.'

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. Each parameter (audio_paths, keywords, workers, model_size) already has a description in the schema, including the important note to 'ALWAYS use tiny unless...' for model_size. The description text itself adds no extra parameter meaning, but since the schema covers all parameters, score 3 is appropriate.

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 action: 'Search multiple audio files for keywords in parallel.' It identifies the resource (audio files), the operation (search), and the distinguishing feature (parallel, multiple files). This separates it from sibling tools like 'search_audio' which likely handles single files, and 'deep_search' which may imply a different scope.

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 provides strong usage context by mentioning 'Ideal for processing podcast libraries, interview collections, or any batch of audio files.' This implies when to use it (batch scenarios), but it does not explicitly mention when not to use it or name alternative tools (e.g., 'use search_audio for single files'). This is clear context without exclusions, fitting score 4.

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