search_books

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

With no annotations, the description carries the full burden of behavioral disclosure. It reveals the non-obvious per-folder search behavior (results gathered folder by folder, earlier folders can fill the limit, later folders contribute nothing) and the truncation indication. It also states that limit values outside 1-100 are refused, not clamped. These are critical behavioral traits that an agent must know.

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 concise and well-structured. It front-loads the primary purpose in the first sentence, then details folder behavior and limit constraints in a logical sequence. There is no redundant or filler content; every sentence adds actionable 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?

For a search tool with an output schema present, the description covers all necessary usage details: search scope, folder filtering, limit validation, and the truncation caveat. It does not need to explain return format since an output schema exists. The description is complete for an agent to call the tool 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 0%, so the description must compensate. It explains all three parameters: query (the search terms across listed fields), folder_id (omitted searches all folders), and limit (range 1-100, default 20, refused outside range). This adds substantial meaning beyond the raw schema, which only provides types and defaults.

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: 'Search titles, descriptions, series, contributors and tags.' It clearly distinguishes itself from sibling tools like list_books (which lists all books) and get_book (fetches a single book) by indicating it performs a search across multiple metadata fields. The folder-scoping behavior further clarifies its role.

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 clear context on how to use the tool: it explains the effect of omitting folder_id (searches every folder) and the limit behavior. While it does not explicitly mention alternatives or when not to use it, the purpose is unambiguous and the usage context is well-defined for a search tool, making the distinction from siblings implicit.

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