nuvio-mcp

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

Beyond the annotations, the description discloses important behavior: the current list is preserved, dry_run is supported, the previous state is snapshotted, and the operation can be reverted with nuvio_undo. This gives an agent a concrete mental model of side effects and safety, which annotations alone do not provide.

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?

Two tight sentences with no filler. The core purpose is front-loaded, and the behavioral details about append, dry_run, snapshot, and revert are packed efficiently without redundancy.

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?

The description is adequate for a basic installation call, covering the required URL and key safety behavior. However, with six parameters, no output schema, and minimal schema descriptions for half the parameters, it leaves gaps around optional parameter semantics and success/return behavior that an agent would need for richer calls.

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 only 33%, so the description needed to compensate for undocumented parameters like name, enabled, profile_id, and sort_order. It does not: it only reiterates the URL-based install and dry_run support, both of which the schema already describes.

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 a specific verb ('Install'), resource ('addon'), and mechanism ('by manifest URL'), and clarifies the operation appends to the existing addon list rather than replacing it. This clearly distinguishes it from sibling tools like nuvio_update_addon, nuvio_reorder_addons, and nuvio_remove_addon.

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 gives clear context: use this to add a new addon to a profile while preserving the current list. It does not explicitly name alternatives or state 'use nuvio_update_addon to modify existing addons,' but the append-only wording implies the boundary well enough.

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 description discloses important behavioral details beyond the annotations: the operation is a write, it snapshots the previous state, it supports dry_run, and it can be reverted with nuvio_undo. This provides strong transparency about side effects and recovery, especially valuable because the annotations do not convey these specifics.

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 front-loaded: it states the core operation first, then the supporting behaviors. Every sentence adds value, with no filler or repeated schema 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?

The description covers the essential prerequisites, side effects, and rollback path needed to invoke the tool correctly. Since there is no output schema, a brief statement about the return value on success or the audit behavior would improve completeness, but this is a minor gap given the tool's straightforward add operation.

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 only 25% because only dry_run has a description. The description adds some meaning by noting the folder carries catalog sources and that the collection already exists, but it does not compensate for the lack of descriptions for collection_id, profile_id, or the folder object's fields beyond what their names suggest. The schema structure provides partial clarity, but the remaining gaps keep this at a minimally adequate level.

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 a specific verb ('Append') and resource ('a folder with catalog sources to an existing collection'), clearly distinguishing this from sibling tools like update_collection_folder, remove_collection_folder, or create_collection. The addition of 'existing collection' reinforces what action is being performed.

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 clearly indicates when to use the tool: when appending a folder to an already existing collection. It does not explicitly name alternatives or state when not to use it, but the operation and prerequisite are unambiguous enough for correct selection.

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?

Beyond the annotations, the description discloses important behaviors: it is additive ('preserving the existing plugin list'), supports dry runs, snapshots the previous state before the write, and provides a revert path via nuvio_undo. This meaningfully augments the sparse annotation set and helps agents understand side effects.

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?

Two dense sentences contain all core information with no filler. The primary action is front-loaded, and the behavioral notes (dry run, snapshot, undo) are placed in a single follow-up sentence.

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?

The description covers the main action and safety semantics well, but with 6 parameters, no output schema, and no usage alternatives, it leaves meaningful gaps: parameter meanings for name/enabled/repo_type and guidance on when to use related sibling tools are missing.

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 only 17%, so the description should compensate, but it only clarifies 'url' (the plugin source) and 'dry_run' implicitly. Parameters such as name, enabled, repo_type, and profile_id receive no semantic explanation beyond basic names, leaving agents to guess at their formats and roles.

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 a specific verb and resource ('Install a plugin on a profile by URL') and adds the key scope 'preserving the existing plugin list.' This clearly distinguishes it from related plugin management siblings like nuvio_update_plugin, nuvio_remove_plugin, and nuvio_reorder_plugins.

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 when to use the tool: adding a plugin to a profile via URL without replacing the current list. However, it offers no explicit guidance on alternatives or exclusions, such as when to use nuvio_update_plugin instead, nor does it mention prerequisites like profile existence or valid URL sources.

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 description discloses key behavioral traits beyond annotations: it snapshots the previous state before writing and allows revert via nuvio_undo, and supports dry_run for non-destructive previews. This complements the annotations (readOnlyHint false, destructiveHint false) by explaining how the mutation is made safe and reversible. No contradiction with annotations.

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?

Two concise sentences front-load the core purpose (upsert) and then add the key safety features (dry_run, snapshot, revert). Every word contributes value with no redundancy or irrelevant detail.

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?

The description covers the essential operation and safety mechanisms, but given the complexity of the items array (many optional fields) and the presence of profile_id, it omits details about the expected response, error behavior, and any limits on batch size. The schema provides field structure, but the description could be more complete about operational expectations.

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 only 33% (only dry_run has a description). The tool description explains the upsert key for items, adding meaning to the array parameter, but does not describe profile_id or the structure/optional fields of items. It partially compensates for the low coverage but leaves profile_id and item field semantics undocumented in prose.

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 a specific verb (add/update) and resource (library items) with explicit upsert semantics based on content_id + content_type. This clearly distinguishes it from siblings like nuvio_remove_from_library, nuvio_add_addon, and nuvio_add_plugin, which target different resources or operations.

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 clearly indicates the intended use case (bulk upsert of library items) and mentions the revert workflow via nuvio_undo. It does not explicitly exclude alternatives or list when not to use, but the resource specificity and mention of the opposite tool (remove) in the sibling list make usage 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 description explicitly claims the tool is 'Idempotently' adding items and states that a repeated call does not create a duplicate, but the annotation idempotentHint is false. This is a direct contradiction between the description and the structured metadata, which is a serious inconsistency. Per instructions, any contradiction with annotations warrants a score of 1, regardless of other disclosed behaviors like dry_run and snapshots.

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 concise and front-loaded, with the core action ('Idempotently add watched items') in the first sentence. It covers key behaviors (idempotency, upsert key, dry_run, snapshot, undo) without redundancy. Every sentence adds value, and there is no fluff.

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?

The description covers the essential behavioral aspects: idempotency, upsert key, dry_run, snapshot, and undo capability. Given there is no output schema, it omits specifics about the return value or error conditions, but these are not critical for a write operation with undo support. The main gap is the contradiction with the idempotentHint annotation, which could mislead an agent, but that is already accounted for in behavioral transparency. Overall, it is fairly complete for the tool's complexity.

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 low (33%) with only dry_run documented. The description adds useful context by identifying the upsert key fields (content_id, season, episode) for the items array, which clarifies the purpose of some parameters. However, it does not explain profile_id or elaborate on the structure of items beyond the key fields, so it only partially compensates for the lack of schema descriptions.

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 the tool's purpose: 'Idempotently add watched items to a profile's history' with a specific verb (add) and resource (watch history). It also specifies the upsert key (content_id + season + episode), which differentiates it from sibling tools like nuvio_mark_watched or nuvio_get_watch_history. This is unambiguous and actionable.

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 provides context for when to use the tool (adding watched items) and mentions supporting dry_run and undo, but it does not explicitly compare to alternatives like nuvio_mark_watched or nuvio_set_watch_progress. The usage is implied rather than clearly delineated, leaving the agent to infer when this tool is preferred over others.

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. The description adds meaningful context beyond that: the operation is transactional, takes a composite snapshot, and supports rollback. It also notes the dry-run default, though that duplicates the schema default. No contradiction with annotations.

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 single, tightly packed sentence with no filler. The most important behavior (transactional atomic apply) is front-loaded, and the dry-run default is a useful trailing note. Every phrase earns its place.

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, non-idempotent tool with no output schema, the description leaves too much unspecified: what 'canonical operations' refers to, what the dry-run return looks like, what rollback behavior actually entails, and how errors are surfaced. An agent would need significant external knowledge or schema inspection to invoke this correctly with confidence.

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 only 50%: 'operations' has no top-level description, while 'dry_run' does. The description adds no parameter-level meaning beyond 'canonical operations', which is ambiguous, and it merely restates the dry_run default already in the schema. It does not compensate for the operations parameter being underdocumented.

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 a specific verb and resource: 'Apply several canonical operations as one transaction.' It also conveys the core value (transactional composite snapshot with rollback) that separates it from one-off mutation tools. However, 'canonical operations' is not defined, and no sibling is explicitly contrasted.

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 transactional and rollback language implies use cases where atomicity matters, and the dry-run default implies a safe preview mode. But there is no explicit when-to-use, when-not-to-use, or alternative routing, leaving the agent to infer when to pick this over individual mutation tools.

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 mark it readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds valuable transparency about what the tool will surface, including automatic-undo behavior and deprecated aliases, which is behavior-relevant context. Nothing in the description contradicts the annotations.

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 single sentence that front-loads the resource and then lists exactly what will be described. It avoids repetition and contains no 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?

For a zero-parameter, no-output-schema introspection tool, the description is complete: it tells an agent exactly what information the call will yield. No additional operational detail is needed to invoke it correctly.

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 tool has zero parameters, so the baseline is 4; there is nothing for the description to add beyond the empty schema. Schema description coverage is 100% because the schema has no properties.

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 uses a specific verb ('Describe') with a clear resource ('this Nuvio MCP server') and enumerates the exact facets it covers: backend, transport, undo behavior, canonical tool list, and deprecated aliases. It is easily distinguished from the sibling operational tools, which all perform concrete data or setup operations.

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 intended use is implied: it is the meta-discovery tool for the server, contrasting with the operational siblings. However, it does not explicitly say when to use it (e.g., before calling other tools) or when not to use it, and there are no exclusions or named alternatives.

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?

