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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so 'no state is modified' largely restates structured data. The description adds useful pagination framing via page/per_page, but says nothing about ordering (newest-first?), retention, or whether an empty page signals the end, which are the behaviors an agent actually needs for a read tool.

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

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

Two tight sentences with the resource and pagination scope front-loaded and the usage hint immediately after. No filler or redundant phrasing.

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

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

For a simple read-only, three-parameter listing tool with no output schema, the definition covers purpose, usage, and safety adequately. The main residual gap is return-shape and ordering guidance (what an audit event contains, newest or oldest first), which would help an agent interpret 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 100%, with page, per_page, and server_id all documented including defaults and the 1-25 cap. The description only echoes that page and per_page control pagination without adding ordering, boundary behavior, or server_id fallback semantics beyond the schema, 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 and resource: 'Read one page of Wisp audit events for a server.' The resource ('audit events' vs. the sibling 'read_log_tail' which implies console/log tailing) is distinct enough that an agent can tell them apart, and the pagination scope is stated up front.

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

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

Gives explicit when-to-use guidance: 'Use to investigate recent panel actions or changes.' It does not name a when-not condition or point to the alternative sibling (e.g., read_log_tail for console output), which keeps it from a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The phrase 'without changing it' largely restates readOnlyHint rather than adding new information. It does not disclose whether the response contains a signed URL, how long such a link lives, or what permissions are needed.

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

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

Two short sentences with the core purpose front-loaded and no filler. The wording is efficient, though 'download metadata' could be sharpened to remove the ambiguity noted above.

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

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

There is no output schema and no annotation about the return payload, yet the description never says what 'download response' actually contains (URL, token, expiry). For a read tool whose only real product is that response, this leaves a meaningful gap, though the input side is fully covered.

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

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

Schema description coverage is 100%, so both parameters, including the server_id default fallback to WISP_SERVER_ID, are already documented in the schema. The description only echoes the backup ID requirement and adds no format or constraint detail beyond the schema, which makes 3 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?

The description gives a specific verb+resource: request Wisp download metadata for a backup. It is clearly distinct from siblings such as create_backup, deploy_backup, and delete_backup. Slight ambiguity remains between whether it returns metadata or performs an actual download, 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?

It provides a when-to-use condition: when a client needs the panel-provided backup download response for an existing backup ID. It does not name alternatives (deploy_backup, list_backups) or state when not to use it, so routing guidance is implied rather than explicit.

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

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

Annotations already declare read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful context that it returns configuration flags and the default server ID, and explicitly excludes API tokens or other secrets, which is behavior beyond the annotations.

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

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

Two sentences with no waste: the first states the action and timing, the second states key return scope and the security boundary. It is front-loaded and appropriately sized for a no-argument discovery 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?

With an output schema present, the description need not enumerate return fields. It gives enough context to use the tool correctly as a preflight check, though 'Wisp operation classes' could be clearer for an agent unfamiliar with that term.

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

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

The tool has zero parameters, so there are no parameter semantics to explain. The baseline for no parameters is 4, and the description appropriately does not invent parameter details.

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

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

The description states a specific verb and resource: inspect which Wisp operation classes are enabled. It also frames the tool as a preflight discovery step before choosing a management tool, though it does not name specific siblings to differentiate from.

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

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

The phrase 'before choosing a management tool' gives clear timing and context for when to call this tool. It does not explicitly list when-not conditions or named alternatives, but the preflight role is plain.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the write-safety profile is covered. The description adds real value beyond that: the WISP_ALLOW_FILE_WRITES prerequisite is a hard environmental gate an agent must know about, and 'creates a new filesystem object' clarifies it is additive rather than modifying existing files. It does not disclose the generated archive's name or format, which is the main remaining 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?

Two sentences, both earning their place, with the core action and the path limit front-loaded before the usage hint and the write-permission requirement. No filler or redundancy.

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

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

There is no output schema, so the description should say what an agent gets back — the archive's filename, location, or format — especially since 'to' defaults to '/' and the generated name is unpredictable. It adequately covers the input side and the permission gate but leaves the return contract opaque for a tool that produces a new artifact.

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

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

Schema description coverage is 100%, so paths, to and server_id are all documented in the schema itself. The description only restates the 100-item maximum already enforced by maxItems and adds no semantics about the 'to' destination or server_id default behavior. Baseline 3 applies since the schema does the heavy lifting.

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

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

The description states a specific verb and resource ('Create an archive from up to 100 server paths') and includes the cardinality bound. It is clearly distinct from the inverse sibling decompress_archive, but it never explicitly differentiates itself from backup tools like create_backup, which is the most likely confusion.

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 for packaging or pre-change snapshots' gives clear positive usage context, and the 100-path cap signals when the tool is not appropriate. It stops short of naming an alternative (e.g. create_backup for managed backups) or stating any exclusion, so it sits at a solid 4 rather than a 5.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, and the description adds two facts beyond them: it mutates filesystem state, and it requires the WISP_ALLOW_FILE_WRITES permission — an auth prerequisite not visible in annotations. It stops short of noting the non-idempotent behavior (repeated calls leave multiple copies) or whether an existing copy would be overwritten.

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

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

Two tight sentences with the action front-loaded and the permission requirement carried in the same breath. The only soft spot is the qualifying hedge 'when supported by the panel', which adds a condition without specifying how the agent checks it.

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

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

