nuvio-mcp

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

The description adds substantial behavioral context beyond the annotations: it discloses that the existing addon list is read and preserved (append, not replace), and that a snapshot is taken before the write with a revert path via nuvio_undo. This aligns with destructiveHint=false and idempotentHint=false while giving the agent actionable safety information that annotations alone could 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?

Three tight sentences, each earning its place: the first states the core operation, the second discloses the append semantics, and the third covers the snapshot/undo safety net. The most decision-relevant information is front-loaded, with zero 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 write operation with no output schema, the description covers the critical context: what action is performed, how existing state is treated, and how to recover via nuvio_undo. The only gaps are the absence of return-value expectations and undocumented optional parameter details, both minor given the tool's moderate complexity and robust 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 only 20%, so the description carries the burden for undocumented parameters. It clarifies the URL's role as the install source and hints that the operation targets a profile (connecting to profile_id), but it does not explain the semantics of name, enabled, or sort_order. The compensation is partial — enough for the required parameter, insufficient for the optional ones.

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 an addon on a profile by manifest URL." It names the installation mechanism (manifest URL), which distinguishes it from sibling tools like nuvio_update_addon, nuvio_toggle_addon, and nuvio_remove_addon. An agent can tell this is the tool for adding a new addon without inspecting other 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 operation context is implied by "Install an addon on a profile" and "only the new addon is appended," which clearly signals this is for adding a new addon rather than modifying existing ones. However, it never explicitly names alternatives or states when NOT to use it (e.g., "to modify an existing addon use nuvio_update_addon"). The usage guidance is clear in context but left to inference.

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 and explicitly points to nuvio_undo for revert. This goes beyond the annotations and helps the agent understand the mutation's safety and reversibility. 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 sentences with no filler. The core action is front-loaded, and the snapshot/revert note is a high-value addition. 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 mutation tool with no output schema, the description covers the key behavioral context (snapshot, undo path) and the main parameters. It doesn't explain profile_id or the exact effect of catalogSources, but the schema already details those. The undo pointer compensates for the lack of output schema and idempotency info.

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. It mentions 'folder (with catalog sources)' and 'existing collection', which maps to the 'folder' and 'collection_id' parameters, but it does not explain 'profile_id' or the nested folder fields beyond what the schema already provides. The description adds some meaning but leaves the profile_id parameter 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 ('Append') and resource ('a folder (with catalog sources) to an existing collection'), which clearly distinguishes it from sibling tools like nuvio_update_collection_folder and nuvio_remove_collection_folder. It could be slightly more explicit about the 'add' semantics versus 'create', but the action and target are clear.

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 when you want to add a folder to an existing collection. It does not explicitly state when not to use it or name alternatives, but the sibling list includes nuvio_update_collection_folder and nuvio_remove_collection_folder, which an agent could infer. No explicit exclusions or conditions are provided, so it's adequate but not 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 signal a mutating, non-destructive operation, and the description adds genuinely useful behavior beyond that: it preserves the existing plugin list and snapshots the previous state before the write, with nuvio_undo as the revert mechanism. This is a strong behavioral contract for a 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?

Two short sentences, no filler, and the most important facts are front-loaded: what the tool installs, what it preserves, and how to undo it. Every sentence adds operational 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?

This is adequate for the straightforward url-plus-profile call, and the snapshot/undo detail adds meaningful context. It falls short of complete coverage, however, because several optional parameters are unexplained, the failure behavior is not mentioned, and there is no output schema to clarify what the tool returns.

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 the burden of explaining the parameters, but it only clarifies the URL and profile intent, and even that is implicit. The name, enabled, and repo_type parameters are not explained at all, leaving gaps for agents trying to use the full tool correctly.

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, while also noting the existing plugin list is preserved. This distinguishes it clearly from sibling actions like 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?

The description implies when to use it: when installing a plugin by URL. It also gives an explicit recovery path via nuvio_undo, but it never states when not to use the tool or which sibling alternatives are better for enabling, reordering, or removing plugins. The agent has to infer that 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?

The description adds valuable side-effect information beyond the annotations: the previous state is snapshotted before the write and can be reverted with nuvio_undo. This is meaningful context because the annotations only provide generic hints and do not mention undo behavior.

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 core action and scoped to a profile's library. The second sentence adds an important revert note without unnecessary detail. 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 operation and its key undo behavior, and the schema supplies required fields and types. However, without parameter descriptions or an output schema, an agent must infer the meaning of content_id/content_type and cannot anticipate the response shape. This is a noticeable gap for a nested-object write tool.

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 provides no parameter-level semantics. It does not explain what makes a valid item, how content_id/content_type identify the item, or what profile_id refers to. The property names in the schema are suggestive, but the description itself fails 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-resource pair: 'Add or update an item in a profile's library.' It clearly separates this mutation tool from sibling read/removal tools like nuvio_get_library and nuvio_remove_from_library. There is no tautology or ambiguity.

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 states when to use the tool: to add or update an item in a profile's library. It does not explicitly name alternatives or exclusion conditions, but the usage context is clear and no misleading guidance is present.

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 useful context by saying it covers automatic-undo behavior and transport details, which are not visible in the annotations or schema. It does not elaborate on those behaviors, but for an introspection tool this is sufficient.

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, well-structured sentence with a colon-delimited list of exactly what the tool describes. Every word earns its place, and the most important content categories appear immediately after the verb.

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 parameters, no output schema, and simple introspection semantics, the description fully specifies what the agent will learn: backend, transport, automatic-undo behavior, and tool list. Nothing necessary for correct invocation is 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?

The tool has zero parameters, so the baseline is 4. There are no parameter semantics to clarify, and the description correctly focuses on output content rather than inputs.

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') and resource ('this Nuvio MCP server'), and enumerates the exact content areas: backend, transport, automatic-undo behavior, and full tool list. No sibling tool performs this meta-introspection role, so it is clearly differentiated from the operation-oriented sibling names.

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 it obvious that this tool is for obtaining a server-level overview, and there are no similar sibling tools competing for that use case. It does not explicitly state 'use this when...' or list exclusions, but the context is clear enough for an agent to know when to call it.

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 idempotentHint=false, but the description adds meaningful behavior beyond this: the operation cannot be undone and requires a prepare/execute flow with a short-lived token. This gives an agent the critical knowledge that a single call is insufficient and that a second call with a token is mandatory, which is not conveyed by the annotations alone.

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-loads the core purpose. The only minor flaw is a slight redundancy: 'Not reversible' and 'This operation cannot be undone' express the same idea twice. Otherwise, every sentence earns its place and the key procedural detail about two-phase confirmation is included.

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 4 parameters and no output schema, the description explains the core procedure well but omits important operational details: what current_pin is for, how profile_index should be set, and what the first call returns beyond a token. An agent could likely call it correctly after inferring some details from the schema, but the description alone leaves 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 description coverage is only 50%; profile_index and current_pin have no descriptions. The description partially compensates by explaining the confirmation token and two-phase flow, but it does not clarify the role of current_pin or how profile_index should be supplied. The token-related prose adds some value beyond the schema, but the gap in parameter semantics remains.

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 the PIN lock from a profile.' This clearly identifies what the tool does and distinguishes it from sibling tools like nuvio_set_profile_pin or nuvio_delete_profile. It adds important procedural context about two-phase confirmation immediately after 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 effectively tells an agent when to use this tool: whenever a profile's PIN lock needs to be removed. It also provides explicit call guidance, stating the operation is not reversible and must be executed in two phases with a short-lived confirmation token. It does not mention the alternative set_profile_pin, but the purpose is distinct enough that the usage context is 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?

