komga_series

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

Annotations already declare destructiveHint=true and readOnlyHint=false, yet the description adds substantial context beyond them: the auth mechanism (X-API-Key or basic auth env vars), the self-hosted-only constraint, the double gate for writes, the no-op dry-run preview, and an explicit list of actions that trigger extra warnings. This is exactly the extra behavioral detail the annotations cannot convey.

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?

Dense but front-loaded: auth and write-safety come before the action enumeration, which suits a 16-operation dispatcher. There is minor redundancy ('in the preview and here') and the action list is long, but every clause carries operational 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?

With no output schema, the description compensates by explaining the `help` action as the discovery path for per-action parameters. It does not describe return shapes for read actions or pagination, which a dispatch tool of this breadth could note, but the core call-time requirements (auth, confirm gate, params/query/body) are all covered.

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 coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema cannot: `target` is only meaningful together with `action: help`, and `confirm` omission specifically means a preview that sends nothing. The mapping of `params`/`query`/`body` to path/query/body is left to the schema.

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 it is the series toolset covering 16 operations and enumerates every action, so an agent can tell it apart from komga_books/komga_collections by resource scope. The opening verb phrase ('covers the series toolset') is a bit abstract and never explicitly routes against named siblings, but the action list makes the resource domain 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?

It gives clear workflow guidance: use `action help` with `target` to discover an action's parameters, omit `confirm` for a dry-run, and set both `confirm: true` and KOMGA_ALLOW_WRITES=true to execute. It also flags which action families are destructive. It stops short of saying when to prefer a sibling tool (e.g. komga_books for book-level queries).

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