Beyond annotations (destructiveHint=true), the description discloses that the operation is irreversible, not idempotent, requires a two-phase confirmation token, and that the token is short-lived. It also mentions dry_run support. This is valuable behavioral context that the annotations alone do not provide.

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 brief and front-loaded with the core purpose. The only minor issue is 'Not reversible. Cannot be undone.' is somewhat redundant, but the overall structure is efficient and scannable.

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, two-phase tool with no output schema, the description covers the essential call flow, irreversibility, and dry_run option. It leaves current_pin's purpose undocumented and does not describe the response format, but the token-handling instructions are sufficient for an agent to call the tool correctly.

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 description substantially clarifies confirmation_token by explaining the two-phase prepare/execute flow, but it does not explain current_pin or profile_id beyond what the schema already shows. With 50% schema description coverage, it adds some value but does not fully compensate for the missing parameter descriptions.

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 exact action and resource: 'Remove the PIN lock from a profile.' This clearly distinguishes it from the sibling nuvio_set_profile_pin, and the added detail about irreversibility and the two-phase flow makes the tool's role unmistakable.

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 gives clear context for when to call it and how: remove a PIN, call once for a token, then call again with that token. It does not explicitly compare against nuvio_set_profile_pin or state exclusions, but the purpose and call sequence are clear enough for an agent to select it correctly.

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 indicate non-readonly, non-idempotent, and non-destructive. The description adds that it snapshots the previous state before writing and supports dry_run, which are valuable behavioral details beyond the annotations. It also mentions revert via nuvio_undo, providing operational context.

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 single sentence that front-loads the deprecation notice and packs in the core function, dry_run support, and snapshot/undo behavior. It is concise and clear, though it crams a lot of information into one sentence.

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 deprecated tool with 8 parameters and no output schema, the description is minimal. It omits details about the credential flags, return values, and the exact semantics of the snapshot. However, since it directs users to the replacement, the lack of completeness is somewhat mitigated.

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 only 13% (only dry_run has a description). The description partially compensates by mentioning the copy_tv/mobile/desktop and provider credentials parameters, but it does not clarify the distinction between copy_provider_credentials and replace_provider_credentials, nor does it explain the profile ID semantics beyond the schema. Given the low coverage, this is insufficient.

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 the tool copies TV/mobile/desktop settings and optionally provider credentials between profiles, and it explicitly names the replacement sibling (nuvio_copy_setup), distinguishing itself from it. The deprecated flag is front-loaded 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?

It explicitly instructs the agent to use nuvio_copy_setup instead, which is direct guidance on when not to use this tool. It also mentions dry_run and snapshot/undo capabilities, which indicate safe usage patterns.

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 description discloses that it replaces the target's settings blob (a write), supports dry_run to avoid writes, snapshots prior state, and allows revert via nuvio_undo. This goes beyond the annotations (which only indicate readOnlyHint false, destructiveHint false) by explaining the safety net, which is essential for an agent to gauge risk. No contradiction with annotations is present.

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 two sentences, front-loaded with the deprecation notice, and covers the core behavior in a compact manner. It is efficient with no fluff, though it could be slightly better structured by separating the deprecation note from the functional details.

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 deprecated tool, the description provides enough to understand its function, safety (dry_run, snapshot), and the recommended alternative. However, it does not explain all five parameters in detail or cover edge cases like same source/target, and since it's deprecated, the lack of full detail is somewhat acceptable but still leaves gaps for an agent that might use it.

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?

With only 20% schema description coverage (only dry_run described), the description adds minimal parameter context. It uses 'source' and 'target' implicitly mapping to from_* and to_* parameters, but does not explain defaults, constraints, or parameter interactions. The parameter names are self-descriptive, but the description does not compensate for the low schema 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 the action: 'copy settings between profiles/platforms' and specifies it 'Replace the target's settings blob with a copy of the source's.' It also distinguishes itself from the sibling nuvio_copy_setup by marking itself deprecated and naming the replacement, making its purpose unmistakable.

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 explicitly says '[DEPRECATED] Use nuvio_copy_setup instead,' which is direct guidance on when not to use this tool and which alternative to choose. It also mentions dry_run and snapshot/revert capabilities, offering practical usage context, though it doesn't elaborate on broader conditions for copying vs other update operations.

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?

Adds substantial behavior beyond the sparse annotations: transactional rollback with rollback-status reporting, dry_run semantics, snapshot-before-write, and a named revert tool. This is exactly the kind of context annotations (only readOnly/openWorld/idempotent/destructive hints) do not convey. No contradiction with annotations since readOnlyHint=false matches the write operation.

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; every clause carries information (modes, transactional behavior, dry_run, snapshot, revert). Front-loaded with the core purpose before the details. Slightly long but nothing is wasted.

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?

Thorough for a complex 6-param mutating tool with no output schema: covers modes, credentials, platform mapping, transactionality, and recovery. The only gap is that it never describes what the response/return value looks like, which matters since there is no output schema to fall back on.

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 only 33% (2 of 6 params described), so the description must compensate. It explains settings_mode (merge vs replace), provider_credentials (none/merge/replace), and platforms defaults, which the schema leaves mostly unexplained. Source/target profile IDs are self-evident as integers 1-6, so no loss there.

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 a specific verb+resource ('Copy a profile setup to another profile') with cross-platform nuance. The sibling nuvio_copy_settings is very similar in intent, and the description doesn't name it to differentiate, so it stops short of a 5.

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?

Explains the mode choices (merge/replace), provider-credentials handling (none/merge/replace), and when dry_run is appropriate, plus the revert path via nuvio_undo. It gives clear context on how to operate but never explicitly states when to prefer this over the sibling copy_settings tool.

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 description discloses important behavioral details beyond the annotations: it snapshots the previous state before writing and can be reverted via nuvio_undo. This tells an agent about side effects and recovery options, which the annotations do not convey. It does not contradict any annotation.

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 two sentences with no wasted words. It front-loads the core purpose, then adds the most relevant behavioral caveats (dry_run, snapshot, undo) in a compact second sentence.

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?

The description covers the tool's primary purpose and the undo/snapshot behavior, which is essential for safe invocation. However, it omits what the tool returns, does not clarify the profile_id semantics, and gives no guidance about the required nested collection fields beyond what the schema already states.

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 only 33%, so the description should compensate by explaining key parameters. The only parameter behavior mentioned is dry_run, which is already documented in the schema. The description adds no value about the collection structure or profile_id, leaving the agent to infer their meaning from required fields and names.

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 uses a specific verb and resource combination ('Add a new collection to a profile') that clearly states what the tool does. It does not explicitly differentiate from sibling tools like nuvio_update_collection or nuvio_delete_collection, but the 'new collection' wording makes the create intent 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 the tool is for creating collections and mentions dry_run as a supported mode, giving some context for when to use it. However, it does not explicitly state when not to use it or name alternatives such as nuvio_update_collection for modifying existing collections.

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 description goes beyond the annotations by disclosing that the tool preserves existing profiles, enforces a max of 6, supports dry_run, snapshots the previous state before writing, and can be reverted with nuvio_undo. This is rich behavioral context that an agent would not otherwise derive from readOnlyHint=false or destructiveHint=false.

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?

Two sentences carry the core action, constraints, dry-run behavior, snapshot guarantee, and rollback path with no filler. The most important information is front-loaded, and every clause earns its place.

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?

The description covers the essential operational context: creation, non-destructive behavior, limits, primary-slot semantics, dry_run, and undo path. It does not specify error handling when the 6-profile cap is reached or describe return behavior, but given the absence of an output schema and the presence of rich sibling context, it is reasonably complete.

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 57%, so several parameters (name, avatar_url, avatar_color_hex) lack schema descriptions, and the tool description does not explain them. It does add useful meaning for dry_run and the primary slot rule, but it only partially compensates for the coverage gap.

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 a specific verb and resource ('Add a new profile') and adds a key constraint ('preserving every existing one'), which clearly distinguishes it from update/delete/list siblings. The max-6 and primary-slot details further pin down the operation's scope.

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 clearly indicates creation as opposed to the sibling update/delete/list tools through 'Add a new profile'. It provides relevant context such as the 6-profile cap and primary slot rule, but does not explicitly name alternatives or when-not-to-use conditions, so it falls short of a 5.

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 flag destructiveHint=true and readOnlyHint=false, and the description adds valuable safety context: dry_run support, snapshotting of the previous state before the write, and revert via nuvio_undo. It does not contradict the annotations; it enriches them. It stops short of mentioning the confirm-required behavior, but that is documented in the schema.

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?

Two tight sentences with no fluff: the first front-loads the core operation, the second adds the safety/revert hook. Every word earns its place.

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 low-complexity destructive operation, the description covers intent, dry-run behavior, snapshotting, and undo path, while the schema handles the confirm gate and profile_id default. No output schema exists, but this is a delete tool rather than a query, so the lack is not critical.

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 only 50%; the description partially compensates by clarifying that a profile is the container and that the operation removes a collection from it. However, it does not explain collection_id format or profile_id semantics beyond the default and range already in 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 a specific verb-resource pair ('Remove a collection from a profile') and is clearly distinguished from sibling tools that operate on profiles, addons, plugins, folders, or watch history. The title and description align without being tautological.

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?

No explicit guidance on when to choose this over alternatives such as nuvio_update_collection, nuvio_remove_collection_folder, or nuvio_delete_profile. The description implies it is for deleting a whole collection, but never states exclusions or alternative conditions.

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 mark destructiveHint=true and readOnlyHint=false, but the description goes well beyond them. It discloses the irreversible nature ('cannot be undone'), the exact scope of data deletion, the two-phase confirmation token mechanism (not hinted at in annotations), and the dry_run capability. These are substantial behavioral details that an agent cannot infer from structured fields alone. No contradiction with annotations.

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?