There is no output schema, so the description should say what the call returns, yet it never states the resulting copy's name or path — a real gap for a copy tool with no destination parameter. Combined with the silent non-idempotency, an agent knows the prerequisites but not the outcome, which is only minimally viable for a write operation.

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

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

Schema description coverage is 100%, so both path and server_id are already documented, and the description adds no extra parameter meaning. Baseline 3 applies; the only notable omission is that nothing explains how the missing destination relates to the single path argument.

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

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

States a specific verb and resource: copy a file via Wisp. The phrase 'in place' signals that no destination is supplied, which is consistent with the schema having only a source path, but it leaves unclear where the copy lands and what it is named — the one thing an agent most needs to know. It is still clearly distinguishable from write_file, rename_file, and create_backup by intent.

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

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

Gives an explicit use case ('create a safety copy before risky edits') plus a precondition ('when supported by the panel'). It does not name alternatives such as safe_write_file or create_backup, so an agent has to infer that this is the pre-edit snapshot option rather than the general write path.

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

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

Beyond the annotations, the description discloses that this creates panel state and requires WISP_ALLOW_BACKUPS. That permission and side-effect detail is useful for an agent, though it does not explain what the backup contains or whether creation is synchronous.

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

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

The description is two sentences, front-loaded with the core action and followed by when-to-use guidance. Every phrase contributes useful information without repetition.

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

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

For a creation tool with full schema coverage and annotations covering safety hints, the description supplies the key missing context: purpose, timing, and the WISP_ALLOW_BACKUPS prerequisite. It does not cover return behavior, backup scope, or expected duration, which keeps it from being fully complete.

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

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

Schema description coverage is 100%, and both parameters are already documented in the schema. The description adds no extra semantics about the name format, server_id fallback behavior, or parameter interactions 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?

The description states a specific verb and resource: 'Create a named server backup.' It also clarifies the effect as creating a 'new recovery point,' which distinguishes it from siblings such as list_backups, deploy_backup, delete_backup, and lock_backup.

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

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

It gives clear usage context: use before risky changes or when a new recovery point is required. It does not state when not to use it or explicitly compare it to deploy_backup or other backup-related siblings, so it falls short of a 5.

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

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

Annotations already declare the write, non-idempotent, non-destructive profile, so the description's added value is the mutation warning ('this changes panel state') and the required WISP_ALLOW_DATABASES configuration. Useful context beyond the structured fields, though it says nothing about behavior when the name already exists.

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

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

Two short sentences with the action first and the constraint second; there is no redundant or filler wording.

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

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

With no output schema, the description leaves open what a successful call returns — notably whether credentials or a password are surfaced — which matters for a database provisioning tool. The inputs, prerequisite flag, and state-change warning are covered, so it is adequate but incomplete on the result side.

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%, with host, name, server_id default, and the connections_from wildcard all documented in the schema itself. The description adds no syntax, naming rules, or format detail beyond that, so the baseline of 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?

The description states a specific verb and resource — 'Create a database allocation for a server' — which clearly separates it from list_databases, delete_database, and rotate_database_password among the siblings. It does not explicitly name a contrasting sibling, but the creation scope is unambiguous.

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

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

It gives a clear usage gate: 'Use only when a new database is requested,' which implicitly excludes re-use on existing databases. It also names the enabling configuration flag WISP_ALLOW_DATABASES. No alternative tool is named for checking whether a database already exists, which keeps it just short of a 5.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is partly known. The description adds meaningful context beyond them: this mutates filesystem state and requires the WISP_ALLOW_FILE_WRITES environment flag enabled. It does not say what happens on an existing path (relevant given idempotentHint=false) or whether parent directories are created, which is the main remaining 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?

Two short sentences, front-loaded with the action and immediately followed by the usage constraint and prerequisite. No filler or redundancy.

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

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

For a simple two-parameter, single-purpose mutation with full schema coverage and annotations, the description covers purpose, gating condition, and the write-permission prerequisite. Only the edge-case behavior (existing directory, implicit parent creation) is left unexplained, which is a minor gap at this complexity 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%, so both 'path' and 'server_id' are already documented with their semantics and default behavior. The description adds no path format, nesting, or server-selection guidance beyond the schema, so the baseline of 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: 'Create a directory in the server filesystem.' An agent can distinguish it from list_directory, delete_file, and write_file by name and description. No explicit sibling routing, but the operation is unambiguous.

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

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

'Use only when a new directory is required' gives a clear negative-leaning condition, and the WISP_ALLOW_FILE_WRITES prerequisite is a real gating rule. It stops short of naming an alternative for directory creation (there is none among siblings) or saying what to do if the path already exists.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new context: existing paths may be overwritten and the WISP_ALLOW_FILE_WRITES environment prerequisite must be set — a real gating condition an agent cannot learn from annotations.

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

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

Two tight sentences with zero filler; the primary action is front-loaded and the destructive gating information follows immediately.

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

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

For a two-parameter tool with full schema coverage, no output schema, and annotations covering safety, the description supplies the remaining essentials: the write precondition and the overwrite risk. Format support and destination semantics are the only minor omissions.

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 parameters are already documented, and the baseline is 3. The description adds only marginal meaning ("existing paths may be affected") and notably does not clarify whether `path` is the archive itself and where the extracted contents land, nor which formats are supported.

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 ("Extract an archive in the server filesystem"), which is unambiguous and implicitly contrasts with the sibling compress_files. It does not name that sibling or any alternative explicitly, so it stops short of full differentiation.

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

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