Annotations mark this as a write (readOnlyHint=false), and the description goes further by disclosing that the previous state is snapshotted before the write and that nuvio_undo can revert it. This gives an agent useful safety context beyond the schema/annotations, though it does not say exactly what is overwritten.

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 front-load the action and immediately add the snapshot/undo safety note. 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?

Core action and required parameters are clear, but for a 7-parameter mutation with no output schema, the description omits the semantics of replace_provider_credentials and the exact overwrite behavior on the target profile. An agent may need to inspect the schema or guess defaults.

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 0% schema description coverage, the description must carry parameter meaning. It maps copy_tv/copy_mobile/copy_desktop to 'TV/mobile/desktop settings' and hints at copy_provider_credentials, but it leaves replace_provider_credentials unexplained and does not clarify defaults or the relationship between the two credential flags.

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 operation—copying TV/mobile/desktop settings between profiles—and clearly delimits the resource (profile setup) and optional credential scope. This is enough to distinguish it from generic tools like nuvio_copy_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 implies the intended use (duplicating setup across profiles) and points to nuvio_undo for revert, but it never states when to choose this over nuvio_copy_settings or when not to use it. No explicit exclusions or alternatives beyond the undo path.

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 target is overwritten, that a snapshot is taken before the write, and that the operation can be reverted via nuvio_undo. This adds meaningful behavioral context beyond the annotations, which only indicate read/write and destructiveness hints.

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-loaded with the core action, followed by cross-platform scope and undo safety. Every sentence adds relevant information with 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 simple four-parameter tool with no output schema, the description covers the essential behavior, cross-platform usage, and rollback path. It could be slightly more complete by explicitly naming source/target parameters, but an agent has enough information 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?

Schema coverage is only 50%: to_platform and from_platform have descriptions, but to_profile_id and from_profile_id do not. The description's source/target wording helps map to the from/to parameters, but it does not explicitly describe the profile ID parameters beyond what the property names 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 states a specific verb and resource: 'Replace the target's settings blob with a copy of the source's.' It clearly identifies the operation as copying settings between profiles/platforms, which distinguishes it from profile-setup copying and single-setting updates.

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 on when the tool is applicable ('Works across profiles and platforms') and includes a concrete example (tv -> mobile). It does not explicitly name alternatives or when-not-to-use conditions, but the intended scenario 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?

The description discloses a meaningful behavioral trait beyond the annotations: the previous state is snapshotted before the write and can be reverted with nuvio_undo. This complements the destructiveHint=false annotation by explaining why the operation is safe, and it usefully names the recovery path. It does not cover failure or conflict behavior (e.g., duplicate collection id), so it is strong but not exhaustive.

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 first states the primary action and target, the second adds the critical snapshot/undo caveat. It is front-loaded with purpose and 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 non-idempotent write operation with a nested object parameter and no output schema, the description covers the essential purpose and the key undo safeguard, but omits return-value expectations and behavior on repeated calls or duplicate ids. Given the tool's complexity, an agent would still have open questions about what to expect after 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 0%, so the description must compensate, but it only adds minimal meaning: the phrase 'to a profile' clarifies that profile_id identifies the target profile. The large nested collection object, its required id/title fields, and the defaults (profile_id default 1, max 6) receive no explanatory help, leaving the agent to infer semantics from property names and enums alone.

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

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

The description states a specific verb ('Add'), resource ('collection'), and target scope ('to a profile'), clearly differentiating creation from siblings like nuvio_update_collection, nuvio_delete_collection, and nuvio_list_collections. It is clear and unambiguous, though it does not explicitly name any sibling it is not, which keeps it just 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?

Usage context is implied rather than stated: 'Add a new collection' suggests it is the tool for creating collections as opposed to updating or duplicating them (nuvio_update_collection, nuvio_duplicate_collection). No explicit when-to-use or when-not-to-use guidance, and no prerequisites such as the profile needing to exist, are 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 already declare readOnlyHint=false, destructiveHint=false, so the description doesn't contradict them but adds useful behavioral context: 'The previous state is snapshotted before the write; revert with nuvio_undo.' This goes beyond annotations by explaining the snapshoting behavior and the undo path, which is valuable for an agent understanding side effects and recovery options.

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 key constraints front-loaded: the main action, the limits, and the undo option. No fluff, but it could be more concise by merging the second and third sentences. Overall efficient and informative.

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 is a creation operation with 6 parametersley no output schema, the description covers the core behavior, limits, and undo path. It lacks details on return values (e.g., created profile object) and edge cases like what happens when max profiles reached, but those might be inferred from the limits. Adequate for a relatively simple creation 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 coverage is 50%, with some parameters having descriptions (avatar_id, profile_index, uses_primary_addons) but others lacking (name, avatar_url, avatar_color_hex). The description references 'profile 1 is primary' which sheds light on profile_index semantics, but it does not fully compensate for the missing parameter details — e.g., it doesn't clarify avatar_url vs avatar_color_hex precedence or validation rules beyond the schema 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 clearly states the tool adds a new profile while preserving existing ones, and differentiates it from siblings like nuvio_update_profile and nuvio_delete_profile by specifying 'add' and 'preserving every existing one'. The title reinforces the resource, but the description adds specific scope (max 6, primary profile) that distinguishes it.

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 (max 6 profiles, profile 1 is primary) and mentions an alternative for revert (nuvio_undo), but does not explicitly contrast with sibling tools like nuvio_update_profile or nuvio_copy_profile_setup. It effectively tells the agent when to use it (adding a new profile) but not when not to use 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?

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the destructive nature is known. The description adds valuable context beyond this: the previous state is snapshotted before the write and can be reverted with nuvio_undo. This gives an agent a concretely safe recovery path.

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 short sentences with no filler. The primary action is front-loaded, and the recovery mechanism is placed immediately after, making it easy for an agent to parse both the purpose and the safety behavior quickly.

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 plus annotations covers the essentials: what is deleted, that it is destructive, and how to revert. The confirm-to-execute behavior is documented in the schema's confirm description, so the agent can discover it. It could mention the preview-without-confirm behavior in prose, but the schema already covers that.

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

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

Schema description coverage is only 33%; only the confirm parameter is documented in the schema. The description does not compensate for this: it does not explain the role of profile_id, the meaning of collection_id beyond the obvious, or that confirm must be true to perform the destructive write. 'From a profile' hints at profile_id, but this is far from adequate 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?

The description states a specific verb and resource: 'Remove a collection from a profile.' It clearly distinguishes this from sibling collection operations like update, create, duplicate, or remove_collection_folder, and the profile scoping adds useful precision.

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: when you need to delete a collection from a profile. It also adds the useful note that the operation is reversible via nuvio_undo. However, it does not explicitly mention alternatives or exclusion cases, such as using nuvio_remove_collection_folder for folders or nuvio_update_collection for modifications.

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 already marking this as destructive, the description discloses that the operation is irreversible, wipes all profile data, and requires a two-phase confirmation with a short-lived token. It also explains the exact call pattern: first call to obtain a token, second call to execute.

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-loads the destructive scope, then gives the warning and usage pattern. Minor redundancy exists: 'this cannot be undone' and 'This operation cannot be undone' repeat the same point.

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 destructive scope, irreversibility, Profile 1 restriction, and the two-phase token flow. It leaves the confirm parameter's role ambiguous and does not describe the response format of the first call, which an agent needs to reliably extract the 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?

