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

Annotations already declare readOnly, idempotent, non-destructive, and open-world, so the safety profile is covered. The description adds real value beyond that: it discloses the enforced rejection of mutating paths, the relative-path convention, and that pagination rides in the parameters object. It does not describe error behavior for rejected or unknown paths.

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 information: scope with examples, the mutation guardrail, and the two parameter conventions. Front-loaded with the purpose and free of filler, though the example list is slightly long for the value it adds.

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 an open-world raw-API passthrough, the description covers usage, safety, and path conventions, and an output schema exists so return values needn't be explained. What's missing is how an agent discovers valid endpoints (e.g. via tvh_get_schema) and what a rejected path returns, which matters for a catch-all reader.

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 carry the load. It does explain that 'path' is relative without '/api/' and that pagination goes into 'parameters', which is genuinely helpful. But it leaves the path format (leading slash? .json suffix?) and the shape of the parameters object undocumented in both schema and 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?

States a specific verb (Read) and resource (metadata/enum/grid endpoints) and enumerates concrete examples like bouquets, EPG grabbers, and stream profiles. The word 'additional' signals these are endpoints not covered by the dedicated list_* siblings, though it never names a sibling explicitly.

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

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

It gives one clear exclusion – 'Mutating endpoints are rejected' – and implies the tool is for endpoints lacking a dedicated wrapper. However, it never tells the agent to prefer tvh_list_channels or tvh_list_dvr_rules when those exist, so the routing decision against ~38 siblings is 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?

The description adds substantial behavioral context beyond the annotations: plans expire after 15 minutes, real executions consume the plan ID, stale or invented plans are rejected, active inputs/subscriptions cause refusal, inventory and node fields are rechecked, and guarded rollback is attempted on partial failure. It also warns that this is not an atomic transaction or full backup and instructs the caller to keep the recovery_snapshot. These details are consistent with the destructive and non-idempotent 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 compact and front-loaded, starting with the core action and default preview behavior. The second paragraph is dense with relevant operational constraints and contains no wasted 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?

For a destructive, non-idempotent mutation tool, the description covers the critical safety and operational behaviors: expiry, ID consumption, validation, refusal conditions, rollback behavior, and snapshot retention. An output schema exists, so return values need not be explained in detail, and the description still highlights the key recovery artifact.

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 0%, the description carries most of the parameter semantics. It explains the origin, expiry, one-time use, and rejection conditions for plan_id. It also implies the dry_run default and contrast between preview and actual execution, though it does not explicitly name the dry_run 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: apply a reviewed maintenance plan from this MCP process. It also distinguishes preview versus execution through the default dry-run behavior. It does not explicitly name sibling planning tools or alternatives, so it falls short of full sibling differentiation.

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

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

The description implies usage by referring to previously reviewed plans and stating that previews happen by default. It also explains execution semantics such as ID consumption and stale-plan rejection. However, it does not explicitly say when to use this tool versus alternatives such as restore_snapshot or the planning tools, and it does not name exclusions beyond runtime refusal 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 destructive=true, openWorld=true, and non-idempotent, so the baseline is covered. The description adds meaningful behavioral context: add preserves existing sources, while empty replace explicitly clears them, and source IDs are non-UUID enum keys.

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: purpose and mode behavior come first, followed by the critical source-ID format and empty-replace behavior. Every sentence adds 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?

With annotations covering safety traits and an output schema covering return values, the description supplies the key missing details: source ID format/origin and mode semantics. The main gap is that dry_run is never mentioned despite being relevant to a destructive 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 0%, so the description must carry parameter meaning. It explains source_ids as enum keys from get_field_options and clarifies mode behavior, but it does not explain dry_run or channel_uuid, leaving a meaningful gap for a mutation 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: assign advertised EPG source IDs to a channel. It also distinguishes the add mode's preservation behavior, which helps separate it from other EPG configuration siblings.

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

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

It gives useful mode guidance for add and empty replace, and points to get_field_options for source IDs, but does not explicitly say when to use this tool instead of alternatives such as list_epg_sources or get_epg_config. The remove mode is not explained either.

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, readOnlyHint=false, idempotentHint=false, and openWorldHint=true. The description adds meaningful semantics beyond that: 'add' preserves existing assignments, 'replace' replaces them, and 'remove' removes only the listed networks. It does not explain dry_run or permission requirements.

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 definition is front-loaded with the core action, then moves efficiently into DVB-C/T vs DVB-S guidance and mode behavior. Four sentences with little waste, though 'network_a/network_aa etc.' is slightly vague and could be tighter.

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?

Output schema exists, so return values need not be explained, and annotations cover the safety profile. The description covers field and mode well but omits dry_run, which matters for a destructive operation because an agent may not realize it can preview changes.

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 carry the burden. It clarifies field selection (frontend.networks vs satellite input nodes), mode semantics for add/replace/remove, and implicitly what hardware_uuid and network_uuids mean. The dry_run parameter is never mentioned, leaving one of five parameters unexplained.

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 ('Assign networks') and adds scope ('to the exact frontend or satellite-input node that owns the field'). It is clearly distinct from tvh_assign_services by resource, but it does not name a sibling or explicitly contrast with one, which keeps it below 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?

It gives concrete conditional guidance: 'For DVB-C/T use frontend.networks' versus 'For DVB-S inspect the hardware tree' where fields like network_a/network_aa may live. It also says to use field options to match supported network types. It lacks explicit when-not-to-use guidance or named alternatives.

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

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

Annotations already flag destructiveHint=true, idempotentHint=false and openWorldHint=true, so the risk profile is largely covered. The description contributes one genuinely useful behavioral fact — add mode preserves existing mappings — but says nothing about what replace/remove destroy or how dry_run changes 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?

A single tight sentence with the operation and the key scoping caveat front-loaded; nothing is wasted. It is short to a fault, but not padded or disorganized.

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 destructive, non-idempotent mutation on live channel configuration with an output schema available, and four parameters at 0% schema coverage. The description omits the dry_run escape hatch and the destructive effect of replace/remove, leaving an agent with an incomplete picture before a risky write.

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 0%, so the description must carry the parameter burden. It does clarify that add mode preserves other mappings, but it never explains dry_run, nor what service_uuids means in remove/replace mode (e.g., whether an empty list is valid), and simply echoes the enum values already in the schema.

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

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