"Use only when archive contents should be written to disk" gives a clear positive condition and implies the negative case (inspect or read without writing). However, it never names which sibling to use instead when disk writes are not wanted, leaving the agent to infer the alternative.

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

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

Annotations already flag destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds real value beyond that by stating permanence and the two required environment gates (WISP_ALLOW_BACKUPS, WISP_ALLOW_DESTRUCTIVE), which pre-empt predictable auth failures. It does not say whether dependent artifacts or backups are affected.

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

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

Two short sentences with the action and its irrevocability front-loaded, followed by the usage restriction and prerequisites. Nothing is redundant 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 two-parameter destructive mutation with full annotation coverage, full schema coverage, and no output schema, the definition supplies action, restriction, and prerequisites. The remaining gap is downstream effect - whether deleting a backup removes associated download artifacts or leaves the server in a locked state - which is not addressed.

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%, with backup_id documented as coming from list_backups and server_id documented as defaulting to WISP_SERVER_ID. The description adds only 'by ID', so the schema is doing all the parameter work and the baseline of 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 ('Permanently delete a backup') plus the selector ('by ID'), which clearly separates it from list_backups, create_backup, and deploy_backup. It stops short of explicitly naming sibling tools, so an agent must infer the distinction, keeping it at 4 rather than 5.

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

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

'Use only for an explicit backup deletion request' is a genuine when-to-use restriction that discourages speculative or bulk cleanup calls. It gives no named alternative for the adjacent cases (locking, archiving, redeploying), so the guidance is clear but not exhaustive.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds genuinely new behavioral facts: permanence and the required environment gates (WISP_ALLOW_DATABASES and WISP_ALLOW_DESTRUCTIVE). It does not say whether the deletion is immediate or what happens to related backups/data, which is the remaining 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?

Two short sentences with the destructive permanence and the usage restriction front-loaded, followed by the permission prerequisites. Nothing is wasted.

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

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

For a two-parameter destructive mutation with no output schema, the description covers permanence, the usage trigger, and the required permission flags, which is enough for correct invocation. Only the downstream consequences (backups, dependent services) are left unstated.

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

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

Schema description coverage is 100%, including the note that database_id comes from list_databases and that server_id falls back to WISP_SERVER_ID. The description's 'by ID' adds nothing beyond that, so the baseline of 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?

The description states a specific verb and resource ('Permanently delete a database allocation by ID'), which is far more precise than the bare name. It does not explicitly distinguish itself from sibling tools like delete_file or delete_backup, but the resource noun makes misselection unlikely.

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 only for an explicit deletion request' gives a clear, actionable when-to-use constraint with an implicit exclusion for speculative or bulk cleanup. It stops short of naming any alternative tool or escalation path, so it is clear context without exclusions.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description earns credit for adding beyond them: it discloses permanence/irreversibility and names the two required capability flags (WISP_ALLOW_FILE_WRITES, WISP_ALLOW_DESTRUCTIVE) that gate execution. It does not say how a missing path is handled, which matters given idempotentHint=false.

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

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

Two sentences with zero filler, front-loading the action and then the usage constraint and prerequisites. Every clause carries decision-relevant 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 two-parameter, single-resource deletion tool with full schema coverage and no output schema, the description covers purpose, caution, and prerequisites adequately. Minor gap: no mention of success/failure behavior or whether deletion of a nonexistent file errors.

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 path and server_id are already fully documented in the schema. The description adds no syntax, path-resolution, or defaulting detail beyond what the structured fields provide, 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 and resource: 'Permanently delete a server file,' with 'permanently' scoping the operation. It is clearly distinguishable from siblings like delete_backup or delete_database by the 'server file' resource, though it never names 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?

'Use only for an explicit deletion request' gives a genuine gating condition and implicitly warns against speculative or bulk cleanup use. However, it does not point to an alternative for non-destructive cleanup or state what to do if the intent is ambiguous.

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 non-idempotent, so the safety profile is covered structurally. The description still adds real value beyond that: it spells out the concrete consequence ('current server data can be replaced') and the required environment gates (WISP_ALLOW_BACKUPS, WISP_ALLOW_DESTRUCTIVE), which no annotation conveys. It omits behavior on an invalid/expired backup ID or whether the server is verified after restore, so not a 5.

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

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

Two sentences, zero filler. The destructive consequence is front-loaded right after the trigger condition, which is exactly the ordering an agent needs before acting.

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 restore with only two params and no output schema, the definition covers action, precondition, consequence, and env prerequisites. The remaining gap is post-call expectation (does a restore return a task/status, and how should the agent confirm success), which is minor given there is no output schema.

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

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

Schema description coverage is 100%: backup_id already documents 'Backup object ID returned by list_backups' and server_id documents the WISP_SERVER_ID default. The description adds no syntax, format, or constraint details beyond the schema, so the baseline of 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?

The description opens with a specific verb and resource: 'Restore a server from an existing backup ID.' That verb set is distinct from every backup sibling (list_backups, create_backup, delete_backup, lock_backup, backup_download), so an agent can route correctly without opening any schema.

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

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

'Use only for an explicit restore request because current server data can be replaced' gives a clear trigger condition plus an explicit when-not rationale. It doesn't name an alternative tool (e.g. that the ID must come from list_backups, or create_backup for the inverse flow), which keeps it short of a full 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered; the description adds value by disclosing that content is deliberately not returned and that the output is a hash plus size used for concurrency checks. The 'text file' qualifier hints at a scope limitation but the behavior on binary or missing files is left unstated.

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 padding, front-loaded with the return value and immediately followed by the usage condition. Nothing is redundant with the schema or annotations.

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

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