The description clarifies confirmation_token's two-phase semantics and implies profile_index must be 2–6 by stating Profile 1 cannot be deleted. However, the schema's confirm parameter is left unclear: its description mentions 'reversible destructive changes,' which conflicts with this tool's irreversible nature, and the description never explains how confirm relates to confirmation_token.

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 precise verb and resource: 'Delete a profile and ALL of its data,' and enumerates the affected data categories (addons, settings, collections, library, history). It also adds the key constraint that Profile 1 cannot be deleted, clearly distinguishing this from profile creation/update 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?

It gives clear operational context: this is the whole-profile deletion path, including all associated data, and explicitly warns that Profile 1 is excluded. It does not name alternative sibling tools, but the exhaustive deletion scope makes the intended use 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?

Annotations already mark the tool as destructive, so the description adds value by disclosing that the previous state is snapshotted before the write and that nuvio_undo can revert the change. It does not contradict the annotations, and the confirm-based preview behavior is covered 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?

The description is two short sentences with no filler. The primary action is front-loaded, and the second sentence adds a useful safety detail about undo without bloating the text.

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 3-parameter destructive tool, the combination of annotations, schema, and description is largely sufficient. The description adds the undo/snapshot context, while the schema documents the confirm requirement and profile_id default. A slightly fuller mention of the preview-without-confirm behavior would make it fully 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 only 33%, so the description should compensate by clarifying parameters. It only loosely maps 'provider credential' to the provider parameter and 'profile' to profile_id, without explaining valid provider values or the role of confirm 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 uses a specific verb ('Remove'), a specific resource ('stored provider credential'), and a location ('from a profile'). This clearly distinguishes the tool from sibling tools like nuvio_set_provider_credential and nuvio_list_provider_credentials.

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

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

The description explains what the tool does but gives no explicit guidance on when to use it versus alternatives such as nuvio_set_provider_credential. It does not mention prerequisites, exclusions, or context where deletion would be inappropriate.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds valuable context: 'The previous state is snapshotted before the write; revert with nuvio_undo.' This transparently discloses the safety mechanism and recovery path, going beyond the annotation defaults.

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. The description leads with the operation, lists the key identifiers, and includes a reversibility note with a pointer to the undo tool. Every sentence earns its place with 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?

As a destructive operation, the description covers what is deleted and how to undo it, which is critical context. However, it does not explain the preview behavior when 'confirm' is false, nor does it mention any return value or side effects (e.g., whether season/episode deletions cascade). The overall context 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 description coverage is only 33%, so the description needed to compensate for the undocumented parameters. The tool description references content id, season, and episode, but does not explain the 'confirm' flag, keys array structure, or profile_id parameter. The schema carries most of the semantic burden with little help from the 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 states a specific action: 'Delete watch-history entries by content id (and season/episode).' This clearly identifies the resource and operation. It could further differentiate itself from nuvio_delete_watch_progress, 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?

The description implies the tool deletes watch-history entries, and the schema implies a preview/commit workflow via the 'confirm' parameter. However, it does not explicitly state when to use this tool versus nuvio_delete_watch_progress or nuvio_mark_watched. Usage context is mostly 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 destructiveHint=true and readOnlyHint=false, so the destructive nature is known. The description adds valuable transparency by stating that the previous state is snapshotted before the write and that revert is possible via nuvio_undo. This goes beyond annotation and is critical for a destructive operation. There is 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 two sentences: the first states the core action, the second provides the undo context. There is no redundant wording, and it is front-loaded with the primary purpose. Every 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?

For a destructive tool with three parameters, the description covers the key purpose, the undo mechanism, and hints at the preview behavior (via confirm). However, it doesn't explain the role of profile_id, which is a gap given that it's undocumented in the schema as well. Additionally, the output is not described, but there is no output schema. Since the core usage is clear and the undo context is provided, it is nearly complete but missing a small detail.

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%, which covers keys and confirm but not profile_id. The description says 'by progress key' which aligns with the 'keys' parameter, and mentions the confirm behavior (preview vs. destructive) which is helpful. However, profile_id is undocumented in both schema and description; the description could clarify that profile_id selects the profile context. Since coverage is high, baseline of 3 is appropriate.

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

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

The description clearly states the action (delete) and the resource (continue-watching entries identified by progress key), distinguishing it from related tools like 'delete_watch_history' and 'set_watch_progress'. The phrasing is specific 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?

The description implies this is for deleting continue-watching entries by key, and mentions a revert option via nuvio_undo, which helps in deciding when to use it. It doesn't explicitly contrast with sibling tools like delete_watch_history, but the key-based deletion is clear enough. A note about when to use confirm versus preview would improve it.

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 snapshots the previous state and supports revert via nuvio_undo. It also clarifies that the copy includes folders and catalog sources and is placed directly after the source, which helps set expectations.

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 concise sentences with no filler. The core behavior is front-loaded, and the snapshot/revert detail is added only after the primary 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 main effect, placement, and undo behavior, but lacks explicit semantics for new_title and profile_id, and there is no output schema. For a mutation tool with four parameters, this is adequate but 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?

The schema provides no field descriptions, and the description only indirectly maps to collection_id and new_id via 'copy a collection' and 'under a new id'. It does not explain new_title or profile_id, leaving 0% schema coverage mostly uncompensated.

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 a specific operation: copying a collection under a new id, including folders and catalog sources. It distinguishes this from simple creation or update by emphasizing duplication and placement after the source.

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 duplication use case is implied by the description, but there is no explicit guidance on when to choose this over nuvio_create_collection or other alternatives. The mention of revert with nuvio_undo is useful but not a direct usage guideline.

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 read-only and idempotent behavior; the description adds valuable operational detail by listing exactly which data domains are included and explicitly noting that credentials and tokens are excluded server-side. This is important security context that the schema and annotations 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 short sentences: the first front-loads the action, target, and output format, and the second adds the only caveat worth stating. 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 zero-parameter export tool with no output schema, the description is complete: it names the return format, lists the content scope, and discloses the sensitive exclusion. Nothing needed to invoke the tool correctly is 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?

The input schema has zero parameters and 100% coverage, so there are no parameter semantics for the description to enhance. The no-parameter baseline of 4 applies.

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

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

