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

Annotations only give readOnlyHint=true, and the description adds real behavioral detail: it reports non-dismissed alerts at WARNING+ only, datasets at 80%/90% of quota/available ceiling, and orders findings worst-first with the measured level/percent cited. It does not cover auth requirements, target resolution failures, or rate limits, so not 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?

Front-loaded with the one-word read marker followed immediately by the outcome, then the mechanics. The trailing Args block largely restates the schema, which is mild redundancy, but the body itself is tight and every clause carries 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?

No output schema exists, yet the description sketches the return shape (one finding per alert, one per dataset, worst-first, each citing the measured value) and the read-only nature is declared. Only operational caveats — what happens if the target is unreachable or if no alerts qualify — are absent.

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 schema gives only an untyped nullable string with default null, so the description carries the load — and does so: 'target: TrueNAS target name from config; omit to use the default.' That resolves both meaning and the null/omit behavior for the single 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?

States a specific verb ('Surface') and two concrete resources (active TrueNAS alerts by level, datasets near full), plus how it composes them ('collects the active alert list and the /pool/dataset listing'). It is distinguishable from alert_list and dataset_list by its aggregation/RCA semantics, though it never names a sibling explicitly, which keeps it just short of a 5.

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

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

Usage is implied by the aggregation framing (reach for this when you want a combined alert-plus-capacity health view), but there is no explicit 'use this instead of alert_list/dataset_list when...' statement and no exclusions or prerequisites. Adequate but leaves the choice against siblings 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 declare readOnlyHint=true, so the '[READ]' prefix is largely redundant. The description does add value by disclosing the returned fields (level, message, class, dismissed), but says nothing about result limits, ordering, or whether dismissed alerts can be filtered out.

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 line plus an args note, front-loaded with the action and the payload shape. The '[READ]' tag is slightly redundant given the readOnlyHint annotation, but nothing is bloated.

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

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

For a single-parameter read tool with no output schema, the description is nearly sufficient: it names the operation, the scope ('active'), the returned fields, and the fallback behavior of the sole parameter. Only return-volume/ordering behavior is left unstated.

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 — and it does, explaining that 'target' is a TrueNAS target name from config and that omitting it uses the default. That resolves the optional/nullable parameter's behavior completely.

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 active TrueNAS alerts') and enumerates the returned fields (level, message, class, dismissed), so the agent knows exactly what it gets. No sibling tool covers alert listing, so explicit differentiation is unnecessary.

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 by 'active alerts' — an agent can infer this is the tool for checking current alert state, but there is no stated when-to-use or when-not-to-use, and the nearby alert_and_capacity_rca sibling is never reconciled against it.

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

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

Annotations only supply readOnlyHint=true, so the description carries the rest and does add real value: it explains that ``state`` reflects the last run's job state (SUCCESS/FAILED/RUNNING), that it is null until the task has run, and that cloud-sync records carry no state of their own unlike replication records. It does not mention pagination, ordering, or what an omitted target returns, which are the remaining gaps.

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 the operation and returned fields, followed by a compact, high-value note on ``state`` semantics. The Args block is short; nothing feels padded, though the state paragraph is slightly verbose for the information conveyed.

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 list tool with no output schema, the description covers the returned fields and the non-obvious ``state`` semantics well. It stops short of explaining null/omitted ``target`` behavior and any filtering or pagination behavior, which an agent would need to call it confidently.

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% with one optional parameter, so the description must compensate and partially does by defining ``target`` as the TrueNAS target name from config. It does not say what happens when target is null or omitted (all targets vs. none), leaving a meaningful behavioral ambiguity in the only 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?

States a clear verb+resource ("List cloud-sync tasks") and enumerates the returned fields (description, direction, path, state). The aside that cloud-sync records "unlike replication ones, carry no state of their own" implicitly distinguishes it from the sibling replication_list, though the routing is left for the agent 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?

No explicit when-to-use or when-not-to-use guidance, and no alternative tools are named. The only usage-adjacent information is the semantics of the ``state`` field and the origin of ``target``, which is data interpretation rather than task 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?