With an output schema present and full parameter documentation, the description only needs purpose and routing, both of which it supplies; the main remaining gap is that 'text file' implies a restriction on non-text inputs that is never explained.

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%, with both 'path' and 'server_id' fully documented including the WISP_SERVER_ID default, so the schema does the heavy lifting. The description adds no path semantics or formatting detail beyond it.

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 ('Return SHA-256 and size metadata for a text file') plus an explicit negative scope ('without returning its content'), which cleanly separates it from read_file and read_file_chunk in the sibling list.

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

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

Gives an explicit when: 'Use before safe_write_file or replace_in_file when only concurrency verification is needed,' naming two sibling alternatives and the condition that selects this tool over them.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered; "makes no changes" largely restates that. The description does add that matching is literal-only and that output is line-numbered and bounded, but bound values and case behavior live in the schema and the return shape is covered by the output schema, leaving only modest added behavioral context.

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

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

Two sentences, zero filler, with the core purpose front-loaded ahead of the usage and exclusion clauses. Every clause carries distinct 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 six fully documented parameters, full annotation coverage and an output schema, the description covers what an agent needs to select and call it: purpose, use case, literal-only semantics and non-mutation. The only thin spot is the multi-server dimension of server_id, which the schema already handles.

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 baseline is 3, and the description reinforces the key semantic constraint that query is literal text rather than a pattern. It adds nothing about the server_id default, max_matches ceiling, or context_lines effect, but the schema already documents those thoroughly.

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 (find literal text in a server file) plus the shape of what comes back (bounded, line-numbered excerpts). It also draws explicit boundaries against regex search and against the read/replace workflows, so an agent can place it among siblings like read_file_chunk and replace_in_file without opening schemas.

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

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

"Use to locate relevant sections before chunked reading or exact replacement" gives a clear when-to-use condition, and "this is not regex search" supplies an explicit exclusion. It stops short of naming the alternative tools directly or stating what to do if no literal match exists, so it is clear context rather than a full routing rule.

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

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

Annotations already cover the safety profile (read-only, idempotent, non-destructive), so the description only needs incremental context. It contributes meaningfully by disclosing that results are paginated ('one page') and by naming the fields returned, which matters since there is no output schema. It stops short of describing page-size limits or total-count behavior.

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

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

Two tight sentences with the core behavior front-loaded and the routing hint second. No filler, no repetition of annotation 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?

With no output schema, the description correctly compensates by naming the returned fields, and it flags the paginated nature of the result. A minor gap is that it doesn't mention when pagination ends or whether empty pages signal the last result, but nothing essential for calling the tool is missing.

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

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

Schema description coverage is 100%, with page, per_page, and server_id each documented including defaults and bounds, so the baseline is 3. The description adds nothing about parameter meaning beyond the schema, which is acceptable here but adds no value.

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

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

States a specific verb and resource ('List one page of backups for a server') and immediately scopes it as read-only discovery. The list of fields it reveals (IDs, names, state, metadata) plus the enumeration of downstream operations (restore, delete, lock, download) makes it easy to distinguish from the mutating backup 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?

Explicitly says when to use it: to discover backup IDs and metadata before restore, delete, lock, or download operations. It also signals the negative case ('without modifying them'), so an agent knows not to reach for it when a mutation is intended, though it does not name the specific sibling tools to use instead.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the description's 'this is read-only' adds nothing new. What it does contribute beyond the structured fields is the paging model ('one page', page/per_page control pagination), which warns the agent that results are partial rather than exhaustive. It says nothing about ordering, total counts, or what happens if the server has no databases.

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

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

Two sentences, front-loaded with the core action and scope before the usage hint. The only wasted phrase is the read-only claim, which merely repeats the annotations; everything else earns its place.

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

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

For a zero-required-parameter read tool with full schema coverage and no output schema, the definition is nearly sufficient: it conveys scope, pagination semantics, the ID-discovery purpose, and the optional host metadata. A brief note that results are capped at 25 per page and that further pages must be requested would close the remaining gap for an agent reasoning about completeness of 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 description coverage is 100%, including defaults, min/max bounds, and the WISP_SERVER_ID fallback for server_id, so the schema already carries the parameter burden. The description only restates that page/per_page drive pagination and that host metadata is optional, which is essentially a paraphrase of the schema rather than added meaning.

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

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

The description uses a specific verb and resource ('List one page of databases attached to a server'), which is unambiguous and clearly distinct from the destructive siblings like create_database, delete_database, and rotate_database_password. It does not explicitly name a competing alternative, but the read/list scope is clear enough that an agent can select it without inspecting siblings.

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

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

It states a concrete use case: 'Use to discover database IDs and optionally host metadata,' which tells the agent when this tool is the right entry point. There are no exclusions or named alternatives (e.g., when to prefer server_details for a single database), so it stops short of full routing 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 read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description usefully adds that results are paginated and that contents are not read, which goes beyond structured fields, though it omits ordering and what each entry contains.

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

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

Two tight sentences with the purpose front-loaded and the usage cue second; nothing redundant or padded.

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, fully annotated read tool with a fully described schema and no output schema, the definition covers purpose, discovery sequencing and pagination. Minor gaps remain around entry contents and sort order, but nothing essential to calling it correctly is missing.

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

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

