komga_series

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It notes that analyze_series and refresh_series_metadata require ADMIN, that list_series_thumbnails does not download image bytes, and that update_series_metadata has null/omission semantics. It also describes the search condition structure in detail, which is complex. Minor gap: it does not state side effects of mark_series_read/unread or that update_series_metadata is a mutation, but the verbs imply it.

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 structured as a bulleted list of operations, which is scannable. However, it is quite long, especially the search condition repeated twice for two operations, adding verbosity. It could be trimmed by referencing the condition once, but overall structure is good and front-loaded with the operation list.

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 tool's complexity (13 operations, many with complex parameters), the description is thorough. It covers return types implicitly (e.g., 'list', 'get details'), and with an output schema present, it doesn't need to detail return formats. It provides enough context for an agent to select and invoke operations correctly, but some operations lack side-effect details (e.g., mark_series_read) which would enhance completeness.

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 schema has 0% coverage (only two generic params: operation and arguments), so the description must compensate by documenting each operation's parameters. It does this effectively by listing exact function signatures with parameter names and defaults, and for search operations, it explains the condition structure in detail (supported fields, operators, enums). This is far beyond the schema's capability.

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 provides a clear list of all operations with specific verbs (e.g., 'analyze_series', 'get_latest_series', 'search_series') and explicit resource scope (all on Komga series). It distinguishes between similar operations like 'get_latest_series', 'get_new_series', and 'get_updated_series' by their exact definitions.

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 explains when to use each operation, e.g., 'List recently added or updated series' vs 'List newly added series' vs 'List series that were updated but are not newly added'. It also notes admin requirements for some operations, providing clear context. However, it does not explicitly mention when not to use this tool compared to siblings, but the sibling scope is obvious.

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