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

Adds useful behavioral detail: panel chooses the name, protected-path checks, no overwriting, mutation-limit counting, auditing, and disk-quota consumption. However, the phrase 'No confirmation' conflicts with the two-phase dry_run/confirmation_token flow in the input schema, making the behavioral guidance partially misleading.

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 dense paragraphs, front-loaded with the core action and naming behavior. Each sentence carries useful information—naming scheme, workflow, alternatives, safety, quota—with minimal filler. Slightly long but justified by the unusual naming behavior.

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?

Covers purpose, naming uncertainty, workflow, alternatives, safety checks, mutation limits, audit, and quota. The 'No confirmation' statement conflicts with the documented confirmation-token flow, creating a gap in completeness that could mislead an agent, so it is not fully reliable.

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 the baseline is 3. The description adds some relevant constraints (protected-path check, quota consumption) but these are behavioral rather than per-parameter semantics. It does not meaningfully extend the schema's parameter explanations.

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?

Description opens with 'Duplicate a file or directory in place,' a specific verb and resource, and immediately explains the panel-controlled naming behavior. It clearly differentiates from siblings like ptero_rename_file and ptero_write_file by describing the post-copy discovery workflow.

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 states the primary use case (safety net before editing a config), the workflow for getting a specific name (copy, rename, list), and the better alternative for larger operations (ptero_create_backup). This satisfies when/when-not guidance with named alternatives.

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

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

Annotations only provide flags, so the description carries the behavioral burden. It discloses blocking/polling behavior up to two minutes, return behavior differences between wait:true and wait:false, the per-server backup-count limit, and the actionable error path when full. The phrase 'Safe' aligns with destructiveHint=false and no contradiction 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?

The description is front-loaded with the core purpose and use case, then adds wait behavior and failure handling in clearly separated paragraphs. Every sentence contributes useful context, with no filler or repetition beyond what is needed for operational clarity.

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

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

The description covers when to use the tool, the main behavioral modes, and the key failure condition. Combined with the fully documented input schema and the presence of an output schema, an agent has everything needed to invoke it correctly without ambiguity.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful meaning for the wait parameter: it explains polling, the final size and success state, and the immediate uuid-only return path. It also adds operation-level context about the backup-count limit that affects whether creation can succeed.

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: 'Take a backup of the server right now.' It frames the tool as a rollback step before file writes, deletes, or power kills, which clearly distinguishes it from sibling backup tools like ptero_list_backups, ptero_delete_backup, and ptero_get_backup_download_url.

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: before any file write, delete, or power kill, to create a rollback point. It also names alternatives: ptero_list_backups for checking completion when wait:false, and ptero_delete_backup as the fix when the per-server backup limit is full, with an explicit 'not a retry' warning.

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

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

Annotations already mark the tool as destructive and idempotent, but the description adds crucial context beyond them: irreversibility with no undo, the no-op preview on first call, the single-use expiring token, the requirement for PTERODACTYL_ALLOW_DELETE=true, and the locked-backup failure mode.

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

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

The description is dense but compact, with the most important warning front-loaded. Each sentence contributes operational value, and the all-caps emphasis is used sparingly for genuinely critical points like IRREVERSIBLE and the human-preview requirement.

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?

Between the detailed schema, the output schema, and the annotations, the description covers the remaining behavioral gaps: environment requirements, safe two-phase deletion, human approval, and a clear exclusion for locked backups. An agent has everything needed to invoke this tool correctly.

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

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

Schema description coverage is 100%, and the schema already explains server, dry_run, backup_uuid, and confirmation_token in detail. The description reinforces the confirmation-token flow but does not add significant per-parameter meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Permanently delete one backup.' This unambiguously distinguishes the tool from sibling backup operations like ptero_list_backups and ptero_create_backup, and from other delete tools like ptero_delete_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?

It gives explicit when-to-use and when-not-to-use guidance: the environment variable prerequisite, the two-phase confirmation flow, the rule to show the preview to the human and wait for approval, and the locked-backup exclusion with the alternative action ('unlock it in the panel first').

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

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