Schema description coverage is 100%, with page, per_page, path and server_id fully documented in the schema. The description only echoes pagination, adding no format or semantics beyond what the schema already 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 concrete verb and resource ('List entries in one server directory') and adds a scope boundary ('without reading file contents') that implicitly separates it from read_file. It stops short of naming a sibling explicitly, so differentiation is inferred 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?

'Use for filesystem discovery before read or write operations' gives a clear usage context and sequencing cue. There is no explicit when-not guidance or named alternative for deeper inspection, but the intent is unambiguous.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior, and the description usefully adds that results are paginated, that visibility is governed by the configured token, and that related metadata can be opted into. It doesn't mention page-size caps or the shape of the response, but the valuable extras are present.

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

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

Two short sentences, front-loaded with the purpose, then the intended use, then the behavioral notes. Nothing is redundant or padded.

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

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

For a simple read-only list tool with no output schema and fully described parameters, the description covers purpose, usage, and pagination behavior adequately. Only minor points like the per_page ceiling or response envelope are left implicit in 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?

Schema description coverage is 100%, so the schema already documents page, per_page, and the include list. The description restates pagination and the include options (node, egg, allocations) without adding format or default details beyond the schema, so it sits at the 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?

The description gives a specific verb and resource ('List Wisp servers') and scopes it to 'visible to the configured API token', which lets an agent tell it apart from per-server siblings like server_details or server_status. It stops short of naming any sibling explicitly, so it's clear but not maximally differentiating.

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 server IDs' states a concrete use case and implicitly routes the agent away from detail-oriented siblings. There is no explicit when-not guidance or named alternative, so it falls short of a 5.

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

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

Adds real value beyond annotations by disclosing the WISP_ALLOW_BACKUPS capability requirement, feature-gated support, and that backup state is mutated. However, with idempotentHint=false and no boolean lock parameter in the schema, the description never explains whether repeated calls toggle or set state — a meaningful behavioral ambiguity the description should resolve.

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

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

Two tight sentences with the action front-loaded and prerequisites trailing; nothing is wasted. The phrase "when supported" is slightly vague but still load-bearing.

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?

Annotations already cover the safety profile (non-readonly, non-destructive, non-idempotent) and the schema is fully documented, so little is required. Still, for a mutation tool with no output schema, the description leaves unanswered what state the backup ends up in and how to lock versus unlock, which is the main residual gap.

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

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

Schema coverage is 100% and both parameters are self-documenting, so the baseline applies. The description mentions only "backup ID" and adds no meaning beyond the schema; notably it does not clarify that the desired lock state is not parameterized at all, which is the thing an agent most needs to know 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?

Names a specific verb and resource ("Change the panel lock state for a backup ID"), which clearly separates it from siblings like delete_backup, create_backup, and list_backups. It does not, however, state whether the call locks, unlocks, or toggles, which leaves the core action slightly under-determined.

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

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

Gives an explicit use case ("protect a backup from accidental deletion") and a prerequisite gate ("requires WISP_ALLOW_BACKUPS"), plus a qualifier that it only works "when supported". It omits any mention of alternatives or the inverse operation, so an agent must infer there is no separate unlock path.

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

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

Annotations already flag destructiveHint=true and non-idempotent, but the description adds genuinely new runtime context: two environment gates (WISP_ALLOW_POWER, WISP_ALLOW_DESTRUCTIVE) that must be set, and the clarification that kill is a forced stop. It does not describe post-action state or return behavior, so not a 5.

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

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

Two sentences, action vocabulary front-loaded, permission constraints after. No filler or repetition of the tool name.

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

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

For a two-parameter mutation tool with full schema coverage and annotations carrying the safety profile, the description covers intent, gating, and the destructive variant. What remains unstated — graceful vs. hard stop semantics and the response shape — is minor given there is no output schema.

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

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

Schema coverage is 100% and the enum plus server_id default are fully documented there, so the baseline is 3. The description only echoes 'force-kill' for the kill signal and adds no format or precedence detail beyond the schema.

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

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

Names a specific verb ('Change a server power state') and enumerates the exact action set (start, stop, restart, force-kill). No sibling in the list touches power state, and the mention of force-kill separates it from the softer console/command tools such as send_console_command.

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

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

Gives an explicit guard ('Use only when a power action is intended') plus the permission preconditions for the tool and for its destructive variant. It stops short of naming alternatives for non-power interventions, so conditional routing to siblings is left implicit.

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

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

The annotations already establish a safe, read-only, idempotent operation. The description adds useful result and limit behavior: fingerprint metadata accompanies the content, and content may be truncated at max_chars; it does not explain the metadata fields or whether truncation is flagged in the response.

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

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

Two compact sentences front-load the operation and output, then immediately state the use case, limitation, and alternative. There is no filler or repetition of annotation-level safety details.

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

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

For a simple three-parameter read with complete schema documentation and safety annotations, the description covers the essential selection and invocation behavior. Because there is no output schema, the unspecified fingerprint structure and truncation indicator leave a small completeness gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description references max_chars as the truncation threshold but adds no path, server_id, or parameter-format guidance beyond the schema.

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

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

The description gives a specific action and resource—reading a text file—and states that the result contains content plus fingerprint metadata. It also distinguishes the operation from read_file_chunk by framing this tool as the full-file read.

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

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