Three sentences, each dense with information. The first sentence establishes scope, the second the irreversibility and exclusion, the third the exact procedure. Every clause earns its place; there is no fluff or repetition. The front-loading of the most critical fact (what gets deleted) is excellent.

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, non-idempotent tool with no output schema, the description covers the essential operational aspects: scope of destruction, irreversibility, the two-phase token requirement, and dry_run support. It could optionally mention permissions or what the success/failure response looks like, but given the annotations and schema, these are not critical. The description is sufficiently complete for an agent to execute the operation correctly.

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 67% (dry_run and confirmation_token have descriptions, profile_id does not). The description compensates for the missing profile_id documentation by stating 'Profile 1 cannot be deleted', which clarifies why the schema enforces a minimum of 2. It also explains the confirmation_token's role in the two-phase flow, complementing the schema text. This adds meaningful context beyond the schema, though it could go further by specifying the token's format or expiry, but 'short-lived' is sufficient.

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 a specific verb ('Delete'), a precise resource ('profile'), and the full scope of what is removed ('ALL of its data' with explicit categories). It also distinguishes itself from related profile tools (nuvio_update_profile, nuvio_delete_collection) by its destructive scope and the unique two-phase token requirement. The purpose is unambiguous and instantly actionable.

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 gives clear operational guidance: the two-phase call flow (call once for token, then again with token) and the warning that Profile 1 cannot be deleted. It also mentions dry_run support. It does not explicitly name alternative tools for other operations (e.g., updating a profile), but the purpose is so specific that the usage context is obvious. A small gap is the absence of explicit 'when not to use' guidance, but the irreversibility warning implicitly covers 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 mark the tool destructive and non-read-only. The description adds valuable behavior beyond annotations: it snapshots previous state before the write and can be reverted with nuvio_undo. It does not contradict the annotations.

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?

One sentence carries purpose, dry_run behavior, snapshot behavior, and revert path with no filler or redundancy. It is front-loaded with the action.

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?

The description covers the key safety behavior (dry_run, snapshot, undo) but leaves provider and profile_id semantics unexplained, and with no output schema and a destructive operation, an agent still has to infer important call details. It is adequate but has clear gaps.

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 only 50%; provider and profile_id have no semantic descriptions in the schema, and the description does not clarify what values they take or their role beyond 'from a profile.' Mentioning dry_run repeats schema content rather than adding parameter meaning, so the description does not compensate for the coverage gap.

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 opens with a specific verb and resource: 'Remove a stored provider credential from a profile.' This clearly differentiates from sibling credential tools like set/test/list and matches the delete semantics implied by the name and title.

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 gives actionable context: dry_run is supported, a snapshot is taken before the write, and nuvio_undo can revert. It does not explicitly name alternatives or exclusion conditions, but the delete-vs-set/test/list distinction is clear enough from the tool name and context.

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 indicate destructiveHint=true, and the description adds valuable behavior: it snapshots the previous state before writing, supports dry_run, and references revert with nuvio_undo. It doesn't mention audit entries or confirm details beyond what schema covers, but it provides essential behavioral context beyond the annotations.

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 two sentences, tightly written, with the purpose front-loaded. It includes essential behavioral notes without redundancy. Every sentence adds value, making it highly concise and well-structured.

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 tool with no output schema, the description covers the key aspects: what it deletes, how to specify keys, the dry_run option, snapshot behavior, and revert path. It omits explicit mention of profile_id and confirm semantics (though confirm is described in schema), but these are relatively minor given the clarity of the tool's purpose and the schema's coverage. Overall, it provides sufficient context for correct invocation.

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 50%: confirm and dry_run have descriptions, while keys and profile_id do not. The description clarifies that keys is an array of objects with content_id and optional season/episode, adding meaning to the keys parameter. However, it does not explain profile_id or its default, leaving a gap. The description partially compensates for the low coverage but not fully.

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 the action ('Delete watch-history entries') and the resource ('watch-history entries') with a specific identifier ('by content id'), and optionally season/episode. It distinguishes itself from siblings like nuvio_add_to_watch_history and nuvio_get_watch_history by indicating the exact deletion scope.

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?

While it doesn't explicitly contrast with alternatives, it implies usage by describing the deletion mechanism and safety features (dry_run, snapshot, revert). It says 'Supports dry_run and snapshots the previous state before the write; revert with nuvio_undo,' giving context on how to use it safely, which is sufficient for an obvious delete operation.

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 the description adds valuable behavior beyond that: it supports dry_run and snapshots the previous state before the write, with revert via nuvio_undo. This gives the agent useful operational context not present in the annotation or schema.

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 two sentences with zero filler: the action and key structure are front-loaded, followed by the dry_run and snapshot/undo behavior. Every clause earns its place.

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 tool with a moderately complex keys parameter, the description covers the core semantics, key structure, dry-run behavior, and undo path. It omits explicit mention of the confirm parameter, but the schema already documents that, so the description is largely complete.

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?

With schema description coverage at 50%, the description compensates by explaining the keys parameter structure (content_id plus optional season/episode), which is the most complex parameter. It does not elaborate on profile_id, but that parameter has a simple default and range in 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 a specific action (delete) on a specific resource (continue-watching entries) and defines the key structure (content_id + optional season/episode). This clearly distinguishes it from siblings like nuvio_delete_watch_history, which targets history rather than progress.

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 does not explicitly state when to use this tool vs alternatives such as nuvio_delete_watch_history or nuvio_set_watch_progress. It implies usage through the action and key structure, and mentions dry_run and undo, but provides no when-not-to-use guidance or direct sibling routing.

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 indicate a non-read-only, non-destructive write. The description adds that dry_run is supported, that a snapshot of the previous state is taken before the write, and that nuvio_undo can revert. It also notes the copy's placement. This is meaningful behavioral context beyond the annotations, though it doesn't cover all edge cases.

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?

Two sentences, front-loaded with the purpose, then a compact statement of side effects and recovery. No redundant or extraneous content.

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?

The description covers the core behavior and safety net, but omits return behavior (no output schema) and leaves new_title/profile_id semantics unstated. For a 5-parameter tool with no output schema, this is moderately complete but not fully.

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 only 20% (dry_run). The description explains collection_id and new_id implicitly, and mentions dry_run, but does not clarify new_title or profile_id. Since the schema itself provides no descriptions for these, the tool description fails to compensate for the low 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 uses a specific verb ('Copy') and resource ('collection'), with scoping details ('including folders and catalog sources') and placement ('right after the source'). This clearly differentiates it from create/update/delete collection siblings.

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 duplicating an existing collection, but provides no explicit when-to-use vs alternatives or exclusions. The mention of nuvio_undo is for recovery, not tool selection, so agents are left to infer when this should be chosen over create_collection or other options.

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?

Beyond the readOnly/openWorld/idempotent annotations, the description adds valuable behavioral context: output is JSON, credentials and tokens are excluded server-side, and scope determines full vs partial backup. This materially helps an agent understand side effects and data handling.

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?

Three sentences carry distinct information: what the tool returns, what it excludes, and how to control scope. It is front-loaded and contains no 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?

With no output schema, the description still conveys the output format, the data categories included, the security guarantee around credentials, and the parameter-driven scope behavior. This is sufficient for an agent to select and invoke the tool correctly.

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 already documents all three parameters with 100% coverage, so the baseline applies. The description adds that passing them narrows the backup and that default is full backup, but it does not add meaning beyond the schema's per-parameter descriptions.

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 a specific action ('Export'), a resource ('account data'), and the return format ('JSON backup'), then enumerates the data sections included. This clearly differentiates it from sibling tools like nuvio_restore_backup and the individual list/get 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?

The description provides explicit usage guidance: with no scope it is a full backup, and you can narrow it via scope/profile_ids/platforms. It does not explicitly name alternatives or say when not to use this tool, but the context is clear enough.

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, openWorldHint, and idempotentHint, covering safety and side-effect behavior. The description adds minimal behavioral context beyond restating the purpose (reading catalog settings), which is already in the name. It doesn't describe return format or potential limitations, but the annotations carry the safety burden, so a 3 is appropriate.

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 single, front-loaded sentence with no filler. It efficiently states the operation and scope without redundancy, making it easy to scan and understand.

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?

The tool has no output schema, so the description should explain what the tool returns. It only says it 'reads' the configuration but doesn't describe the structure or content of the returned data. Additionally, it doesn't mention any prerequisites or limitations, leaving the agent without enough information to fully interpret the response or validate the call.

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 0%, so the description must compensate for parameter meaning. It mentions 'profile' and 'platform' but doesn't explain what values platform accepts (beyond the default 'tv') or what profile_id refers to (e.g., a user profile). The schema provides min/max and default, but the description fails to add semantic depth about the parameters' roles.

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 uses the specific verb 'Read' and identifies the resource as 'home screen layout/catalog configuration' for a profile on a platform. This clearly distinguishes it from the sibling nuvio_update_home_catalog_settings and other getter tools like nuvio_get_settings, which likely target different settings.

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 provides clear context that this is a read-only operation for catalog settings, which implies when to use it (when you need current catalog configuration). It doesn't explicitly state exclusions or name alternatives, but the sibling set makes the read/update distinction obvious. The guidance is adequate but not explicit about 'use this instead of X'.

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, openWorldHint=true, and idempotentHint=true, so the safety profile is covered. The description adds that this lists a profile's saved items, but it does not mention pagination behavior or return format.

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?

