komga_libraries

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

There are no annotations, so the description bears the burden of providing behavioral context. It does well: 'Delete a library without deleting its files', 'Permanently empty a library's trash', and 'Scan a library for new or changed files' disclose side effects and permissions. It lacks some detail about update/analyze behaviors, but the central safety-relevant behaviors are included.

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 efficiently structured: a short usage instruction followed by a bulleted list of operations. Every line conveys a distinct purpose and permission note, with no redundant filler. The front-loaded dispatch instruction helps an agent quickly understand how to call the tool.

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?

The description fully lists all operations, their required roles, and the main effects, which is strong for a dispatcher with nine operations. The output schema provides return-value coverage. However, the incomplete shape of the argument dictionaries for `create_library` and `update_library` means an agent could not fully construct a correct call from description alone.

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?

With 0% schema coverage, the description needs to compensate. It provides function signatures like `scan_library(library_id, deep=False)` and names `library`, `library_id`, and `patch`, which is helpful. Yet it never explains the structure of the `library` object, the contents of `patch`, or the meaning of `deep`, so the actual argument semantics remain under-specified.

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 enumerates nine specific library operations with explicit verbs and resources, such as 'analyze_library', 'delete_library', and 'update_library'. Each line states the exact action, so the tool's purpose as a dispatcher for Komga library operations is unmistakable and distinct from sibling tools focused on other resources.

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 operation list and general 'Komga libraries operations' phrasing imply when the tool should be used, and the ADMIN requirements help agents avoid unprivileged calls. However, it does not explicitly mention the alternative sibling tools or state when to prefer this tool over them, so usage guidance is implied rather than precise.

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