Discloses irreversibility, no trash/undo, recursive directory deletion, automatic backup before delete, and the two-phase confirmation with token expiry. This goes well beyond the destructiveHint/readOnlyHint annotations and explains the preview/confirmation behavior that annotations alone would not convey.

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

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

Long but justified for a destructive tool: the warning is front-loaded, guardrails are bulleted, and the confirmation protocol is clearly sequenced. No filler.

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

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

Covers operator-controlled enablement, protected paths, batch limits, backup behavior, and the human-in-the-loop confirmation flow. With an output schema present, nothing needed to call 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 coverage is 100%, so the schema already documents root, files, server, dry_run, and confirmation_token in detail. The description reinforces key constraints (batch limit, token binding, preview-for-human) but adds little parameter-specific meaning beyond the schema.

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

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

The description opens with 'Permanently delete one or more files or directories' — a specific verb and resource. It also names the safer sibling ptero_rename_file, distinguishing this destructive tool from the alternative.

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

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

Explicitly says to prefer ptero_rename_file when a change might need undoing. It also details when deletion is refused (PTERODACTYL_ALLOW_DELETE, protected paths, >10 files) and mandates the two-phase human confirmation workflow.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds crucial behavioral detail: the URL is short-lived, grants access to anyone holding it, is never written to the audit log, and should be treated as a bearer credential. It also implies the return is a URL, not the archive itself. This goes well beyond annotations and is essential for safe use.

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-loading the purpose and then delivering critical security context. Every sentence earns its place; there is no filler or repetition. It is compact yet comprehensive.

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

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

The tool has an output schema, so return values are covered. The description addresses when to use, security handling, and the ephemeral nature of the URL. It also clarifies that the URL is for a single backup. Nothing essential is missing for an agent to call this tool correctly.

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

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

The input schema provides 100% coverage with clear descriptions for both 'server' and 'backup_uuid', including an example and a pointer to ptero_list_servers for valid identifiers. The tool description does not add parameter-specific semantics beyond the schema, but with complete schema coverage, that is acceptable. It receives 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?

The description states a specific verb-resource pair: 'get a signed, short-lived URL for downloading one backup archive.' It clearly distinguishes from siblings like ptero_list_backups (which lists backups) and ptero_create_backup (which creates them). No other sibling provides a download URL, so the purpose is unambiguous.

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

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