One compact sentence with no filler. The parenthetical '(bookmarks/favourites)' adds disambiguating value without bloating the description.

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 simple read-only list tool with no required parameters, this description plus the annotations and schema defaults is nearly sufficient. It could mention pagination or the shape of returned items, but those are not necessary for correct tool selection and basic invocation.

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 description gives meaning to profile_id by tying it to the profile's library, which partially compensates for the 0% schema description coverage. Limit and offset are not explicitly explained, though their conventional pagination meaning and the schema constraints make them reasonably inferable.

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 uses a specific verb ('List') and a specific resource ('items in a profile's library'), then clarifies with '(bookmarks/favourites)'. This clearly distinguishes it from sibling tools about watch progress, collections, and library mutations.

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 intended use is clear: retrieve saved bookmark/favourite items for a profile. It does not explicitly name alternatives like nuvio_add_to_library or nuvio_remove_from_library, but the read/list vs. mutation distinction is obvious from the sibling tool names.

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, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds useful context by specifying that the result is a JSON settings blob, but it does not disclose behavior for missing profiles, default values, or platform-specific differences.

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?

One short, front-loaded sentence communicates the core behavior with no filler or redundant details. It is appropriately concise for a low-complexity read operation.

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?

The tool is simple, has no required parameters, and annotations cover safety, so the description is mostly adequate. However, with no output schema and no parameter guidance, the agent is left to infer what the JSON blob contains, what values 'platform' accepts, and what happens when no settings exist.

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 0%, so the description must compensate, but it only loosely names 'profile' and 'platform' without explaining their meaning, constraints, or defaults. The schema provides defaults and bounds, yet the description adds little semantic value beyond restating the parameter names in natural language.

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 identifies the action ('Read'), the resource ('JSON settings blob'), and the scope ('for a profile on a platform'). It is specific enough to distinguish from mutation tools like nuvio_update_settings, though it does not explicitly differentiate from close siblings like nuvio_get_home_catalog_settings.

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 gives no guidance on when to use this tool versus alternatives. It does not mention that writes should go through nuvio_update_settings or nuvio_set_setting, nor does it state prerequisites or exclusions.

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 convey readOnlyHint and idempotentHint, so the description's disclosure burden is reduced. However, 'List watched items for a profile' adds no behavioral nuance beyond the annotation, missing pagination-side effects, response shape, or ordering semantics.

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?

A single sentence, front-loaded with the essential verb-resource pair. It is efficient and usually waste-free, but the brevity contains almost nothing beyond the purpose, so it reads as terse rather than richly structured.

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 at least conveys that the tool returns a listing, and the input schema fills in defaults and value ranges. It is not obviously incomplete for the simple read case, but it lacks sibling differentiation and pagination, clarification, leaving some inference to the agent.

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 low (33%). The description's 'for a profile' clarifies the implicit profile_id role, but it does not explain page_size, pagination behavior, or defaults. Meaningful parameter context must be inferred from the schema, and even then, page_size has no description.

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 a specific resource ('watched items') with a specific verb ('list'), and the title 'Get watch history' reinforces the intent. It does not explicitly distinguish from siblings like nuvio_get_watch_progress or nuvio_delete_watch_history, but the core purpose is 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?

No guidance is given on when to use this tool versus alternatives such as nuvio_get_watch_progress or nuvio_set_watch_progress. With a large sibling list, the agent gets no routing information beyond the product description.

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 and idempotentHint, so the description needs to add value beyond that. It does not—there is no mention of pagination, response format, or any behavioral nuance. The description merely restates the tool's action without enriching context.

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 single concise sentence with no fluff, but it is under-specified. While brevity is positive, the structure is minimal and does not convey necessary details, making it borderline acceptable.

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 list operation with no output schema, the description omits what the response contains, whether pagination is involved, or any sorting/ordering. It also does not clarify the meaning of 'continue watching' relative to watch history. This is insufficient for an agent to invoke it correctly without further assumptions.

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 0% and the description mentions neither 'limit' nor 'profile_id'. It provides no semantics beyond the schema's defaults and ranges, failing to compensate for the lack of schema descriptions.

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 uses a specific verb ('List') and a distinct resource ('continue watching' progress entries), which clearly differentiates it from watch history and other siblings. It also scopes to a profile, though it does not explicitly name the alternative tools it is not.

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?

No guidance is given on when to use this tool versus siblings like nuvio_get_watch_history or nuvio_set_watch_progress. There are no exclusions, prerequisites, or mention of alternative conditions, leaving the agent to infer usage from the name and siblings.

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 cover the safety profile (readOnlyHint, idempotentHint, openWorldHint), and the description adds only the database-targeting context beyond that. It does not disclose what a healthy response looks like, whether latency is returned, or how failures surface, which matters given there is no output schema.

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?

A single six-word sentence that front-loads the primary verb ('Ping') and names the target resource. Every word earns its place, and the size is appropriately proportionate to a parameterless tool.

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 zero-parameter tool with strong annotations the definition is nearly complete, but the absence of an output schema means the description should indicate what the ping returns or what signals health. It also never reconciles 'backend' vs. 'backend database,' leaving the scope of the health check slightly underspecified.

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 tool takes zero parameters and the schema is an empty object with 100% coverage, so there is nothing the description needs to document. Baseline 4 applies because no parameter semantics could be missing.

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 uses a specific verb and resource — 'Ping the Nuvio backend database' — which clearly identifies this as a liveness/health probe. It is naturally distinguishable from the ~60 sibling CRUD tools. Minor ambiguity remains between the title's 'backend health check' and the description's narrower 'backend database,' and 'ping' is not defined in terms of what it checks.

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 context is implied by the tool's nature: a health check is for verifying backend connectivity, and no sibling provides a comparable liveness probe. However, the description never explicitly states when to run it (e.g., before troubleshooting other tools) or when not to, leaving the agent to infer the trigger conditions.

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 the tool as read-only, open-world, and idempotent, so the description is not required to restate safety guarantees. It adds useful detail about what is retrieved and summarized, though it does not address potential network failures or invalid manifest behavior. The description does not contradict the annotations.

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 single, well-structured sentence that front-loads the action and purpose, then compactly lists the returned information. There is no redundant filler, and every part contributes to understanding the tool.

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 simple read-only tool with one parameter and no output schema, the description covers the purpose, the input, and the key contents of the output. It does not describe failure modes or exact response formatting, but these are not critical for a straightforward inspection tool whose safety profile is covered by annotations.

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 0%, but there is only one parameter, 'url', which is self-explanatory and has a URI format. The description implies the URL points to the addon manifest, adding a little semantic context, but it could more explicitly state what kind of URL is expected and whether it should be a manifest endpoint.

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 a specific action ('Fetch and summarise'), a clear resource ('Stremio/Nuvio addon manifest'), and enumerates the summary contents (name, version, resources, catalog types). It distinguishes itself from sibling tools like nuvio_add_addon or nuvio_list_addons by framing this as pre-install inspection.

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 phrase 'before installing' gives a clear context for when this tool should be used, distinguishing it from installation or management operations. It does not explicitly mention alternatives or state when not to use it, but the intended usage is still evident.

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 mark it read-only and idempotent. The description adds useful behavioral context beyond annotations by stating the output is the captured previous state and that secrets are masked, which is important for an agent to know before invoking.

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?

A single, front-loaded sentence with no filler. 'Secrets masked' is a worthwhile parenthetical that conveys an important output behavior without wasting words.

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 simple one-parameter, read-only, idempotent tool, the description covers the essential purpose and a key output constraint. The main missing piece is guidance on how to obtain/validate snapshot_id and how this relates to undo/redo sibling tools.

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 description does not explain snapshot_id, its format, or where to obtain it. However, with only one required parameter whose name is self-explanatory, the parameter is arguably inferable; the description still doesn't compensate for the 0% schema coverage with any additional semantic detail.

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 uses a specific verb ('Show') and resource ('snapshot'), and clarifies that it displays the captured previous state rather than current state. It is clear enough to distinguish from nuvio_inspect_addon by resource type, though it doesn't explicitly differentiate from related undo/redo snapshot workflow 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?

There is no guidance on when to use this tool versus alternatives like nuvio_list_undo, nuvio_undo, or nuvio_redo. The phrase 'captured previous state' implies a connection to undo workflows, but no explicit when-to-use or when-not-to-use guidance is provided.

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 only say readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds concrete behavior beyond the annotations: dry_run is supported, a snapshot of the previous state is taken before the write, and nuvio_undo can revert 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?

Three short sentences, with the core purpose first and no filler. Each sentence adds either scope, usage guidance, or side-effect 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?

The key usage rule and write behavior are covered, but with 8 parameters, 25% schema coverage, and no output schema, several optional fields remain unexplained. Still, an agent can call the primary path safely using tracker and access_token.

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 only 25%, so the description needed to compensate. It clarifies tokens relate to OAuth and that a profile is targeted, but it does not explain username, tracker_user_id, expires_in_seconds, refresh_token, or how dry_run interacts with the snapshot beyond what the schema already says.

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 opens with a specific verb and resource: 'Store tracker OAuth tokens for a profile.' It also draws the boundary with the out-of-band token flow, so an agent can distinguish this linking operation from nuvio_unlink_tracker and nuvio_list_trackers.

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?

'Use this only when tokens were obtained out-of-band; prefer the app sign-in flow' explicitly states when the tool is appropriate and gives the preferred alternative. This is clear routing with no ambiguity.

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 supply readOnlyHint, openWorldHint, and idempotentHint, so the safe read-only behavior is established. The description adds that the list is scoped to a profile and includes the returned fields, which gives the agent extra context beyond the schema and annotations.

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 single, efficient sentence that front-loads the verb and resource, then adds only the relevant output fields. There is no filler or redundancy.

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?

A simple one-parameter read-only list is adequately specified with the resource scope, output fields, and implied profile. The only missing piece is a declaration of what happens when the profile_id is omitted, but the input schema default and the simplistic nature of the tool keeps this from being a serious 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 0%, so the description must compensate, but it only mentions 'a profile' without explaining profile_id's meaning, allowed range, or default behavior. The connection to the single parameter is present but implicit, and no additional semantic value is added beyond what the schema already exposes.

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 the action ('List') and the resource ('addons installed on a profile'), and it enumerates the output fields (url, name, enabled, sort_order). It is easily distinguishable from the sibling nuvio_list_plugins because the resource is named directly.

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 intended use is clear: call this tool when you want the addons on a profile. It doesn't explicitly compare with alternatives like nuvio_list_plugins or nuvio_inspect_addon, but the resource name in the description gives enough contextual grounding without creating confusion.

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 declare readOnlyHint, openWorldHint, and idempotentHint, so the safety and idempotency profile is covered. The description confirms the output is a list of catalog ids, which adds useful detail, but it does not provide additional behavioral context beyond what the 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?

A single, front-loaded sentence states the verb, resource, and scope without any filler. Every word earns its place, and the description is appropriately minimal for a zero-parameter read-only list tool.

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 simple, no-parameter, read-only list operation, the description is largely complete: it identifies what is returned ('avatar catalog ids') and for whom ('profile avatars'). The absence of an output schema is slightly noticeable, but the wording makes the expected result clear enough for typical agent use.

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 tool has no parameters, and schema description coverage is 100%, so the description need not explain any inputs. Baseline for zero-parameter tools is 4, and the description adds no misleading or missing parameter information.

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 a specific verb ('List'), a specific resource ('avatar catalog ids'), and the intended use ('available for profile avatars'). This clearly distinguishes it from the many sibling list tools such as nuvio_list_plugins and nuvio_list_profiles.

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 phrase 'available for profile avatars' gives clear context that this tool is for selecting or inspecting avatar choices when working with profiles. It does not explicitly name alternatives or exclusions, but the resource is distinct enough that no strong exclusion is needed.

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, openWorldHint, and idempotentHint, so the read-only nature is covered. The description adds the output scope (titles, view mode, folders, catalog sources), but does not disclose ordering, pagination, or behavior for a missing/invalid profile; without an output schema this is a moderate gap.

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?

A single front-loaded sentence conveys the core operation, the scope, and the expected output fields with no filler. The parenthetical is compact and economical.

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 simple read-only list operation with one optional parameter and no nested objects, the description is nearly complete: it states the target and output fields, and the annotations plus schema cover safety and constraints. It would be fully complete if it described the return shape or the default profile behavior, hence not a 5.

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 0% and the description does not explain profile_id beyond the indirect phrase 'a profile's'. It does not mention that profile_id is optional, defaults to 1, or takes values 1-6; the schema supplies constraints but the description fails to meaningfully compensate for its lack of parameter documentation.

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 identifies the operation ('List') and the target resource ('a profile's custom collections'), and narrows the expected output to titles, view mode, folders, and catalog sources. This distinguishes it from sibling list operations such as nuvio_list_plugins and nuvio_list_profiles.

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 communicates a clear use case: retrieve the custom collections belonging to a profile. It does not explicitly contrast with mutating collection tools like nuvio_update_collection or nuvio_delete_collection, so it stops short of a 5, but the intent is unambiguous.

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 (readOnlyHint, openWorldHint, idempotentHint) already cover safety and side-effect expectations. The description adds the per-profile scoping ('on a profile') but does not disclose further behavior such as whether disabled plugins are included, result ordering, or pagination. No contradiction with annotations.

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?

A single sentence containing the essential components—verb, resource, and scope—with no unnecessary words or structure. It is appropriately front-loaded.

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 simplicity (one optional parameter, no output schema, no nested objects), the description is sufficient for an agent to understand what it does. It does not describe the return format, but for a list operation this is a minor omission given the straightforward nature.

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?

There is one parameter, profile_id, with no schema description (0% coverage). The phrase 'on a profile' implies the parameter selects the profile, and the schema provides default, min, and max. This is adequate for a simple integer ID but the description does not explicitly explain the parameter.

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 a specific verb ('List'), resource ('plugins'), and scope ('installed on a profile'). This clearly differentiates it from sibling tools like nuvio_add_plugin, nuvio_toggle_plugin, nuvio_reorder_plugins, and nuvio_remove_plugin.

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?

There is no guidance on when to use this tool versus the many plugin-related siblings. The agent must infer that this is the read operation among plugin management tools; no explicit exclusions or alternative conditions are given.

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, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds return scope (all profiles, slots 1..6) but does not add behavioral caveats such as ordering, live vs cached data, or whether only enabled profiles 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.

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

A single sentence front-loads the action and resource, then packs the return fields into a parenthetical. Every word earns its place and there is no 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?

For a zero-parameter, read-only listing tool, this is largely complete: it enumerates exactly what the result covers (slots, name, avatar, flags, PIN lock state). With no output schema, it could additionally state the result shape or value formats, but that is a minor 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?

The tool has zero parameters and the schema coverage is complete by construction, so there is nothing for the description to clarify. The zero-parameter baseline applies and no parameter information is missing.

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 a specific verb ('List'), a specific resource ('profiles'), and enumerates the return content: slot, name, avatar, flags, PIN lock state. It is clearly distinguishable from sibling mutation tools like nuvio_create_profile and nuvio_delete_profile, and from other list_* tools by naming 'profiles' explicitly.

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 its use is to read the full set of profiles, and sibling names make the contrast with create/update/delete obvious. It does not explicitly spell out when-not-to-use or name an alternative tool, but for a zero-parameter list operation the context is clear enough.

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 mark this as read-only and idempotent, so the safety profile is established. The description adds one crucial behavioral fact not present in annotations: secret values are masked in the response. This helps the agent avoid expecting raw secrets. No contradictions are present; it just doesn't cover pagination or response shape, which is acceptable given the annotations.

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?

Two short sentences, with the key action and scope in the first sentence and the masking warning in the second. Every word contributes meaning; there is no redundancy or filler. The structure is ideal for this simple tool.

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 one-parameter tool with read-only/idempotent annotations, the description covers the main use cases and explicitly mentions the masking behavior. However, without an output schema, the description doesn't state what the returned list contains (e.g., provider IDs, names, types). It doesn't fully eliminate ambiguity for an agent that wants to predict the response shape, but it's sufficient for a basic read operation.

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 0%, so the tool description must compensate for the undocumented profile_id parameter. It mentions 'for a profile' but fails to link that to the profile_id field, its allowed range (1–6), the default value of 1, or its optionality. The schema itself provides the numeric constraints, but the description adds almost no semantic value beyond the parameter's name and the vague 'profile' reference.

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 the action ('List'), the resource ('configured providers'), and the scope ('for a profile'), and it enumerates the provider categories that are excluded. This distinguishes it from sibling list tools like nuvio_list_plugins or nuvio_list_addons without needing to inspect their schemas.

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 implicitly tells the agent when to use it (when you need to see configured providers and their masked credentials), but it doesn't explicitly compare to alternatives like nuvio_set_provider_credential or nuvio_delete_provider_credential. There is no clear statement of when this tool should be used instead of or along with those, so guidance remains implied rather than explicit.

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, idempotentHint, and openWorldHint, which cover the safe read-only nature of the operation. The description adds useful behavioral detail by specifying what fields are returned: device name, platform, client, last active, and which session is current. No contradiction with annotations.

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 single, front-loaded sentence that states the action and then compactly lists the output fields. Every word earns its place, with no filler or repetition.

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 simple, parameterless, read-only list operation, the description is nearly complete. It names the output fields and the annotations cover safety and idempotency. It could slightly improve by noting that sessions can be revoked via nuvio_revoke_session, but this is not essential for correct invocation.

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 tool has zero parameters and the schema coverage is 100%, so there is no parameter documentation burden. The description appropriately focuses on the result contents rather than inputs, matching the baseline for a parameterless tool.

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 a specific verb and resource: 'List active login sessions/devices', and enumerates the returned fields. It clearly communicates what the tool does, though it does not explicitly contrast itself with sibling tools like nuvio_revoke_session or nuvio_whoami.

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: use this tool when you want to see active login sessions and devices. However, it provides no explicit guidance on when to choose this over related tools such as revoke_session, register_device, or whoami, leaving the agent to infer the appropriate context.

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 mark readOnlyHint, idempotentHint, and openWorldHint, so the description only needs to add non-obvious behavior. It contributes the useful disclosure that access tokens are masked, which is important security context not present in the schema or annotations.

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?

Two short sentences with no filler; purpose is front-loaded and the token-masking note is a single additional clause. Every word earns its place.

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 simple one-parameter, annotation-rich list operation, the description covers what is returned (linked trackers and settings), the provider scope, and a key security behavior. It does not enumerate exact response fields, but that level of detail is not required to invoke the tool correctly.

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 sole parameter profile_id is well-named and has default/min/max in the schema, but the schema has no description for it. The description's 'per-profile settings' hints at profile scoping but does not explicitly state that profile_id filters the listed trackers, so compensation for 0% schema coverage is only partial.

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 a specific action — list — plus a specific resource: linked trackers across MAL, AniList, and Kitsu. Scoping to 'linked' and 'per-profile settings' clearly distinguishes it from mutator siblings like link_tracker, unlink_tracker, and set_tracker_settings.

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 makes clear this is the read-only enumeration tool for trackers, with per-profile settings context. It does not explicitly name alternatives or exclusions, but the sibling names and the word 'list' make the appropriate context evident.

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 declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, so the description does not need to repeat the safety profile. The description does add the trait that snapshots are 'automatically-captured' and 'recent', which explains the expected contents. It does not disclose whether listing is paginated or whether entries are deduplicated, but for a simple list tool this is an adequate level of addition above the annotations.

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?

Two short sentences: the first plainly states the purpose, the second links to the companion undo tool. There is no filler, and the most important action verb 'List' comes first. Every word contributes to an agent's decision about whether to call this tool.

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?

This is a read-only listing tool with a single parameter and no output schema, so the description does not need to explain return values in detail. It correctly notes the snapshots are the undoable kinds, which is exactly what an agent needs to decide between listing, inspecting, or undoing. It would be slightly stronger if it mentioned that the list may be large or that entries can be inspected individually via nuvio_inspect_snapshot, but the current text is sufficient for routine use.

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 0%, so the description carries some burden, but there is only one parameter (limit) whose type, default, and min/max are fully declared in the schema. The word 'recent' in the description implies ordering by recency, which meaningfully complements the limit parameter. The description therefore adds enough value beyond schema for the parameter's purpose, though it could have mentioned 'limit' explicitly.

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 starts with a specific verb and resource: 'List recent automatically-captured snapshots.' It immediately distinguishes itself from sibling tools by noting that each snapshot can be reverted with nuvio_undo, separating it from nuvio_inspect_snapshot. This makes the tool's purpose 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 explicitly routes the user to nuvio_undo when they want to revert, which is the key alternative action for the listed snapshots. It does not provide explicit 'when not to use' guidance, but the sibling context (nuvio_inspect_snapshot could inspect a single snapshot) is implied clearly enough given that this tool is the list counterpart.

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?

Beyond annotations (which only indicate mutation and non-destructiveness), the description discloses that it supports dry_run, snapshots prior state before writing, and can be reverted with nuvio_undo. This adds valuable behavioral context that the annotations do not cover.

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 two sentences and packs deprecation warning, replacement, primary function, dry_run support, snapshot behavior, and revert mechanism without wasted words. Information is front-loaded and concise.

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 deprecated tool, the description adequately redirects to the alternative and explains key behaviors (snapshot, dry_run, revert). It lacks parameter details and error handling, but given the deprecation, the main purpose is to prevent misuse, which it achieves. A fully complete spec is unnecessary for a tool that should not be used.

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 only 33% (only dry_run has a description). The description mentions dry_run but adds nothing beyond what the schema already states. It provides no explanation for the 'item' object (required fields, meaning of season/episode/watched_at) or 'profile_id'. Since schema coverage is low, the description should compensate but does not.

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 the tool adds an entry to a profile's watch history, names the replacement (nuvio_add_to_watch_history), and signals deprecation. It distinguishes itself from siblings by explicitly saying to use the alternative.

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 explicitly instructs the agent to use nuvio_add_to_watch_history instead and mentions nuvio_undo for revert, providing clear when-to-use and when-not-to-use guidance. This leaves no ambiguity.

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 include destructiveHint=true, so the description doesn't need to repeat that. It adds valuable context: defaults to dry_run, requires confirm for actual deletion, and that dry_run forces preview even without confirm. This goes beyond the schema and annotations, explaining the safety behavior. However, it doesn't specify exact effects on local snapshots or confirmation requirements in detail, but the core behavior is well disclosed. Since annotations cover the destructive nature, this is above average but not perfect.

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 single sentence, front-loaded with the action and retention criteria, then adds critical safety notes. Every clause has a purpose: 'Local-only' sets scope, 'defaults to dry_run' and 'previews unless confirm=true' are essential for safe use. No wasted words.

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 operation with 5 parameters, the description covers the action, scope, safety defaults, and confirmation requirement. The schema covers each parameter's meaning, so nothing essential is missing. The tool doesn't have an output schema, but for a prune operation the description doesn't need to explain return values; the core usage is fully understandable.

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 all five parameters are already described in the schema with clear meanings (e.g., 'older_than_days' explicitly says 'Delete snapshots older than N days'). The description adds the interplay between dry_run and confirm, which is not in the schema, but parameters themselves are already well-defined. Baseline 3 is correct because the schema does the heavy lifting.

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 the verb 'delete' and the resource 'old snapshot files' with specific retention criteria (age, count, total size). It also clearly distinguishes from siblings like nuvio_inspect_snapshot and nuvio_restore_backup by focusing on deletion. The 'prune' name is expanded with concrete details.

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 explicitly notes 'Local-only; defaults to dry_run' and clarifies that 'dry_run=true always previews'. It implies when to use (for cleanup) but doesn't name alternatives like inspect or restore, though it's clear this is the deletion tool. No exclusions beyond the preview/confirm logic, so a 4 is appropriate.

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 indicate this is a mutating, non-idempotent operation, so the description does not need to restate that. It adds meaningful context beyond the annotations by stating 'Snapshots current state first,' which clarifies a safety-related behavior and supports the destructiveHint=false annotation. It does not detail failure modes or undo-stack effects, but the snapshot disclosure is valuable.

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 two sentences with no wasted words. The first sentence states the core operation and target, and the second adds the key safety behavior. It does not repeat the title or schema 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?

For a zero-parameter tool with annotations covering mutability, idempotency, and destructiveness, the description is largely complete: an agent knows what the tool does, when to use it, and that a snapshot is taken. A small gap is the lack of guidance on edge cases such as calling redo when there is no undo history or after the redo stack has been consumed, but this is not necessary for basic correct invocation.

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 tool has zero parameters and the input schema is empty, so there are no parameter semantics for the description to explain. With 0 parameters, the baseline is 4, and the description adequately focuses on the operation's meaning rather than parameter details.

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 a specific verb ('Re-apply') and a precise resource ('the change that the most recent nuvio_undo reverted'). This clearly differentiates it from the sibling nuvio_undo and other state-management tools, and the word 'most recent' removes ambiguity about which change is targeted.

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 establishes the precondition implicitly: this tool is appropriate after a nuvio_undo operation, since it targets the change that undo reverted. It does not explicitly name alternatives or say when not to use it, but the undo/redo pairing and the reference to nuvio_undo make the usage context clear.

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 indicate this is a non-idempotent, mutating operation, and the description adds important detail: the operation cannot be undone, must be confirmed via a second call, requires a backend-accepted client_name, and supports dry_run. This meaningfully enriches the structured annotation data without 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?

Three compact sentences with no filler. The irreversible two-phase requirement is front-loaded, followed by the backend constraint and dry_run support. Every sentence earns its place.

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 mutating tool with no output schema, the description covers the non-obvious behaviors an agent needs: irreversibility, two-phase token confirmation, backend validation, and dry_run. It does not detail the exact success/error response or optional parameter formats, but the token flow is sufficiently described for correct invocation.

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 description adds key semantics for client_name (must be accepted by the backend) and explains confirmation_token's two-phase role, which is valuable given only 29% schema coverage. However, it leaves platform, device_name, client_version, and installation_id unexplained, so it does not fully compensate for the low schema-description 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?

States a specific action and resource: 'Register a device/installation against the account.' This clearly differentiates it from the many sibling tools focused on profiles, addons, collections, and settings. The title is redundant, but the description gives a concrete verb+resource pair.

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?

Provides actionable usage context: client_name must be a backend-accepted value, and the two-phase call flow tells the agent to call once, receive a short-lived token, then call again with it. It does not explicitly name when not to use the tool or alternatives, but no close sibling exists, so the omission is minor.

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. The description adds value by disclosing dry_run support, snapshot-before-write behavior, and the revert path via nuvio_undo. This provides concrete operational context beyond the annotations without contradicting them.

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?

Two sentences with no wasted words. The primary purpose is front-loaded, followed by essential behavioral notes (dry_run, snapshot, revert). This is concise and well-structured.

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?

The description covers the core action and safety features (dry_run, snapshot, revert), but omits the confirm requirement (though present in schema), the ambiguity between id and url, and the default profile_id. Since there is no output schema, return values are not needed. For a destructive tool, more guidance on identifiers and confirmation would improve 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?

Schema description coverage is only 40% (confirm and dry_run have descriptions). The description only mentions dry_run, leaving id, url, and profile_id unexplained. It does not clarify which identifier is required or the default profile_id, failing to compensate for the low schema 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 states 'Uninstall one addon from a profile' with a clear verb (uninstall) and resource (addon from a profile). This distinguishes it from siblings like nuvio_add_addon and nuvio_toggle_addon by specifying removal of a single addon. The purpose is 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 does not explicitly state when to use this tool versus alternatives such as nuvio_toggle_addon (for temporary disable) or nuvio_remove_plugin (for plugins). It mentions revert with nuvio_undo, which implies a recovery path, but lacks explicit selection criteria or exclusions. The usage is implied by the name and purpose, not articulated.

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 description discloses that the operation snapshots the previous state and can be reverted with nuvio_undo, which adds context beyond the annotations (destructiveHint=true, readOnlyHint=false). It does not contradict annotations; it confirms the destructive nature and adds dry_run capability. However, it does not mention the confirm requirement, which is a notable behavioral omission.

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 single sentence plus a short clause, with the core action front-loaded and no wasted words. It is concise and well-structured.

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 tool with 5 parameters, no output schema, and a confirm gate, this description is far from complete. It omits the crucial confirm requirement, doesn't explain what the parameters mean, and gives no indication of the response format. An agent would likely invoke it incorrectly without reading the schema, and even then, the undocumented parameters remain ambiguous.

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?

With only 40% schema coverage, the description carries a heavy burden to explain parameters, but it says nothing about folder_id, collection_id, profile_id, confirm, or dry_run. The schema descriptions for confirm and dry_run exist, but the other three parameters are undocumented in both schema and description. This is a severe gap.

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 the verb 'remove' and the resource 'a folder from a collection', distinguishing it from sibling operations like add, update, or reorder. It is not a tautology; it adds the scope 'from a collection' and mentions supporting behaviors.

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 provides no guidance on when to choose this tool over alternatives like nuvio_update_collection_folder or nuvio_delete_collection. It mentions dry_run and revert via nuvio_undo, but does not explicitly state conditions or exclusions. Critical usage context like the need for confirm to actually apply destructive changes is left entirely to the schema.

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 provide destructiveHint=true and readOnlyHint=false, but the description adds valuable context beyond them: it snapshots the previous state before the write and supports dry_run returning a diff without writing. The revert pathway via nuvio_undo is explicitly disclosed. This does not contradict the annotations — the destructive hint aligns with 'remove'.

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?

Two sentences with zero waste. The purpose is front-loaded, and the dry_run/snapshot/undo behavior is appended concisely. Every clause earns its place.

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 tool with a confirm gate, no output schema, and no mention of return format, the description covers the snapshot/undo/dry_run mechanics well. However, it omits the confirm requirement (documented only in the schema) and the profile_id scope, and provides no guidance on what the response contains, leaving some gaps for a mutation with undo semantics.

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 50% (2 of 4 params documented in schema: confirm and dry_run). The description adds meaning for 'keys' (content_id + content_type) and dry_run, but does not mention the confirm parameter — which is safety-critical for a destructive tool — nor profile_id scope. It partially compensates for the coverage gap but leaves the confirm gate undocumented in prose.

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 uses a specific verb-resource pair ('Remove items from a profile's library') and identifies the exact keys ('content_id + content_type'). This clearly distinguishes it from siblings like nuvio_add_to_library (inverse) and nuvio_get_library (read-only). The title 'Remove from library' reinforces the purpose.

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 by stating the removal mechanism and mentions dry_run as a safe preview path and nuvio_undo for revert, which is helpful operational guidance. However, it never explicitly states when to use this tool versus alternatives (e.g., nuvio_add_to_library for the reverse, or nuvio_get_library for inspection) nor any when-not conditions.

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 description adds meaningful behavior beyond the annotations by disclosing that the tool snapshots the previous state before writing and that the operation can be reverted with nuvio_undo. It also advertises dry_run support. This is valuable context not present in the readOnly/destructive hints, and it does not contradict the annotations.

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 single dense sentence that front-loads the core action and then adds the two safety-relevant facts: dry_run support and snapshot/undo behavior. There is no filler or redundant restatement of the title.

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 5-parameter tool with no output schema, this is adequate but has clear gaps. The removal behavior and safety net are explained, and confirm/dry_run are documented in the schema, but the plugin identity semantics and the expected response/preview content are left to inference. An agent could still be unsure which parameter to supply.

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 only 40%, with id, url, and profile_id lacking descriptions. The tool description does not clarify whether a plugin is identified by id or url, what happens if both are provided, or how profile_id scopes the operation. Mentioning dry_run adds little since dry_run already has a schema description.

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 opens with a specific verb+resource combination: 'Uninstall a plugin from a profile.' This clearly distinguishes it from sibling tools like nuvio_add_plugin, nuvio_update_plugin, nuvio_toggle_plugin, and nuvio_list_plugins, and it is not just a restatement of the title.

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 gives a clear operation context and mentions a safe invocation path via dry_run and a recovery path via nuvio_undo. However, it does not explicitly state when to use this tool versus alternatives such as nuvio_toggle_plugin for disabling or nuvio_update_plugin for modifying a plugin. The usage guidance is implied rather than explicit.

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 description discloses the snapshot-before-write behavior and the undo path via nuvio_undo, which is not present in the annotations. It also mentions dry_run and its effect (no snapshot/audit). These add meaningful behavioral context beyond the structured fields, though it does not detail return values or failure modes.

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 two sentences with no fluff. It front-loads the purpose, includes the critical ordered_urls constraint, and mentions dry_run and snapshot/undo—all essential. Every sentence earns its place.

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 that this is a write operation with no output schema, the description covers the main operational aspects: required input format, dry_run behavior, and revertibility. It does not specify the return value or explicitly state prerequisites like profile existence, but the snapshot and undo details make it adequately complete for an agent to call it correctly.

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 only 33% (dry_run only). The description adds value for ordered_urls by specifying the 'exactly once' requirement, which is not in the schema. However, profile_id is not explained in the description, and the schema already provides its default/range. The description partially compensates for low coverage but does not fully clarify all parameters.

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 a specific verb and resource: 'Set the display order of a profile's addons.' This is unambiguous and distinguishes from sibling tools like nuvio_reorder_plugins by explicitly naming 'addons' and 'profile.' It also names the core operation (display order) clearly.

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 provides a key usage rule: 'Provide every installed addon URL exactly once, in the desired order,' which is essential for correct invocation. It implicitly scopes the tool to addons, and the sibling list makes alternatives obvious, but it does not explicitly state when not to use it (e.g., for plugins). The dry_run and snapshot guidance also help decide usage.

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 description discloses that the tool snapshots the previous state before writing and can be reverted with nuvio_undo, which goes beyond annotations like readOnlyHint=false and destructiveHint=false. It also notes dry_run support, adding useful behavioral context about side effects and safety.

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?

Three concise sentences front-load the core purpose, then add the key constraint and side-effect information. No redundant or filler content is present.

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 reorder operation with no output schema, the description covers the critical details: the ordering invariant, dry-run support, snapshot creation, and revert path. It leaves profile_id selection to the schema default, which is acceptable given the low complexity.

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 only 25%, so the description must compensate. It adds essential semantics for ordered_folder_ids by requiring every folder id exactly once, but it does not clarify collection_id or profile_id semantics beyond what the schema's names and defaults imply.

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 opens with a specific verb and resource, 'Set folder order,' and adds a precise invariant: every folder id in the collection must be provided exactly once in the desired order. This clearly distinguishes it from sibling tools like nuvio_reorder_collections, nuvio_reorder_addons, and nuvio_reorder_plugins.

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 intended use is implied through the phrase 'every folder id in the collection,' but the description does not explicitly state when to choose this tool over alternatives or when not to use it. No mention is made of sibling reorder tools, so the guidance is adequate but indirect.

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 signal a mutating, non-idempotent operation, and the description adds genuinely useful context: a snapshot is taken before the write and the change can be reverted with nuvio_undo. It also mentions dry_run support without contradicting the annotations or the schema.

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?

Three short sentences with no filler: the first states the action, the second defines the critical parameter contract, and the third communicates safety behavior. Every clause earns its place.

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 small, three-parameter write operation, the description covers the required parameter semantics, the dry-run preview path, and the rollback mechanism. The main gaps are the unaddressed profile_id parameter and the lack of explicit guidance about when this tool applies versus the other reorder tools.

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?

For ordered_ids, the description adds crucial meaning beyond the schema: every collection id must appear exactly once and the order is the desired final order. However, profile_id is not described at all, and dry_run is described more fully in the schema than in the tool description. With only 33% schema description coverage, this only partially compensates.

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?

'Set collection order' clearly names the verb and resource, and 'Provide every collection id exactly once' adds important scope by indicating this is a full-order replacement rather than a partial move. It is clear enough to distinguish from the addon/plugin/folder reorder siblings by noun, but it does not explicitly call out those siblings.

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 gives operational context—how to supply the ordered ids and that dry_run/undo are available—but it never states when to choose this tool over nuvio_reorder_collection_folders, nuvio_reorder_addons, or nuvio_reorder_plugins. Usage guidance is mostly implied by the resource noun and the instruction to provide every collection id exactly once.

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 show destructiveHint=false and readOnlyHint=false, and the description adds that 'snapshots the previous state before the write' and supports dry_run, disclosing side effects beyond the schema. It also notes that dry_run skips the snapshot/audit, which is useful behavioral context.

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?

Three sentences with high information density—states the essential constraint (all URLs exactly once), mentions dry_run and snapshot features, and points to revert tool. No 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?

The description is complete for a reorder operation with dry_run and revert, but it lacks details on return values (no output schema) and doesn't elaborate on profile_id or validation errors. Given complexity and missing output schema, more context could help, but the core behavior is 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 low (33%), with dry_run and profile_id lacking description in the schema. The description only mentions ordered_urls implicitly ('every installed plugin URL exactly once') but doesn't explain dry_run or profile_id semantics. Since the description adds meaning only for ordered_urls, and 2 of 3 params are undocumented, it partially compensates but leaves gaps.

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 a specific verb and resource ('Set plugin order') and provides the unique constraint (every plugin URL exactly once), distinguishing this from nuvio_add_plugin and nuvio_update_plugin. The action is 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 implies when to use it—when reordering is needed—and mentions dry_run and revert capabilities, but doesn't explicitly list sibling tools or state when NOT to use. Still, the context of reordering is clear against other plugin operations.

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 description goes well beyond the annotations (destructiveHint=true, readOnlyHint=false) by detailing the overwritten components (profiles/addons/library/settings), the irreversible nature with a token-based two-phase process, and the dry_run behavior. This adds crucial context about the tool's operational semantics that annotations alone do not 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 description is concise and well-structured: it starts with the core purpose, then states availability, risk, the irreversible token process, and dry_run support. Every sentence adds essential information with no redundancy 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 tool's high risk and lack of an output schema, the description covers the key operational aspects: what it does, when it's available, what it overwrites, how the token flow works, and the dry_run safety net. It implicitly indicates that the first call returns a token, though it does not explicitly state the return value format, which is a minor 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%, and the schema already explains each parameter (backup from nuvio_export_backup, dry_run returns diff, confirmation_token for two-phase). The description does not add new parameter-specific meaning beyond what the schema provides, so it meets the baseline of 3.

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 a specific action ('Replace account data') on a specific resource ('account data') from a specific source ('backup produced by nuvio_export_backup'). It clearly distinguishes this tool from all siblings, which are unrelated operations (profiles, addons, settings, etc.), and the mention of the backup origin avoids confusion with other restore-like 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?

The description provides clear conditions for use: only on self-hosted backends exposing sync_restore_account_backup, and it explains the two-phase token flow. It also mentions dry_run as a safe option. It does not explicitly list when not to use it, but since there are no alternative restore tools, the guidance is sufficient.

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 mark destructiveHint=true, readOnlyHint=false, and idempotentHint=false. The description adds meaningful behavioral detail beyond annotations: the operation cannot be undone, requires a two-phase confirmation token flow, supports dry_run, and never deletes the account. No contradiction exists.

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 concise and front-loaded with the core purpose. 'Cannot be undone' appears twice, which is mildly redundant, but the overall structure is efficient and the two-phase flow is clearly described.

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, two-phase operation with no output schema, the description covers the essential workflow, irreversibility, dry_run support, and account-safety guarantee. It does not spell out the exact return value of the first call or explicitly require session_id on the second call, but the guidance is sufficient for correct invocation.

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 67%, so the description does not carry the full parameter burden. It adds value beyond the schema by explaining that the confirmation token is short-lived and that the operation requires calling twice. However, it does not clarify how to obtain or format session_id beyond the schema's format/pattern.

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 a specific verb ('Revoke') and resource ('one login session'), and clarifies the purpose in plain language ('log that device out'). It also distinguishes itself from account deletion with 'Never deletes the account', which separates it from delete-style 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?

The description gives clear context: this is for revoking a single session, is irreversible, and does not delete the account. It does not explicitly name an alternative such as nuvio_list_sessions for finding sessions, but the operational guidance about the two-phase token flow is strong.

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=false and destructiveHint=false, so no contradiction. The description adds that it supports dry_run and snapshots previous state before write, and that revert is possible. However, it doesn't mention any side effects like audit entries beyond the dry_run note in the schema, or what state changes are irreversible. With annotations covering the mutation hint, the description adds useful context but could say more about the snapshot mechanism.

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 short and front-loaded with the deprecation warning, which is good. But it packs multiple ideas (deprecation, set operation, dry_run, snapshot, revert) in two sentences, which could be more readable. Every sentence earns its place, but the length is marginal for the guidance it gives.

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 that it's a deprecated tool with a replacement, the description covers deprecation, usage, and basic behavior enough for an agent to know to prefer the alternative. However, it does not explain the exact dot-path syntax or the interaction with profile_id/platform, which are critical for a correct call if the agent does use it. It's adequate but not complete given the 5 parameters and no output schema.

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 only 20%, so the description must compensate, but it only mentions the 'path' and 'value' implicitly via 'dot path' and 'value' in the text. It does not explain the format of 'path' (e.g., dot notation) beyond that phrase, nor does it describe 'platform', 'profile_id', or 'dry_run' semantics beyond what the schema provides. Since the description is brief, it adds minimal value, and with 5 parameters it should do better.

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 the tool sets a nested value by dot path inside the home catalog settings blob, with a deprecated status and an explicit replacement. It distinguishes from nuvio_update_home_catalog_settings by naming it as the successor, but it does not explain why this tool exists separately or what edge cases it covers, so it's clear but not fully distinct.

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 explicitly tells the agent to use nuvio_update_home_catalog_settings instead, and it mentions the dry_run capability and revert path via nuvio_undo. This is exceptional guidance for a deprecated tool: when to use (during migration) and when not to (prefer replacement).

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 mark destructive, non-readOnly, non-idempotent. The description adds crucial behavioral context: irreversibility, that the PIN hash is never returned, and the two-phase confirmation flow with dry_run. 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.

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

Three dense sentences with no filler; purpose, irreversibility, and dry-run support are front-loaded and each sentence adds value.

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?

The description covers the non-reversible two-phase flow and dry_run, which is the essential complexity. It does not explicitly state the return value beyond the indirect mention of a token, but this is inferable and not required for correct invocation.

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 only 40%, so the description must compensate. It explains confirmation_token's role and mentions dry_run, but does not describe profile_id, pin, or current_pin beyond what their names imply. Adequate but incomplete compensation.

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 a specific verb and resource ('Set or change the PIN lock on a profile'), clearly distinguishing from sibling clear_profile_pin. The two-phase irreversibility note reinforces what action the tool performs.

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?

Explicitly describes the required call sequence (first call to get token, second with token) and supports dry_run. Does not name alternatives or exclusions, but the intended use is clear from 'Set or change' and the two-phase instructions.

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 establish this as a write operation, and the description adds valuable behavior beyond that: it snapshots the previous state before writing and supports undo via nuvio_undo. This is meaningful context not available from annotations alone, though it does not detail side effects of overwriting an existing key.

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?

A single, compact sentence that front-loads the action, packs the provider list efficiently, and tacks on dry_run/snapshot/undo behavior without filler. Every clause earns its place.

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 small mutation tool with no output schema, the description covers what the tool does, which provider values are accepted, and what safety/undo mechanisms exist. The only notable gap is that profile_id semantics are left to inference, but the overall definition is sufficient for correct invocation.

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 only says provider is "One of the supported provider ids," while the description lists the actual accepted values and distinguishes API key vs client id for animeskip. It also reinforces dry_run semantics. The profile_id parameter is not explained in the description, but its schema constraints (default 1, range 1–6) provide partial context.

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 a specific action and resource: "Store an API key for a provider," then enumerates the exact supported provider values. It is clearly distinct from the sibling list/test/delete credential tools because the verb and intent are explicit.

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 makes the use case clear: store/set a provider API key, with dry_run as a safe preview option. It does not explicitly contrast itself with nuvio_test_provider_credential or nuvio_delete_provider_credential, but the verb and provider list give enough context to select it correctly.

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 indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true. The description adds valuable behavioral context: it snapshots the previous state before the write, supports dry_run, and can be reverted with nuvio_undo. This goes beyond the annotations and helps the agent understand side effects and safety.

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 front-loaded with the deprecation warning, which is the most important routing information. It packs snapshot, dry_run, and revert behavior into one sentence without waste, though it could be slightly clearer about parameter semantics.

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 deprecated tool with no output schema, the description covers the key behavioral aspects (snapshot, dry_run, revert) and routing. However, it doesn't explain what the return value looks like, how the dot path is validated, or what happens on failure. Given the tool's complexity and the low schema coverage, a bit more detail would be helpful.

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 only 20%, so the description must compensate. It explains 'path' as a dot path and mentions 'dry_run' behavior, but it doesn't clarify 'value', 'platform', or 'profile_id' beyond the schema defaults. The description adds some meaning but leaves several parameters under-explained.

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 a specific verb ('Set') and resource ('one nested value by dot path'), and clearly marks the tool as deprecated in favor of nuvio_update_settings. It distinguishes itself from the sibling by noting it sets a single nested value by dot path, though it doesn't fully explain what nuvio_update_settings does differently.

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 explicitly says '[DEPRECATED] Use nuvio_update_settings instead,' which is a direct when-to-use/alternative instruction. It also mentions dry_run support and the revert path via nuvio_undo, giving clear context for when this tool might still be used.

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 only indicate the tool is not read-only; the description goes further by disclosing dry_run behavior, snapshotting of the previous state before the write, and a revert path via nuvio_undo. This gives an agent a clear preview-and-recovery model beyond the structured annotations.

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?

Two tight sentences with no filler: the core action and scoped fields appear first, followed by the dry_run and revert behavior. Every sentence earns its place.

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?

The description covers the core operation, dry-run behavior, and revert path, but it is thin on parameter details such as profile_id and valid array values, and there is no output schema to clarify the response. With six parameters, this leaves some call details to inference.

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 only 33%, and the description maps enabled_statuses, row_order, and send_progress to their conceptual roles, which partially compensates. However, profile_id is left unexplained, and the expected string values for row_order and enabled_statuses arrays are not provided.

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 a specific verb and resource ('Set ... tracker settings') and names the concrete fields changed: statuses sync, row order, and progress syncing. The 'linked tracker' qualifier clearly separates it from general settings tools like nuvio_update_settings.

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?

Provides clear context that this targets a linked tracker's sync settings and mentions dry_run for previewing changes, but it does not explicitly name alternatives or exclusion criteria, such as when to prefer nuvio_update_settings or what to do if no tracker is linked.

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=false and destructiveHint=false, so the write and non-destructive nature is known. The description adds valuable context beyond annotations: it snapshots previous state before writing, supports dry_run (partially also in schema), and points to nuvio_undo for revert. This goes beyond the annotation baseline by disclosing the safety mechanism and recovery path, though it doesn't address external side effects hinted by openWorldHint=true.

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?

Two sentences with no waste: the first states the core action and scope, the second discloses safety behaviors (dry_run, snapshot, revert). Information is front-loaded and every clause earns its place. Ideal size for the tool's complexity.

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 tool with 3 params and nested entries, the description covers the write intent and safety, but omits important context: it never mentions profile_id (defaults to 1) or that entries are grouped per profile, and doesn't explain required fields like content_id/content_type. With no output schema, an agent still needs to inspect the schema for essential payload details. The mention of nuvio_undo helps, but profile context and parameter semantics are incomplete.

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 33% (only dry_run has a description). The description compensates partially by explaining that entries carry 'position/duration' and target 'movies or episodes', giving meaning to those fields. But it leaves most parameters (content_id, content_type, season, episode, video_id, last_watched, profile_id) undocumented both in schema and description, so it doesn't fully bridge the low-coverage gap.

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 a specific verb ('Create or update') and resource ('continue-watching entries'), scoped to 'position/duration' for 'movies or episodes, in bulk'. This clearly distinguishes it from siblings like nuvio_get_watch_progress (read), nuvio_delete_watch_progress (delete), and nuvio_mark_watched (mark as watched), so an agent can select it without opening schemas.

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 context: bulk writing of watch progress with dry_run support and undo capability. However, it does not explicitly state when to use this tool over alternatives, nor does it name sibling tools like nuvio_mark_watched or nuvio_delete_watch_progress. Usage guidance is implied rather than explicit, so it lacks clear exclusion criteria.

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 declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered externally. The description adds the concrete behavioral content of returning aggregate counts and enumerates the domains, which is useful context, but it does not disclose return structure, grouping, or count semantics. This is consistent with annotations, not contradictory.

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?

A single, front-loaded sentence that immediately states the output type ('Summary counts') and then lists the covered categories. There is no filler, no repetition of the title, and every phrase earns its place.

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