States a specific verb set (add/replace/remove) applied to a concrete resource ('a channel's service mappings'), so an agent knows exactly what is mutated. It doesn't contrast itself with the closely related sibling tvh_map_services, so sibling differentiation is only implicit.

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 modes imply when each behavior applies, and it notes that add mode preserves other mappings, which hints at the add-vs-replace choice. But there is no explicit when-to-use/when-not guidance and no mention of when to prefer tvh_map_services or a dry run first.

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 destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavioral context: regional names stay distinct, HD suggestions are name-only hints rather than proof of duplicate programme, and nothing is merged or deleted.

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 action is front-loaded in the first sentence and each following sentence carries a distinct caveat about how to interpret the report. Slightly fragmented layout, but no wasted 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?

With no parameters, an output schema present, and full annotation coverage, the description supplies what is missing: the interpretive caveats about regional names and HD hints. An agent can call it correctly and read the results sensibly.

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, so the schema baseline of 4 applies; there is nothing further the description needs to explain about 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 states a specific verb ('Read all channels/services and report') and the exact outputs it produces: duplicate names, HD/SD candidates and problems. This clearly marks it as a diagnostic audit rather than a plain listing, distinguishing it implicitly from tvh_list_channels, though it never names that sibling.

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 diagnostic framing implies when to reach for it (when hunting duplicates or HD/SD issues), and 'No automatic merging, numbering or deletion' signals it is investigation-only versus tvh_plan_channel_merge. However, no explicit when-to-use or when-not-to-use instruction is 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=false, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds no behavioral context such as what dry_run does, whether creation is reversible, or whether auth/permissions are required. It does not contradict the annotations, but it contributes almost nothing beyond them.

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

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

A single front-loaded sentence with no wasted wording. The trailing 'etc.' weakens precision slightly, but the definition is appropriately sized for a short tool 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?

This is a create operation with a nested, loosely typed settings object at 0% schema description coverage, and the description does little to fill that gap. The output schema covers return values and annotations cover safety, but dry_run behavior and the full structure of settings remain unexplained for a fairly complex mutation.

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 0%, so the description carries the burden. It partially compensates by naming settings fields ('name, number, services UUID array, tags, EPG settings'), which helps populate the nested settings object. However, it never mentions the dry_run parameter and uses a vague 'etc.', leaving the semantics of both parameters incomplete.

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

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

States a specific verb and resource ('Create a channel') and enumerates the key fields involved, which clearly distinguishes it from read-oriented siblings like tvh_list_channels. The 'etc.' leaves scope slightly open, 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 gives no when-to-use guidance, prerequisites, or alternatives. It does not say when to prefer this over related creation tools (e.g. tvh_create_channel_tag) or what conditions must hold before creating a channel.

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, idempotentHint=false and openWorldHint=true, and the description is consistent with them. It adds no further behavioral context such as permission requirements, whether dry_run leaves anything behind, or what happens on duplicate tags, so it adds nothing beyond the annotation layer.

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. It is efficient, though its brevity reflects under-specification rather than disciplined economy.

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

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

The tool is a non-idempotent, open-world mutation taking an untyped nested settings object, and an output schema exists so return values need no explanation. Still, the description leaves the shape of settings and the meaning of dry_run completely unaddressed, which is inadequate for a tool with this much structural ambiguity.

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 settings object has additionalProperties=true with no defined properties. The description partly compensates by pointing at the channeltag class schema as the source of valid fields, but it never explains dry_run, the one parameter whose behavior is genuinely knowable and worth explaining.

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

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

States a specific verb and resource: 'Create a channel tag/group'. This is clearly distinguishable from the read-only sibling tvh_list_channel_tags. However, it does not explicitly contrast itself with siblings like tvh_create_channel or tvh_update_node, so it falls 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?

The phrase 'using fields from the channeltag class schema' implies a workflow: inspect the schema (e.g. tvh_list_classes or tvh_get_schema) before calling. There is no explicit when-to-use, when-not-to-use, or named alternative, so guidance remains 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 declare it is a non-idempotent, open-world, non-destructive write. The description adds only that fields come 'from dvr_config', without explaining dry_run behavior, what permissions are needed, or what happens on failure — a meaningful gap for a mutation tool.

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 padding. It is appropriately sized, though brevity comes at the cost of the missing parameter detail noted elsewhere.

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?

An output schema exists so return values need not be explained, but with 0% schema coverage and an unconstrained nested settings object plus an undocumented dry_run, the description is not complete enough for reliable invocation.

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

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

Schema coverage is 0%, so the description carries the burden. It mentions storage/padding/retention as settings content, which helps slightly, but never explains the dry_run parameter or the accepted structure of the arbitrary 'settings' object.

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 (Create) and resource (named DVR profile) and hints at the fields involved. It is distinguishable from siblings like tvh_create_dvr_rule and tvh_list_dvr_profiles, though the reference to 'dvr_config' is unexplained and slightly opaque.

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 create a profile vs a rule, no prerequisites, and no mention of when to use dry_run or settings. The agent must infer usage entirely.

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 non-read-only, non-destructive, non-idempotent, open-world behavior, so the safety profile is covered. The description adds genuinely useful context — that rule times use Tvheadend's native units and that the class schema should be inspected first — but says nothing about permissions, duplicate-handling, or what happens on invalid settings.

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, front-loaded with the purpose and followed by prerequisites and lifecycle pointers. No filler, though the schema-inspection instruction could be folded into the first sentence for tighter structure.

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?

An output schema exists, so return values need not be described, and annotations cover the mutation profile. For a tool whose payload is an externally-defined schema, redirecting the agent to the class schema is the right completeness move; the remaining gap is that it doesn't name the specific tool to fetch that schema.

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

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

Schema coverage is 0% and `settings` is a free-form object with additionalProperties, so the description must compensate. It does partially, by pointing at the dvr_autorec/dvr_timerec class schema and warning about native time units, but it never indicates which keys belong in `settings` or what `dry_run` does beyond its name.

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

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

States a specific verb and resource — 'Create an automatic series/title rule or recurring timer' — and names the two underlying kinds (dvr_autorec/dvr_timerec). It does not explicitly differentiate itself from siblings like tvh_create_timer or tvh_schedule_recording, so a reader must infer that a DVR rule differs from a one-off timer.

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

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

Gives explicit routing for the lifecycle: edit/disable via update_node, delete via delete_node, and a prerequisite to inspect the class schema first. It stops short of saying when to choose this over tvh_create_timer / tvh_schedule_recording, which is the main unresolved alternative.

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 non-readOnly, openWorld, and non-idempotent. The description adds real behavioral value beyond that: frequency_hz is silently converted to native kHz for DVB-S/S2 but left in Hz for DVB-C/T, and the two frequency paths are mutually exclusive. It does not mention what happens on duplicate muxes or any auth/permission requirement, which matters for a non-idempotent write.

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?

Four short sentences, front-loaded with the action, then the unit rules, then the pre-flight step. Every sentence carries a non-obvious constraint; nothing is repeated from the schema or annotations.

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?

An output schema exists and annotations cover the safety profile, so return values and side effects needn't be restated. The unit-conversion rules plus the pointer to tvh_mux_schema make the tool callable despite a free-form nested settings object. The gaps are the undocumented dry_run flag and the lack of any statement about network_uuid referring to an existing network.

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 settings is a free-form object with additionalProperties, so the description carries the full burden. It compensates well by pinning down units for frequency_hz and symbolrate, spelling out the mutual exclusion with settings.frequency, and routing the agent to tvh_mux_schema for the nested fields. network_uuid and dry_run remain unexplained.

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

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

States a specific verb and resource ('Create a mux') and immediately qualifies it with the domain fields involved (symbolrate, FEC, PLP/PLS), which distinguishes it from tvh_list_muxes, tvh_update_node, and tvh_create_network. An agent can tell this is the mux-creation path without opening the 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?

Gives an explicit prerequisite ('Inspect mux_schema first') and an explicit either/or rule ('Alternatively pass settings.frequency... Do not pass both'). It does not say when to prefer this over sibling creation tools such as tvh_create_network, but for creation of a sub-resource the sequencing guidance 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 declare this is a non-read-only, open-world, non-idempotent, non-destructive operation. The description adds meaningful behavior beyond that: existing networks are never silently reused, and delivery-specific fields depend on what the build supports.

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, front-loads the core action, and each sentence contributes useful information. The only slight inefficiency is the vague phrase 'as supported by this build', but overall it is well-structured.

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

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

The tool has a nested free-form settings object and an output schema, so the description need not explain return values. However, it should more clearly explain how to structure settings and what dry_run does. It is adequate but leaves gaps that could cause an agent to invoke the tool incorrectly.

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 that class_name comes from network_types and gives example settings fields (networkname, enabled, orbital_pos, scanfile), but it does not explicitly map those fields into the settings object and never mentions the dry_run 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: creating a network using a class/schema from network_types. It is clearly distinguishable from sibling tools like tvh_list_networks or tvh_create_mux, though it does not explicitly contrast with 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?

Usage is implied through the reference to getting a class/schema from network_types, but there is no explicit statement of when to use this tool versus alternatives or when not to use it. The note about existing networks never being silently reused adds useful context but is behavioral rather than a usage rule.

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 write profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), so the description's job is supplemental context. It does add real value by stating that core channel/title/time/profile fields cannot be overridden via extra, but it never mentions the dry_run flag or warns that repeated calls create duplicate timers given idempotentHint=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 short, front-loaded blocks with no filler; the tool's action comes first and the formatting/extra constraints follow. The telegraphic 'extra accepts...' fragment is slightly clipped but not wasteful.

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?