It explicitly says 'Use this when the human wants to pull a backup down outside the panel.' This is a clear condition for use. The description also provides security-oriented instructions (treat as bearer credential, don't store/paste/reuse), which act as usage constraints. Since no sibling offers a similar function, alternatives are not needed.

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

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

Annotations already mark it read-only, idempotent, and non-destructive, but the description adds crucial behavioral context beyond that: the websocket round trip is the *only* way to read console output, the buffer rolls over (~1 hour), and collection behavior is governed by `max_lines` and `window_seconds`. It also discloses the `truncated` flag. No contradiction with annotations.

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

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

The description is well-structured: it opens with the core function, then explains why this is the only path, then the alternative, then the mandatory follow-up usage, and finally the filter. Every sentence adds unique value, and there is no fluff or repetition. It's long but appropriately so for a tool with non-obvious websocket behavior.

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 tool with websocket collection, streaming, filtering, and truncation, the description covers everything an agent needs: the mechanism, the buffer limitation, the alternative for historical logs, the requirement after sending commands, and the filter semantics. Since an output schema exists, return values don't need description. No relevant gap remains.

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 the schema already documents each parameter, including the filter's regex-vs-substring behavior. The description adds only minor elaboration (e.g., 'without needing a wider window') that largely repeats the schema. Since the schema carries the heavy lifting, a baseline 3 is appropriate.

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

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

The description precisely states the verb and resource: 'Connect to the server's live console websocket and return the backlog... plus whatever new lines stream in.' It explicitly distinguishes this from the log-file tool `ptero_read_file` and even from `ptero_send_console_command`, so an agent can instantly tell what this tool does and what it doesn't.

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 explicit when-to-use and when-not-to-use guidance: it names `ptero_read_file` as the alternative for boot-time/plugin-load output and states 'you MUST call this tool to see what the command did' after `ptero_send_console_command`. This is unambiguous routing to the correct tool in each scenario.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read. The description adds meaningful behavioral context beyond annotations: 'This is static configuration' and the limitation that an allocated port does not imply a bound service. No contradictions.

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 detailed but every sentence serves a distinct purpose: the first enumerates contents, the second gives concrete use cases, the third clarifies limits and routes to siblings. Information is front-loaded and structured logically. Nothing is redundant.

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

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

Given the presence of an output schema and comprehensive annotations, the description covers all necessary operational context: what data is returned, how it differs from similar tools, and the important semantic caveat about port allocations. An agent can confidently select and interpret the result without further guessing.

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

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

Schema description coverage is 100% for the single 'server' parameter, which already explains the short identifier, the default via PTERODACTYL_DEFAULT_SERVER, and how to discover valid identifiers. The description adds no additional parameter-specific details beyond the schema, 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 opens with a precise verb and resource ('Get the full configuration of one server') and enumerates exactly what is returned: name, node, lifecycle status, resource limits, feature limits, allocations, SFTP, Docker image, startup command. It also names the sibling tools it is not (ptero_get_server_resources, ptero_list_allocations), making selection unambiguous.

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

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

The description explicitly states when to use it ('Use this to answer...') and what it does NOT do ('does NOT tell you whether the server is up... use ptero_get_server_resources'). It also gives a narrower alternative for ports alone and a practical caveat about allocated vs. bound ports. This fully covers when-to-use and when-not-to.

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, and non-destructive hints, so the bar for behavioral disclosure is lower. The description adds valuable context beyond those hints: 20-second panel caching, cpu_absolute meaning across cores, comparison with limits.cpu, and zeroed metrics when offline.

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?

Every sentence serves a distinct purpose: definition, use cases, sibling differentiation, caching caveat, CPU semantics, offline behavior, and follow-up routing. The information is dense but front-loaded and stays relevant with no filler.

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

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

For a single-optional-parameter read-only tool with an output schema, the description covers the surprising behaviors an agent needs to interpret results correctly and even routes to the console-log tool for deeper diagnosis. Nothing essential is missing.

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

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

The sole parameter 'server' is fully documented in the input schema, including how to discover valid identifiers and the default-server fallback. With 100% schema coverage, the description does not need to repeat parameter detail, 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: it gets live power state and resource usage metrics. It also explicitly distinguishes itself from ptero_get_server, which reports panel lifecycle status, so an agent can identify the right tool without ambiguity.

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

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

It gives concrete question patterns ('is the server up?', 'what is the memory doing?') and names the two alternatives: ptero_get_server for panel lifecycle status and ptero_get_console_log for diagnosing why something is wrong. This is explicit when-to-use and when-not-to-use 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context beyond the annotations: hidden variables are never returned, the tool cannot mutate anything, and no update tool exists. This goes beyond what the structured annotations alone provide.

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

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

The description is front-loaded with the full return payload in the first sentence, then adds a practical use case, then disclosure about hidden variables and read-only behavior. Every sentence carries substantive information and there is no fluff; it is slightly long but not 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?

The description covers the main operational needs: what the tool returns, why an agent would use it, what it cannot do, and the hidden-variable caveat. An output schema exists, so return structure is already available. Minor gaps like error behavior for an invalid server identifier are not material given the schema's default fallback and sibling listing guidance.

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 single optional 'server' parameter is fully documented in the input schema, including the default and how to discover valid identifiers. The description adds no new parameter-level meaning, so the baseline of 3 is appropriate.

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

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

The description names a specific verb ('Get') and a precise set of resources: resolved startup command, raw template, Docker image, and user-viewable egg variables with their attributes. It also gives a concrete use case (inspecting jar file, memory flags, Geyser toggle), which clearly distinguishes it from sibling tools like power state, file, or console tools.

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

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

The description explicitly states when to use the tool: 'before troubleshooting a boot failure or explaining current configuration.' It also clearly says the tool cannot change variables and that no sibling tool does, routing changes to the panel UI. It does not name a specific alternative sibling for similar config reads, but the guidance is otherwise concrete and useful.

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?

Even with readOnlyHint=true and destructiveHint=false in the annotations, the description adds valuable behavioral context: it returns allocated ip:port pairs plus the default/primary, does not indicate whether anything is listening, and explicitly states that adding/removing/repointing allocations is not exposed. No contradiction 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?

The description is front-loaded with the core purpose, followed by concrete usage guidance and a clear read-only note. Every sentence contributes usable information without redundancy or fluff.

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 list tool with an output schema and rich annotations, the description fully covers what the agent needs: what is returned, how to interpret it, the key limitation about listening ports, and the read-only scope. Nothing essential 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 coverage is 100% for the single optional server parameter, which already documents the short identifier, the default environment variable fallback, and how to discover valid identifiers. The description does not need to add more and does not meaningfully extend the schema's parameter documentation.

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

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

The description states a specific verb and resource: list the network allocations (ip:port pairs) assigned to this server, including the default/primary. This clearly distinguishes it from sibling tools like ptero_list_files, ptero_list_backups, and ptero_list_schedules.

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 tells the agent when to use the tool (to find which port a service should bind to) and when not to rely on it alone (allocation does not mean something is listening), and names the alternative confirmation path via ptero_read_file on logs/latest.log.

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 and destructiveHint=false; description adds valuable semantics: completed_at is null until the backup finishes, and it only reports what exists. No contradiction between text and annotations, and the added detail goes beyond the structured hints.

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

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

Three sentences each earn their place: the field list, the usage scenario, and the explicit clarification of scope. Slightly verbose but information-dense and front-loaded with the primary purpose.

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

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

Output schema covers return structure, description covers usage and limitations, annotations cover safety. Nothing an agent needs to call it correctly is missing, including the pointer to ptero_create_backup as the complementary 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 covers both parameters fully (server with default and discovery hint, per_page with clamp and default). Description adds no additional parameter info 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?

Clear verb 'list' with resource 'server backups', enumerates the fields returned (uuid, name, size, success, locked, timestamps), and stands apart from sibling tools like ptero_create_backup and ptero_delete_backup as a read-only reporting tool.

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

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

Explicitly states when to use (finding rollback points before/after risky changes, checking async backup completion) and explicitly warns to call ptero_create_backup before risky operations, clarifying that this tool only reports existing backups and does not create one.

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

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

Annotations already signal read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond those annotations: it is non-recursive, returns entries with full server-relative paths, lists directories before files, and sorts each group by name. No contradiction with annotations.

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

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

The description is well-structured and front-loaded: result semantics first, then use cases, then limitations. Every sentence carries useful information for tool selection or invocation, with no filler or repetition of schema 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?

Given the rich input schema, safe annotations, and presence of an output schema, the description covers everything an agent needs: what is listed, how results are ordered, the non-recursive behavior, the lack of file contents, and how the returned paths connect to other file tools. Nothing important 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 coverage is 100%, so the baseline is 3. The description adds extra practical meaning by explaining that the returned `path` is the value other file tools expect and by giving concrete directory examples like `plugins/Geyser-Spigot`. This enriches parameter understanding 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?

States a specific verb and resource: 'List one directory on the game server, relative to the server root.' It also describes exactly what each entry contains and the ordering, so an agent can distinguish this from file-content and write/delete tools 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?

Explicitly says when to use it ('Use this to find out what is actually on disk before reading or changing anything'), what it is not ('not recursive', 'does not return file contents'), and names ptero_read_file as the alternative for contents. This gives clear routing guidance against sibling tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered declaratively. The description adds value beyond this by explicitly stating that mutations are 'not exposed by this server' — a scope boundary disclosure — and by detailing the semantic contents of each schedule entry (task types, payload, delay). No contradiction with annotations.

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

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

The description is organized into three purposeful paragraphs: what is returned, when to use it, and its read-only boundary. It is front-loaded with the core purpose and each section earns its place. The first paragraph's field enumeration overlaps somewhat with the existing output schema, making it marginally longer than strictly necessary, but the redundancy is compact and aids rapid comprehension.

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

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

For a low-complexity list tool with one optional parameter, rich annotations, and an output schema, the description is complete. It covers purpose, output semantics, use-case context, and scope limitations. Nothing an agent needs to select and invoke this tool correctly is missing.

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

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

Schema description coverage is 100% — the single optional 'server' parameter is fully documented with an example, a default fallback (PTERODACTYL_DEFAULT_SERVER), and a pointer to ptero_list_servers for valid identifiers. Per the baseline rule for high coverage, the description need not add parameter detail; it adds none, which is acceptable.

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+resource: 'List a server's scheduled tasks (the panel's Schedules feature)'. It further enumerates exactly what is returned (cron timing, active/running state, online-only flag, last/next run, ordered tasks with payload and delay), leaving no ambiguity about the tool's scope. Among the 20 sibling tools, it is uniquely identifiable as the schedule-listing tool.

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

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

The second paragraph gives explicit when-to-use guidance: discover existing automation before assuming a state change was manual or before adding a new schedule via the panel to avoid clashes. It also states an explicit when-not-to-use boundary: creating/editing/deleting schedules is not exposed, and directs the agent to 'the panel UI for that'.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, and the description does not contradict them. It adds valuable non-obvious context: the `status` field is the panel lifecycle field, not a running indicator, and is null for normal servers regardless of power state. It also discloses 50-per-page pagination and the meaning of `has_more`.

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

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

The description is compact and front-loaded, with each paragraph serving a distinct purpose: scope, usage cue, status caveat, and pagination. There is no filler, repetition, or unnecessary detail, making it easy for an agent to parse and apply.

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

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

For a read-only, one-parameter list tool with an output schema and complete annotations, the description covers everything the agent needs: what is returned, when to call it, how to paginate, and what `status` does and does not mean. No critical behavioral or usage detail 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%, so the baseline is 3 because the only parameter `page` is already documented in the schema. The description adds extra actionable value by explaining that pagination is 50 per page, that `page` fetches further pages, and that `has_more` signals remaining results, going beyond the schema's basic parameter definition.

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: 'List the game servers this Pterodactyl API key can access,' and names the returned fields: short identifiers, node, primary allocation, and resource limits. It is clearly distinguishable from ptero_get_server and ptero_get_server_resources because it is explicitly about listing all accessible servers rather than fetching one resource or live power state.

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 explicit when-to-use guidance: 'Use this first when you do not already know a server identifier, or when a call fails with "not found"' and notes that every other ptero_* tool requires that identifier. It also directs the agent to ptero_get_server_resources when live power state is needed, providing a clear 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?

Beyond the readOnlyHint annotation, the description discloses key behaviors: the size guard that refuses oversized files, the fact that head/tail trimming happens after download (so it doesn't bypass the size limit), and the inability to read binary files. These are critical operational details not visible in the annotations or schema.

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

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

The description is thorough yet organized with clear paragraphs and bullet-like separation. It front-loads the most critical use case (boot logs) and then covers other uses, followed by limitations. No unnecessary filler; every sentence adds value, making it easy for an agent to parse quickly.

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

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

The description is comprehensive for a complex tool with an output schema and rich annotations. It covers key use cases, critical limitations, and operational constraints. The presence of an output schema means return values are already documented, so the description focuses on when and how to use the tool, which it does fully.

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?

Even though the input schema already covers all parameters at 100%, the description adds substantial semantic context. It explains the default and hard cap for max_bytes, the relationship between head_lines and tail_lines (mutually exclusive, post-download), and practical advice like using tail_lines for logs. This goes well beyond the schema descriptions.

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

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

The description clearly specifies the action ('Read a text file from the game server') and the resource (file relative to server root), with concrete examples. It distinguishes itself from siblings by emphasizing that this is the definitive method for retrieving full boot logs, unlike the console log tool.

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

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

The description provides explicit when-to-use guidance, including a critical scenario (boot-time diagnostics) and names the alternative tool (ptero_get_console_log) with a concrete reason to prefer this one. It also lists other common use cases (config files, crash reports) and notes when not to use it (binary files, large files).

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

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

The description discloses protected-path checks, no-overwrite behavior, no-directory-creation, and mutation accounting, which adds real value beyond the annotations. However, it states 'no confirmation is required' while the confirmation_token parameter says the tool will refuse to act without a token and requires human approval, an internal inconsistency that undermines an otherwise strong 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?

The description is front-loaded with the core action and move capability, and every paragraph adds operational context. It is longer than necessary and contains the contradictory confirmation statement, but there is no filler.

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

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

For a mutation tool with six parameters, the description covers use case, constraints, safety, and relationship to sibling tools; a rich output schema covers the return value. The confirmation-token contradiction is the main completeness gap, preventing a 5.

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

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

Schema coverage is 100%, so the schema already documents all six parameters. The description adds a concrete move example and reinforces that from/to are both root-relative, going slightly beyond the bare 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 names the operation ('Rename a file or directory') and immediately extends it to moving by interpreting both from and to relative to root, with a concrete example. This clearly distinguishes the tool from ptero_delete_file and ptero_copy_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?

It explicitly says to prefer this over ptero_delete_file whenever a change might need undoing, giving a clear when-to-use rule. It also sets boundaries by stating the destination directory must already exist and that overwriting is not supported.

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

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

Annotations already mark this as destructive and non-read-only, but the description adds substantial behavioral context: the action is asynchronous, output is not correlated by Wings, no request/response shape exists, and the panel returns HTTP 502 when the server is offline. This goes well beyond the structured annotation fields and does not contradict them.

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

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

The description is front-loaded with the core action and then uses every remaining sentence for a high-value caveat: dispatch-only semantics, the follow-up log call, the power-state alternative, and the offline error behavior. Nothing feels redundant or promotional; the length is justified by the tool's async and destructive nature.

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

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

Given the tool's complexity—async console dispatch, destructive potential, and offline failure mode—the description covers all essential operational context: what is returned, what is not returned, how to observe results, which sibling tool to use for power state, and how offline errors are reported. An output schema exists, so not detailing return fields is acceptable.

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 all three parameters (server, command, dry_run) already documented in detail. The description adds a relevant example command (`stop`) and mentions `window_seconds` for the follow-up log call, but it does not need to restate parameter meanings. Baseline 3 is appropriate since the schema carries the parameter documentation burden.

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

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

The description opens with a specific verb and resource: 'Send a command to the server console via the panel's command endpoint.' It also clarifies the exact scope of the action by stating it is 'DISPATCH ONLY' and does not return command output, which clearly distinguishes it from ptero_get_console_log and ptero_set_power_state.

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 explicit usage guidance: call ptero_get_console_log immediately afterwards to read output, do not use this tool to stop/restart/kill the server, and prefer ptero_set_power_state for power changes. It also explains the offline 502 behavior and directs the agent to start the server first. This leaves no ambiguity about when to use this tool versus alternatives.

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

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

Beyond destructiveHint=true, it discloses that stop/restart/kill require confirmation, the first call is preview-only, kill is gated behind an environment variable plus auto-backup and aborts if the backup fails, and power actions are rate-limited. This adds substantial non-obvious behavior not visible from 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?

Although long, every paragraph carries a distinct safety or workflow fact, and the most critical warnings (kill risk, confirmation, preview) are front-loaded. Paragraph breaks keep it scannable rather than a wall of text.

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

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

For a destructive, confirmation-gated, rate-limited tool with five parameters and an output schema, this description is complete: an agent knows when to act, what will happen, what can go wrong, how to confirm, and what wait_seconds changes about the return value.

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

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

The schema already covers all five parameters with 100% description coverage, so the baseline is high. The description still adds real value by explaining world-saving semantics for stop, corruption risk for kill, the preview/two-phase token contract, and the state_after polling effect of wait_seconds.

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 opening sentence pins the action to a specific verb ('Send a power signal') and resource ('the server'), and the four signal names make the scope unmistakable. It is clearly distinct from the sibling read, file, backup, and console-command tools.

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

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

It gives explicit operational rules for choosing signals: prefer stop, use kill only when hung, and start needs no confirmation. It also explains the two-phase confirmation workflow and rate limit, so an agent knows exactly when to call, when to wait, and when to avoid the tool.

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

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

Even though annotations already mark destructiveHint=true, the description adds substantial operational detail: overwriting is two-phase with a preview and single-use token, automatic backup is taken, protected paths are refused, files over 64 MiB are refused, the empty 200 confirms only receipt not integrity, and the audit log excludes file content and signed URLs. This materially exceeds what the annotations alone convey.

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

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

The description is long but front-loads the core purpose and key constraint in the first sentence, then each paragraph delivers a distinct operational fact: binary vs text, path semantics, no unpacking, confirmation flow, verification, and audit behavior. Every sentence carries safety or correctness consequence, so nothing feels wasted.

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

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

For a destructive, high-stakes upload tool with an output schema, this description covers every operational concern an agent needs: when to write content to disk first, the two-phase confirmation protocol with human-in-the-loop expectations, size and path refusals, how to verify success via ptero_list_files, and server restart implications. Nothing relevant to correctly invoking the tool is left unexplained.

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 already 100%, and the description adds further meaning on top: local_path must be absolute and existing on the MCP host with no inline payload possible, remote_dir is a directory not a destination path, remote_name must not contain '/', and confirmation_token is tied to the exact arguments and expires in 120 seconds. This gives an agent the operational context the schema alone does not fully imply.

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

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

The description names a specific verb and resource: 'Upload a file from the machine running this MCP server to the game server, BYTE FOR BYTE.' It explicitly distinguishes itself from the sibling ptero_write_file by noting that tool is text-only and corrupts non-UTF-8 bytes, so an agent can immediately tell which tool fits a binary 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?

The description gives explicit when-to-use guidance: use this for binaries such as plugin jars, zips, and images, and names ptero_write_file as the alternative that should not be used for non-UTF-8 content. It also gives post-use verification guidance via ptero_list_files and notes that archives are not decompressed, so no decompress tool is expected.

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?

Even though annotations already mark this as destructive and idempotent, the description adds crucial behavioral detail: the first call returns needs_confirmation with a preview and token, an automatic backup is taken, the token expires in 120 seconds and is bound to argument hash, protected paths are refused, and file content is never written to the audit log. This goes well beyond the annotations.

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

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

The description is long but every block earns its place: replacement semantics, read-first guidance, new-vs-overwrite workflow, protected paths, and audit logging. It is front-loaded with the most important warning about destructive replacement and stays focused throughout.

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 high-risk mutation tool with two-phase confirmation, the description is fully complete. It covers the exact call sequence, confirmation preview, token lifecycle, protected paths, backup behavior, and audit-log implications, so an agent has all necessary context to invoke it correctly.

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

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

Although schema coverage is 100%, the description adds significant meaning: content must be the complete new file and may need a trailing newline; dry_run validates without issuing a token; confirmation_token is single-use, time-limited, and invalidated by argument changes. This meaningfully enriches 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: 'Write a text file on the game server' and immediately clarifies that the body REPLACES the file entirely rather than appending or patching. This clearly differentiates it from ptero_read_file and other file tools even before considering 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?

The description explicitly instructs the agent to ALWAYS call ptero_read_file first and build new content from what exists. It also specifies when writes run immediately (new files) versus when confirmation is required (overwrites), tells the agent to show the preview to the human, and calls out protected paths that are refused.

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