Server Quality Checklist

Tool Scores

• komga_referential_metadataB
  3.2/5.0
  Behavior3/5

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

  The annotation readOnlyHint=true is provided, and the description makes clear these are list operations, which aligns. The description adds value by listing the specific operations, which are all read-only queries, but it does not go beyond the annotation in disclosing behavioral traits like pagination defaults or potential performance considerations. No contradiction.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is well-structured with a clear introductory sentence followed by a bullet-like list of operations. It is efficient in that each line is concise and informative. The list format is easy to scan, and the description is front-loaded with the core instruction. Slight redundancy in repeating common parameters is acceptable for clarity.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the high complexity of this tool (ten operations with many parameters), the description provides reasonable coverage by listing each operation and its parameters. However, it lacks details on response structure (though an output schema exists), filtering behavior, or edge cases. The absence of usage guidelines and limited parameter semantics makes it less complete for a tool with such a broad scope.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters2/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema has a low description coverage of 0% (the 'arguments' property is a generic object with additionalProperties true), so the description carries the full burden of explaining parameters. The description lists the parameters for each operation, which is helpful, but it provides minimal semantics beyond parameter names and a brief purpose. For example, it does not explain what 'search' filters against or how 'sort' works, leaving gaps in understanding.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states that this tool performs list operations on distinct metadata values like age ratings, authors, genres, etc. It enumerates each operation with a one-line summary, making the purpose clear. However, it does not distinguish itself from sibling tools beyond listing metadata-specific operations, which is inferred from the operation names.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description implies usage by saying to pass an `operation` and an `arguments` dict, and it lists each operation with its parameters. It does not explicitly state when to use this tool versus sibling tools, but the metadata-specific nature is implied. No exclusions or alternatives are mentioned.

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

• komga_readlistsA
  3.8/5.0
  Behavior4/5

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

  Since no annotations are provided, the description carries the transparency burden. It explicitly flags ADMIN requirements for create_readlist, delete_readlist, and update_readlist, which is valuable beyond the schema. However, it does not describe side-effect behavior in detail or confirm read/list operations as safe.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is well structured as an intro line plus compact operation bullets. It front-loads the key dispatch rule and each operation earns its place with a short actionable summary.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  All eight operations and their ADMIN requirements are covered, which is helpful for a generic dispatcher schema. Yet the argument semantics are not fully complete: create_readlist and update_readlist rely on underspecified objects, and filter parameter values are not defined well enough for reliable invocation.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 0%, so the description is the main source of parameter meaning. It provides full signature lines including defaults, pagination, and filter parameters for get_readlist_books and list_readlists. It stops short of defining the structure of the readlist object and patch argument, which would materially improve confidence in creating or updating readlists.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly identifies this as the readlists area of Komga and enumerates eight distinct operations with one-line purposes. It distinguishes the tool at the resource level from sibling Komga tools, though the opening phrase is somewhat generic and leans on the operation list for specificity.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The operation list makes it clear what the tool can do, but the description does not explicitly state when to use this tool instead of a sibling such as komga_collections or komga_books. Usage context is implied rather than directly prescribed.

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

• komga_librariesA
  4/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines3/5

  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.

• komga_users_api_keysA
  4.1/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the transparency burden. It discloses important behavior such as which operations require ADMIN, which affect the current user vs other users, and which create or revoke credentials. It does not explain error behavior or reversibility, but state-changing verbs plus permission notes cover the main operational traits.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  A brief dispatcher instruction is followed by a well-organized bullet list with one-line explanations for each operation. Every line conveys a parameter signature, a concise behavioral description, and permission context, with no fluff or repetition.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The tool has 12 operations, a mostly untyped arguments schema, and no annotations, so the description needs to do heavy lifting. It covers operation names, parameters, and admin requirements, but it falls short of fully specifying payload structures for create_user, update_user, and create_api_key.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The description adds significant value over the free-form arguments schema by listing per-operation parameter signatures and pagination defaults. However, opaque parameters such as user, request, and patch lack shape or required-field documentation, so agents still must infer important parts of the argument payload.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description lists concrete operations such as change_my_password, create_user, delete_user, list_users, and whoami, making the dispatcher's purpose unmistakable. The users/auth/API-key scope clearly distinguishes it from sibling Komga tools like komga_series, komga_libraries, and komga_books.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The scope is obviously Komga user, API-key, and authentication activity management, and every operation is documented. It does not explicitly provide when-not-to-use statements or sibling alternatives, but the domain context is strong enough to route relevant requests here.

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