The description uses a specific verb ('Export') with a clear resource ('account data'), names the output format ('JSON backup'), and enumerates the included domains. This clearly differentiates it from the many granular list/get siblings and from nuvio_restore_backup.

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 tool is self-contained with zero parameters and the description makes its use case unambiguous: full-account backup rather than a granular read of one data category. It does not explicitly name alternatives or state when not to use it, so it stops 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 declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, so the safety profile is covered. The description's 'Read' wording is consistent with those annotations and adds no conflicts. It adds some context with 'home screen layout/catalog configuration', but does not describe return format or other behavioral details.

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 or redundancy. It is appropriately concise, but the terse phrasing sacrifices useful context that other dimensions (parameter semantics) could have provided.

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 2 parameters, no output schema, and read-safe annotations, so a rich description is not essential. However, the description does not mention what a caller receives (the actual settings structure) and leaves profile_id semantics vague. It is acceptable for a simple getter but has notable 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 description coverage is 50%; profile_id has no schema description and the tool description only says 'for a profile on a platform', without explaining the profile_id meaning or its 1–6 range. It does not compensate for the undocumented parameter and adds little beyond what the schema already provides.

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 verb ('Read') and resource ('home screen layout/catalog configuration'), scoped to 'a profile on a platform'. This distinguished it from mutating siblings like nuvio_update_home_catalog_settings or path-setting nuvio_set_home_catalog_path, though it doesn't explicitly cite those alternatives.

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 on when to use this tool versus alternatives such as nuvio_get_settings or when to prefer nuvio_update_home_catalog_settings. The 'Read' verb implies usage, but no explicit condition, exclusions, or alternative tool references 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=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, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds a little context by specifying that the result is a raw JSON settings blob rather than a parsed or filtered response, but it does not describe any other behavioral traits beyond that.

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 states the action, the resource, and the parameter scoping in under 120 characters.

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 tool with two optional parameters, the schema plus annotations cover most invocation details. The description adds the key output context ('JSON settings blob') despite lacking an output schema. It could be slightly more explicit about what the blob contains, but it is complete enough to guide 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 documents platform's allowed values but leaves profile_id mostly to type/min/max. The description's phrase 'for a profile on a platform' maps directly to the two parameters and helps disambiguate their roles, but it does not fully compensate for the missing profile_id explanation. With 50% schema coverage, this is adequate but not strong.

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 ('Read') and a precise resource ('the JSON settings blob for a profile on a platform'). It is clearly distinguished from siblings like nuvio_update_settings, nuvio_set_setting, and nuvio_get_home_catalog_settings by targeting profile settings specifically.

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 by the verb 'Read' and the settings-related sibling names, so an agent can infer this is the retrieval counterpart to mutation tools. However, there is no explicit statement of when to use this tool versus alternatives like nuvio_update_settings or nuvio_get_home_catalog_settings.

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 signal read-only, idempotent, and open-world behavior, so the bar is lower. The description adds that the entries are profile-scoped 'continue watching' entries, but it does not mention ordering, pagination, or output shape—acceptable but not exceptional.

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 clean, front-loaded sentence with no filler. It conveys the key facts quickly and is appropriately small for a simple 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?

For a two-parameter read-only tool, the combination of schema, annotations, and description covers purpose, safety, and profile scoping. It lacks an explicit statement of return shape or pagination, but the tool's simplicity makes this 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 phrase 'for a profile' gives profile_id contextual meaning beyond its name and default. The limit parameter receives no description-level explanation, and with 0% schema coverage the description 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?

States a specific verb ('List'), a specific resource ('continue watching' progress entries), and the scope ('for a profile'). This clearly separates it from sibling write/delete progress tools and from watch-history 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?

No guidance on when to choose this over nuvio_get_watch_history or the set/delete watch-progress tools. The intended selection context must be inferred entirely from the tool name and description, with no explicit exclusions or 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 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 already indicate readOnly=false, destructiveHint=false, but the description adds valuable behavioral context: the previous state is snapshotted before the write and can be reverted with nuvio_undo. This goes beyond annotations and helps the agent understand side effects and recovery.

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 main purpose, followed by usage condition and revert note. It is efficient but could have added a little more parameter context without becoming bloated.

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 complexity (7 params, no output schema, write operation), the description covers the key behavioral aspects: purpose, usage condition, and revert path. However, it omits parameter semantics for the non-obvious params (refresh_token, tracker_user_id, expires_in_seconds), which would help the agent build correct 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 14%, so the description should compensate, but it doesn't explain individual parameters beyond 'tracker OAuth tokens' and 'profile'. The schema already provides basic parameter descriptions for 'tracker' and 'access_token' but most parameters (username, profile_id, refresh_token, etc.) lack description in both schema and tool description. The description adds general context but not per-parameter meaning.

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 stores tracker OAuth tokens for a profile, with a specific verb ('Store') and resource ('tracker OAuth tokens'). It also distinguishes from the normal sign-in flow and mentions the sibling undo tool.

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 'Use this only when tokens were obtained out-of-band; prefer the app sign-in flow.' This is a clear when-to-use and when-not-to-use instruction, and it names the alternative flow even though not a sibling 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?

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, and the description adds concrete behavioral detail by specifying the fixed index range 1..6 and the exact data fields returned. This gives an agent useful expectations beyond the structured hints.

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 operation, scope, and output fields with no filler. Every part 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 parameterless read-only list tool with no output schema, the description completely covers what an agent needs to know: what it lists, the index range, and which fields are included. No critical information is 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?

The tool has zero parameters, so there are no parameter semantics to clarify. The description still adds value by describing what data the no-argument call returns.

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 verb ('List'), the resource ('all profiles'), and enumerates the returned fields: index 1..6, name, avatar, flags, and PIN lock state. This clearly distinguishes it from profile mutation tools like nuvio_create_profile or nuvio_delete_profile.

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 read-only enumeration nature makes its basic use clear, and the description implies it is the appropriate tool for inspecting all profiles rather than modifying them. However, it does not explicitly state when to choose this over sibling profile tools or mention any prerequisites or exclusion cases.

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?

Annotations already flag this as a mutating, non-idempotent write, and the description adds meaningful context: the previous state is snapshotted before the write and can be reverted with nuvio_undo. This goes beyond the structured fields and 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?

Two sentences, with the core action front-loaded and the undo behavior following immediately. There is no filler, and every phrase contributes useful 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 write and undo behavior are covered, but for a mutating tool with a nested object and no output schema, it leaves gaps around optional fields like `watched_at`, duplicate-entry behavior, and expected return value. It is minimally viable but not fully self-sufficient.

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 prose needed to compensate for parameter meaning, but it only loosely identifies `item` as the entry and `profile_id` as the profile. It leaves `content_type`, `watched_at`, `season`, and `episode` semantics to the schema, so an agent cannot fully construct a correct call from the description alone.

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

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

The description opens with a specific verb and resource: 'Add an entry to a profile's watch history.' This clearly distinguishes it from sibling get/delete watch-history tools and from watch-progress tools. The title reinforces the intent without carrying the definition.

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 explicit when-to-use versus alternatives, such as when to prefer nuvio_set_watch_progress or nuvio_get_watch_history. It mentions nuvio_undo for recovery, but that is a post-write fallback, not guidance for selecting this tool over 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 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 description clearly discloses that the operation cannot be undone, uses a two-phase prepare/execute flow, produces a short-lived token, and has backend validation on client_name. These traits go well beyond the annotations, which only state readOnly=false, idempotent=false, and destructive=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?

Three tight sentences front-load the purpose, then add the most decision-critical constraints (backend-accepted client_name, irreversibility, two-phase call flow). No filler or repetition of schema fields.

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 operation's irreersible nature, the confirmation-token flow, and return behavior (a token is produced on the first call), which is strong for a tool without an output schema. It leaves minor gaps such as exact token lifetime and semantics of the remaining self-explanatory parameters, but is otherwise 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 coverage is only 17%, so the description must compensate. It adds meaningful semantics for client_name (must be a backend-accepted value, with example) and confirmation_token (two-phase flow), but it does not explain platform, device_name, client_version, or the required installation_id beyond their 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: 'Register a device/installation against the account.' It also clarifies the operation's two-phase nature and backend constraints, making it distinct from the large sibling set of list/update/delete 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?