The description asserts 'Non-destructive (creates new storage)' while annotations declare destructiveHint=true, a direct contradiction that could mislead an agent about whether user confirmation is warranted. It also omits other behaviors an agent needs, such as what happens when the dataset already exists (annotations say non-idempotent) or what the response contains.

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?

Well front-loaded: the write marker and one-line purpose come first, then the preview hint, then parameters. The 'No undo descriptor' sentence is slightly awkward and the Args block partially echoes the schema, but each line adds usable information.

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

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

For a 4-parameter mutation tool with no output schema, the description covers parameters and preview behavior but leaves key operational gaps: no return shape, no statement of what happens on a name collision (non-idempotent per annotations), and no permission/target prerequisites beyond 'from config'. Adequate but not complete.

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

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

Schema description coverage is 0%, so the description must carry the burden, and it does document all four parameters with meaning: 'name' is a full dataset path with a concrete example ('tank/projects'), 'pool' is optional context/labelling, 'dry_run' previews, and 'target' is a config target name. The name/pool distinction in particular resolves genuine ambiguity the bare schema leaves open.

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 ('[WRITE] Create a ZFS dataset'), which is unambiguous and immediately distinguishes it from dataset_list, dataset_get, and snapshot_create siblings. An agent can select this tool 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 condition for dry_run ('Pass dry_run=True to preview') and states that deletion is out of scope, which implicitly tells the agent this tool never removes data. However, it never names an alternative or states the prerequisite/preconditions for creating a dataset (e.g., pool must exist, target must be configured), leaving usage largely 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 '[READ]' prefix is consistent with readOnlyHint=true and adds a small amount of clarity, but it largely restates the annotation. Beyond safety it discloses nothing about behavior — no indication of what 'detail' includes, whether the id must exactly match, or what happens when the dataset is missing.

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?

Compact and front-loaded: the one-line purpose precedes the parameter notes, and there is no filler. Slightly under-specified rather than wordy, so it earns its length.

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

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

For a simple read of one record with no output schema and only two params, the essentials are present. Still missing: what the returned detail comprises, whether target is required when multiple targets are configured, and failure behavior — meaningful gaps for an agent that must call it correctly.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it does document both params: dataset_id as a TrueNAS dataset id with an example and a pointer to dataset_list, and target as a TrueNAS target name from config. The target description is thin (where in config? optional?) and no format/validation detail is given for dataset_id, so it compensates only partially.

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?

'Return detail for a single dataset by id' gives a specific verb (return/get) and resource (single dataset), with an example id ('tank/data'). It implicitly differentiates from dataset_list by saying 'single', though it never states the contrast 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?

The parenthetical '(see dataset_list)' routes the agent to the sibling for enumerating datasets, which implies this tool is for fetching one known dataset. However, there is no explicit when-to-use statement, no prerequisite (e.g. must the dataset exist / must target be configured), and no exclusions.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is carried structurally; the description adds the [READ] marker and, more valuably, the set of fields returned (id, name, type, pool, used/available), which compensates for the absent output schema. It still omits any pagination or filtering behavior for large pools.

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 lines with the purpose and the returned fields front-loaded; the Args block is slightly heavier machinery than one optional parameter warrants, but nothing is wasted.

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

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

With no output schema, the description supplies the return fields and the optional target semantics, which is enough to call the tool correctly. It stops short of describing result ordering, filtering, or scale behavior for environments with many datasets.

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 explain the single 'target' parameter on its own, and it does: it is a TrueNAS target name from config, optional, defaulting to the configured default. This fully covers the one parameter the schema leaves undocumented.

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 (ZFS datasets) and enumerates the returned fields (id, name, type, pool, used/available). The list-vs-get distinction from siblings like dataset_get is inferable from the verb, but the description never explicitly contrasts them.

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 only contextual guidance is that 'target' may be omitted to fall back to the default; there is no statement of when to reach for dataset_list versus dataset_get, pool_list, or any other sibling. The [READ] tag hints at a safe operation but does not route the agent.

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?