• komga_collectionsA
  4.4/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters5/5

  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.

  Purpose5/5

  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.

  Usage Guidelines3/5

  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.

• komga_seriesA
  4.4/5.0
  Behavior4/5

  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.

  Conciseness4/5

  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.

  Completeness4/5

  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.

  Parameters5/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• komga_serverA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the burden of behavioral disclosure. It does this well by noting ADMIN requirements for most operations, flagging clear_server_tasks as canceling queued tasks and returning the number removed, and marking update_server_settings as an update. It does not cover error behavior or return shapes for every operation, but the core side effects and permissions are disclosed.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is well-structured: a one-sentence dispatcher explanation followed by compact bullet entries. No word is wasted, and the format makes it easy for an agent to scan operations, parameters, and permission requirements.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool aggregates seven distinct server operations with generic schema coverage, the description covers each operation, its parameters, and admin requirements. It does not explain output schemas, but an output schema exists, reducing that burden. Minor gaps like the exact structure of 'patch' prevent a perfect score.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema only exposes a generic operation enum and an opaque 'arguments' object, so the description's per-operation signatures add substantial meaning. It lists parameters with defaults (page=0, size=50, unpaged=False, show_files=False) and gives enough context for most arguments; the main gap is that 'patch' is not structurally defined, but the operation name and general 'patch' convention help.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly defines the tool as a dispatcher for Komga server operations and enumerates seven specific operations with precise verbs (clear, get, list, update). Each bullet names a distinct server-level action, which differentiates this tool from sibling tools focused on libraries, series, books, collections, etc.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The opening instruction 'Pass operation and an arguments dict matching that operation's parameters' gives concrete invocation guidance. The server-scoped title and operation list make the intended domain clear versus sibling tools, though it does not explicitly state when not to use this tool or name specific alternatives.

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

• komga_booksA
  4.8/5.0
  Behavior5/5

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

  With no annotations, the description carries full responsibility for disclosing behaviors. It explicitly notes permissions (ADMIN for some ops), side-effect semantics for updates ('null unsets a field'), and non-downloading behaviors for page/thumbnail listing. It also explains the arguments structure and search syntax, covering edge cases like nullable arguments.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is front-loaded with the general invocation pattern, then presents a well-organized bullet list of operations with minimal but sufficient detail. Each line is concise and information-dense, avoiding redundancy while covering 16 distinct operations.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool's complexity (16 operations, varied parameters, permissions, rich search conditions), the description is exceptionally complete. It details permissions, null handling, and search operator semantics. Since an output schema exists, lack of return-value descriptions is acceptable.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema only defines `operation` (enum) and a generic `arguments` object with 0% coverage. The description fully compensates by enumerating every operation's parameters, defaults, and types (e.g., 'page=0, size=50'). This is essential for correct tool use and is provided comprehensively.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states it performs 'komga books operations on Komga' and lists all 16 supported operations with specific verbs and targets (e.g., 'get_book_next', 'search_books'). It distinguishes from sibling tools by focusing exclusively on books, and the operation list makes the tool's scope unambiguous.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description provides clear guidance on how to invoke the tool (pass operation + arguments dict) and details each operation's parameters and required permissions (e.g., 'Requires ADMIN'). However, it does not explicitly mention when not to use this tool or contrast with sibling tools, though the separation is obvious from naming.

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