It establishes clear context for when to use the tool—registering a device/installation—and gives critical procedural guidance (valid client_name values, two-phase confirmation). It does not explicitly state when not to use it or name alternatives, but no direct sibling tool performs registration.

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 destructiveHint=true, but the description adds useful behavior beyond that: the previous state is snapshotted before the write and can be reverted via nuvio_undo. This gives the agent important information about recoverability that the 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 two tight sentences with no filler. The action verb is front-loaded, and the snapshot/undo note is valuable, compact context that 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 operation with four parameters and no output schema, the description covers the core action and undo safety but omits identifying-parameter semantics. The schema's confirm description helps, but the combination of id/url ambiguity and the absence of required-parameter guidance leaves the definition only minimally viable.

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%, with only 'confirm' documented in the schema. The description adds little parameter-level meaning: 'from a profile' hints at profile_id, but it does not explain how to identify the addon via 'id' versus 'url', whether one is required, or how profile_id is used. This is a meaningful gap for a tool with four undocumented 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 uses a specific verb ('Uninstall') and names the resource ('one addon from a profile'), making the operation unmistakable. It distinguishes itself from sibling tools like nuvio_add_addon, nuvio_toggle_addon, and nuvio_update_addon without needing to open 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 implies this is the tool for permanently removing an addon and mentions the undo path, but it does not explicitly state when to choose this over nuvio_toggle_addon or nuvio_remove_plugin. The usage context is inferable but not spelled out with alternative 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 declare destructiveHint=true and readOnlyHint=false, so the description's job is to add context. It does: it discloses that the previous state is snapshotted before the write and that revert is possible via nuvio_undo. This is valuable behavioral context beyond the annotations. It does not contradict annotations. The only minor gap is not explaining what happens to the folder's contents or whether the removal is permanent if not undone, but the snapshot mention covers the key safety behavior.

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 core action is stated first, and the safety net (snapshot/undo) is added in the second sentence. 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 destructive tool with annotations covering the safety profile and a description adding the snapshot/undo behavior, the definition is largely complete. There is no output schema, but the description doesn't need to explain return values for a simple removal action. The only missing context is what the preview looks like when confirm is false, but the schema description for confirm already mentions that a preview is returned. Overall, an agent has enough to call this 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?

Schema description coverage is only 25% (only the 'confirm' parameter has a description). The description does not explain the parameters beyond the schema. However, the parameter names (collection_id, folder_id, profile_id, confirm) are fairly self-explanatory, and the confirm parameter's schema description already explains its role. The description adds no extra meaning about parameter semantics, so a baseline 3 is appropriate given the low coverage but self-evident 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 states a specific verb and resource: 'Remove a folder from a collection.' This clearly distinguishes it from sibling tools like nuvio_add_collection_folder and nuvio_update_collection_folder. It could be slightly more explicit about the scope (e.g., that it removes a folder within a collection, not the collection itself), but the title and description together are 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 usage context by mentioning that the previous state is snapshotted and revert is possible with nuvio_undo, which hints at when this tool is appropriate (destructive removal with undo safety). However, it does not explicitly state when to use this tool versus alternatives like nuvio_delete_collection or nuvio_remove_addon. The mention of nuvio_undo is a useful pointer but not a full usage guideline.

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 destructive and not read-only. The description adds valuable context by disclosing that the previous state is snapshotted before the write and can be reverted with nuvio_undo, giving the agent a clear safety profile beyond the raw annotations. 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 sentences with no filler. The core action and key identifiers are front-loaded, and the snapshot/undo note is a useful, compact addition.

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 3-parameter tool with no output schema, the description covers the core action and undo safety, and annotations handle the destructive profile. However, it omits the confirm/preview requirement and does not describe return behavior or side effects, so the agent must rely on the schema for the full invocation contract.

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 'confirm' has a description). The description helps by naming content_id and content_type and by indicating the operation targets a profile's library, which maps to profile_id. However, it does not explain the confirm/preview gate or content_type value semantics beyond what the schema already provides.

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 ('Remove'), a clear resource ('items from a profile's library'), and the identifying parameters ('content_id + content_type'). This cleanly distinguishes it from sibling tools like nuvio_add_to_library and nuvio_get_library.

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

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

Usage is implied by the explicit remove action, but the description does not state when to choose this over alternatives such as nuvio_add_to_library or nuvio_get_library. The only related guidance is 'revert with nuvio_undo', which is post-action advice rather than tool-selection guidance.

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, so the description's job is lighter. The description adds valuable context: the previous state is snapshotted before the write and can be reverted with nuvio_undo. This goes beyond the annotations by explaining the safety net. It does not contradict the annotations. It could mention that confirm is required for the destructive change, but the schema already covers that.

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 filler. The core action is front-loaded, and the undo/revert information is placed second, which is the most important behavioral note. 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 destructive tool with annotations and a schema, the description is mostly complete. It explains the action, the profile scope, and the undo mechanism. It does not explain what the 'url' parameter refers to or what a preview looks like when confirm is false, but the schema's 'confirm' description covers the preview behavior. The lack of an output schema is acceptable for a mutation tool. Minor gap: no explicit statement that the plugin must be installed or what happens if it isn't.

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 'confirm' has a description). The description does not explain the 'url' parameter or 'profile_id' beyond what the schema provides. The 'url' parameter is required but its meaning (likely the plugin URL or identifier) is not clarified. The description adds no parameter-level detail, so it does not compensate for the low schema coverage. Baseline 3 is appropriate because the schema does provide some structure and types.

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 ('Uninstall') and resource ('a plugin from a profile'), which clearly distinguishes it from sibling tools like nuvio_add_plugin, nuvio_toggle_plugin, and nuvio_reorder_plugins. The title 'Remove a plugin' is reinforced with more precise language, and the profile context is 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 implies the tool is for removing plugins from profiles, and the sibling list shows related plugin tools (add, toggle, reorder) that an agent could confuse it with. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention prerequisites like needing a profile_id or that the plugin must already be installed. The undo hint provides some usage context but not a full when/when-not.

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 behavioral context beyond the annotations by disclosing that 'The previous state is snapshotted before the write; revert with nuvio_undo.' This gives the agent insight into undo/revert capability and a snapshotting side-effect that the annotations alone do not convey, without contradicting the `readOnlyHint: false` or `destructiveHint: false` 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 short sentences, each adding value: purpose, required input semantics, and revert behavior. No filler words or redundant restatement of the title; the key constraint is 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?

The description is complete enough for a simple write tool with two parameters and no output schema: its behavior, the meaning of `ordered_urls`, and a revert path are covered. The only notable gap is the undocumented `profile_id` semantics, but the schema provides its name, type, default, and range, so an agent can infer meaning without 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?