An output schema exists so return values need no explanation, and the time-format requirement is covered. Still, for a 7-parameter mutating tool with 0% schema coverage, the description omits the dry_run parameter and the meaning of config_uuid, which are material gaps for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate, and it partially does: the ISO 8601 / explicit-UTC-offset format for start_time and stop_time is genuinely useful, and the extra field's accepted contents and restrictions are explained. But channel_uuid, config_uuid (defaulting to empty), and especially dry_run are entirely undocumented anywhere, leaving roughly half the parameters opaque.

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 first sentence names a specific verb and resource ('Create a manual DVR timer'), which is clear and actionable. However, it never distinguishes itself from close siblings like tvh_create_dvr_rule or tvh_schedule_recording, so an agent must infer that 'manual' is the differentiator.

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 word 'manual' hints that this is for one-off timers rather than rule-based recording, which implicitly routes against tvh_create_dvr_rule, but no alternative is named and no when-not condition is given. Usage is inferred 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 declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: deletion may cascade to dependent objects, and network deletion specifically cascades to muxes and services. It does not explain reversibility or what happens if dependents exist, leaving a small 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?

Three short sentences, front-loaded with the core action and cascade warning, with the sibling routing statement placed after the primary purpose. 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?

An output schema exists so return values need no explanation, and cascade behavior is covered. However, for a destructive tool with zero parameter documentation, the unexplained dry_run option and unclear uuid semantics leave the definition only minimally 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% for both parameters, and the description never mentions 'uuid' or 'dry_run'. The dry_run flag is a meaningful safety control that an agent would otherwise miss entirely, so the description fails to compensate for the documentation gap.

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

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

The description opens with a specific verb and resource set ('Delete a DVB/channel/rule/profile object') and adds scope ('possibly dependent objects'). It also explicitly separates this tool from tvh_recording_action, so an agent can distinguish it from siblings without opening a 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?

It names a concrete alternative ('For DVR recordings use recording_action instead') and clarifies that hardware availability is not this tool's job. It gives clear usage context but stops short of stating prerequisites (e.g. required permissions) or other when-not conditions.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description still adds real behavioral value beyond those flags: pagination of network/mux counts, recursive hardware traversal, and the explicit stance that missing assignments or repeated failures are reported as evidence rather than a guessed diagnosis.

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 lines, front-loaded with the core action and scope, with no wasted wording. The evidence-vs-diagnosis note earns its place as the tool's distinguishing promise.

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?

An output schema exists, so return values need not be described. For a single-parameter read tool the description covers purpose, scope and reporting philosophy adequately; only the parameter's meaning remains thin.

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 network_uuid is undocumented in both schema and description. With only one self-descriptive parameter, the baseline applies rather than a penalty, but the description contributes nothing about identifier format or how to obtain a network_uuid.

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 ('Inspect') and concrete resources (network assignment, scan failures, active inputs), which is far more than the tool name alone conveys. The qualifier 'without starting a scan' implicitly separates it from tvh_scan_networks, though it never names that sibling outright.

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?

'Without starting a scan' gives an implied usage boundary, signaling this is the read-only alternative to tvh_scan_networks. However, it never explicitly says when to choose this tool over tvh_list_networks or tvh_hardware_tree, so the routing guidance is 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 carry the safety profile (destructiveHint=true, openWorldHint=true, idempotentHint=false), so the bar is lower. The description adds a prerequisite but never explains what the discovery actually does on the server or why it is flagged destructive (e.g., whether it persists discovered devices/muxes), leaving a meaningful gap for a mutation-flagged tool.

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

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

Two tight sentences, with the action front-loaded before the prerequisite. No wasted words, though so little is said that low verbosity borders on under-specification.

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?

