bookshelf_queue

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

The description explicitly warns 'DESTRUCTIVE: this deletes data' for the delete operations, which is valuable since no annotations are present. However, other operations such as grab_queue_bulk and grab_queue_item are likely to mutate queue state but are not flagged, and no permissions, side effects, or rate-limit behavior are disclosed.

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 a front-loaded, well-structured bullet list with a clear usage line followed by seven compact operation entries. Each line is purposeful, contains no filler, and the format makes it easy for an agent to scan and match operations.

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 the high complexity of seven distinct sub-operations and the absence of annotations, the description provides a comprehensive map of operations, parameters, and destructive warnings. An output schema exists, so return-value explanations are not required; the main remaining gap is behavioral depth for non-destructive mutations, but overall the description is sufficiently complete.

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% and the schema only exposes operation and a generic arguments dict, so the description carries the parameter documentation burden. It compensates well by listing each operation's function signature, parameter names, defaults, and query parameters (e.g., removeFromClient, pageSize, includeUnknownAuthorItems), which is essential for invocation. It still lacks detailed explanations for ambiguous parameters like blocklist or change_category.

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 opens with 'bookshelf queue operations on Bookshelf' and then enumerates seven specific operations with action verbs ('Bulk delete queue', 'Grab multiple queue items', 'List queue'), making the domain and scope clear. It distinguishes itself from sibling tools by focusing specifically on the queue resource, though the opening sentence is somewhat generic.

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?

No explicit when-to-use guidance or alternatives are provided; the only usage instruction is to pass an operation and a matching arguments dict. The description lists operations but does not tell an agent when queue operations should be chosen over other Bookshelf tools or when one sub-operation is preferable to another.

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