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

The description adds one useful behavioral detail (None query params are filtered out), which the schema does not state. However it explicitly advertises DELETE support while annotations declare destructiveHint=false — an agent routing a delete through this tool would not be warned of destruction by the annotations. It also omits that `wait` (default true) makes the call block/poll, which materially changes call behavior.

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

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

Three short sentences, front-loaded with the capability and followed by the two actionable hints. No filler; a small amount of space is arguably underused for a 12-parameter escape hatch, but nothing present is 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?

This is a 12-parameter, nested-object, no-output-schema passthrough, so the description carries the full burden of explaining return shape and blocking semantics — and it does neither. An agent cannot tell from the text whether a call returns immediately with a task/event handle, whether `wait` blocks until completion, or how download_path/upload_file change 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?

With 58% schema coverage, the description fills some gaps: it clarifies body construction via sylve_api_schema and explains query_params filtering behavior, and the method list mirrors the enum. But the most consequential parameters — wait, wait_timeout, event_kind, upload_file, download_path — are left entirely to brief schema text, and the interaction between wait and wait_timeout is never explained.

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

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

The description states a specific verb (execute) and resource (any documented Sylve API operation) and enumerates the supported HTTP methods, so an agent immediately knows this is a raw API passthrough rather than a domain tool. It does not, however, distinguish itself from the ~30 dedicated siblings (sylve_vm_action, sylve_backup, etc.), so the agent must infer that this is the fallback for undocumented operations.

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

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

"Combine with sylve_api_schema to build accurate bodies" gives a concrete workflow hint, which is genuine usage guidance. But there is no statement of when to prefer this over the many purpose-built sibling tools, and no warning that this bypasses those higher-level wrappers — usage is implied rather than prescribed.

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=false, so the safety profile is covered. The description adds a useful behavioral detail beyond annotations: it returns the schema with $refs resolved, which tells the agent what kind of output to expect.

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

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

The description is two sentences with no wasted text. The primary purpose is front-loaded, followed by the prerequisite for finding the operation.

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

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

This is a simple read-only schema introspection tool whose annotations already convey safety. The description explains what is returned ('full request/response schema with $refs resolved') and the required discovery step, which is sufficient given the schema and absence of an output schema.

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

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

Schema description coverage is 75%, and the schema documents node, path, and context, while method is constrained by an enum. The description only implies that method and path identify 'one Swagger operation'; it adds no further meaning about the node or context parameters.

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

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

The description states a specific verb and resource: 'Show the full request/response schema ... for one Swagger operation.' It also distinguishes this tool from the discovery step by directing the agent to sylve_api_search first, 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?

The description gives a clear prerequisite: use sylve_api_search to find the operation before calling this tool. It does not explicitly mention sylve_api_call or state when not to use this tool, but the intended workflow 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=false, so the safety profile is fully covered by structured data. The description adds no behavioral context beyond that - nothing about result size, the default limit of 50, pagination, or what a match record contains. With annotations carrying the load, this is adequate but adds little.

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, zero filler, with the resource and the workflow hint front-loaded. Nothing is repeated from the schema and nothing could be cut without losing information.

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

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

For a zero-required-parameter discovery tool feeding into sylve_api_call, the description never says what a result contains (operation path, method, summary?) or how to feed it into the follow-up call, and there is no output schema to cover that. It is enough to invoke the tool but not enough to use its output 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?

The description mirrors the query, tag and method parameters, but says nothing about node, limit or context, which together make up the other half of the six parameters (schema coverage 67%). Baseline 3 is appropriate since the schema documents most parameters on its own, but the description compensates for none of the 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 and resource ('Search all Sylve Swagger operations') plus the three searchable dimensions (keyword, tag, HTTP method), and frames the discovery-then-call workflow. It does not name the closely related siblings sylve_api_schema or sylve_api_call, so the boundary between searching for an operation and inspecting/calling one is left 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?

'Use this to discover any of the 441 endpoints before calling them' gives clear when-to-use context and establishes this as the entry point of the API workflow. There is no explicit exclusion versus sylve_api_schema (which presumably drills into a single endpoint), so an agent must infer the split.

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 readOnly=false, so the safety bar is lower. However, this tool mixes harmless read actions (targets, jobs, events) with a destructive restore in one entry point, and the description never warns that restore overwrites guest data or that `wait`/`wait_timeout` make calls blocking. That mixed-risk profile is exactly what the description should disambiguate.

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 sentence is waste-free and front-loads the inspection purpose, but at nine words it is drastically undersized for a 7-action, 12-parameter tool. Brevity here trades away necessary structure rather than achieving conciseness.

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 a destructive, non-idempotent tool with nested body object, 25% schema coverage, no output schema, and no per-action contract, the description leaves the agent without the information needed to invoke it correctly. It should at minimum enumerate action modes with their required parameters and flag restore as destructive.

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

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

Schema description coverage is only 25% across 12 parameters, so the description must compensate — and it adds nothing. It does not explain which parameters are required per action (e.g., job_id for run_job, target_id/guest_id/body for restore), nor what `wait`, `wait_timeout`, `limit`, or `node` do at the call level.

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

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

The description names a resource (backups) and rough verbs (inspect, run, restore), but it is a single sentence covering a multiplexed tool with seven distinct action modes. Three of those modes (snapshots, event_progress, and the per-job/target/guest scoping) are not signalled at all, and nothing distinguishes it from siblings like sylve_vm_snapshot, sylve_zfs_snapshot, or sylve_replication.

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?

"Inspect ... run or restore" implies a usage, but there is no guidance on when to pick this tool over the ZFS/VM snapshot siblings. It also never says that the `action` parameter selects the mode, so the agent must infer the entire routing logic from the enum 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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds only the aggregation scope, with no mention of return shape, pagination, or cost of a full-cluster sweep across many nodes.

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, and the scope qualifier is placed where it matters. Nothing to trim.

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

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