An output schema exists, so return values need not be explained. Still, for a tool flagged destructive and open-world, the definition omits what the discovery changes on the server and how the dry_run option interacts with that, leaving the agent under-informed about consequences.

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 zero description coverage, so the description must explain the single 'dry_run' parameter, which it does not mention at all. An agent can guess dry_run semantics, but nothing in the definition confirms whether it suppresses actual state changes.

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 ('Trigger') and resource ('Tvheadend's SAT>IP server discovery'), so the action is unambiguous. It does not differentiate itself from the closest sibling, tvh_scan_networks, which also performs discovery-like activity.

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 prerequisite 'Requires SAT>IP client support' is stated, which is a useful gating condition. However, there is no guidance on when to use this versus tvh_scan_networks or tvh_diagnose_network, and no note on expected prerequisites such as configured networks.

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 readOnly/idempotent/non-destructive, so the description's job is to add the non-obvious traits — and it does: a 500-channel cap, disabled channels only appearing on explicit selection, overlapping events de-duplicated, and errors surfaced instead of silently under-reporting. Minor omission: it doesn't say whether an out-of-range 'hours' value errors or is clamped.

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?

Six short clauses, front-loaded with the core action and the window size, then layered scope rules and finally the exclusions. No sentence is redundant with the schema or annotations.

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?

An output schema exists so return values need no explanation, and both parameters get meaningful treatment. The only real gap is edge-case handling for out-of-range hours and what a partial-coverage result looks like, which an agent auditing gaps would want.

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 0%, so the description must carry the meaning — and it does, supplying the 1..168 hour range that the bare integer schema lacks and explaining that channel_uuids defaults to enabled channels only while an explicit list also picks up disabled ones. It leaves the UUID format/dtype guidance implicit.

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 ('Measure') and precise resource ('time coverage, gaps and description presence') for a bounded time window. The closing line explicitly rules out adjacent concerns (tuning a receiver, proving reception quality), which separates it from siblings like tvh_probe_reception and tvh_search_epg.

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

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

Gives clear operating context: default scope is all enabled channels, explicit selection flips to include disabled ones, and the 'does not tune a receiver or prove reception' clause tells the agent when a different tool is needed. It stops short of naming the specific alternative tools for those cases, so it is not a full when/when-not mapping.

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 readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds the useful nuance that metadata is 'live' and includes schedules (i.e., values reflect current state, not cached config), but says nothing about auth or size/shape of the read.

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. The resource and scope appear immediately, and nothing is repeated from the annotations.

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 an output schema present, return values need no explanation, and annotations cover safety. The only missing element is sibling differentiation, which matters given many nearby EPG 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 tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. No misleading parameter claims are made.

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 ('Read') and a specific resource ('global EPG grabber settings' plus live metadata/schedules). It is reasonably distinguishable from mutating siblings like tvh_update_epg_config, but it does not explicitly differentiate itself from close read siblings such as tvh_list_epg_modules or tvh_list_epg_sources.

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 when-to-use guidance, no mention of alternatives, and no exclusions. An agent must infer that this is the global-settings counterpart to the per-module/source listing tools, which is exactly the distinction that matters in a large sibling set.

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 readOnly, idempotent, non-destructive and openWorld, so safety is covered. The description adds one genuinely useful trait — that some enums are static while others are API-backed — which explains variability in results. It says nothing further about rate limits, freshness, or failure modes for the API-backed case.

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, though it is arguably too terse given the unresolved uuid/field semantics.

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

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

An output schema exists, so return values needn't be described, but the input side is underspecified: with 0% schema coverage, the description should have clarified what uuid identifies and what 'field' accepts. Adequate only at minimum-viable level.

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 neither parameter is described in the description text; the examples hint at what 'field' values look like but do not bind it to a known enumeration or explain what 'uuid' refers to. The agent has no reliable way to populate required arguments without guessing.

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 ('Resolve') with a clear resource ('a field's static or API-backed enum') and gives concrete examples (networks, LNB types, switches). It does not, however, differentiate itself from siblings like tvh_network_types or tvh_get_schema, which appear to serve overlapping enum/schema purposes.

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 versus alternatives such as tvh_network_types or tvh_get_schema, and no stated prerequisites. The agent has no idea what the 'uuid' must identify (which entity) before calling.

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 carry readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds a useful detail that the response includes advanced/expert fields not shown in normal listings, but says nothing about failure behavior (e.g. an unknown uuid) or how the open-world lookup is resolved.

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 front-loaded sentence with no redundancy. It is lean rather than wasteful; the issue is missing content, not excess verbiage.

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?

An output schema exists, so return values need not be explained, and the shape (a single uuid in, one object out) is simple. Still, the meaning of 'node' and the uuid format are unresolved, which leaves an agent guessing about applicability before calling.

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 single uuid parameter is undocumented in the schema (0% coverage) and the description does not explain it at all – not what it identifies, nor whether it is a node UUID versus some other identifier. Given low schema coverage, the description was expected to compensate and does not.

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

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

It has a specific verb ('Inspect') and states the intent (current values and metadata), but it never says what kind of object a 'node' is. With siblings covering channels, muxes, networks, services and DVR rules, an agent cannot tell from the description whether this applies to all of them or a subset.

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 when-to-use / when-not-to-use guidance and never mentions the natural alternatives, such as tvh_list_* for enumerating entities or tvh_api_read for raw access. The choice between this and tvh_update_node or tvh_delete_node is left entirely 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?

The annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds that the result includes fields, types, defaults and options, which is useful, but with an output schema present there is little left for the description to disclose.

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 the return content front-loaded and the prerequisite trailing — no filler at all.

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 single-parameter, read-only introspection tool with an output schema and full annotation coverage, the description supplies the key missing piece (class-name provenance). It could be richer about how this differs from sibling schema/introspection 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?

Schema description coverage is 0%, so the description must compensate for the lone class_name parameter. It does so by stating where valid class names come from (list_classes or hardware_tree), which is real meaning beyond the schema.

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

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

The description uses a specific verb ('Get') and a precise resource ('fields/types/defaults/options for a class'), which is far more informative than the bare name. It does not, however, distinguish itself from closely related siblings such as tvh_get_field_options or tvh_mux_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?

By naming list_classes and hardware_tree as the ways to find a class, it defines the prerequisite step and implies the correct workflow. It stops short of stating exclusions — e.g. when to prefer get_field_options instead.

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 readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds genuine value beyond that: it discloses that recursive expansion returns actual UUIDs, settings, descriptions and option metadata, and clarifies the read-only nature of hardware discovery. Rate limits, pagination and auth needs are not mentioned, keeping it below a 5.

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 with no filler, front-loaded with the resource enumeration before the calling semantics. Every clause earns its place by adding either scope, usage or a capability boundary.

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?

An output schema exists, so return-format explanation is not required, and the description still usefully previews what recursive mode yields. The remaining shortfall is max_depth behavior (default 8, recursion depth limiting) plus no hint about how deep or large the tree can get.

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 carry the parameter burden, and it does for two of three: uuid semantics ('root' vs a device UUID) and recursive=true expansion. max_depth is never mentioned and must be inferred from its title and default of 8, which is the one real gap.

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

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

The description opens with a specific verb plus an enumerated set of hardware resources (adapters, frontends, satellite inputs, LNBs, switches, rotors, Unicable nodes), which is far more distinctive than the generic tvh_list_* siblings. It is clearly a hardware-topology read tool rather than a channel/mux/network listing, though it never names a sibling such as tvh_get_node to draw the boundary explicitly.

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

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

It gives concrete usage context for the calling pattern: uuid='root' enumerates adapters, a device UUID enumerates its children, and recursive=true expands downward. It also draws a capability boundary ('Physical tuners are discovered by Tvheadend/its drivers, not created by this tool'), which implicitly tells the agent not to reach for this tool to provision hardware. It stops short of naming an alternative when a single node is wanted (e.g. tvh_get_node).

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 readOnly, idempotent, openWorld and non-destructive behavior, so the safety profile is covered. The description adds one useful behavioral fact — disabled channels are included and mappings are returned — but says nothing about pagination limits or how large the result may be for an openWorld read.

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

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

One sentence, front-loaded with the verb and the result scope; nothing is wasted. It is perhaps slightly too terse given the undocumented parameters, but structurally sound.

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?

An output schema exists, so return-shape explanation is unnecessary, and annotations cover safety. However, for a 3-parameter paginated list tool with zero schema documentation, the omission of pagination and filter semantics leaves it only adequate.

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 says nothing about limit, start, or filters. For a paginated list tool, failing to explain pagination or the filter object shape leaves the agent guessing at the most consequential 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?

Specific verb (list) and resource (channels) with meaningful scope qualifiers: includes disabled channels and returns service/EPG mappings. It is implicitly distinguishable from siblings like tvh_list_services or tvh_list_channel_tags, but it never names them or states the boundary explicitly.

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

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

No guidance on when to call this versus alternatives (e.g., filtering via tvh_search_epg, or listing services with tvh_list_services). The agent must infer usage from the sibling names alone.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful routing behavior: membership changes must go through channel.tags/update_node rather than this tool. However, it does not disclose pagination behavior for limit/start, which is meaningful behavioral context for a list tool.

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 zero waste. The purpose is front-loaded, and the follow-up immediately routes mutation to the correct tool. 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 tool is simple, annotated as read-only, and has an output schema, so return-value explanation is not needed. Still, an agent calling this tool may need to understand pagination via limit/start, and neither the schema nor the description explains those parameters. The definition is minimally adequate but incomplete for paginated listing.

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% for the two parameters (limit and start), and the description does not mention either parameter. With low schema coverage, the description should compensate by explaining pagination semantics, but it provides no meaning, units, or expected use for limit/start.

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 channel groups/tags.' This clearly identifies a read/list operation for channel tags. It does not explicitly differentiate from nearby siblings such as tvh_list_channels or tvh_list_classes, but the resource noun is specific enough for an agent to understand the tool's 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 gives a clear usage boundary by directing edits elsewhere: 'Edit membership through channel.tags using update_node.' That is an explicit alternative for mutation. It does not explicitly state when to use this listing versus tvh_list_channels, but the read-only listing 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 declare readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds only that results can be narrowed by name/caption; it says nothing about result size, ordering, or what a 'class' represents, which for a discovery tool would have been genuinely additive.

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

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

One short sentence with the resource and the filter option front-loaded; no filler, nothing redundant with the schema.

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?

An output schema exists, so return values need no explanation, and the tool is simple (zero required params). Still, the agent is left unsure what a Tvheadend 'class' is and when this beats direct schema/API read tools, which is a meaningful gap for the exploration phase of a workflow.

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 single parameter is named only 'contains', so the description has to carry the meaning — it does confirm the filter targets name/caption. However it never states that matching is substring-based or whether it is case-sensitive, leaving the parameter's exact semantics unresolved.

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 concrete verb ('Discover') and a concrete resource ('Tvheadend class names'), plus the optional filter. It is distinguishable from the create_/list_channels-style siblings, though it never clarifies how 'class names' relates to the neighboring introspection tools tvh_get_schema and tvh_api_read.

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 'optionally filtering name/caption' implies a discovery-then-filter workflow, but there is no explicit when-to-use guidance or pointer to alternatives such as tvh_get_schema or tvh_get_field_options for schema exploration.

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 this to be a read-only, idempotent, non-destructive, open-world operation, so the safety profile is covered. The description adds useful context about the kinds of DVR settings returned, but it does not disclose pagination behavior, default limits, or any other execution detail 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 a single front-loaded sentence that quickly communicates the tool's resource and included settings. It contains no filler or redundant restatement of the 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?

With an output schema present and annotations covering the read-only safety profile, the description does not need to explain return values in detail. However, it omits pagination semantics and usage guidance for the two undocumented input parameters, leaving the definition minimally adequate rather than 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?

The input schema has 0% description coverage for both the 'limit' and 'start' parameters, and the description does not mention either parameter or explain their semantics. The parameter names and schema defaults hint at pagination, but the description does not compensate for the missing schema 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 uses a specific verb ('List') and names the resource ('DVR profiles') plus relevant returned settings such as output directories, padding, and retention. It is clearly distinguishable from the sibling creation tools, though it does not explicitly contrast itself with tvh_create_dvr_profile or tvh_list_dvr_rules.

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 only states what is listed; it gives no guidance on when to use this tool versus alternatives such as tvh_create_dvr_profile or tvh_list_dvr_rules. There are no prerequisites, exclusions, or contextual cues for selecting this 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is fully covered without the description's help. The description adds only the domain distinction between the two rule kinds; it says nothing about paging behavior for limit/start, ordering of results, or what happens when zero rules exist.

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 with no filler, and the key term ('autorec') is front-loaded. It is efficient but arguably sized too small for a tool with three undocumented parameters.

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?

Output schema exists, so return values need no explanation, and annotations carry the safety profile. For a simple paginated list tool the remaining gap — pagination semantics — is minor, and the description supplies the one piece of domain knowledge an agent could not infer elsewhere: what autorec and timerec mean.

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, and it does so only for 'kind' by unpacking the otherwise opaque 'autorec'/'timerec' enum values. The 'limit' and 'start' parameters are left entirely unexplained — no indication that they are pagination knobs, defaults, or caps.

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?

Specific verb ('List') plus a resource that is explicitly disambiguated into its two variants, explaining that 'autorec' means automatic EPG recording rules and 'timerec' means recurring clock timers. An agent can tell it apart from the create/list-profile siblings by the word 'rules', though it never names an alternative 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?

Usage is only implied: you call it when you want to enumerate DVR rules of a given kind. There is no statement of when to prefer it over tvh_list_dvr_profiles, tvh_create_dvr_rule, or tvh_list_recordings, and no prerequisites are mentioned.

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 this as read-only, idempotent, open-world, and non-destructive, so the description does not need to carry the safety profile. It adds useful context about what is listed (native OTA/internal/external grabber modules) and that UUIDs and enabled status are included, but it does not mention result ordering, pagination, or any relationship between modules and EPG sources.

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, resource, module types, and returned fields without any 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?

Given the empty input schema, full annotation coverage, and presence of an output schema, the description provides enough context to understand the tool's scope. It could be slightly more complete by clarifying its relationship to EPG sources or configuration tools, but nothing critical is missing for invoking a no-argument listing 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?

The tool takes zero parameters, so there is no parameter behavior for the description to compensate for. This matches the baseline expectation for a no-parameter operation.

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 gives a specific verb and resource: list EPG modules, and identifies the module categories (native OTA/internal/external grabber) plus the returned fields (UUIDs, enabled status). It is clear what the tool does, but it does not explicitly differentiate itself from nearby siblings such as tvh_list_epg_sources or tvh_get_epg_config.

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 tvh_list_epg_sources, tvh_get_epg_config, or tvh_update_epg_module. The list operation is implied by the name and description, but no usage context or exclusions 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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered without the description. The description adds that results include module IDs and existing mappings (useful scoping context), but says nothing about pagination behavior, result volume, or how the open-world lookup behaves when EPG sources are unreachable.

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; the resource list leads. It is efficiently sized, though that efficiency comes partly from omitting needed detail rather than from tight wording.

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?

An output schema exists, so return values need not be explained. However, for a paginated list tool with two undocumented parameters and no stated usage conditions, the description leaves meaningful gaps an agent must guess at.

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% for both parameters: 'limit' and 'start' carry only types and defaults, with no indication that they are pagination controls. The description never mentions them, so it fails to compensate for the coverage gap and the agent has no stated semantics for either 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?

Clear verb 'List' plus the concrete resources returned: EPG source channels, module IDs and existing channel mappings. An agent can tell this apart from tvh_search_epg or tvh_epg_coverage, though it doesn't explicitly distinguish itself from the closely related tvh_list_epg_modules or tvh_get_epg_config.

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 when-to-use guidance, no prerequisites, and no mention of alternatives such as tvh_list_epg_modules or tvh_assign_epg_sources. The agent must infer the call context from the sibling list alone.

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 destructiveHint=false, so safety is covered. The description adds one useful behavioral fact (results include scan state/result), but says nothing about pagination behavior from limit/start or what the generic 'filters' parameter does, which are the remaining behavioral unknowns.

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 clause-plus-clause sentence with the primary action front-loaded and the filter secondary. Efficient, though extremely terse for a tool with four parameters.

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?

An output schema exists, so return values need not be explained. However, with four parameters at 0% schema coverage and a flexible 'filters' argument, the description is too thin to let an agent call this confidently beyond the simplest case.

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 full burden, yet it only explains network_uuid. The limit, start, and especially the opaque 'filters' array parameter are left entirely undefined in both schema and 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?

States a specific verb and resource ('List muxes') and adds scope detail ('including scan state/result'). It does not explicitly contrast with nearby siblings such as tvh_list_networks or tvh_list_services, so an agent must infer the distinction from the resource name alone.

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 clause 'optionally filter by network UUID' implies the filtering use case, but there is no explicit when-to-use/when-not guidance and no named alternative for listing muxes in other ways. The usage is inferable 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 declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds only a field list, which largely duplicates the output schema, and says nothing about pagination behavior across a potentially large network list.

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. Its brevity is a virtue structurally, though the saved space is not reinvested in the missing parameter guidance.

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?

An output schema exists, so return values need not be explained, and annotations cover safety. However, for a paginated, filterable list tool with three undocumented parameters, the description leaves a real operational gap around how to page and filter.

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?

All three parameters (limit, start, filters) have 0% schema description coverage, so the description carries the full burden of explaining them — yet it never mentions pagination or the filters array format. Only 'list networks' hints at collection semantics; a caller has no idea how to page or filter.

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

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

States a specific verb and resource ('List networks') and enumerates the fields returned (UUID, delivery system, enabled state, scan queue, counts). It is distinguishable from tvh_create_network and tvh_scan_networks by the read verb, but it never explicitly contrasts with read-oriented siblings such as tvh_diagnose_network or tvh_network_types.

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 tvh_diagnose_network (single-network detail), tvh_network_types (type catalog) or tvh_scan_networks. The agent must infer usage purely from the verb, with no exclusions or preconditions 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 declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description still adds real behavior: how the 'upcoming' state behaves (includes active recordings) and how pagination works via total/start. It omits nothing safety-critical for a read tool, though it doesn't mention ordering or result size 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?

A single compact sentence with the resource and scope front-loaded followed by two useful behavioral notes; nothing is wasted. The 'total/start' phrasing is terse to the point of being slightly cryptic, keeping it off a 5.

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?

An output schema exists (covering return values) and annotations cover the safety profile, so the main remaining burden is parameter semantics. The description handles state and pagination but leaves limit and filters unexplained, which is a meaningful gap for a 4-parameter list 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%, so the description must carry all parameter meaning. It clarifies 'state=upcoming' and points to start/total for pagination, but leaves limit and especially the opaque 'filters' parameter (arbitrary object array) completely unexplained, so it 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) and resource (DVR entries), making it clear this is a read/list operation. It does not distinguish itself from siblings like tvh_list_dvr_rules or tvh_list_dvr_profiles, and 'DVR entries' is slightly ambiguous against those sibling resources, so it stops short of a 5.

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

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

There is no guidance on when to use this versus tvh_recording_action or tvh_schedule_recording, nor any mention of prerequisites. The only usage-adjacent content is a semantic note that the 'upcoming' state includes active recordings, which explains a filter value but not tool 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?

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior. The description earns credit for disclosing that disabled and unverified services are included, which is real behavioral context. However, it says nothing about pagination defaults or filter behavior, which matter for a list tool with limit/start parameters.

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. It is efficient, though slightly terse for a tool with four undocumented parameters.

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?

An output schema exists, so return values need not be described. But with 0% parameter documentation and no guidance relative to the many sibling listing/mapping tools, an agent cannot confidently decide how to page, filter, or scope the call.

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

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

Schema description coverage is 0% across four parameters (limit, start, filters, mux_uuid), and the description does not compensate: it never mentions pagination, filtering, or mux scoping. The word 'discovered' hints at the domain but gives no guidance on how to constrain the listing.

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) and resource (services) and adds scope detail that separates it from generic listing: disabled/unverified entries, encryption, and mappings are included. It is clear what the tool returns, though it does not explicitly contrast with siblings like tvh_map_services or tvh_assign_services.

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 statement of when to use this versus alternatives such as tvh_map_services, tvh_assign_services, or the other tvh_list_* tools. The listing verb implies a read/inspection use, but no prerequisites or exclusions 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, idempotentHint, and destructiveHint=false, so safety is covered. The description adds useful context by naming the specific data exposed (success/failure counters and configuration/options). It does not mention freshness, scope, or whether the counters are cumulative or per-run.

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 waste. It conveys the tool's purpose and output content efficiently.

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 tool with an output schema and rich annotations, the description is nearly complete. It could add a brief note on when to use it versus general status tools, but nothing critical is missing 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 takes zero parameters, so the baseline is 4. There are no parameter semantics to clarify, and the description does not need to compensate for any schema gaps.

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

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

