komga_collections

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

Since no annotations are present, the description carries the full transparency burden. It discloses that create_collection, delete_collection, and update_collection require ADMIN, and it specifies that arguments must match the operation's parameters. However, it does not cover side effects (e.g., cascading deletes), error handling, or read-operation specifics beyond what is inherent in the operation names.

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 compact, well-organized bullet list that front-loads the overall purpose and then presents each operation's signature and any permission requirements in a single line. No redundant text or filler.

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 complexity of six operations with varying parameters, the description provides complete signatures for all, along with permission flags. It covers all documented operations and their parameters, making it sufficient for an agent to invoke the tool correctly. The output schema likely handles return values, so no extra explanation is needed.

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?

The input schema only defines operation and arguments, while the description provides detailed parameter lists for each operation, including defaults (e.g., page=0, size=50) and optional filters for get_collection_series and list_collections. This adds significant semantic meaning beyond the sparse schema, which has 0% coverage.

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 covers 'komga collections operations' and enumerates six specific operations (create, delete, get, list, update) with concise descriptions for each, distinguishing it from sibling tools focused on other Komga entities like series or books. The verb+resource pattern is explicit and unambiguous.

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 implies usage for collection-related tasks but does not explicitly contrast with sibling tools. It does note ADMIN requirements for mutating operations (create, delete, update), which guides when to use which operation, but lacks direct alternative tool guidance like 'use komga_series for series operations.'

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