For a two-optional-parameter read-only listing tool with full annotation coverage and no output schema, this is nearly complete. The only residual gap is that an agent gets no hint about the volume or shape of results from a cluster-wide sweep.

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

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

Schema description coverage is 100%, so both the node and context parameters are already documented in the schema. The description's phrase 'across all cluster nodes' reinforces that node is optional, but adds no syntax or format detail beyond what the schema provides.

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

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

States a specific verb ('List') and resource set ('every VM, Jail, and template') with an explicit scope ('across all cluster nodes'). This clearly differentiates it from sylve_vm_list and sylve_jail_list by being the cross-node aggregate, though it never names those siblings directly.

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

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

The cluster-wide framing implies when to use it (a full inventory rather than a single-type listing), but there is no explicit 'use this instead of sylve_vm_list/sylve_jail_list when...' guidance or exclusion statement. Usage is inferred, not 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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the scope of returned data (leader, quorum, health, counts), which is genuinely useful, but says nothing about freshness, cost, or failure behavior when quorum is lost.

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 the verb and resource first and the enumerated payload after. No filler, nothing redundant.

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 usefully enumerates what the response contains, which is the right compensation. Slightly incomplete in that it doesn't clarify whether the counts are cluster-wide or per-node when the node parameter is supplied.

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

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

Schema description coverage is 100% and both parameters (node, context) are documented in the schema, including the 'Omit for cluster-wide' semantics. The description contributes no additional meaning about how node scoping affects the reported leader or quorum view.

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 (Show) and resource (cluster status), then enumerates the exact contents: Raft leader, quorum, node health, guest counts. This distinguishes it from the closest sibling sylve_cluster_resources, though it never names 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?

Usage is only implied by the content list — an agent can guess this is the overview/health call rather than a detail call, but the description gives no when-to-use or when-not guidance and no reference to sylve_cluster_resources or sylve_node_list as 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds one useful behavioral fact — that it reads a local YAML config file rather than the cluster API — but says nothing about output shape, empty results, or error behavior when the file 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?

A single sentence that front-loads the verb and resource with zero filler or redundancy. Nothing could be removed without losing 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 simple, read-only, zero-required-parameter list tool with full schema coverage and rich annotations, the description is sufficient to invoke it correctly. It omits only minor details such as return format and behavior when the config file is absent, which the annotations partly compensate for.

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 100%, so both the `node` and `context` parameters are already documented in the schema. The description only explains the config file that `context` refers to, adding marginal meaning beyond the schema, which is the baseline 3 case.

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 (List) and resource (configured Sylve login contexts) plus the exact source file, so the agent knows precisely what is returned. It does not reference any sibling tool or contrast its role (e.g., versus sylve_whoami or sylve_cluster_status), 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?

Usage is only implied: the agent can infer this is the discovery step for valid context names before calling other tools, but the description never states when to use it, when not to, or which sibling to prefer. No prerequisites or follow-up guidance 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 destructiveHint=true, readOnlyHint=false, idempotentHint=false, and openWorldHint=false, so safety is largely covered. The description adds that the tool can queue URL downloads and delete ISOs/images, but it does not disclose irreversibility, permission requirements, or side effects beyond what annotations provide.

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

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

The description is a single front-loaded sentence that covers the main operations without wasted words. It is appropriately concise for a tool summary, though brevity here contributes to gaps covered in other dimensions.

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 complex 12-parameter tool with low schema description coverage and no output schema. The one-sentence description is not sufficient to guide action selection, parameter usage, or expected behavior for add/delete operations, leaving significant gaps for an agent invoking it.

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

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

Schema description coverage is only 33%, yet the description does not explain the 12 parameters or map actions to required fields such as ids, url, storage_pool, extract, filename, download_type, raw_convert, or ignore_tls. It mentions URLs and images in passing but provides no substantive parameter guidance to compensate for the low schema coverage.

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

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

The description names specific operations (list, show, queue/add, delete) on a concrete resource (URL downloads, ISOs/images) and identifies the downloader as the target. It is clear enough for an agent to distinguish this from VM, jail, ZFS, and network siblings, though it does not explicitly differentiate itself from those tools.

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

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

The description enumerates the available actions, implying when each might be used, but it does not state when to prefer this tool over alternatives, prerequisites, or constraints such as when deletion is appropriate. The action mapping is helpful but incomplete.

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 only the batch aspect ('one or more'). It never explains that stop/restart terminate running workloads, what 'wait' and 'wait_timeout' do (synchronous blocking up to 60s), or what happens to a jail that fails mid-action.

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, and the action set plus identifier form appear first. It is efficient, though that efficiency comes partly from omitting needed detail.

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

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

For a destructive, non-idempotent mutation tool with six parameters, a third of them undocumented and no output schema, the description is thin. The safety and dry-run/async expectations an agent needs before firing a stop across a cluster 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 description coverage is only 33%: 'node' and 'context' are documented in the schema, but 'wait', 'wait_timeout', 'jails' and 'action' are not. The description clarifies only that jails are identified by CTID or name; it says nothing about the wait/timeout semantics or the action enum values, leaving half the 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 gives a specific verb set (start/stop/restart) and resource (Jails), plus batch scope ('one or more') and identifier form ('by CTID or name'). This clearly separates it from sylve_jail_create, sylve_jail_delete and sylve_vm_action, though it does not name those siblings 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?

There is no guidance on when to use this versus sylve_jail_create/delete, no prerequisites, and no note on the 'node' parameter choosing cluster-wide versus single-node execution. The agent must infer all routing and preconditions from the schema 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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds almost nothing beyond that: it does not say that create is a long-running download of base sets, that delete is irreversible, or that the list action is a harmless read despite the blanket destructive flag. For a three-mode tool, the description leaves the agent to guess the behavior of each mode.

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 the three modes come first. It is efficient, though the brevity is achieved by omitting information rather than by editorial discipline.

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 8 parameters, three distinct modes, no output schema, and destructive behavior, this tool needs far more than one sentence. The description never covers which parameters are required for which action, what the return looks like, or how the operation relates to the download/jail siblings, so it is inadequate for the tool's complexity.

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

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