Schema description coverage is 0%, so the description must compensate. It explains `ordered_urls` fully: it must include every installed addon URL exactly once, in the desired order. However, it does not mention `profile_id`, leaving the agent to rely on the schema's type, default, and constraints. The partial compensation gives a score of 3, not 5.

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: 'Set the display order of a profile's addons.' This clearly identifies what the tool does and, combined with the sibling names `nuvio_reorder_plugins` and `nuvio_reorder_collections`, an agent can distinguish it from other reorder tools before opening any schema.

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 operational guidance, telling the caller to 'Provide every installed addon URL exactly once, in the desired order.' However, it does not explicitly state when to use this tool versus the sibling reorder tools or mention any exclusions; the usage context is implied rather than stated.

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 write operation with readOnlyHint=false. The description adds valuable behavioral context: the previous state is snapshotted before the write and can be reverted with nuvio_undo, which is a meaningful safety property not present in the annotations. It also communicates the exact-once constraint, giving the agent expectations about input validation.

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 tight sentences: it front-loads the operation, then states the critical input rule and the undo safety net. Every sentence earns its place with no redundant 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 simple reorder operation with two required parameters and no output schema, the description is nearly complete: it covers the exact composition of ordered_folder_ids)Skip, the collection scope, and the rollback mechanism. The main gaps are the absence of any note about profile_id and no mention of what the tool returns after a successful reorder.

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. It clearly explains ordered_folder_ids as the complete list of folder ids in the desired orderched and implies that collection_id refers to the target collection. However, profile_id is not mentioned, and no types or formats are clarified beyond what the schema already states.

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 'Set folder order,' a specific verb and resource, and the title identifies the scope as folders in a collection. This distinguishes it from sibling tools like nuvio_reorder_collections, which reorders collections, and nuvio_update_collection_folder, which updates a single folder rather than the whole ordering.

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 use case by saying 'Set folder order' and gives a key operational rule: every folder id must be supplied exactly once. However, it does not explicitly state when to prefer this tool over siblings such as nuvio_reorder_collections or nuvio_update_collection_folder, nor does it mention any 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?

The description adds meaningful behavioral context beyond annotations by disclosing that the previous state is snapshotted before the write and that the operation can be reverted with nuvio_undo. This is especially useful given readOnlyHint=false and no destructive hint.

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. Three short sentences deliver the core action, the exact input requirement, and the undo behavior with 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 covers the essential contract: what the tool does, how ordered_ids must be provided, and how to revert. It lacks explicit mention of profile_id's role and does not reference how to obtain the collection id list, but the tool remains usable with schema clues and 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?

With 0% schema description coverage, the description must compensate. It nicely explains the required 'ordered_ids' parameter as a complete ordering of every collection id exactly once, but it does not explain 'profile_id' or how it scopes the reorder, leaving one parameter under-specified.

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 clear verb-resource pair: 'Set collection order' and explains the desired effect. It is distinguishable from sibling reorder tools by naming 'collections' specifically, though it does not explicitly contrast with nuvio_reorder_collection_folders.

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

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

It gives clear operational guidance: provide every collection id exactly once in the desired order. It does not name alternatives or explicitly state when not to use it, but the context is clear enough for selection among sibling 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?

The description discloses that the previous state is snapshotted before the write and that the operation can be undone with nuvio_undo. This adds useful behavioral context beyond the annotations, which only indicate readOnlyHint=false, idempotentHint=false, and 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?

The description is three short sentences with no filler. It front-loads the core purpose, then states the critical input constraint and the undo 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 main operation and undo path, but it omits the meaning of profile_id and does not mention that the plugin list may be scoped to a specific profile. Since there is no output schema and parameter descriptions are absent, this leaves a meaningful gap 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 explains ordered_urls well: it must contain every installed plugin URL exactly once, in the desired order. However, profile_id is not mentioned at all, and schema description coverage is 0%, so the description only partially compensates for the missing 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 states the exact action ('Set plugin order') and resource ('plugins'), and immediately clarifies the key requirement: provide every installed plugin URL exactly once. This distinguishes it from sibling reorder tools like nuvio_reorder_addons and nuvio_reorder_collections.

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 context: the caller must supply the complete set of plugin URLs exactly once, and can undo via nuvio_undo. It does not explicitly mention alternatives or when not to use the tool, but the usage condition is concrete enough to guide 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 (destructiveHint=true, readOnlyHint=false), the description adds critical context: what gets overwritten, that the operation cannot be undone, that it requires a short-lived token, and that execution requires a second call. This substantially exceeds what annotations alone 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?

Three sentences, each carrying distinct value: purpose, availability, risk, and procedure. No filler or redundant restatement of the tool name.

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 complex destructive tool, the description covers availability, risk, irreversibility, and the two-phase execution flow. It does not clarify how the 'confirm' boolean in the schema relates to the token-based confirmation, and with no output schema it leaves the second call's response unspecified, but the essential call sequence is clear.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds 'short-lived' for the token and ties the backup parameter to nuvio_export_backup, but the schema already says the backup comes from that tool and already explains the two-phase token flow. The confirm parameter's role is not clarified by the 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 states a specific verb ('Replace account data') and resource ('account data from a backup produced by nuvio_export_backup'), clearly distinguishing this from the many sibling tools. It also names the exact data domains overwritten, leaving no ambiguity about what the tool does.

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 provides a clear availability condition ('Only available on self-hosted backends that expose sync_restore_account_backup') and a precise two-phase calling procedure. It does not explicitly contrast with alternative tools like nuvio_undo, but the operation is unique enough that the guidance is still 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 destructiveHint and non-read-only behavior, but the description adds a distinct irreversibility warning, explains that the device must re-authenticate, and discloses the two-phase confirmation flow with a short-lived token. These details go beyond what the annotations state, and nothing 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 front-loaded and only a few sentences long, but it repeats "cannot be undone" twice and says "Never deletes the account" after already implying the account remains intact. The redundancy is distractible given the same point is made in consecutive sentences.

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 explains the two-phase confirmation process and the key irreversible consequence, but it leaves the `confirm` parameter unexplained and does not mention whether a preview is returned on the first call. For a destructive, irreversible tool with no output schema, it could usefully state the exact state expected on each of the two 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?

With 67% schema description coverage, the schema already documents `confirm` and `confirmation_token`. The description adds meaningful use-order semantics (first call prepares, second call executes with token), but it does not clarify the role of `confirm`, and `session_id` must still be inferred as the target session. It partially compensates for the undocumented 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 opens with a specific verb and resource: "Revoke one login session (log that device out)". It further clarifies the scope by stating it "Never deletes the account", which distinguishes it from account-level destructive tools in the sibling list.

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

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