States a specific verb ('Read') and a specific resource ('service mapper success/failure counters and mapper configuration/options'), making the purpose clear. It does not explicitly distinguish itself from siblings like tvh_status or tvh_map_services, but the resource is distinctive enough to infer.

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 a diagnostic/status-check use case but provides no explicit when-to-use guidance, exclusions, or alternatives. It does not say when to prefer this over tvh_status or tvh_stop_mapper.

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

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

The annotations already disclose that this is destructive, non-read-only, non-idempotent, and open-world. The description adds useful behavioral context by noting the underlying service/mapper/save endpoint, the absence of a mapper/start API, empty-selection rejection, and recommended post-call monitoring.

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, compact, and structured around purpose, implementation detail, validation behavior, and follow-up monitoring. Every sentence provides actionable information without excessive verbosity.

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 annotations and an output schema, reducing the description's burden for safety and return-value documentation. The description covers the main operational flow and post-call monitoring, though it could more fully explain the options object and dry_run behavior.

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 0%, so the description must carry parameter meaning. It explains service_uuids as explicit service UUIDs and lists several options fields, but it omits dry_run entirely and uses 'etc.' rather than fully documenting the options object.

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: starting Tvheadend's native service-to-channel mapper for explicit service UUIDs. This is clear enough to distinguish it from sibling tools such as tvh_mapper_status, tvh_stop_mapper, and tvh_list_services.

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 explains that the tool is for explicit service UUIDs, that empty selections are rejected, and that mapper_status and list_channels should be monitored afterwards. It does not explicitly compare itself with alternatives like tvh_assign_services, but the operational 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds a little by indicating the read returns enum/metadata content rather than live tuner state, but says nothing about whether an unknown UUID errors, what the payload volume is, or caching. Adequate but thin given the annotated baseline.

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; the key noun phrase ('network-specific mux fields') leads. Nothing to cut.

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 an output schema present, return-shape explanation is unnecessary, and the tool takes one required parameter, so the description is close to sufficient. What is missing is the purpose behind the call – i.e., that these field/enum definitions are what you consult before constructing a mux or tuning-parameter payload via tvh_create_mux.

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 single parameter network_uuid has no description or format in the schema. The description only indirectly hints at its role via 'network-specific', giving no indication of whether it is a UUID, integer, or name, nor what happens if it does not exist. The description therefore fails to compensate for the coverage gap.

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

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