Eight parameters at 63% schema coverage, and the description contributes no parameter meaning at all. Critically, it does not map parameters to actions (name for delete, major/minor for create, pool for all) nor explain the action enum values, which is the single most important thing for a multi-action tool. The phrase 'on a ZFS pool' only weakly hints at the pool parameter that the schema already documents.

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 three concrete verbs (list, create, delete) and a specific resource ('pkgbase FreeBSD jail bootstraps on a ZFS pool'), so the agent knows exactly what the tool touches. It does not differentiate itself from close siblings like sylve_jail_create, sylve_jail_delete, or sylve_jail_list, so an agent cannot tell from the description alone whether 'bootstrap' is a prerequisite step or an alternative to jail creation.

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 choose this tool over the jail_* siblings, no prerequisites (e.g., pool must exist, base sets must be fetched), and no per-action conditions. The reader must infer usage entirely from the verb list.

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 readOnlyHint=false, so the safety and re-invocation profile is covered structurally. The description adds nothing beyond them — no mention of what gets provisioned, whether creation partially fails and leaves artifacts, permission/auth requirements, or how long it takes. With annotations carrying the basics, this is a thin but not contradictory addition.

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

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

One short, front-loaded sentence with no filler, which is structurally clean. However the brevity here is under-specification rather than economy — the size is far too small for a 19-parameter destructive creation tool.

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

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

For a destructive, non-idempotent creation tool with 19 parameters, no output schema, and low schema coverage, the description omits essentially everything an agent needs: required-field meaning, defaults, network configuration expectations, and what is returned (e.g. a jail identifier). It is only marginally 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 only 21% across 19 parameters, so the description must compensate and it does not. Fields like base, bootstrap_name, switch_name, dhcp, ipv4_raw, ipv4_gw_raw, start_order and start_at_boot are undocumented in both places, leaving the agent to guess at formats and cardinality for a high-stakes creation 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?

The description states a specific verb and resource ("Create a FreeBSD Jail") and adds the storage substrate ("on a ZFS pool"), which clearly separates it from sylve_jail_list, sylve_jail_show, sylve_jail_delete and sylve_jail_action. It does not distinguish it from the adjacent creation-adjacent siblings sylve_jail_template or sylve_jail_bootstrap, so it stops short of full disambiguation.

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 sylve_jail_bootstrap (which likely populates the jail) or sylve_jail_template (which likely creates from a template), nor on ordering or prerequisites. The agent is left to infer the full workflow from 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 destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is carried structurally. The description does add value by naming what gets destroyed (rootfs and MAC objects), but calling it "optionally" is misleading given both flags default to true — an agent reading only the prose would assume nothing is removed unless asked.

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 resource, no padding. 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?

For a destructive 5-parameter operation with no output schema and two undocumented boolean parameters, the description is too thin: no statement of irreversibility, no prerequisites (jail state, running containers), and no clarification of the destructive defaults that determine whether data is actually lost.

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 60%; jail, node, and context are documented in the schema itself, while delete_macs and delete_rootfs have no schema descriptions. The prose gestures at those two booleans ("rootfs and MAC objects") but omits the critical fact that both default to true, which is the single most decision-relevant parameter detail here.

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 ("Delete a Jail") plus the notable consequence (rootfs and MAC removal). The verb alone differentiates it from sylve_jail_show / sylve_jail_list / sylve_jail_action, though it never says anything about the VM counterpart or the jail lifecycle 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?

No statement of when to use this versus sylve_jail_action (which likely handles stop/restart) or sylve_jail_snapshot/backup before deleting. No prerequisites such as whether the jail must be stopped first, and no warning about irreversibility.

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=false, so the safety profile is fully covered. The description only adds the cluster-wide default scope, and says nothing about output shape or pagination for what could be a long 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 short, front-loaded sentence with no filler. It is efficient, though the brevity edges toward under-specification rather than maximal information density.

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-required-param, read-only list tool with rich annotations and a fully documented schema, the description is minimally sufficient. With no output schema, it could have said what each listed jail entry contains, and it never mentions the 'context' login selection at the tool 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 coverage is 100%: both 'node' (hostname or UUID, omit for cluster-wide) and 'context' are fully documented in the schema. The description adds no meaning beyond that, so the baseline 3 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?

States a specific verb ('List') and resource ('FreeBSD Jails') plus the default scope ('across the cluster'), so an agent can distinguish it from sylve_jail_show, which operates on a single jail. It does not explicitly name the sibling it is not, 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?

The description gives no when-to-use or when-not-to-use guidance and names no alternative. The only routing hint ('omit for cluster-wide') lives in the schema, not the description.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds nothing about log extent (full buffer vs. tail), whether output is live or point-in-time, or size limits — useful context that is absent.

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 short sentence with zero waste, front-loaded with the verb and resource. Nothing is padded or redundant.

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

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

For a simple read tool with three fully described parameters and a clear annotation profile, the essentials are present. However, with no output schema, the description could say what the returned log output looks like (format, truncation, ordering), which it omits.

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

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

Schema description coverage is 100%, so the jail, node, and context parameters are already fully documented in the schema. The description contributes no additional parameter meaning, which is the baseline-3 case when the schema does the heavy lifting.

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

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