readOnlyHint=true already tells the agent this is a safe read, so the '[READ]' prefix is largely redundant. The description does add useful context that target resolves against a named config entry and falls back to a default, but says nothing about pagination, scope of enumeration, or failure modes when a target is 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?

Two sentences plus a parameter line, front-loaded with the action and its output fields. The '[READ]' tag and 'Args:' framing are mild overhead but nothing is padded or buried.

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 read-only, no-required-parameter list tool with no output schema, the description covers what the caller needs: what is listed, what comes back, and how the optional target resolves. Missing only edge-case behavior such as empty results or invalid target handling.

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% – the single target parameter has no description in the schema – so the description must carry the load, and it does by explaining that the value is a TrueNAS target name from config and that omission selects the default. That is real added meaning, though it doesn't specify format or valid values.

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 physical disks') and enumerates the returned fields (name, serial, model, size, pool), which makes it easy to tell apart from pool_list or dataset_list. It stops short of naming a sibling to disambiguate against, so 4 rather than 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 description implies the use case (inventory physical disks) and gives one concrete operating rule – omit target to use the default – but never states when to prefer this over pool_list, pool_get, or smart_test_results. Usage is inferable rather than explicit.

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

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

readOnlyHint=true already covers the safety profile, and the description reinforces it with the '[READ]' prefix while disclosing that this is an aggregate snapshot of three domains rather than a single resource. It does not mention pagination, latency, or failure behavior, but with annotations carrying the safety burden and no output schema, this is solid contextual disclosure.

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 paragraphs, the purpose and routing rule front-loaded, with the argument note kept to a single line. No filler.

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

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

For a no-required-argument aggregate read with annotations and no output schema, the description supplies the selection policy, the param meaning, and the returned domains. Only the shape of the aggregated payload is left implicit, which is a minor gap.

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

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

Schema description coverage is 0% for the single 'target' parameter, so the description must carry it entirely – and it does, explaining that it is the TrueNAS target name from config and that omission falls back to the 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?

It names a specific verb and resource ('one-shot health summary') and enumerates the covered domains (pools capacity/health, alerts, services), which cleanly distinguishes it from the granular siblings like pool_status, alert_list, and service_list.

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

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

'Call this first to triage a TrueNAS system before drilling into a specific pool, dataset, or service' is explicit routing guidance, both telling the agent when to use it and pointing to the drill-down alternatives it supersedes on the first call.

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?

readOnlyHint=true already declares the safety profile, so the '[READ]' prefix is largely redundant. The description does add output-content context (the per-pool fields returned) despite there being no output schema, but says nothing about pagination, permissions, or behavior when target is omitted.

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 '[READ]' tag, then a compact one-line summary and a short args block. No filler, though the args formatting is slightly awkward for a tool whose single parameter is optional.

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 tool with no output schema, the description covers what is returned and what the parameter means. The remaining gap is sibling disambiguation, which matters given pool_list/pool_get/pool_status in the same family.

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 — and it does, explaining that 'target' is the TrueNAS target name from config rather than, say, a pool name. It stops short of explaining the null default (what happens when target is omitted).

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 — a read-only capacity summary per pool — and enumerates the returned dimensions (size/allocated/free, used percent). It is distinguishable from dataset-level siblings, though it does not explicitly contrast with pool_list or pool_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?

No when-to-use guidance is given. With pool_list, pool_get and pool_status as siblings, an agent gets no hint about which to call for a capacity question versus a health or inventory question. The '[READ]' tag implies safety but not selection criteria.

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

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

The '[READ]' prefix is consistent with readOnlyHint=true, so there is no contradiction, but it repeats what the annotation already declares. The description adds the useful scoping fact that it returns a single pool rather than a collection, yet says nothing about failure behavior for an unknown id or what fields come back. With annotations covering the safety profile, a 3 is appropriate.

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

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