States a specific verb+resource: reading network-specific mux fields, tuning parameters and modulation/FEC enums. That is far more concrete than a tautology and tells an agent what kind of data comes back. It does not, however, distinguish itself from siblings like tvh_get_schema or tvh_get_field_options, so an agent cannot tell which schema-style tool to pick without guessing.

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 when-to-use guidance at all: no mention of prerequisites, no exclusion of alternatives, and no hint about which task (creating a mux, updating tuning parameters) would prompt this call. The closest thing to guidance is the word 'network-specific', which implies per-network scoping but not a call condition.

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 readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds two useful behavioral facts beyond them: only creatable classes are returned, and each class comes with its schema, which tells the agent the payload is richer than a plain list.

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

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

One sentence, zero filler, with the enumeration and the 'creatable' constraint front-loaded before the return-content note.

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?

Output schema exists and annotations cover the safety profile, so the description need not explain return values. For a no-param read tool with complete structured fields, the single sentence supplies everything an agent needs to decide to call 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?

Zero parameters, so there is nothing to mis-specify and no schema semantics to compensate for; the baseline for a no-param tool 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?

Specific verb (List) plus a precisely bounded resource (creatable DVB-S/C/T, ATSC, ISDB, IPTV network classes and their schemas). The 'creatable' qualifier and class enumeration distinguish it clearly from sibling introspection tools like tvh_list_classes, tvh_get_schema and tvh_mux_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 'creatable' wording implies this is the discovery step before creating a network, but the description never states that explicitly or names alternatives such as tvh_create_network or tvh_get_schema. Usage is inferable 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 cover readOnly/idempotent/destructive, yet the description adds substantive behavior: sources are disabled rather than deleted, certain source types block the plan, name/region mismatches require explicit verification, and the plan_id expires in 15 minutes. That is exactly the extra context annotations cannot express.

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

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

Front-loaded with purpose and scope, and each subsequent sentence carries distinct information (side effects, blockers, verification, TTL, no mutation). Minor redundancy between the leading 'Preview' framing and the trailing 'does not change configuration' restatement.

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 planning tool with rich annotations and an output schema, the description covers side effects, blockers, follow-up usage, and result lifetime. An agent has everything needed to decide whether to call it and how to act on its return.

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 never names target_uuid, source_uuids, or allow_name_mismatch directly. It does implicitly convey merge semantics (target retained, sources unioned) and that mismatch handling requires explicit opt-in, which partially compensates but leaves the parameter-to-argument mapping to inference.

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

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

States a specific verb and resource ('Preview an explicit channel merge') plus the exact semantics of the merge: target name/number retained, mappings unioned. It also distinguishes itself from the mutating sibling by naming apply_maintenance_plan as the consumer of its output, so an agent can tell plan-vs-apply apart without opening a 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?

Gives clear context for use: this is the dry-run step whose 15-minute plan_id feeds apply_maintenance_plan, and it explicitly does not change configuration. It also states conditions that block a plan (DVR references, bouquet-managed sources). No explicit pointer to an alternative merge/consolidation tool, so it stops short of full when/when-not 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 establish that this is a read-only, idempotent, non-destructive, open-world preview. The description adds useful behavioral detail beyond that: tuner inputs are reassigned, mapped services are replaced only on unique ONID/TSID/SID matches, source networks are disabled in the proposed plan, and certain mismatches block execution. The only minor ambiguity is that 'disable source networks' could sound mutating, but the leading 'Preview migration' makes the preview-only intent clear.

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 with the core purpose and constraints, and every sentence adds relevant planning or blocking information. There is 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 consolidation-planning operation, the description covers the important behavioral constraints and blockers, and an output schema exists so return-value explanation is not required. The remaining gap is mostly explicit parameter-role documentation, which keeps it just short of 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 0%, so the description must carry the explanatory burden. It provides some semantics by referring to an existing target network and plural source networks to be consolidated, but it does not explicitly map target_uuid and source_uuids to those roles or clarify UUID formatting and scope.

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

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