It gives relevant context by saying the device must sign in again and that the account is not deleted, but it never references sibling tools like nuvio_list_sessions or explicitly says when to use this instead of another session-related tool. The recommendation that this is a device logout is clear, but documented alternatives are missing.

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 valuable behavioral context beyond the annotations: the previous state is snapshotted before the write and can be reverted with nuvio_undo. This is a meaningful disclosure for a mutating tool. It does not cover return behavior or invalid paths, but the snapshot/undo detail is a strong contribution.

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 filler. The first sentence states the operation and mechanism, and the second gives the key undo behavior. Information is front-loaded and 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 is short and clear but does not cover behaviors that could affect correct invocation: whether missing nested objects are created, whether the path must pre-exist, what happens on invalid paths, or how platform/profile scoping applies. It relies heavily on schema defaults and annotations, which are sparse for a 4-parameter mutation tool.

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 25%, the description partially compensates by explaining that `path` is a dot path and `value` is a nested value inside the blob. However, it does not clarify how `platform` or `profile_id` affect the target, nor what types or path shapes are accepted for `value`.

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: setting one nested value inside the home catalog settings blob via dot path. This clearly differentiates the tool from broader operations like nuvio_update_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 says what the tool does but not when to prefer it over alternatives. It would be clearer to explicitly contrast it with nuvio_update_home_catalog_settings or state that it is meant for a single nested value change. No exclusion or alternate routing 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 already signal destructive intent, but the description adds meaningful behavioral disclosure: the operation is irreversible, the PIN hash is never returned, and a two-phase confirmation token flow is required. This significantly enriches the agent's understanding 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 short and front-loaded with the purpose faction. However, 'Not reversible' and 'cannot be undone' are redundant, and the two-phase flow could be tightened. Still, all sentences add useful information overall.

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 two-phase workflow and irreversibility, which are the most critical aspects for a destructive tool. However, with no output schema and low parameter coverage, an agent will have to infer what the first call returns besides a token, and the meaning of current_pin and confirm is insufficiently specified.

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 40%, so the description must compensate. It explains the confirmation_token and the two-phase prepare/execute flow, but it does not clarify the semantics of current_pin (e.g., required when changing an existing PIN) or profile_index beyond what the schema implies. Partial compensation for an under-documented 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 and resource: 'Set or change the PIN lock on a profile.' This clearly distinguishes the tool from the sibling nuvio_clear_profile_pin, since the purpose is setting/changing rather than locking/clearing.

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 it clear this is the tool to use for setting or changing a profile PIN, and it explains the two-phase invocation pattern. It does not explicitly contrast with nuvio_clear_profile_pin or document when not to use it, but the primary use context is 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?

Annotations already indicate it is a write (not read-only) and not idempotent. The description adds valuable behavior: it snapshots the previous state and explicitly points to nuvio_undo for reverting, which is not inferable from the annotations. This gives the agent a clear picture of the operation's mutability and reversibility.

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 purpose and immediately gives the provider enumeration. The snapshot/revert note is concise and placed after the primary action, making it easy to parse without clutter. 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 credential-setting tool with no output schema, the description covers the essential operational aspects: what providers are accepted, the key type distinction, and the undo path. The profile_id parameter is left to the schema, which is acceptable given its default and bounds. The description does not mention success/error behavior, but that is minor for a simple write 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?

The schema describes api_key and provider with brief text, but the description enriches the provider parameter by listing exact accepted values (debrid:torbox, tmdb, etc.) and distinguishes that animeskip requires a client id rather than an API key. This compensates for the lack of an enum and adds meaning beyond the schema. profile_id is not mentioned, but its schema includes default and range, so the 67% coverage is partially mitigated.

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 ('Store') and a specific resource ('an API key for a provider'), and enumerates the allowed providers, which makes the purpose unambiguous. It clearly differentiates from siblings by implying a write operation (store) versus list/delete, so an agent can distinguish it from nuvio_list_provider_credentials and nuvio_delete_provider_credential.

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 like nuvio_delete_provider_credential or nuvio_list_provider_credentials. It mentions revert with nuvio_undo, but that is about recovery, not about choosing the tool. There is no explicit context like 'use this to set a new credential' or 'use delete to remove'.

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 behavioral detail beyond annotations: it creates intermediaries and snapshots the previous state for nuvio_undo. The annotations already indicate this is not read-only and not idempotent, but the description enriches the mutation model with reversible write behavior.

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 no filler. The core purpose and path examples are front-loaded, and the undo/rollback behavior is provided as a short follow-up. Every sentence contributes information an agent needs.

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 four-parameter setter with no output schema and annotations already covering read-only/idempotent/destructive traits, the description is sufficiently complete: it explains the path syntax, creation behavior, and undo path. It could mention `platform` and `profile_id` more explicitly, but the schema already supplies those details.

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 value for the primary path parameter with dot-path examples and semantics for creating intermediate objects/arrays, going beyond the schema's brief 'Dot path into settings_json.' Platform and profile_id remain schema-managed with defaults and explanations, and overall schema coverage is 75%, so the description does not need to duplicate every 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 and resource: 'Set one nested value by dot path,' with concrete examples. This clearly distinguishes the tool from sibling tools like nuvio_update_settings, which implies a broader settings update, and nuvio_unset_setting.

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 enough usage context by explaining dot-path semantics and noting that intermediate objects/arrays are created. However, it does not explicitly contrast this tool with nuvio_update_settings or nuvio_unset_setting, leaving when-not-to-use guidance 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 adds meaningful behavioral context beyond the annotations by disclosing that the previous state is snapshotted before the write and that the change can be reverted with nuvio_undo. This is useful for a non-read-only, non-idempotent tool and goes beyond what readOnlyHint/destructiveHint alone 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 tightly written in two sentences, with the primary purpose front-loaded and the important undo behavior appended. Every sentence provides useful information without restating the tool name or 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?

The description is adequate for a mutation tool given the annotations and the undo note, but it lacks important context for full usability. It doesn't explain the meaning of profile_id, whether unspecified parameters preserve or reset existing settings, or what the tool returns after execution.

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 maps 'statuses sync' to enabled_statuses, 'row order' to row_order, and 'progress syncing' to send_progress, which adds meaning. However, profile_id is left unexplained, and the description doesn't clarify how omitted parameters behave.

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 a specific verb ('Set') and resource ('tracker settings'), and lists the aspects being configured: statuses to sync, row order, and progress syncing. It also scopes the tool to a 'linked tracker', which separates it from generic settings tools, though it doesn't explicitly name sibling alternatives.

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 provided about when to use this tool versus alternatives such as nuvio_update_settings, nuvio_set_setting, or tracker linking/unlinking tools. The phrase 'for a linked tracker' implies a prerequisite, but there is no explicit when/when-not or alternative 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-readonly, non-destructive operation. The description adds valuable behavioral context by disclosing that the previous state is snapshotted before the write and that it can be reverted with nuvio_undo. It also clarifies the upsert nature ('create or update'). 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 sentences, no fluff. The primary purpose is front-loaded in the first sentence, and the second sentence adds a critical behavioral detail (snapshot/undo). 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?

The tool has a nested entity and 2 parameters, and the description covers the core purpose and undo behavior. However, it does not explain the required fields for different content types (movie vs episode) or the profile_id parameter. With no output schema and 0% parameter coverage, this leaves gaps for an agent constructing a valid 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 only mentions 'position/duration' and 'movie or episode', which hints at the content_type and two fields, but it ignores the nested entry object's other properties (season, episode, video_id, last_watched) and the profile_id parameter. The description adds minimal value beyond the schema field 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 states a clear verb ('Create or update') and a specific resource ('continue-watching entry'), plus the scope ('for a movie or episode'). This distinguishes it from sibling read/delete tools like nuvio_get_watch_progress and nuvio_delete_watch_progress, so an agent can immediately tell what it does.

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 recording a position/duration, but it does not explicitly contrast it with alternatives like nuvio_mark_watched (which likely marks as fully watched) or nuvio_get_watch_progress. It gives context (snapshot/undo) but no explicit 'use this when...' or 'instead of...' guidance.

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.

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

For a zero-parameter, read-only overview tool with strong annotations and no output schema, the description is sufficient to invoke the tool correctly. It names all content areas included in the counts, and nothing else is needed to perform 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?