It explicitly says to use the tool when the full file is needed and routes controlled continuation after truncation to read_file_chunk. This supplies both a use case and a concrete alternative tied to the truncation condition.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds real context beyond that: the whole-file SHA-256 for integrity verification and the pagination model via next_offset_chars. It does not disclose whether chunk boundaries can split lines or characters mid-codepoint, which matters for an agent stitching slices.

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

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

Two short sentences, both front-loaded: purpose and return shape first, then the usage condition and continuation path. No filler or restatement of the tool name.

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

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

With an output schema present, return values need not be explained, and the annotations carry the safety profile. For a four-parameter read tool the description covers selection criteria and continuation adequately; only chunk-boundary semantics remain unstated.

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

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

Schema coverage is 100%, so path, max_chars, server_id and offset_chars are already documented; the baseline is 3. The description only reinforces the offset/pagination concept, and it references a field named 'next_offset_chars' that does not match the input parameter 'offset_chars', adding mild ambiguity rather than meaning.

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

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

The description names a specific verb and resource ('Read a bounded character slice of a text file') and states what is returned ('continuation metadata plus the whole-file SHA-256'). It distinguishes itself from a full-file read by scope ('bounded character slice', 'when full context is unnecessary'), though it never names the sibling read_file 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?

'Use for large files when full context is unnecessary' gives a clear selection condition against a full-file read, and 'continue with next_offset_chars' explains the iterative workflow. There is no explicit exclusion naming read_file for small files, so the routing is inferable rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so "reads the file without modifying it" largely restates structured data. It adds no detail on behavior the annotations cannot express, such as what happens when the file is shorter than the requested line count or whether large tails are truncated.

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

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

Two compact sentences, the core action first and the usage cue second. Nothing is padded and no clause needs rereading.

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 rich annotations, a fully documented three-parameter schema and an output schema, the description covers what an agent needs to call it correctly. The only remaining gap is sibling differentiation against read_file and read_file_chunk.

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%, with path, lines (default 200, max 2000) and server_id all documented in the schema. The description only echoes 'last requested lines' and adds no format, encoding, or cost guidance beyond that.

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: return the last N lines from a text log file. The 'tail' framing implicitly separates it from read_file and read_file_chunk, but no sibling is named, so the agent must infer the split.

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 for recent diagnostics after commands, power actions, or edits" gives a concrete triggering context, which is better than most. It stops short of explicit exclusions — nothing says to prefer read_file_chunk or find_in_file when the interesting output is not at the end of the file.

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 real value beyond that by naming the WISP_ALLOW_FILE_WRITES prerequisite, which is a gating requirement the annotations cannot express.

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

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

Two sentences, zero filler, with the action stated first and the usage constraint and write prerequisite following. Every sentence carries information the agent needs.

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

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

For a three-parameter mutation with no output schema, the definition covers purpose, gating condition and required permission. It omits one materially relevant behavior: whether an existing destination is overwritten or the call fails, which matters for a destructive rename.

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 required parameters and the optional server_id default are fully documented in the schema. The description adds no further meaning about path semantics or destination handling, 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 ('Rename or move a server file to a new path'), which an agent can distinguish from copy_file or delete_file. It does not name a sibling explicitly, so the differentiation is implicit rather than spelled out.

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 only when the existing path should change' gives a clear selection condition that rules out copy-style operations. It stops short of naming the alternative tool (copy_file) for cases where the original should be preserved, leaving that inference to the agent.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=false, so the mutation profile is known. The description adds real value on top: the edit is conditional on an exact SHA-256 and match-count check, the result is verified afterward, and an environment permission (WISP_ALLOW_FILE_WRITES) gates 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?

Two sentences, zero filler. The safety precondition comes first and the use-case preference plus permission requirement follow, so the agent gets the critical constraint immediately.

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 edit tool with an output schema and full annotation coverage, the definition supplies the guard conditions, the permission prerequisite, and the intended use case. It leaves mismatch behavior (error vs. no-op) implicit, but the verify-and-guard framing plus the output schema covers most of what an agent needs.

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 every parameter is already documented, including expected_sha256's provenance and expected_count's exact-match requirement. The description restates the guard semantics at a high level rather than adding new per-parameter meaning, 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 ('Replace') plus resource ('exact text snippet') and the atomic precondition (SHA-256 + match count must match exactly). It hints at the sibling distinction with 'Prefer for small edits to existing files', which implicitly contrasts with whole-file writes, but never names write_file or safe_write_file.

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?

'Prefer for small edits to existing files' gives a clear selection context versus full-file write tools, and 'requires WISP_ALLOW_FILE_WRITES' states a hard prerequisite. It stops short of naming alternatives or saying when not to use it (e.g. multi-match or large rewrites).

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

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

Beyond the annotations (destructiveHint=true, non-idempotent), the description discloses the operationally critical consequence that the old password stops working and names the two required environment gates, WISP_ALLOW_DATABASES and WISP_ALLOW_DESTRUCTIVE. That is precisely the pre-call context an agent cannot get from the annotations alone.

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

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

Two sentences, zero filler: the action comes first, then the usage constraint and prerequisites. Every clause carries information the caller needs.

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

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

For a destructive, non-idempotent mutation the safety and prerequisite picture is complete, but with no output schema the description never says whether the new password is returned in the response or must be fetched elsewhere. That is the one gap an agent needs closed before calling.

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

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

Schema description coverage is 100% and both parameters (server_id, database_id) are documented in-schema, including the WISP_SERVER_ID default. The description adds no additional parameter meaning, 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 ('Generate a new password for an existing database') with an explicit scope qualifier ('existing'). It is unambiguously distinct from create_database, delete_database, and update_server in the sibling list.

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

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