The description states a specific action and resource: previewing a migration/consolidation into an existing scanned DVB network while preserving channel UUIDs. It is clear enough to distinguish this from general network updates, though it does not explicitly name the closest sibling alternatives such as channel merge or apply-plan 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 implies when the tool is appropriate by describing the preview/planning scenario and listing blockers such as different delivery systems, satellite positions, and missing unique matches. However, it does not explicitly say when to use this versus alternatives like tvh_plan_channel_merge, tvh_assign_services, or tvh_apply_maintenance_plan.

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

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

Beyond the annotations, the description discloses important destructive behavior: explicit tuner isolation temporarily disables competing enabled frontends, requires an idle server/no imminent DVR, and journals and restores prior settings. It also covers crash recovery and read-only blocking, giving the agent strong operational context.

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

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

The definition is front-loaded with the core purpose and then adds necessary operational caveats. It is dense but appropriate for a complex destructive probing tool, with little obvious filler.

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

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

Given the tool's complexity, destructive annotations, and the presence of an output schema, the description covers the critical prerequisites, side effects, recovery path, and read-only restriction. An agent has enough information to decide whether and how to invoke it safely.

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 carry parameter meaning. It adequately explains tuner_uuid selection/isolation, the preview-vs-run distinction via its opening phrase, and bounds duration and max_bytes, though it does not explicitly document every parameter name or default.

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 gives a specific verb and resource: previewing or running a bounded service MPEG-TS test. It clearly distinguishes this from sibling tools such as tvh_reception_recoveries by focusing on active reception probing with explicit duration and size bounds.

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 explains key usage conditions: omitting tuner_uuid lets Tvheadend choose the receiver, while supplying one isolates that tuner. It also states active probing is blocked in read-only mode and points to reception_recoveries after crashes, though it does not comprehensively compare against every alternative sibling.

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

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

With annotations already declaring readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, the description adds useful behavioral context: it never changes settings and never reads files outside the configured state folder. It also explains that journals normally disappear after probes, so their presence signals an abnormal recovery situation.

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, front-loaded with the primary action, and every sentence adds useful context about normal behavior, crash recovery, and safety constraints. There is no redundant restatement of the name or schema.

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

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

Given that there are no parameters, an output schema exists, and annotations already declare the safety profile, the description supplies the remaining workflow context: what pending journals mean, when to inspect them, and that restore_snapshot is the follow-up. Nothing essential for correct invocation appears to be 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 for the description to clarify. The baseline score for a parameterless tool 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 uses a specific verb and resource: it reads pending tuner-isolation recovery journals for this Tvheadend URL. It also distinguishes the tool from probe and restore workflow behavior, making its purpose clear without opening the 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?

It gives a clear usage context: normally probes restore settings and remove journals, but after a process or host crash the agent should inspect recorded snapshots and current hardware, then use restore_snapshot. This names the relevant alternative and the condition for escalation, though it does not explicitly state when not to call this 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 flag destructiveHint=true and readOnlyHint=false, but the description adds the crucial nuance that only remove_files destroys files while stop/cancel do not, plus an explicit consent precondition. It omits idempotency behavior (what a repeat 'stop' returns) and never mentions dry_run, which is the safety valve for a destructive mutation.

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 clauses with no filler; the destructive warning is emphasized in caps and the consent rule follows directly. The mid-sentence line break between the stop/cancel clause and the remove_files clause slightly muddles front-loading of the most important 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?

An output schema exists and annotations cover the safety profile, so return values and risk framing need not be restated. But for a three-parameter destructive mutation with zero schema documentation, leaving dry_run and uuid unexplained leaves the agent without enough to call the tool safely in ambiguous cases.

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 whole burden; it does cover all three action enum values with real semantics, which is the most important parameter. However, 'uuid' is left entirely unexplained and 'dry_run' is never mentioned at all — a significant omission for a permanently-deleting operation.

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 defines each of the three action values with a specific verb and resource ('stop finishes an active recording', 'cancel cancels a timer/active recording', 'remove_files PERMANENTLY DELETES the recording files'), which lets an agent distinguish the enum cases. It never states the overall frame ('act on the recording identified by uuid') or differentiates itself from siblings like tvh_list_recordings or tvh_delete_node, so a 4 rather than 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?

It gives an explicit gating condition for the dangerous path: 'Use only when the user explicitly requests deletion of recordings', and the per-action definitions imply when to pick stop vs cancel. It offers no guidance on when-not to use the tool or which sibling to prefer for listing or rescheduling recordings, which keeps it below 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?

Goes well beyond annotations by disclosing that validation happens before the first write, restores are sequential and non-atomic, partial failures report completed/remaining UUIDs, and topology changes can invalidate child UUIDs. These are concrete operational traits an agent needs before invoking a destructive mutation.

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?

Four tight sentences, front-loaded with the main action and scope, followed by operational cautions. Every sentence adds useful information with no 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?

Behavioral and safety context is strong, and the output schema means return values need not be explained. However, with a required nested snapshot object and 0% schema description coverage, the description leaves a significant gap about how the snapshot parameter should be formed.

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 clarifies the dry_run default indirectly ('Default previews the changes'). The required 'snapshot' object has a nested schema with additionalProperties, and the description does not explain its expected structure or fields.

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

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