The tool accepts zero parameters, so parameter semantics are non-applicable; the baseline of 4 applies. The description does not need to compensate for undocumented parameters and does not try to add any.

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 resource ('profiles, addons, plugins, library items, watch progress and history') and the nature of the output ('summary counts'), which together identify it as the aggregate overview tool. The title 'Get data overview' reinforces the verb+resource, but the description itself is a noun phrase rather than a clear verb-led action, and it does not explicitly distinguish itself from the many sibling list 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 summary-count wording implies this tool is for aggregate numbers rather than detailed item listings, so a capable agent can infer when to use it. However, the description gives no explicit 'use this instead of X when...' guidance and does not name any alternative, leaving the selection to inference.

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 that this is a non-read-only, non-idempotent mutation. The description adds valuable extra behavior: the prior state is snapshotted before the write and can be reverted via nuvio_undo. This gives the agent important safety context beyond the structured hints. It does not fully describe side effects or failure modes, but it is solid for a 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?

Two sentences, no filler, and the primary action is front-loaded. The second sentence provides a useful operational caveat without bloating the description. 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?

The core action and undo behavior are documented, and the schema provides parameter names, types, and constraints. However, the tool has no output schema and no parameter descriptions, leaving the relationship among id, url, and profile_id implicit. An agent could plausibly call it incorrectly because identifying the target addon is not fully specified. This makes the definition adequate but not 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 0%, so the description carries the burden of explaining parameters, but it only maps 'on or off' to enabled and 'profile' to profile_id. It does not clarify how id versus url identifies the addon, whether one or both are needed, how profile_id relates to the target, or what the optional parameters mean. The description adds minimal semantic value beyond parameter 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 states a precise action ('Turn one addon on or off') and a specific resource scope ('for a profile'), clearly distinguishing it from addon lifecycle siblings like nuvio_add_addon, nuvio_update_addon, and nuvio_remove_addon. The title reinforces the same behavior. There is no ambiguity about what operation this 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?

The description gives clear context for when to use this tool: when you want to enable or disable a single addon for a profile. It does not explicitly reference alternatives like nuvio_update_addon, nor does it state exclusions, but the focused verb and scope make the intended use reasonably evident. It stops short of fully routing the agent among the many addon-related 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 indicate a non-readonly, non-idempotent write. The description adds valuable context beyond annotations: the previous state is snapshotted before the write and can be reverted via nuvio_undo, signaling reversibility without contradicting 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, ~25 words, no fluff. The core action is front-loaded and the snapshot/undo behavior is stated in the second sentence 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?

For a simple toggle with no output schema, the description covers the essential behavior, scope, and reversibility. It doesn't explain return values or prerequisites like whether the plugin must already exist, but the sibling list and tool name imply those. Good enough for an agent to invoke 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 schema has 0% description coverage, so the description must compensate. It maps overall semantics well ('one plugin' → url, 'on or off' → enabled, 'profile' → profile_id), but it doesn't clarify what URL format is expected or that profile_id defaults to 1. It partially compensates but leaves some param-level ambiguity.

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 ('Turn... on or off') with a clear resource ('one plugin') and scope ('for a profile'). This immediately distinguishes it from siblings like nuvio_toggle_addon and nuvio_add_plugin/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?

Clear context: this toggles an existing plugin's enabled state for a specific profile. It doesn't explicitly exclude add/remove operations, but the plugin/profile framing makes the intended use obvious, and the undo pointer adds practical guidance.

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 a valuable behavioral detail beyond the annotations: 'Snapshots the current state first, so an undo can itself be undone.' This explains side effects and reversibility, which is important context given readOnlyHint=false and idempotentHint=false. No contradiction with annotations; destructiveHint=false is consistent with the reversible nature described.

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 three short sentences, each conveying essential information: the action, the default, and the side-effect. No filler or redundant wording, and the most important detail is 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?

For a simple tool with one optional parameter, the description covers the operation, default behavior, and a key side-effect. It could mention return values (since there is no output schema), but the absence is minor given the simplicity and the presence of annotations providing safety context.

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%: the snapshot_id parameter is fully described in the schema ('Snapshot id from nuvio_list_undo. Omit to undo the most recent change.'). The tool description restates the default behavior but adds no new parameter semantics beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states a specific action ('Revert a previous change') and a mechanism ('using its snapshot'), with the default behavior also specified. It does not explicitly contrast itself with sibling tools like nuvio_redo or nuvio_list_undo, 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?

The description implies when to use the tool (whenever you need to undo a previous change) and the schema adds that snapshot_id comes from nuvio_list_undo. However, it provides no explicit when-not-to-use guidance or alternatives, such as pointing to nuvio_redo or nuvio_inspect_snapshot for related use cases.

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; the description goes beyond by specifying what is destroyed (stored tokens) and disclosing the safety mechanism — the previous state is snapshotted before the write and can be reverted via nuvio_undo. This adds decision-relevant context about reversibility that annotations do not carry.

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: the first states the core action, the second discloses the snapshot/undo safety behavior. No redundant phrasing or schema repetition; essential information is 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?

For a destructive 3-param tool with no output schema, the description plus annotations cover what is removed, that it is destructive, that a preview is returned without confirm (via schema), and how to revert. The only gap is the undocumented profile_id parameter and no mention of what the preview/response looks like.

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% — confirm and tracker are described in the schema, so the description need not repeat them. However, the description adds no parameter-specific guidance and does not compensate for profile_id's missing schema description; 'on a profile' only weakly hints at profile_id's role. Baseline 3 is appropriate.

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

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

States a specific action — 'Remove stored tokens for a tracker on a profile' — with a precise verb, resource (stored tokens), and scope (profile). This differentiates it from siblings like nuvio_link_tracker (the reverse operation) and nuvio_set_tracker_settings (configuration, not credentials).

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 intent clear: remove stored tracker credentials from a profile, implying when to reach for it (when unlinking a tracker relation). It does not explicitly name the counterpart nuvio_link_tracker or state when not to use it, so clear context without explicit exclusions keeps it at a 4.

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 a write rather than destructive. The description adds the key behavior that the previous state is snapshotted before the write and that nuvio_undo can revert it, which justifies the non-destructive classification and gives the agent a recovery path.

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 filler: the first states the operation and mechanism, the second states the snapshot/undo behavior. The most important information is front-loaded and 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 simple single-path mutation, the combination of description and schema is nearly complete: it defines the path mechanism, the platform default and allowed values, and the undo path. It does not state behavior when the path doesn't exist or describe the return value, but those are minor for this tool, especially with 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 description coverage is only 33%, with platform documented in the schema but path and profile_id not described. The description adds meaning only to path ('dot path') and says nothing about what profile_id selects or how platform scopes the settings blob, so it fails 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 opens with a specific action ('Delete'), a precise resource ('one nested value' in 'the settings blob'), and the mechanism ('by dot path'). This clearly distinguishes it from siblings like nuvio_set_setting without requiring schema 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 description implies when to use it: to remove a single nested setting rather than set or bulk-update settings. However, it never explicitly names alternatives or gives exclusion criteria, leaving the routing partly to inference.

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 a non-read-only, non-idempotent, non-destructive write. The description adds meaningful behavioral context: the previous state is snapshotted before the write and can be reverted via nuvio_undo. This goes beyond the structured annotations and helps the agent understand the operation's reversibility.

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-loaded with the updateable fields, followed by identification and undo behavior. No filler or redundant restatement of the tool name/title.

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