Semantic search

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description's job is reduced. It adds transparency about the prerequisite (index built by calibre_build_index), the hybrid fusion behavior, and the domain-specific behavior of target=figures. A minor gap: it doesn't mention that include_excluded is supported or what the output format looks like beyond noting where to get figure pixels. Despite this, it provides meaningful behavioral context beyond annotations, earning a 4.

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 packed with information in a tight, efficient structure, starting with the core purpose and then systematically covering scopes, modes, prerequisites. It uses semicolons effectively. However, it could benefit from bullet points or clearer separation between concepts (e.g., scope vs mode vs target), as the current wall of text may be dense for an agent to parse quickly. Still, no fluff earns a 4.

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 high complexity (9 parameters, 3 enums, 3 modes, 2 scopes, 2 targets), the description covers most critical behaviors: modes, scope filtering, figure search, filter bundle. An output schema exists, so return values don't need documentation. Missing details: no mention of topK or include_excluded behavior, and no explanation of how hybrid fusion works. For a high-complexity tool with rich annotations and output schema, this is nearly complete, but small gaps keep it from a 5.

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 carries the full burden. It adds semantics for 5 of 9 parameters (mode, scope, target, filter, bookId) but lacks descriptions for topK, library, include_excluded. The description compensates well for a complex tool, but omits the optional filtering and result count parameters. With 9 params and 0% coverage, a 4 is appropriate for substantial added value, though some gaps remain.

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 it performs 'meaning-based search over the local index' and distinguishes itself from siblings by detailing three scopes (library, book, book with target=figures) and three modes (hybrid, vector, keyword). It explicitly explains when target=figures should be used, setting it apart from text-based searches. This is specific and actionable for an agent.

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 explicit when-to-use guidance: for figure searches, it says 'use when the user asks for a diagram/chart/schema', and for each mode it describes the appropriate use case (e.g., mode=keyword for exact/FTS). It also instructs to use calibre_get_figures for image pixels and calibre_build_index as a prerequisite. This comprehensive guidance with alternatives is a 5.

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