States a specific verb and resource ('Restore a snapshot's fields') and clarifies target scope ('to EXISTING nodes'), which distinguishes it from snapshot creation or node updates. An agent can tell what this tool does without opening the 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 implies a safe default preview via 'Default previews the changes' and gives a preference ('prefer restoring only the fields you actually changed'), but it does not explicitly state when to use this versus tvh_update_node, tvh_snapshot, or other siblings. Usage is implied rather than clearly routed.

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/openWorldHint/idempotent=false; the description adds genuinely new behavior: the call is asynchronous and returns immediately, and it consumes tuner capacity, which implies contention with live viewing/recording. It does not explain what a rescan does to existing services on the mux (the destructive aspect), which keeps it short of a 5.

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-loaded with the async contract, then monitoring, then the single-mux alternative. No filler; the final clause "with its schema's scan_state" is slightly terse but still parseable.

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?

Output schema exists so return values need no explanation, and the async/monitoring story is covered. However, for a destructive, tuner-consuming mutation, the absence of any dry_run guidance or UUID sourcing leaves a real 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 coverage is 0% and the description does not mention dry_run at all, nor where network UUIDs come from or what format they take. "Selected networks" only loosely maps to network_uuids, so the agent gets no help on the one parameter that could make this a safe operation.

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

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

States a specific verb+resource ("Queue a service scan for selected networks") and immediately fixes the scope with "returns immediately." It also separates itself from the single-mux path by naming update_node, so the agent can tell the bulk tool from the singular one.

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

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

Explicitly routes the agent: use this for selected networks in bulk, use update_node for a single mux. It also names the monitoring calls (list_networks.scanq_length, list_muxes.scan_state/scan_result), so selection and follow-up are both specified.

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, idempotentHint=false, and openWorldHint=true, so the safety profile is carried by structured data. The description adds only the default-DVR-profile detail; it does not explain that a call creates a new timer/recording entry, that repeats may duplicate, or what the destructive effect actually touches (the DVR schedule).

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; the action comes first and the config_uuid caveat second. It is efficient, though compression is partly achieved by omitting information rather than by tight phrasing.

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

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

For a destructive, non-idempotent scheduling tool with four parameters at 0% schema coverage, the description is far too thin: no event_id sourcing, no dry_run guidance, no duplicate-prevention warning. The presence of an output schema excuses explaining return values, but not the missing invocation 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 0%, so the description must compensate, and it does so for only one of four parameters (config_uuid='' selects the default DVR profile). It never explains where a valid eventId comes from (e.g., tvh_search_epg), nor what dry_run or comment do, leaving three parameters undocumented in both schema and 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 and resource ('Record an EPG eventId'), making the core action unambiguous. It does not differentiate this from siblings like tvh_create_timer or tvh_recording_action, leaving the agent to infer the boundary between scheduling a new recording and managing existing ones.

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 explicit when-to-use guidance, no alternatives named, and no mention of the dry_run preview path or when a pre-existing timer makes this call unnecessary (idempotentHint=false). The only guidance-like content is the config_uuid default behavior, which is really a parameter note.

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 readOnly, idempotent, non-destructive, open-world, so the safety profile is covered. The description adds genuinely non-structured behavioral detail: timestamps are Unix seconds, fulltext controls whether descriptions are included, and filters are EPG-specific grid filters with time bounds. Pagination/limit behavior is not disclosed.

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 compact sentences, front-loaded with the purpose and packed with actionable detail; nothing is filler. The grid-filter clause is slightly jargon-heavy and reads as an aside rather than structured guidance, which keeps it just short of ideal.

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?

An output schema exists, so return-value explanation is unnecessary, and the eventId handoff covers the main integration need. But for a tool with 6 parameters at 0% schema coverage, leaving limit and channel_uuid entirely undocumented and the filters object shape unexplained is a meaningful gap an agent must guess through.

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% for 6 parameters, so the description carries the burden. It usefully explains query (regex), start (Unix seconds), fulltext (includes descriptions), and hints that filters accept time bounds, but says nothing about limit or channel_uuid, and leaves the opaque array-of-objects filters structure unspecified.

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

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

States a specific verb and resource ('Search upcoming EPG programmes') and adds the crucial qualifier that the query is a Tvheadend regular expression, which an agent could not infer from the name. It does not explicitly contrast itself with siblings such as tvh_schedule_recording, though the handoff sentence implies the division of labor.

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 tells the agent what to do next with the results ('Results contain eventId for schedule_recording'), which is a real usage signal. However, it never says when not to use this tool or how it relates to the other 30+ sibling tools (e.g., tvh_get_node, tvh_list_channels), so selection guidance is only implied.

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 read-only, idempotent, non-destructive, and open-world behavior. The description adds important behavioral limits beyond the annotations: it cannot recreate deleted nodes, recordings, or hardware, and it excludes secrets and write-once fields.

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: the export purpose comes first, followed by local-save guidance and then critical limitations. Every sentence adds useful information without 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?

An output schema exists, so the description does not need to explain return structure. It covers the key export semantics and limitations well, though it leaves the required uuids parameter under-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?

The schema has one required parameter, uuids, with 0% description coverage. The description only mentions 'selected objects' and does not explain that the selection is by UUID array or how those UUIDs should be obtained, so it does not compensate for the schema gap.

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

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

The description uses a specific verb and resource: export selected objects' writable/readable fields as a JSON change snapshot. It clearly identifies the output artifact and distinguishes itself from a complete backup, so an agent can tell what this tool produces.

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 usage context: save the returned JSON locally and do not treat it as a complete Tvheadend backup. It also states what cannot be recovered, but it does not explicitly compare against siblings such as tvh_restore_snapshot, tvh_get_node, or tvh_api_read.

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 readOnly, idempotent, non-destructive, and openWorld behavior. The description adds useful context by noting permission errors and naming the exact runtime data exposed, though it does not elaborate on failure modes or authentication requirements.

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 definition is a single front-loaded sentence with no filler. Every listed item contributes to the tool's scope.

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 rich annotations, an output schema, and no parameters, the description is nearly complete: it names the data returned and notes permission errors. Minor ambiguity remains around whether permission errors are returned values or raised errors, but the output schema likely resolves 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?

The tool takes zero parameters, so there are no parameter semantics to document. Per the baseline for zero-parameter tools, a 4 is appropriate even with full 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 uses a specific verb, 'Read,' and names the exact resources: server version, active tuners/signals, and subscriptions. This clearly distinguishes it from sibling list and mapper_status tools by scope and content.

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 status-oriented verb and listed resources, but the description gives no explicit when-to-use guidance or alternatives such as tvh_mapper_status or tvh_api_read. An agent can infer it is for server status but must decide the boundary with siblings on its own.

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

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

Annotations already declare destructive=true, idempotent=false, readOnly=false, and openWorld=true, so the safety profile is largely covered. The description confirms that a running operation is stopped but does not explain effects on in-progress mappings, required permissions, or how dry_run changes 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?

A single front-loaded sentence with no filler or repetition. It is terse but appropriately sized for the stated 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 output schema and annotations reduce the description's burden, and the main action is clear. However, dry_run semantics and basic operational context for deciding whether to stop versus inspect mapping status are missing.

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

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

The sole parameter, dry_run, has 0% schema description coverage and is not mentioned in the description. An agent sees only its name and default, so the description fails to compensate 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?

States a specific verb ('Stop') and resource ('automatic service-to-channel mapping operation'), with the scope limited to a running operation. The purpose is clear, though it does not explicitly distinguish itself from siblings such as tvh_map_services or tvh_mapper_status.

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

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

Provides no when-to-use or when-not-to-use guidance and does not point to alternatives like tvh_mapper_status or tvh_map_services. The agent must infer from the name that this applies only to an already-running mapping job.

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 this as a non-readonly, destructive, non-idempotent, open-world operation. The description adds useful behavioral detail beyond that: collection is asynchronous, delay limits differ for OTA vs. internal grabbers, and external XMLTV imports are excluded.

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 compact: the main action and asynchronous behavior are stated first, followed by timing constraints and the external XMLTV exclusion. Every sentence adds useful information without 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?

The output schema and annotations already cover return shape and safety profile, so the description does not need to explain those. It supplies the key async and timing context, but leaves dry_run semantics unstated, which is a noticeable gap for a destructive trigger 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?

With 0% schema description coverage, the description does meaningful work by explaining the kind distinction and delay constraints, including the internal-grabber requirement that delay must be 1. However, it does not explain dry_run at all, leaving one of the three parameters undocumented in both schema text and 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 uses a specific verb and resource: queueing/rerunning EPG collection, with a clear OTA vs. internal grabber distinction. It also excludes external XMLTV socket imports, which helps separate it from adjacent EPG tools, though it does not explicitly name a sibling alternative.

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

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

It gives clear usage context for OTA collection vs. rerunning enabled internal grabbers, including the key exclusion that external XMLTV socket imports are not triggered. It lacks explicit routing guidance to sibling tools, but the when-to-use conditions are otherwise 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 flag destructiveHint=true, idempotentHint=false and openWorldHint=true; the description adds useful scope by saying it writes global config and does not touch grabbers or XMLTV, and that the field set varies by build. But for a destructive, non-idempotent write it never warns about irreversibility, the dry_run escape hatch, or what state gets overwritten — the most important behavioral facts for an agent.

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 lines, prerequisite first, exclusion last, no filler. Every sentence carries information the 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?

An output schema exists, so return values needn't be described, and the prerequisite read is well covered. But for a destructive mutation over an opaque settings object, the missing dry_run guidance and the absence of any overwrite/irreversibility note leave a real 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 coverage is 0% and 'settings' is a free-form object with no declared properties, so the description must compensate; it does partly by directing the agent to get_epg_config for the actual cron/OTA/save field names. However, the dry_run parameter is never explained at all, which matters given destructiveHint=true.

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 (Update) and resource (global EPG fields) and names the backing endpoint (epggrab/config/save), which separates it from read siblings like tvh_get_epg_config. It does not say concretely which globals are covered, leaving 'fields' abstract.

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

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

Explicitly instructs 'Read get_epg_config first' and names the parameter source (cron/OTA/save fields), plus an exclusion: it does not install grabbers or upload XMLTV data. No mention of when to prefer tvh_assign_epg_sources or tvh_update_epg_module instead, so the routing is good but not complete.

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 destructive, non-idempotent and open-world, so the description's job is to add the missing context — yet it never warns that settings overwrite existing module state, doesn't explain what dry_run previews, and says nothing about permissions or reversibility. 'Configure' is non-contradictory but behaviorally empty for a destructive mutation.

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