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

Goes well beyond the annotations by disclosing the auth mechanism (X-API-Key or basic auth), the self-hosted-only constraint, the KOMGA_ALLOW_WRITES gate, and the dry-run preview behavior. It also enumerates which actions carry extra destructive warnings (delete, scan, user/role, API key, password, settings, session, claim), which a preview alone would not surface in advance.

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?

Front-loads auth and write-safety before the action list, and each sentence carries useful information. The trailing action enumeration is somewhat long and partially duplicates the enum, but it aids scanning.

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?

For a 16-operation dispatcher with no output schema, the description covers auth, write gating, dry-run semantics, and destructive-action warnings well. It could say more about return shapes or how body/query/params map per action, but the essential calling information is present.

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 parameter descriptions are already solid, but the description adds operational meaning: confirm must be the boolean true (false and string 'true' rejected) and omitting it triggers a preview that sends nothing, plus how target pairs with action help. That workflow context is not fully conveyed by the schema alone.

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?

States it covers the Komga books toolset (16 operations) and enumerates the available actions, so the verb+resource is clear. It does not explicitly say how it differs from siblings like komga_series or komga_readlists (which even appears as an action here), leaving some ambiguity to be inferred from the name.

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?

Gives concrete procedural guidance: use action help with target to inspect a single action, set confirm to execute a write, omit it for a dry-run. It does not name when to pick this tool over a sibling, but the operational context is clear and actionable.

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

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

Annotations already declare destructive/openWorld/non-idempotent, but the description adds real context beyond them: the confirm-gate mechanics, dry-run default behavior, the explicit list of high-risk action categories that trigger extra warnings, secret redaction in output, and the self-hosted-only constraint. The only blemish is the '5 operations' count against six enum values, a minor inconsistency rather than a contradiction.

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 efficient — five sentences covering auth, write gating, dry-run, and the destructive list, with no filler. Front-loading is weak: it opens with a vague toolset statement rather than the write-safety rule, and the long warning enumeration is a comma run-on.

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?

For a 6-parameter destructive dispatcher with no output schema, the description covers the safety model well but leaves the action semantics unexplained — an agent cannot tell from the text what delete destroys (a collection? its entries?), how get differs from get_id, or what patch/post expect in body. Delegating detail to 'action help' mitigates but does not close the gap.

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 100%, so the schema already explains body, query, params, target, and confirm (including the rejection of false and the string 'true'). The description repeats the confirm rule but adds nothing about body/query/params structure or what path parameters like seriesId the collections endpoints expect. Baseline 3 applies.

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 names the resource (collections) and enumerates the actions (delete, get, get_id, patch, post) plus help, which lets an agent place it against siblings like komga_books or komga_series. But the opening 'covers the collections toolset (5 operations)' restates the name and miscounts (six enum values including help), and it never says what a collection is or what get vs get_id does. Purpose is inferable, not stated.

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?

Strong operational guidance: it names the auth mechanism, states writes require confirm=true plus KOMGA_ALLOW_WRITES=true, explains that omitting confirm yields a no-op dry-run, and points to 'action help with target' for per-action parameters. What's missing is routing guidance against siblings, though the resource name largely carries that.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds substantial context on top: the auth mechanism (X-API-Key or basic auth), the KOMGA_ALLOW_WRITES gate, the confirm=true requirement, and that omitting confirm yields a dry-run that 'sends nothing.' It further enumerates which actions trigger extra warnings (delete, scan, trash empty, API key revoke, password change), which is precisely the behavioral detail an agent needs before a destructive call.

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?

Front-loaded with purpose, then auth, then write-safety, which is the right priority order. It is dense but nearly every sentence carries non-obvious information; the only waste is the destructive-action list partially duplicating the action enumeration that follows it.

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?

For a six-parameter, nested-object, multi-action mega-tool with no output schema, the description covers auth, write gating, dry-run behavior, destructive-action warnings, and secret redaction. What remains thin is per-action semantics for the generic verbs, though the documented 'help' action provides a discovery path for that.

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 100%, so body, query, params, action, target and confirm are already documented, including the const:true constraint on confirm. The description's only added meaning is the help/target discovery workflow and the dry-run consequence of omitting confirm, both of which the schema largely restates; baseline 3 applies.

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 names the resource ('libraries toolset') and enumerates all ten actions, so an agent knows exactly what surface it covers. It stops short of explaining what the generic verbs (delete, get, patch, post) operate on, and never contrasts itself with siblings like komga_series or komga_books, relying on the resource name alone to differentiate.

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?