The purpose is front-loaded in the first sentence, and the Args block is compact with one line per parameter. Structure is clean and every sentence earns its place; only the redundant '[READ]' tag slightly duplicates the annotation.

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-record read tool with an explicit readOnlyHint and no output schema, the description covers purpose, both parameters, and the source of a valid id. Nothing critical for invocation is missing, though the absence of a vs-sibling note leaves some ambiguity against pool_status and pool_capacity.

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, and it does document both parameters: pool_id as a TrueNAS pool id with a pointer to pool_list, and target as a TrueNAS target name from config. That meaningfully compensates for the empty schema descriptions, though it gives no format examples for pool_id.

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: 'Return detail for a single pool by id', which clearly separates it from the list-style sibling pool_list. It does not, however, distinguish itself from the other per-pool readers in the sibling set (pool_status, pool_capacity, pool_health_rca), so an agent must infer whether 'detail' overlaps with those.

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 parenthetical '(see pool_list)' implicitly tells the agent how to obtain a pool_id, which is useful routing. But there is no statement of when to use this tool versus pool_status or pool_capacity, and no exclusions or prerequisites beyond that hint.

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 readOnlyHint=true already covering safety, the description adds real behavioral context: it pulls /pool with topology + scan, orders output worst-first, and states each finding cites measured status/counts/percent plus a concrete action. It stops short of noting auth requirements, pagination, or behavior across multiple targets.

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 a '[READ] Flag ...' headline followed by a tight scope paragraph; the trailing Args block is slightly redundant boilerplate but still useful for the undocumented parameter. Overall every sentence carries information.

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

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

For a single-parameter, read-only tool with no output schema, the description supplies everything an agent needs: what is fetched, what triggers a finding, the ordering, the evidence included per finding, and the default value behavior of the sole parameter.

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% (the lone 'target' param has no schema description), so the description carries the burden and does so fully: it names the parameter, explains it is a TrueNAS target name from config, and states that omitting it uses the 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?

States a specific verb and resource — 'Flag ZFS pools by state, error counters, and capacity' — and enumerates the exact conditions (DEGRADED/FAULTED/OFFLINE, non-zero error counters, 80%/90% thresholds). It implicitly distinguishes itself from raw-listing siblings like pool_list/pool_status by describing analysis-and-flagging rather than dumping, though it never names an 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?

Clear context is given: this is the tool to call when you want problematic pools surfaced and triaged, with the triggering conditions spelled out. However there is no explicit 'use pool_list instead when you want the raw listing' routing statement, so the agent must infer the boundary with siblings.

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

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

Annotations already declare readOnlyHint=true, so the '[READ]' prefix largely repeats structured data. The description does add the list of returned fields and the fact that all pools are listed (no filtering mentioned), which is modest extra context. No pagination, ordering, or failure behavior is 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?

Front-loads the verb and resource, keeps to one sentence plus a short Args block. The '[READ]' tag is slightly redundant given readOnlyHint but does not hurt readability. Overall compact and structured.

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

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

For a simple read-only list tool with one optional parameter and no output schema, the description covers the essentials. It lacks explicit guidance on filtering, ordering, or error cases, and gives no hint about result volume, but is adequate for a low-complexity enumerator.

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% but there is only 1 parameter, so the baseline is 4 for zero-param-like simplicity; however the single 'target' parameter does have a description in the text (config target name, defaults to default). This adds some meaning over the bare schema, landing at 3 given the low coverage is largely mitigated by param count.

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?

Clearly states verb+resource: 'List ZFS pools' with the fields returned (id, name, status, health, capacity). Distinguishes from pool_get, pool_status, pool_capacity, and pool_health_rca by being the general enumerator, but does not explicitly name those siblings, so it falls short of a 5.

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

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

Usage is only implied: the list nature and the '[READ]' marker suggest it's a safe enumeration, and the target note gives light context. There is no explicit when-to-use guidance vs pool_get or pool_status, and no when-not-to-use exclusions.

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

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