'Use only for an explicit credential rotation because the old password stops working' gives a clear triggering condition and an implicit exclusion (don't use it for routine setup or probing). It stops short of naming an alternative tool for related tasks, so it falls just short of a 5.

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

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

Beyond the write/destructive annotations, it discloses the optimistic-concurrency guard, verification of the stored result, and the WISP_ALLOW_FILE_WRITES requirement. These details explain both the safety mechanism and an operational prerequisite, and they do not conflict with the annotations.

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

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

Two compact sentences front-load the operation and guard, then provide selection and configuration guidance. There is no filler or redundant enumeration of schema fields.

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

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

Together with the complete input schema, output schema, and annotations, the description supplies nearly everything needed for safe selection and invocation. Naming read_file or file_fingerprint as concrete hash sources and stating how mismatch or verification failures are reported would make the workflow slightly more complete.

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

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

Schema coverage is 100%, so parameter formats, sources, and defaults are already documented. The description adds meaningful context by explaining that expected_sha256 is checked against the file's current hash as a write precondition, rather than merely being a 64-character value from a prior read or fingerprint.

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 specifies the operation and resource—overwriting an existing text file—and identifies its defining SHA-256 precondition and post-write verification. It also distinguishes the tool from its closest sibling, write_file.

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?

"Prefer this over write_file for existing files" gives explicit when-to-use guidance and names the alternative. Limiting the operation to existing files also signals that this is not the general choice for creating a new file.

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

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

The annotations already disclose destructiveHint=true, readOnlyHint=false, and non-idempotency. The description adds genuine context beyond them: effects are arbitrary and depend on the command, and an environment feature flag (WISP_ALLOW_COMMANDS) must be enabled, so a call can fail on a configuration gate. It still omits what the tool returns and whether the command's output is captured, which matters for a tool with 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?

Two short sentences lead with the action, then the usage context, and then the prerequisite. There is no filler, and each clause carries information the agent can act on.

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 execution tool with no output schema, the description covers the prerequisite gate and warns that effects vary. However, it does not state what comes back to the caller, whether the console output is returned, or what happens on failure. These omissions are tolerable but real, so the description is adequate rather than complete.

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

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

Schema coverage is 100%, and both parameters are documented in the schema, including the default server_id behavior. The description's phrase 'one command' adds a real constraint: the command parameter takes a single command rather than a batch or sequence. That is the appropriate baseline of 3 and no more, because the schema does the heavy lifting.

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

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

The description gives a specific verb and resource: 'Execute one command in the game-server console'. This clearly separates the tool from the file, backup, and database siblings. However, it does not name any sibling explicitly, and it also does not clarify how this tool differs from the 'power' sibling, so it does not fully earn a 5.

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

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

The phrase 'Use for explicit runtime administration commands' weakly implies usage that is not covered by the file-operation siblings. It does not name a single alternative or state a when-not-to-use condition; for example, power for start/stop or server_status for inspection. The WISP_ALLOW_COMMANDS prerequisite is a useful gating condition, but the guidance for choosing this tool remains implicit rather than explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so 'without changing it' largely restates structured data. The one genuinely additive note is the default-server fallback when server_id is omitted, which is also in the schema, so little new behavioral context is contributed.

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 tightly written sentences with the core action front-loaded followed by usage routing and the one conditional caveat. No filler and nothing redundant within the text itself.

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

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

A simple read-only, two-optional-parameter tool with rich annotations and full schema coverage needs little more. The only real gap is that 'metadata' is vague about what comes back, which matters more given there is no output schema.

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

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

Schema description coverage is 100%, so both the include list (node, egg, allocations, features) and the server_id default fallback are already documented in the schema. The description adds only the conditional omission rule and a loose hint at what facet each include value yields, meriting the baseline score.

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: 'Read metadata for one Wisp server', and enumerates the metadata facets (identity, allocation, feature, node, egg). It implies single-server scope versus the sibling list_servers, but never names that sibling explicitly to fully disambiguate.

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

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

The description gives clear usage context ('Use for identity, allocation, feature, node, or egg details') and an explicit conditional rule for omitting server_id when a default is configured. It stops short of naming alternatives or stating when not to use 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 fully covered by structured data and "performs no mutation" largely restates it. The description does add what categories of data are surfaced, but says nothing about behavior on an unknown or unreachable server, auth failures, or latency. Against an already-rich annotation set, this is adequate but not additive.

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

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

Two short sentences, front-loaded with the core action and followed by the data categories and the no-mutation guarantee. No filler, no redundancy, and the most decision-relevant information comes first.

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

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

For a simple read-only, single-optional-parameter tool with full annotation coverage and no output schema, the description covers purpose and data categories sufficiently to call it. What it omits is any hint of the response shape or failure modes, which matters more here precisely because there is no output schema to fall back on.

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

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

There is a single optional parameter and schema description coverage is 100%; the schema already explains the WISP server ID and the configured WISP_SERVER_ID fallback. With zero parameters requiring description-side compensation and the schema doing the work, the baseline applies and there is no gap to penalize.

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

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

The description opens with a specific verb and resource: "Read the current runtime state and resource usage for one server." It then enumerates the concrete signals returned (power state, CPU, memory, disk, network, game-query), which lets an agent recognize it as a monitoring tool. It does not explicitly distinguish itself from siblings such as server_details or list_servers, 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?

"Use for power state, CPU, memory, disk, network, and game-query checks" gives a clear positive usage context, and "this performs no mutation" rules out write scenarios. However, no alternative is named and no exclusion is stated, so an agent comparing this against server_details or list_servers must infer the boundary itself.

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, but the description explains the consequence — each call flips the setting — and adds an auth prerequisite (WISP_ALLOW_SERVER_SETTINGS) plus a retry warning. It does not say whether the new state is returned or how the flip fails if monitoring is unavailable, so it stops short of full disclosure.

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

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

Three short sentences, front-loaded with the action, followed by the non-idempotency warning and the permission requirement. Every sentence carries unique, actionable information.

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

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

For a single-parameter tool with no output schema, the description covers the mutation's effect, the retry hazard, and the permission gate. Only the return behavior (whether the resulting state is reported) is unaddressed, which is a minor gap.

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

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

With one optional parameter at 100% schema coverage, the schema already documents the server_id default behavior. The description adds nothing about the parameter, which is acceptable here but not additive.

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

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

The description uses a specific verb-plus-resource pairing ("Switch Wisp monitoring to its opposite state") and scopes it to "the selected server." This clearly separates it from adjacent mutation tools such as update_server and toggle_support_access, which the toggle semantics could otherwise be confused with.

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

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

It gives a caution ("do not retry blindly") that implies usage context, but never states when to prefer this over inspecting state first (e.g., server_details) or over update_server for setting an explicit value. The guidance is implied rather than explicit, and no alternative is named.

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

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

The annotations already declare destructiveHint=true and idempotentHint=false; the description goes further by explaining the mechanism (each call flips the current state) and the resulting retry hazard. The required environment/permission gate (WISP_ALLOW_SERVER_SETTINGS) is also disclosed, which annotations do not cover. It stops short of saying what enabling support access actually grants or how to verify the resulting state.

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 action and its flipping semantics, then the retry warning and prerequisite. There is mild redundancy between 'opposite state' and 'flips the current setting', but the second sentence earns its place by adding the consequence.

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

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

For a one-parameter, no-output-schema mutation tool, the description covers the key risks an agent must know: non-idempotency, retry danger, and the permission requirement. A minor gap remains in not indicating how to inspect the current setting beforehand, but the essential calling information is present.

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

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

With a single parameter and 100% schema description coverage, the schema already explains server_id and its default from WISP_SERVER_ID. The description adds no additional meaning about how server_id affects the toggle, 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?

The description states a specific verb ('Switch') and resource ('hosting-provider support access') and makes the toggling semantics explicit ('to its opposite state'). This distinguishes it from the sibling 'toggle_monitoring', which targets a different setting, and from state-reading siblings like 'server_details'.

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

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

It gives a concrete operational instruction ('do not retry blindly') and states a prerequisite (WISP_ALLOW_SERVER_SETTINGS), which an agent needs before calling. It does not name an alternative for reading the current state first, so it falls short of full when/when-not routing, but the usage context is clear.

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

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

Annotations already declare destructiveHint=true and non-idempotent behavior, and the description goes beyond them by stating the permission requirements (server-settings plus destructive access) and that server files/runtime can change. It does not say what happens post-update (e.g. runtime restart or rollback), which keeps it from a 5.

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

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

Two sentences, no filler: the action and scope come first, followed by the gating condition and permission cost. Every clause carries decision-relevant 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 two-parameter, zero-required mutation tool with a full annotation set and no output schema, the description covers purpose, preconditions, and risk. Only the post-execution effect (whether the server restarts or the update fails atomically) is left unstated.

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

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

Schema description coverage is 100%, so both `beta` (channel choice) and `server_id` (default from WISP_SERVER_ID) are already fully documented. The description adds only that the channel switch is optional, so it sits at the schema-covered 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?

The description names a specific verb and resource ("Run the Wisp egg update action for the selected server") plus its scope option (beta channel), which is enough to separate it from general mutators like power or send_console_command. It stops short of naming which sibling to use instead when the intent is not an egg update.

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 only for an explicit update request" is an explicit use-condition, and it states the prerequisites (server-settings plus destructive access). No named alternative tool is offered for near-miss cases, but the positive and negative conditions are both present.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description contributes information they cannot carry: the WISP_ALLOW_FILE_WRITES prerequisite and the lack of concurrent-edit protection. That is meaningful operational context beyond structured fields, though it stops short of describing failure behavior or whether prior content is recoverable.

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 stating purpose, then the selection criterion, then the permission and concurrency caveats. There is no filler and every clause carries distinct 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 three fully documented parameters, complete annotations, and no output schema, the description covers the main gaps an agent needs: permission requirement, overwrite semantics, and concurrency risk. Only error/rollback behavior is unaddressed, which is a minor omission for a simple write tool.

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

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

Schema description coverage is 100%, with path, content, and server_id all documented in the schema, so the baseline is 3. The description adds no syntax, size, encoding, or path-resolution detail beyond what the schema already states.

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

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

The description opens with a specific verb and resource ('Create or fully overwrite a text file') and adds the scope qualifier 'fully overwrite', which separates it from incremental-editing tools. It does not explicitly name the sibling it competes with (safe_write_file), so an agent must infer the distinction from 'deliberate full replacement'.

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 for new files or deliberate full replacement' gives a clear positive selection condition, and 'does not protect against concurrent edits' implicitly warns when to prefer a safer alternative. It never names that alternative outright, so the routing guidance is contextual rather than explicit.

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