Strong operational guidance: 'action help with target returns one action's parameters' tells the agent how to self-discover per-action schemas, and 'Self-hosted Komga only' sets a clear applicability constraint. It does not state when to choose this toolset over a sibling (e.g. libraries vs. series), so the routing decision is left implicit.

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

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

The annotations already disclose readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds meaningful context about authentication (API key or basic auth) and the self-hosted-only constraint, but it does not describe the return behavior or scope of get_actuator_info beyond the action name.

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 compact and mostly front-loaded: it identifies the toolset, then auth, self-hosted constraint, help behavior, and available actions. Minor awkwardness like '(1 operations)' is present, but the structure is efficient and every sentence contributes context.

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?

For a dispatcher with one real action, the description covers auth, self-hosted scope, help usage, and the action list. It still omits what get_actuator_info actually does or returns, and there is no output schema to compensate, so an agent must infer the operation's behavior from the name 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?

Schema description coverage is 100%, so the schema already documents action, target, body, query, and params. The description reiterates the help/target behavior already documented in the target schema field and adds no further parameter semantics; with full schema coverage, a baseline 3 is appropriate.

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 names the tool as a management toolset with one operation and lists the action 'get_actuator_info', which gives an agent a concrete operation to select. However, it never explains what 'management' or 'actuator info' means, so the purpose remains vague beyond the action name and does not clearly distinguish it from resource-oriented siblings like komga_series or komga_libraries.

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 states this is for self-hosted Komga only and explains authentication, which is useful context. It also mentions 'action help with target' for discovering parameters, but it does not say when to choose this tool over the sibling komga_* tools or when this tool is inappropriate.

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

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

With destructiveHint=true and readOnlyHint=false already declared, the description still adds real value: auth mechanism (X-API-Key or basic auth env vars), the confirm/dry-run contract, that writes require KOMGA_ALLOW_WRITES=true, that secrets are redacted in output, and that destructive/credential actions get an extra preview warning. This is well beyond what annotations 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?

The auth and write-safety rules are front-loaded, which is good, but the middle sentences are dense and the destructive-action enumeration lists operations (scan, analyze, trash empty, settings, session, claim) that are not in this tool's action enum, which reads as boilerplate and can mislead. The action list is tacked on at the end.

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?

For a destructive 6-parameter dispatcher with nested body/query/params objects and no output schema, the description covers auth, the write gate, dry-run behavior, and discovery via help — enough for an agent to call it safely. What remains thin is per-action semantics, but the help action is offered as the escape hatch for that.

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 100% and the confirm and target fields are documented in the schema itself, so the description's restatement of confirm semantics adds little. It does clarify the help+target pairing and note that body secrets are redacted, but the mapping of query/params fields to specific actions is not explained beyond pointing at the help action.

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 identifies the resource ('readlists toolset') and enumerates the actions (delete, get, get_id, patch, post), so an agent knows it dispatches Komga readlist operations. However, the opening sentence largely restates the tool name and never says what a readlist actually is or how these operations differ meaningfully from komga_collections or komga_books.

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 concrete procedural guidance: use action help with target to discover an action's parameters, writes require confirm:true plus KOMGA_ALLOW_WRITES, and omitting confirm yields a dry-run. What it does not do is say when to choose this tool over its siblings; the routing decision to komga_readlists vs komga_collections is left entirely to the reader.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the auth mechanism (X-API-Key header or basic auth via KOMGA_USERNAME/KOMGA_PASSWORD) and the self-hosted-only deployment constraint, both of which affect whether a call can succeed at all.

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?

Front-loaded with scope, then auth, then the action inventory — a sensible order with no filler. The action enumeration partially duplicates the schema enum, but on a dispatcher tool it doubles as a routing summary, so it earns most of its space.

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?

For a 13-operation read-only dispatcher with no output schema, the description covers auth, deployment scope, the action inventory, and the self-documenting 'help + target' path to per-action parameters. It stops short of noting whether results are paginated or what shape the metadata lists take, which is a minor residual gap.

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 100%, so body, query, params, action, and target are all documented in the schema itself. The description only restates the help/target mechanism and adds no routing detail about which actions accept query vs. path parameters, so baseline 3 applies.

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?

States the tool covers the 'referential_metadata' toolset and enumerates all 13 actions, which are self-descriptive (get_genres, get_publishers, get_sharing_labels). An agent can tell this is the lookup/enumeration namespace rather than the book/series/library tools, though the description never explicitly contrasts with the sibling tools.

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?

Usage is implied by the action list plus the 'Self-hosted Komga only' constraint and the 'action help with target' escape hatch, but there is no explicit guidance on when to pick this over komga_series or komga_books, and no stated preconditions beyond auth.

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

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.