States a specific verb (Retrieve) and resource (a Jail's console log output), making the intent unambiguous. It does not explicitly distinguish itself from near-siblings such as sylve_jail_show or sylve_vm_logs, 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 by the verb 'Retrieve' — an agent can infer this is for fetching console logs rather than metadata. There is no explicit when-to-use/when-not guidance or reference to the sibling tools that surface jail details or VM logs.

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 idempotentHint=false, so the safety profile is covered. The description adds only the word 'validate', leaving the important behaviors unstated: whether the CT is stopped/restarted, downtime, what happens if migration fails mid-transfer, and how wait/wait_timeout affect the call.

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 short sentence with no filler and the action front-loaded. It is terse rather than padded; the problem is under-specification, not 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?

For a destructive migration operation with 7 parameters, no output schema, and three undocumented parameters, the description is far too thin. An agent cannot tell how failures are reported or how wait/timeout semantics apply without reading the schema and guessing.

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

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

Schema coverage is only 57%, with wait, wait_timeout, and validate_only undocumented anywhere. The description does not explain these or resolve the confusing overlap between the required 'target' and the optional 'node' parameter (documented as 'omit for cluster-wide'), which looks like a genuine ambiguity an agent could get wrong.

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 pair (validate and migrate) and resource (Jail) plus the destination scope (another cluster node). It clearly differs from sylve_vm_migrate by naming Jail, though it never explicitly contrasts the two.

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, no prerequisites (e.g. is the target node required to be drained or in the cluster?), and no mention of when to prefer validate_only or a different sibling. The agent must infer all of this from the parameter names.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is fully covered. The description adds that output includes 'live guest info', telling the agent it returns runtime state in addition to static config, but says nothing about response size, node-scoped vs cluster-wide aggregation, or failure modes when a jail 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?

A single front-loaded sentence with zero filler that covers the verb, resource, and returned content. Nothing wasted and nothing 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?

With no output schema, the description does its job by naming what is returned (configuration plus live guest info), and params are fully covered by the schema and annotations. It could be slightly more complete by hinting at how the node/context scoping affects the result set.

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

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

Schema description coverage is 100%, so all three parameters (jail, node, context) are already documented in the schema. The description adds no further meaning about identifier formats or how node/context interact with the jail lookup, so baseline 3 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?

States a specific verb+resource (show a jail) plus exactly what comes back: full configuration and live guest info. It distinguishes itself from sylve_jail_list by implying detail rather than enumeration, though it never names the 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 phrase 'full configuration' implies this is the detail view to use after listing, but there is no explicit when-to-use statement or mention of sylve_jail_list / sylve_jail_logs as alternatives. Usage is only inferable from context.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is known. The description merely enumerates actions and adds no behavioral context such as irreversibility of rollback/delete, required permissions, or effects on the jail.

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. It is appropriately concise, though the terseness contributes to gaps in other dimensions rather than being a flaw of 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?

This is a destructive multi-action tool with seven parameters and no output schema. A one-sentence description leaves important context unexplained: action-specific behavior, return values, prerequisites, and the consequences of rollback/delete.

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 71%, so most parameters are documented in the schema. The description contributes no parameter meaning at all; its action list duplicates the action enum, and the undocumented 'description' parameter is not compensated for.

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 set of verbs (list, create, roll back, delete) and a precise resource (Jail ZFS snapshots). It distinguishes itself from sylve_vm_snapshot by scoping to jails, though it does not explicitly reference the sibling sylve_zfs_snapshot.

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 lists possible actions but gives no guidance on when to use this tool versus alternatives such as sylve_zfs_snapshot or sylve_vm_snapshot. It also does not explain when each action (list vs create vs rollback vs delete) is appropriate.

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

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

Annotations declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, but because five actions with very different risk profiles are bundled, the description should say that 'delete' is the destructive path and that 'list'/'show' are safe reads. It says none of that, nor does it note permissions or that delete removes the template from the cluster.

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 no filler, action verbs front-loaded and easy to scan. It is efficient, though its brevity comes at the cost of the conditional detail this five-action tool requires.

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 seven-parameter, five-action, destructive, non-idempotent tool with no output schema, the description leaves the entire action-parameter contract and the read/write risk split unstated. An agent could plausibly invoke 'delete' with only template_id or 'capture' without a source jail and have no warning.

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 57%, with count, template_id, and the action enum undocumented in both places. More critically, the description never maps parameters to actions (jail/name for capture, template_id/count for deploy, template_id for delete), which is the key semantic the agent needs and the schema does not provide.

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 specific verbs (list, show, capture, deploy, delete) against a specific resource (jail templates), so the agent knows the domain and the action surface. It does not differentiate this multi-action tool from siblings like sylve_jail_list, sylve_jail_show, or sylve_vm_template, leaving overlap to inference.

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 consolidated tool versus the per-action siblings (sylve_jail_list, sylve_jail_show, sylve_jail_delete, sylve_vm_template). The description merely enumerates actions already in the enum; there are no preconditions, no exclusions, and no routing logic.

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=false, so the safety profile is fully covered without prose. The description adds only the scoping notion of "one subsystem" and says nothing about result volume, cost of the broad `all` value, or failure modes when `node` 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?

A single front-loaded sentence with no filler; the scope word "one" appears early. Its brevity is a virtue, though the parenthetical enumeration could have been spent on the values it actually omits.

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 carries the burden of conveying what comes back, and it says nothing about return shape or granularity. The discrepancy between "one subsystem" and the available `all` value is left for the agent to discover from the 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?

Node and context are documented in the schema (67% coverage); `kind` is enum-only, so the description is the only prose source — but its list is both incomplete and imprecise, collapsing four distinct firewall values into "firewall" and omitting `global_config` and `all`. That leaves the most consequential enum values (`all`, `global_config`) 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?

Specific verb ("Query") plus resource class ("one network subsystem") and an illustrative enumeration of the subsystems, so an agent knows this is the network read tool. Sibling differentiation is implicit rather than stated — none of the listed siblings cover networking, so the gap is minor.

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?

Implies one call per subsystem, which hints at how to drive the `kind` parameter, but gives no explicit when/when-not, no mention that `kind` is optional, and no guidance on combining `node` with cluster-wide queries. Usage is inferable from the parenthetical list only.

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=false, so the safety profile is fully carried by structured fields. The description adds one genuine behavioral detail — records include 'parsed request paths' — which is not in any schema since no output schema exists. It says nothing about record volume, time window, or truncation behind the vague 'recent'.

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 the scope qualifier attached inline; nothing is wasted and nothing important is 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 2-parameter, read-only tool with no output schema, the description should at least convey what the returned records look like and how many/over what period. 'Recent' and 'parsed request paths' gesture at this but leave the return shape and time window undefined.

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

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

Schema description coverage is 100% and both parameters are documented there, including the 'omit for cluster-wide' behavior and the config file path for context. The description only restates the node/no-node distinction and adds nothing about the context parameter. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Show recent audit records') and adds the scope qualifier 'from a node (or all nodes)'. It is distinguishable from the sibling log tools (sylve_vm_logs, sylve_jail_logs) by resource, though it never explicitly names 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 parenthetical '(or all nodes)' implies the cluster-wide fallback, but that is already spelled out in the schema's node description. There is no explicit when-to-use vs. alternatives guidance or advice on which sibling log tool to pick.

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 readOnlyHint=false, so the safety profile is covered. The description adds the useful fact that execution is opt-in via a dry-run default, but says nothing about what happens to guests that fail mid-drain, partial-failure states, or what the built plan contains — significant for a 10-parameter destructive operation.

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

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

One compact sentence, front-loaded with the action and scope, then the strategy options, then the safety default. Nothing is redundant or 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?

For a destructive, 10-parameter node-wide operation with no output schema, the description is terse: it never says what the returned plan looks like, whether execution blocks or returns a task handle, or how wait/wait_timeout interact with the dry-run default. Adequate but leaves real gaps an agent would want filled.

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 80%, so most parameters (node, context, dry_run, stop_only, target_node, stop_only, fallback_stop, ignore_errors) are already documented in the schema. The description adds no syntax, defaults, or interaction rules beyond what the schema provides, so the baseline 3 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?

States a specific verb and resource ('Build and optionally execute a maintenance drain plan for a node') and enumerates the strategies (HA failover, migration, stop). This clearly separates it from single-guest siblings like sylve_vm_migrate, though it never names an alternative 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 'dry run by default for safety' clause implies the intended maintenance workflow and nudges toward previewing first, but there is no explicit when-to-use vs sylve_vm_migrate or sylve_node_show, and no stated prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the useful detail of which metrics are returned, but says nothing about pagination, output format, or auth/context requirements beyond what the schema implies.

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 efficient sentence with the resource and returned fields front-loaded. Every clause earns its place by telling the agent what it gets back.

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 listing tool with no output schema, naming the returned metrics is the right compensating detail. An agent can call it correctly; only explicit sibling differentiation and pagination behavior are missing.

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

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

Schema description coverage is 100%, and both parameters (node, context) are fully documented in the schema. The description adds no parameter-level guidance, so baseline 3 is appropriate when the schema carries this burden.

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 ('cluster nodes') and enumerates the metrics returned (CPU%, RAM%, disk, guest counts, version). This clearly separates it from mutation siblings like sylve_node_drain, though it doesn't explicitly contrast with sylve_node_show for single-node detail.

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 'List all cluster nodes' as a read/overview operation, but there is no explicit when-to-use guidance and no mention of alternatives such as sylve_node_show for per-node detail or sylve_cluster_status. The agent must infer the distinction.

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=false, so the safety profile is fully covered by structured data. The description adds only the default-target behavior, saying nothing about permissions on remote nodes, output volume, or whether telemetry is sampled/live — modest added value given the low bar set by annotations.

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

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

One sentence, front-loaded with the action and resource, no boilerplate or redundancy. Every clause (metric list, default target) 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?

With no output schema, the description carries the burden of describing returns and does so at the level of metric families (CPU/RAM/swap/disk). For a two-optional-parameter read-only tool that is close to sufficient, though it omits whether the response is a snapshot vs. time series and how the `context` param interacts with discovery.

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

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

Schema description coverage is 100%, so both `node` and `context` are already documented, and the description's "defaults to the connected node" restates the schema's own default note. Baseline 3 applies; no new semantics such as accepted hostname format or context precedence are introduced.

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 ("Show detailed CPU/RAM/swap/disk telemetry for a node") and names the exact metric families returned, so an agent knows this is a single-node telemetry read rather than a listing. It does not explicitly differentiate itself from close siblings like sylve_node_list or sylve_cluster_resources, which keeps it from 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 parenthetical "defaults to the connected node" implies the common no-arg usage, but there is no explicit statement of when to pick this over sylve_node_list or sylve_cluster_resources, nor any exclusions. Usage is inferable rather than guided.

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 tool as non-read-only, non-idempotent, and destructive, so the critical safety profile is covered. The description adds little beyond the vague 'Manage' framing and does not explain failover risks, data-loss confirmation, wait behavior, or policy/event handling.

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

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

It is a single, front-loaded sentence with no filler. However, for a 12-parameter multi-action tool, the structure is too terse to be genuinely appropriate, even if it avoids 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?

Given the tool's complexity, destructive annotation, and lack of an output schema, the single-sentence description leaves major gaps. It does not explain the five action types, failover implications, safety-related parameters, or operational prerequisites.

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

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

Schema description coverage is only 25% across 12 parameters, and the description does not compensate. It vaguely maps to the action groups 'policies', 'events', and 'failovers' but never clarifies action values, mode, wait, limit, target_node, confirm_data_loss, move_pinned_source, or the other parameters.

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

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

The description names the resource domain precisely: HA replication policies, events, and failovers. It clearly distinguishes this tool from VM, jail, and storage siblings, though the generic verb 'Manage' and lack of action-level distinctions keep it from being fully specific.

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 guidance on when to use this tool versus alternatives, when to choose each action, or when not to use it. The sentence only broadly implies that it is for replication management, without operational context.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false; the description's 'cancel migrations' is consistent with that (no contradiction). However, it omits key behavior an agent needs: that 'wait' presumably blocks up to the timeout, and that cancelling a migration is irreversible. Those gaps keep it at a mid score rather than higher.

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, and the primary capability is stated first. It is terse but not padded; the brevity is more under-specification (scored elsewhere) than waste.

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?

Five distinct actions, six parameters, a destructive cancel path, and no output schema — the definition gives one line for all of that. An agent cannot determine which parameters apply to which action or what wait/cancel actually return or do from this description.

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

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

Schema coverage is only 33% — limit, action, task_id and timeout have no schema descriptions. The description loosely maps to action values ('list, show, wait, cancel migrations') but never explains which actions require task_id, what limit does, or how timeout interacts with 'wait', 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?

Specific verbs (list, show, wait, cancel) tied to a clearly named resource (guest lifecycle tasks), which is distinct from the VM/jail CRUD siblings. It does not name a sibling or clarify overlap with tools like sylve_vm_migrate, but the resource boundary is clear enough to select it.

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

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

It lists the action modes in prose but never says when to pick 'recent' vs 'active' vs 'show', nor when to prefer this over sylve_vm_logs or sylve_vm_migrate. No prerequisites or exclusions are stated, leaving the agent to infer selection from the enum 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 destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered structurally. The description adds the useful behavioral fact that this is a batch operation over multiple VMs, but says nothing about whether 'stop' is a hard kill, whether waiting is blocking, or whether partial failures roll back.

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 with zero waste, front-loading the action set ahead of the resource and identifier forms. Nothing is padded or redundant.

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 batch mutation with no output schema and two-thirds of parameters undocumented, the description is far too thin. An agent cannot tell whether the call blocks for wait_timeout seconds, whether it targets cluster-wide by default when node is omitted, or what a partial failure looks like.

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

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

At 33% schema coverage, the description must compensate and does not. It only reinforces the vms identifier format; node, wait, wait_timeout and context are given no meaning at all, and even the schema leaves 'wait' and 'wait_timeout' completely undocumented despite wait defaulting to true and wait_timeout defaulting to 60.

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 (start, stop, shutdown, reboot, restart) and resource (VMs), plus the batch scope 'one or more' and the identifier forms 'by name or RID'. This clearly separates it from sylve_vm_create, sylve_vm_delete, sylve_vm_migrate and from the parallel sylve_jail_action, 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?

No when-to-use or when-not-to-use guidance. Critically, the five actions are listed but not differentiated: stop vs shutdown vs restart vs reboot have materially different semantics (force vs graceful) and an agent must guess which to pick, as well as what happens when 'one or more' VMs partially fail.

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 destructive, non-idempotent, non-read-only profile, and the description adds genuine value beyond that: it discloses auto-allocation of RID and VNC port (side effects the agent cannot see in the schema) and cloud-init YAML validation. It does not cover failure behavior, what a partial creation leaves behind, or whether dry_run still validates, which keeps it below 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 short sentences, front-loaded with purpose and with zero filler; the auto-allocation and validation details earn their space. It is arguably too terse for a 45-parameter mutation tool, which is the only real structural weakness.

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 45-param, nested-object, destructive, non-idempotent creation tool with no output schema and no required fields, yet the description never says which parameter combinations produce a valid request, what is returned (e.g., an RID), or what happens on partial failure. The complexity-to-description ratio is badly unbalanced; three sentences cannot cover it.

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

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

With 45 parameters and only ~51% schema description coverage, the schema does roughly half the work and many fields (tpm, serial, cloud_init, qemu_guest_agent, pci_devices, rewrite_cloud_init_identity, wait_timeout) have no description at all. The description explains only a tiny slice — size-string parsing for memory/disk_size, automatic RID/VNC port allocation, and dry_run — leaving template-mode params and mode-exclusivity 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+resource ("Provision a Bhyve VM") and names the two creation modes (from scratch or from a template), which separates it from the read/action siblings. It stops short of explicitly distinguishing itself from sylve_vm_template or sylve_vm_action, so the agent must infer that boundary from the 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?

There is no when-to-use / when-not-to-use guidance and no prerequisites (which params are needed for scratch vs template mode, which are mutually exclusive). The only usage signal is "Supports dry_run", which hints at a safe preview path but is not framed as guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered structurally. The description adds genuine blast-radius context (associated volumes, raw disks and MAC objects are also removed), but says nothing about irreversibility, prerequisites (VM powered off?), or what force changes.

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 comes first and the cascade clause follows. It is efficient, though the wording choice 'optionally' costs precision rather than words.

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

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

For a destructive 7-parameter tool with 43% schema coverage and no output schema, the description is too thin: it omits default cascade behavior, the force flag's effect, and any precondition such as stopping the VM. An agent could call this and unintentionally destroy volumes because the defaults are not surfaced anywhere.

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

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

Schema coverage is only 43%: vm, node and context are documented in the schema, while force and the three delete_* flags are not. The description names the three cascade targets but omits their default-true behavior and never mentions force, and 'optionally' implies the opposite of the actual defaults, so it 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 and resource (delete a VM) and adds the scope of cascading deletion (volumes, raw disks, MAC objects). It does not name any sibling (e.g. sylve_vm_action for lifecycle, sylve_jail_delete for jails) to differentiate, so it stops short of a 5.

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

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

No when-to-use or when-not-to-use guidance: nothing says whether the VM must be stopped first, when to prefer sylve_vm_action, or when to pass force. The word 'optionally' actively obscures usage, since the schema defaults for delete_volumes/delete_macs/delete_raw_disks are all true, meaning the cascade is opt-out, not opt-in.

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 non-destructive, so the safety profile is covered. The description adds the cluster-wide scope, but says nothing about result shape, pagination, or whether omitting 'node' changes cost — modest added value beyond structured 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?

A single front-loaded sentence with no filler. It is efficient, though it borders on under-specification given the tool's alternatives.

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 three fully documented optional parameters and no output schema, the definition is minimally sufficient to invoke the tool. It lacks any hint of return content (what fields a listed VM carries) or how 'detailed' alters the payload's size, which an agent planning a workflow 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 description coverage is 100%, and each parameter (node, context, detailed) is already documented, including the 'omit for cluster-wide' behavior. The description adds no parameter detail, so baseline 3 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 specific resource ('Bhyve VMs') and scope ('across the cluster'), so an agent knows exactly what it returns. It does not, however, distinguish itself from siblings like sylve_vm_show or sylve_jail_list, leaving the list-vs-detail decision to the agent.

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-use guidance, and no mention of the obvious alternative sylve_vm_show for per-VM detail. The only usage signal is implied by the verb 'List'.

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=false, so the safety profile is covered. The description adds that the output is a serial console log, but it does not explain whether logs are live or historical, how large they may be, or whether the VM must be running.

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

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

The description is a single front-loaded sentence with no wasted words. It efficiently communicates the core operation without unnecessary preamble.

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

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

For a low-complexity log retrieval tool with full parameter documentation and clear safety annotations, the description is nearly sufficient. It could be improved by noting log recency or runtime requirements, but nothing critical is missing for basic invocation.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema. The description adds no parameter-specific syntax, defaults, or constraints beyond what the schema provides, making the baseline score 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 states a specific verb and resource: retrieving a VM's serial console log output. It clearly identifies the operation and data type, but it does not explicitly distinguish this tool from related siblings such as sylve_jail_logs or sylve_node_audit_logs.

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, nor any exclusions or preconditions. The purpose implies log retrieval, but the description leaves the agent to infer the appropriate context 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 destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the agent knows this is a non-reversible mutation. The description adds that the migration is 'live' (no downtime) and that validation is part of the flow, which is real context beyond the annotations, but it says nothing about what happens on failure, downtime windows, or whether the VM is left running on the source.

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 zero filler; the verb and destination come first. It is arguably too terse for a destructive cluster operation, but nothing in it 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?

This is a destructive, non-idempotent cluster migration with seven parameters and no output schema, and the one-line description leaves out error behavior, the meaning of validate_only, wait/timeout semantics, and what state the VM ends up in. An agent would need to open the schema and guess at the failure semantics.

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

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

Schema description coverage is 71%, so the key parameters (vm, target, node, context, validate_only) are already documented in the schema. The description adds no syntax, format, or interaction guidance for those, and 'wait'/'wait_timeout' are undocumented in both places – a 3 is the correct baseline.

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 (live-migrate) and resource (VM) plus destination (another cluster node), which an agent can distinguish from sylve_jail_migrate and sylve_vm_show without opening the schema. It stops short of naming the sibling or the scope conditions that select it.

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

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

The description gives no when-to-use guidance, no prerequisites (e.g. node must be in the cluster, VM must be running), and no steer toward validate_only versus a full migration. 'Validate and live-migrate' implies a preflight exists but never says when to prefer it.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine value beyond that by disclosing what the response contains — configuration, live runtime state, and guest-agent-derived IPs — 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?

A single front-loaded sentence that enumerates the payload contents and contains no filler. Nothing could be cut without losing 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 simple three-parameter read tool with rich annotations and fully described schema, one sentence plus the return-content hint is nearly sufficient. It stops short of explaining node omission semantics or guest-agent dependency, but no critical gap blocks 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 100%, so vm, node, and context are already documented in the schema. The description adds no additional meaning such as what happens when node is omitted or how RID vs name resolution behaves; baseline 3 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?

States a specific verb (Show) and resource (VM) plus the exact payload scope: full configuration, live state, and guest-agent IPs. That distinguishes it implicitly from sylve_vm_list, though no sibling is named 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?

Usage is only implied by the phrasing 'a VM's' (fetch details for one VM). It gives no explicit when-to-use vs when-not, no pointer to sylve_vm_list for enumeration, and no prerequisites for the guest-agent IP behavior.

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 agent knows the tool is unsafe to fire blindly. The description adds no per-action nuance: it never says that 'list' is a harmless read while 'rollback' and 'delete' are irreversible, nor that rollback overwrites current VM disk state. That mixed-safety profile is the single most valuable thing a multi-action description could disclose, and it is absent.

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 every word earning its place. No filler, no restatement of the title, and the action set leads.

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, four-action, seven-parameter tool with no output schema, one sentence is thin. Nothing tells the agent what a successful rollback returns, whether snapshots are per-node (the node parameter's cluster-wide semantics), or what the failure modes are, leaving the schema and annotations to carry nearly all the weight.

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 86%, so the schema already documents vm, node, name, snapshot_id, context and description, and the action enum is self-explanatory. The description contributes nothing beyond restating those actions in prose — no mapping such as 'rollback/delete require snapshot_id' or 'create requires name' to help the agent assemble a valid 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?

States specific verbs (list, create, roll back, delete) against a specific resource (VM ZFS snapshots), which separates it from sylve_zfs_snapshot and sylve_jail_snapshot by target type. It stops short of explicitly naming those siblings as out of scope, so the differentiation is implied rather than stated.

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 four action verbs imply the situations the tool covers, but there is no explicit when-to-use guidance and no mention of the sibling snapshot tools the agent must choose between. The agent must infer from the action enum that this is a single multi-purpose entry point rather than four separate tools.

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

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

Annotations declare destructiveHint=true and idempotentHint=false, and the description adds nothing to refine that: it does not say that only 'delete' is destructive, that 'capture' creates a new artifact from a live VM, or that 'deploy' clones N VMs and is therefore the most consequential action. For a multi-action tool where the safety profile varies per action, this is a meaningful gap.

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

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

A single front-loaded sentence with zero filler. It is efficient, though the terseness leaves no room for the per-action detail the tool actually 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?

This is a seven-parameter, five-action, destructive, non-idempotent tool with no output schema, and the description never explains what each action requires or returns (e.g., capture needs vm+name, deploy needs template_id+count). The per-action parameter mapping exists only as parentheticals in the schema, leaving the agent to infer the lifecycle semantics.

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

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

Schema description coverage is 86%, so the schema already documents parameters well, including per-action applicability like 'Source VM (capture)' and 'Template ID (show/deploy/delete)'. The description adds no parameter meaning beyond that, which is the baseline 3 case.

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 (VM templates) and enumerates the five supported operations, so an agent immediately knows the domain. It does not distinguish itself from the parallel sibling sylve_jail_template, which manages the same lifecycle for jails.

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 choose this tool over sylve_jail_template or when to fall back to sylve_vm_* tools, and no prerequisites or exclusions. The only implicit routing signal is the action enum, which the schema already provides.

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=false, so the safety profile is fully covered structurally. The description adds genuine value by disclosing that JWT expiry status is surfaced — a useful behavioral fact — but says nothing about what happens when the token is expired or how auth failures manifest.

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 waste, leading with the verb and listing exactly the four data points returned. Nothing could be trimmed without losing 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 no output schema present, the description usefully enumerates what comes back (context, user, node, JWT expiry status), which covers most of the return-value burden. What is missing is the failure/empty-state behavior when no valid login exists, a real gap for an auth-introspection 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 100%, so both `node` and `context` are documented, giving a baseline of 3. The description adds no parameter meaning beyond that, and there is mild tension: it advertises the "active" context while `context` is a required input, leaving the agent to reconcile that from the schema alone.

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

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

Names a specific verb ("Show") and a concrete resource set: active login context, user, node, and JWT expiry status. This is clearly distinguishable from write-oriented siblings like sylve_node_drain or sylve_vm_create, though it never names sylve_context_list, the closest read-side alternative, so the boundary there is left 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?

Usage is implied rather than stated — an agent can infer this is the "check I'm authenticated and whose credentials I'm using" tool. There is no explicit when-to-use, no exclusion, and no pointer to sylve_context_list for the case where the caller wants all configured contexts rather than the active one.

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, so the safety profile is known; the description adds nothing on top — no statement that `delete` is irreversible, whether snapshots/children are affected, or that creation requires a node or context. For a tool spanning read and destructive write paths, the description contributes no behavioral context beyond the annotation.

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

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

A single front-loaded sentence with no wasted words, which is good structurally. However the brevity is under-specification rather than economy, given nine parameters and five actions.

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 nine-parameter, five-action tool with a nested `properties` object and no output schema, one sentence is inadequate. An agent cannot tell from the description what `properties` accepts on edit, what delete removes, or how node vs cluster-wide scope interacts with each action.

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 78%, so the schema carries most parameter meaning and the baseline applies. The description adds zero parameter detail — notably nothing about `properties`, the nested object that is entirely undocumented, and nothing clarifying `edit` semantics.

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 (list/create/edit/delete) against a specific resource (ZFS filesystems and volumes), which cleanly separates it from siblings sylve_zfs_pool and sylve_zfs_snapshot. What it omits is that all five operations are multiplexed through a single `action` parameter rather than being distinct calls.

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 choose this tool over sylve_zfs_pool or sylve_zfs_snapshot, no prerequisite or permission notes, and no hint about which action value suits which situation. The five enum values are listed only in the schema, with no routing advice.

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 declare destructiveHint=true and readOnlyHint=false, but the description lumps safe reads (list/status) together with scrub without saying which action is destructive or what scrub does to a live pool. It also omits whether scrub is synchronous, long-running, or permission-gated — context the annotations alone cannot supply for a mixed-mode 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 compact sentence with no filler, which is good, but its brevity comes at the cost of omitting an entire action rather than trimming redundancy. Efficient shape, insufficient content.

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

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

No output schema and a destructive, multi-action tool with a required enum and cluster/node scoping: the description should explain action behavior and return expectations. It leaves the agent unable to predict what a scrub returns or how node omission affects results.

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 75%, but the single uncovered element is the required `action` discriminator, whose four enum values carry no descriptions anywhere. The description's parenthetical '(resolves pool names to GUIDs)' only partially clarifies the `pool` parameter, so the most important parameter semantics 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 specific verbs (list, inspect, scrub) against a specific resource (ZFS storage pools) and distinguishes itself from the sibling dataset/snapshot tools by resource. However, the fourth supported action, disks_usage, is never mentioned, so the stated purpose under-describes the 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?

No indication of when to choose list vs status vs scrub vs disks_usage, and no mention of prerequisites, node scoping, or that scrub is a mutating/long-running operation while the others are reads. An agent must open the enum and guess the intended workflow.

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 known. The description adds nothing beyond that: it does not say which of the five actions are destructive (rollback/delete vs list), what rollback discards, or whether delete needs confirmation, despite being a single tool with mixed read and destructive actions.

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 zero padding. There is no bloat, but the terseness leaves content gaps rather than earning full marks for 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?

For an 8-parameter, five-action tool that mixes read and destructive operations, with no output schema and only hint-level annotations, the description is too thin. An agent cannot tell from the description which parameters each action requires or what a list/periodic_list returns.

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

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

Schema description coverage is 75% (below the 80% threshold) with 8 parameters, and the description contributes nothing about any of them. It only echoes the action vocabulary; the action-to-parameter mapping (dataset+name for create, snapshot for delete, recursive and destroy_more_recent only for rollback) is left entirely 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 specific verbs (list, create, roll back, delete) against a specific resource (ZFS snapshots, plus periodic snapshot jobs). An agent can distinguish it from sylve_zfs_pool / sylve_zfs_dataset, though the description does not explicitly rule out sylve_vm_snapshot or sylve_jail_snapshot.

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 verb list roughly maps onto the action enum, but the description gives no when-to-use guidance, no prerequisites (permissions, context, node scoping), and never names the sibling snapshot tools it should be preferred over or deferred to.

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