The description states "Non-destructive," while the annotations declare destructiveHint=true — a direct conflict on the same axis. It does add useful behavior (dry-run preview, no undo descriptor, don't re-issue, poll via scrub_status), but the flat contradiction with the structured safety hint is precisely what triggers a score of 1 and the Annotation Contradiction flag.

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 the [WRITE] tag and the one-line purpose, followed by short, high-signal sentences on preview, undo, and polling. The undo-descriptor aside is slightly meta but carries real information about the surrounding undo_list/undo_apply ecosystem, so little is wasted.

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

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

With 0% schema coverage, no output schema, and a mutating operation, the description covers purpose, preview, idempotency guidance, and progress tracking. It omits anything about the result shape, required privileges, or how long a scrub takes, but the essentials for calling it correctly are present.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does: pool_name is explained with an example ('tank'), dry_run's preview semantics are stated, and target is identified as a TrueNAS target name from config. No types, defaults, or value constraints beyond the schema are added, which keeps it just short of a 5.

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

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

Specific verb + resource: "Start a scrub (integrity check) on a pool," with the mode tagged as [WRITE]. The parenthetical gloss clarifies what a scrub is, and the sibling scrub_status is named as the progress-polling counterpart, so an agent can distinguish the two without opening either 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?

Explicit routing: "Pass dry_run=True to preview" and "Poll progress with scrub_status; do not re-issue." It states both the preview path and the alternative tool for progress, which is exactly the when-to-use/when-to-use-something-else guidance the dimension asks for.

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?

readOnlyHint=true already establishes the safe-read profile, and the '[READ]' tag merely restates it. The description does add value by scoping the return to health plus scan/topology status, but it says nothing about auth requirements, failure modes, or how expensive the call is.

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 single-sentence summary is front-loaded and the Args block is terse and scannable. Nothing is padded, though the bracketed '[READ]' tag is redundant with the annotation and slightly wastes the opening position.

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

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

With no output schema, the description must convey what comes back, and it does so at a useful level (health and scan/topology status). It omits return structure and error behavior, but for a simple read-only status call it is 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%, so the description carries the full burden, and it does document both parameters: pool_id as the TrueNAS pool id and target as the target name from config. That meaningfully fills a gap the schema leaves entirely blank, though it does not note that target is optional or has a null 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 names a specific verb+resource: health and scan/topology status of a single pool, which is more informative than a bare 'get pool'. However, it never distinguishes itself from closely overlapping siblings like pool_get, pool_health_rca, pool_capacity, or scrub_status, so an agent cannot tell from the text alone which one to pick.

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, when-not-to-use, or alternative-tool guidance. The phrase 'of a single pool' weakly implies contrast with pool_list, but the reader gets no signal about when pool_status is preferable to pool_get or pool_health_rca.

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

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

Annotations only declare readOnlyHint=true, and the description goes well beyond that: it explains that state is never absent (PENDING before first run), that ERROR rows carry an appliance-supplied error sentence naming what to fix, and that lastSnapshot/lastRun are returned in epoch milliseconds. This is exactly the kind of runtime behavior an agent needs and cannot get from the schema.

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

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

The summary line is front-loaded and the state/return-value detail is placed after it, then the args block. It is slightly verbose in the state enumeration, but every sentence conveys operational meaning rather than filler.

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

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

With no output schema, the description correctly takes on the burden of describing return content (state values, error sentence, lastSnapshot, lastRun). It is nearly complete; it does not mention ordering, filtering, or result size for a list operation, which is a minor remaining gap.

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

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

Schema description coverage is 0%, so the schema alone would leave the single target parameter undocumented. The description compensates by defining target as a TrueNAS target name from config and stating that omitting it falls back to the default, which is the key semantic an agent needs.

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?

Opens with a specific verb and resource ("List replication tasks") plus the exact fields returned (name, direction, transport, state), and the [READ] tag marks it as a non-mutating inspection tool. It is clearly distinguishable from siblings like cloudsync_list and snapshot_list, which cover different resources.

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 only usage guidance is the target parameter's default behavior ("omit to use the default"). There is no statement of when to reach for this tool over cloudsync_list or snapshot_list, and no prerequisites or exclusions are given, leaving usage to inference from the name.

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, so the '[READ]' tag is partly redundant. However, the description adds value by disclosing the shape of the returned state (function/state/percentage), which matters since there is no output schema.

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

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

Front-loaded with the read marker and purpose, followed by a compact Args block. No wasted filler; the only minor redundancy is restating read-only intent that the annotations already carry.

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

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

For a simple two-parameter read tool with no output schema, the description covers the returned fields and both inputs adequately. Minor gaps remain around the optionality/default of target and the possible enum values of the scrub 'function' field.

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 parameter burden and does cover both parameters: pool_id is identified as the TrueNAS pool id and target as the TrueNAS target name from config. It adds useful context that target derives from config, though it omits that target is optional/nullable and does not explain the 'function' field formats.

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 ('Current scrub scan state ... for a pool') and even names the returned fields (function/state/percentage). It is distinguishable from the write sibling pool_scrub_start, though it does not name that 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?

The '[READ]' marker and the word 'Current' imply this is for inspecting an in-progress or completed scrub rather than starting one, but there is no explicit when-to-use, when-not-to-use, or named alternative (e.g. pool_scrub_start). Usage is only inferable.

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?

readOnlyHint=true already tells the agent this is a safe read, and the description adds value beyond that by declaring the state domain (RUNNING/STOPPED) and the fields returned, which matters because there is no output schema. It stops short of covering auth, pagination, or error behavior, but the bar is lower with annotations present.

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

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

Front-loaded with the [READ] marker and the core purpose, followed by a short Args block. Efficient with no filler, though the bracketed marker and Args formatting are slightly more verbose than strictly necessary.

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 read-only one-parameter list tool with no output schema, the description supplies the missing pieces: the read nature, the returned fields, and the parameter's default behavior. Only minor gaps remain (no mention of service_restart as the mutation counterpart, no sort/filter notes).

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 single parameter, and it does: target is the TrueNAS target name from config and can be omitted in favor of the default. That is exactly the semantics an agent needs for a nullable, defaulted argument.

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+resource ("List system services") and even enumerates the returned fields (name, state, enable), which is more than most list tools offer. It does not explicitly name the sibling alternative (service_restart), so it falls short of the top mark for 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 only usage guidance is on the target argument ("omit to use the default"), which is really parameter help rather than when-to-use guidance. There is no statement about when to pick this over service_restart or other *_list tools, so usage is only implied by the verb.

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?

While annotations already flag destructiveHint=true and idempotentHint=false, the description adds substantial context beyond them: it captures prior state for audit, declares no undo, explains the ssh guard and its out-of-band rationale, and notes refusals hold under dry_run. This is unusually rich disclosure 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?

The critical constraints are front-loaded and every passage carries meaning, but the dry_run refusal sentence is somewhat wordy and the description is longer than strictly necessary. Structure and ordering are otherwise excellent.

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

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

With no output schema and a destructive operation, the description supplies everything an agent needs: preconditions, the ssh special case, dry_run semantics, audit behavior, and irreversibility. Nothing material is left unstated.

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 — and it does, documenting all four params including the conditional semantics of 'confirm' (required only for ssh, ignored otherwise) and the target's config provenance. This fully compensates for the empty schema descriptions.

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

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

The description states a specific verb and resource ('Restart a system service') with concrete examples ('smb', 'nfs') and a '[WRITE]' marker. An agent can immediately distinguish this from read-oriented siblings like service_list.

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

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

It gives explicit conditions: use dry_run=True to preview, confirm=True only for restarting 'ssh', and the service name must exist in service_list. It names the discovery alternative (service_list) and states refusal behavior rather than leaving it 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?

readOnlyHint=true already establishes the safe-read profile, and the '[READ]' tag merely restates it. The description does add one piece of context beyond annotations: that 'target' comes from config, and that the result set is per-disk with status/description fields. It says nothing about how many disks are queried, whether a target can be omitted, or freshness of results.

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 the resource and scope in the first clause, then a compact Args block. Every line earns its place; the only redundancy is the '[READ]' tag, which duplicates readOnlyHint.

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 tool with no output schema and annotation-covered safety, the description is nearly sufficient: it identifies the resource, scope, and returned field hint (status/description). It omits how results are scoped when target is absent, which is the one gap an agent would likely hit.

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 single 'target' parameter, so the description must carry the load — and it partially does by stating 'TrueNAS target name from config', which explains the value's origin. It does not explain the null/default behavior (the parameter is optional with default null) or what happens when target is omitted.

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

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

The description names a specific resource and scope: 'Recent S.M.A.R.T. self-test results per disk (status/description)', which is clearly distinct from siblings like disk_list, pool_status, or scrub_status. It lacks an explicit verb and does not name any sibling it contrasts with, 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 when-to-use guidance, no conditions or prerequisites, and no mention of alternatives such as disk_list for raw disk inventory or pool_health_rca for aggregate health diagnosis. The agent must infer that this is for interpreting individual disk self-test outcomes.

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, and idempotentHint=false, so the safety profile is covered. The description adds genuine context beyond that: the [WRITE] tag, that dry_run previews without creating, and notably that a preview also omits the undo token — implying real creates are undoable via the undo_list/undo_apply siblings.

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 the [WRITE] marker and inverse reference, and the Args block is justified given zero schema coverage. Slightly formulaic listing, but no sentence is wasted and the essential information comes first.

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

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

A mutation tool with no output schema and annotations covering the destructive profile; the description covers semantics, preview behavior, and undo-token implications. It omits failure behavior — e.g. what happens if the snapshot already exists, which matters given idempotentHint=false.

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 parameter burden and does so: dataset with a path example ('tank/data'), name with a naming example, dry_run with its preview and undo-token implication, and target as a TrueNAS target name from config. All four params gain meaning the schema lacks.

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 ZFS snapshot'), gives the exact naming form 'dataset@name', and names the inverse sibling snapshot_delete. An agent can distinguish it from snapshot_list and snapshot_delete 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?

Clearly frames this as the write path with snapshot_delete as its inverse, and describes the dry_run preview option. It stops short of stating explicit exclusions (e.g. when to prefer snapshot_list first, or behavior when the snapshot already exists).

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds substantive context beyond them: irreversibility, the dry-run preview path, and that prior state is captured for the audit record with no undo declared. This meaningfully informs the agent's risk calculus.

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

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

Front-loads '[WRITE]' and 'IRREVERSIBLE', then preview guidance, then args – a sensible ordering. Minor redundancy between 'IRREVERSIBLE' and 'declares no undo' costs a point.

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

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

For a 3-param destructive tool with no output schema and no annotation coverage of detail, the description supplies purpose, safety, preview path, and per-param meaning. Missing only peripheral items like auth requirements or behavior when the snapshot does not exist.

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

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

Schema description coverage is 0%, so the description must carry the params, and it documents all three: snapshot_id with its 'dataset@name' format, dry_run's preview behavior, and target as a TrueNAS config name. Only the target's default/optional nature is left to the schema.

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

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

Names a specific verb (Delete) and resource (ZFS snapshot) plus the exact identifier format 'dataset@name'. It is clearly distinguishable from snapshot_create and snapshot_list among its 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?

Gives real usage context: preview via dry_run=True, and points to snapshot_list for id format. It does not, however, explicitly route the agent to undo_apply/undo_list or state when restoration is preferable, so it falls short of a full when/when-not guide.

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

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

Annotations only declare readOnlyHint=true; the description goes further by disclosing the exact return shape (snapshots, returned, limit, truncated) and the meaning of the truncation flag. That extra return-value and result-cap behavior is genuine value beyond the annotation, though no pagination or permission notes are given.

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 the purpose, then the return shape, then the args block — a logical order with no filler. The Args section largely restates parameter names, but each line adds a clarifying phrase, so little is wasted.

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

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

There is no output schema, and the description compensates by documenting the response envelope and truncation semantics. Combined with full parameter explanation and the read-only framing, an agent has what it needs, though limits/ranges and error behavior remain unstated.

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 and does: dataset is explained with a concrete example ('tank/data'), limit is defined as max rows with its default, and target is identified as the TrueNAS target name from config. All three parameters gain meaning absent from 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 and resource ('List ZFS snapshots') plus scope ('optionally filtered to one dataset'), and the [READ] tag immediately separates it from snapshot_create and snapshot_delete. An agent can select it without opening any schema.

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

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

Gives clear operational guidance for the truncation case ('re-run with a higher limit or filter to one dataset'), which tells the agent how to follow up. However, it never states when to prefer this tool over siblings such as snapshot_delete or replication_list, so differentiation is implicit rather than explicit.

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

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

readOnlyHint=true already establishes the safety profile, and the '[READ]' tag in the description is consistent with it. The description adds that this is a summary view (not a deep inspection), but says nothing about latency, auth requirements, or failure modes when a target is 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?

One front-loaded line naming the resource and its contents, followed by a compact Args block. No filler or restated boilerplate; slightly more could be said about the sibling relationship within the same budget.

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

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

A single-optional-parameter read tool with no output schema and readOnlyHint supplied; the description covers the return fields and the target semantics, so an agent has what it needs. Only the routing versus `overview` is left unstated.

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% — the schema only says 'Target' with a null default. The description compensates by explaining it is a 'TrueNAS target name from config' and that omitting it uses the default, which is exactly the missing semantic. It is the sole source of meaning for the parameter.

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

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

States a specific resource (TrueNAS system info) and enumerates what it returns (version, hostname, memory, cores, uptime), which tells an agent exactly what to expect. It does not explicitly contrast itself with the sibling `overview`, which likely overlaps, but the scope is unambiguous.

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

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

No statement of when to use this versus `overview` or the various `pool_*`/`dataset_*` siblings. The only guidance offered is about the target argument, which is parameter-level rather than usage-level.

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; the description adds that the inverse executes through its own governed tool and risk tier (audit behavior) and that tokens are single-use. Useful beyond the annotations, though it doesn't say what the inverse might mutate.

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 [WRITE][risk=medium] tag front-loads the mode and risk, and the body is tight. The Args block partially restates the schema titles, but each line adds semantics, so little is wasted.

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

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

No output schema, but the description explains the dispatch model, the dry-run preview path, and the one-time token constraint, which covers the essentials for a mutation tool. It could clarify failure behavior (e.g., applying an already-used token) to be 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 load, and it documents all three params: undo_id's source, dry_run's preview semantics, and target's pass-through role. The 'target' explanation ('when it accepts a target') is a bit thin but directionally complete.

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 ('apply') and resource ('a recorded undo') plus the mechanism (dispatching its inverse tool). This clearly distinguishes it from the sibling undo_list, which only enumerates tokens.

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

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

Gives concrete guidance: undo_id comes from undo_list or an _undo_id in a write result, use dry_run=True to preview, and a token can only be applied once. It stops short of saying when not to use it or when preview is mandatory, but the 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 cover only readOnlyHint=true, yet the description adds substantive behavior the annotations cannot: the truncation contract ('re-run with a higher limit rather than treating the list as complete'), the off-by-one measurement detail, and the crucial effectVerified semantics warning that a reversed change may be PROBABLE, not confirmed. This is exactly the kind of context that changes agent 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?

Front-loaded with purpose, then the return shape, then the caveats; each paragraph addresses a distinct decision. It runs slightly long for a two-parameter list tool, but no sentence is filler — the truncation and effectVerified notes both prevent concrete agent errors.

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?

No output schema exists, but the description supplies the return shape ({"undos", "returned", "limit", "truncated"}) and per-entry fields (original tool, inverse tool, note, effectVerified). Combined with the parameter documentation, an agent has everything needed to call it and interpret the result correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden and does: limit is documented with default 50 and hard cap 500, and target is explained as unused/host-local/accepted-for-CLI-uniformity — a non-obvious parameter that would otherwise confuse an agent into trying to scope the call.

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?

Opens with a specific verb+resource and scope: 'List recorded, not-yet-applied undo tokens (most recent first).' It also names the companion tool undo_apply and the field linking them (undoId), so an agent can separate it from undo_apply without opening either 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?

Explicitly tells the agent to 'Use the undoId with undo_apply', routing it to the sibling that performs the mutation. It gives clear operational context (check live state before applying when effectVerified is false) but never states exclusions, e.g. that this is host-local and cannot target remote systems beyond the 'target' note.

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