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

Substantial disclosure beyond the annotations: the private key is generated locally and never returned in the reply, files land in a folder on the MCP host, phone_or_computer devices are view-only and cannot be moved, linux_machine devices self-register and become rotatable, one device slot is consumed, and an admin-scope token is required for the first kind. Also covers the delayed self-deletion of temporary devices.

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?

Purpose is front-loaded in the first clause, and every subsequent sentence carries operational information (file output, key handling, moveability, slot usage, auth scope). It is dense and longer than typical, but almost no sentence is filler; a slight trim of the kind restatements would help.

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 5-parameter mutation tool with no output schema, the description still tells the agent everything needed to call it correctly: which kind to pick, what side effects occur on the local filesystem, what is returned (commands vs. tunnel files, never the key), auth requirements, and capacity implications.

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 consequences the schema only hints at — what each kind produces mechanically, that kind selection determines move/rotate eligibility, and that slot budget is affected. It does not restate folder defaults or split_tunnel routing details, which the schema already handles well.

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 ("Add a new device to the account") and then splits the operation into its two mutually exclusive kinds, explaining what each actually produces (local WireGuard tunnel files vs. root-run commands). An agent can distinguish this from get_device/list_devices/move_device immediately.

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

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

Gives clear selection guidance between the two kinds (phone/laptop with the WireGuard app vs. Linux server or agent host) and points to get_account for slot consumption. It does not explicitly state when to use update_device or move_device instead, but the mute/edit distinction is conveyed by "view-only: they can't be moved remotely."

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=true, and the description adds real context on top: exactly what breaks (traffic stops traversing Portveil, VPN protection is lost), what survives (device remains on the account), and that it self-restores on reconnect. It also discloses auth requirements (control-scope token, Portveil-agent device) and mandates user confirmation, none of which the annotations 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?

Four short sentences, each earning its place: effect, consequence, scope, prerequisite. The core effect is front-loaded in the first clause and nothing is padded or restated.

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, idempotent mutation with no output schema, the description covers effect, reversibility, and the human-in-the-loop requirement. It does not say what the call returns (e.g., the resulting device state), which is the only notable omission.

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 covers the single `device` parameter at 100%, including accepted formats, case-insensitivity, and a pointer to list_devices, so the description has nothing to compensate for. Baseline 3 applies since the description adds no parameter detail of its own.

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?

"Turn off a device's VPN tunnel" is a specific verb+resource, and the follow-up sentences disambiguate it from the nearest siblings: the device is not removed from the account (vs remove_device) and traffic resumes when it reconnects (vs reconnect_device). An agent can distinguish this from every sibling without opening a schema.

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

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

It gives an explicit procedural precondition ("Confirm with the user first") and states the key scoping fact ("The device stays on the account"), which implicitly routes removal requests to remove_device. It does not name sibling alternatives outright, so the routing is inferred rather than stated.

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

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

The readOnlyHint annotation already marks this as safe, and the description's 'Read-only' restates that rather than adding new behavioral context. It does not disclose auth requirements, rate limits, or response shape details, but with annotations covering the safety profile, a mid score is appropriate.

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

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

Two short sentences deliver the purpose, output summary, usage trigger, and safety trait without any wasted words. The key scoped information is front-loaded.

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

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

For a zero-parameter read-only tool with annotations already covering safety, the description fully states what the agent will learn (plan and device usage against limit) and when to call it. 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 tool has zero parameters and the schema coverage is 100%, so there is no parameter ambiguity. The description adds useful context about what the result will contain, which is sufficient for an empty-parameter tool.

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

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

The description names a specific verb, resource, and output: getting the account's plan and device usage against its limit. It is clearly distinct from the sibling tools, which all operate on devices or activities.

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 states when to use the tool: when asked about the plan or before suggesting adding devices. This gives the agent actionable selection criteria without ambiguity.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds useful behavioral context by enumerating the live state fields returned (online status, exit location, tunnel confirmation, speed, rotation, clock match, last report). The trailing 'Read-only' repeats the annotation, and no permissions or rate limits are mentioned, so it falls short of a 5.

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

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

The description is front-loaded with the purpose and the return-field enumeration is dense but necessary because there is no output schema. The only minor waste is the final 'Read-only', which duplicates the readOnlyHint annotation.

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

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

Given a single-device read tool with a fully described parameter, read-only annotations, and no output schema, the description is complete: it explains what state is returned, when to use it, and that it is read-only.

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 device parameter is fully documented in the schema with accepted formats and how to obtain names/IDs. The description adds no parameter-level meaning beyond what the schema already provides, 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 states a specific verb and resource: 'Get one device's current state', then enumerates the exact state fields returned. 'One device' implicitly distinguishes it from sibling list_devices, and an agent can tell what the tool does without opening the schema.

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

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

It gives clear usage context: 'Use it to check a device before or after an action.' However, it does not explicitly name alternatives (such as list_devices for listing all devices) or state when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, so the trailing 'Read-only' is redundant and earns no credit. Beyond that, the description genuinely adds behavior: results are ordered newest first and each entry carries the token that performed the action. It does not say whether history is bounded or how far back it goes, keeping it at 4.

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

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

Three short clauses, front-loaded with the verb and resource, then the payload contents, then the use case. Only the closing 'Read-only' duplicates the annotation, a minor cost against otherwise zero-waste prose.

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-optional-parameter read tool with no output schema, the description covers what is returned (action types plus the acting token) and the ordering, so an agent can call it competently. Retention window and absence of time-range filtering are unstated, a small remaining gap.

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

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

Schema coverage is 100%, so the single 'limit' parameter is already fully documented including the 1–100 range and default. The description only echoes the newest-first ordering, which the schema also states, 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 ('list recent actions on the account') and enumerates the action types it covers (moves, reconnects, rotations, renames, tokens created), which separates it from list_devices/get_device by making clear it is an audit trail rather than a resource listing. Sibling names are not cited explicitly, so it falls just short of a 5.

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

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

Gives concrete use cases: answering 'what changed?' and auditing an assistant's actions. That is a clear context for selection, but it names no alternative tool or exclusion (e.g. when to prefer get_device for current state), so it stops at a strong 4.

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 openWorldHint=false, so the read-only nature is known. The description adds value by disclosing the output content (one line per device with protected status, exit country, speeds, remote control acceptance) and confirming it is read-only, which goes beyond the annotation's generic safety signal.

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

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

The description is two sentences with no fluff. The first sentence states the purpose and scope, the second provides usage guidance. All information is front-loaded and every clause 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 read-only list tool with no parameters and no output schema, the description covers the essential aspects: what it lists, the fields returned, and when to use it. It does not mention edge cases like pagination or authentication, but these are not critical for a simple listing operation and are not expected given the annotation coverage.

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, and the schema coverage is trivially 100%. With no parameters to describe, the baseline is 4; the description does not need to add parameter semantics since there are none.

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 states the verb 'List' and the resource 'every device on the Portveil account', and enumerates the specific fields returned (protected status, country, speeds, remote control). It also distinguishes itself from get_device by explicitly naming it for single-device lookups, so an agent can tell them apart 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?

It gives explicit guidance: 'Use this first to see what's there or to find a device's exact name; use get_device for one device.' This names the alternative and the condition that selects it, leaving no ambiguity about when to invoke this tool.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description confirms 'Read-only.' It adds genuinely new behavioral context: 'Every plan can use every location' removes a permission/plan-gating concern the annotations do not cover, and it explains why timezone/language matter. No contradiction, though nothing is said about result size or ordering.

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

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

Front-loaded with the core definition, then usage guidance, then plan availability. The browser-timezone sentence is longer than strictly necessary but does earn its place by justifying why the timezone field is returned.

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

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

With no parameters and no output schema, the description carries the burden and does so: it lists the returned fields, the plan-access rule, and the downstream tools that consume this data. Nothing an agent needs 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?

Zero parameters, so the baseline is 4. The description documents the shape of what is listed (country, city, location ID, timezone, language), which is helpful for interpreting results even though there are no inputs to explain.

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 the exit locations') and enumerates the returned fields (country, city, location ID, timezone, language), which clearly separates it from siblings like list_devices. An agent knows exactly what this returns 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?

Explicitly names two dependent tools (move_device, start_rotation) and the condition for calling this first ('when you're unsure what's available'), plus a second concrete scenario about matching browser timezone to exit IP. Both when-to-use and the alternative downstream tools are given.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false; the description goes further by explaining what idempotency means in practice ('moving to where it already is does nothing'), how long the call blocks (10–30 s), that it verifies against the new exit server, and that it reports failure plainly. It also discloses the auth requirement (control-scope token) and the agent/remote-control prerequisite, which annotations do not cover.

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?

Five tight sentences, front-loaded with purpose and wait behavior, then idempotency, then preconditions, then the routing hint. Every sentence carries distinct, non-redundant information and nothing is repeated from the schema.

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

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

For a two-parameter mutation with no output schema, the description covers latency, verification, failure reporting, idempotency, preconditions, and auth scope — everything an agent needs to call it safely and set expectations. Nothing material is left to inference.

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 richly documented (name/partial-name/ID, case-insensitivity, location names vs srv- IDs, cross-references to list_devices and list_locations). The description adds no parameter-level 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?

States a specific verb and object ('Move a device's traffic to exit from a chosen location') and explicitly names the sibling it is not: 'To just go somewhere different, use rotate_device.' An agent can distinguish this from rotate_device, reconnect_device, or update_device 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?

Names the alternative (rotate_device) and the condition that selects it, plus an explicit exclusion: only machines running the Portveil agent with remote control on, and phones using the WireGuard app must be switched on the device itself. Preconditions and the fallback path are both 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?

Adds context annotations do not cover: traffic pauses for a few seconds, a control-scope token is required, and the device must be a Portveil-agent. This is exactly the operational context an agent needs before triggering a non-read-only, idempotent reconnection.

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

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

Four short sentences, front-loaded with the action before the trigger conditions and side effects. Every sentence carries distinct information: behavior, usage, disruption, prerequisites.

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 mutation with no output schema, the description covers side effects, auth scope, and device-type constraints. It does not indicate what a successful result looks like or what happens on failure, which is a small remaining gap.

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

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

Schema description coverage is 100%, and the schema already explains that 'device' accepts a name, partial name, or dev_ ID, is case-insensitive, and can be sourced from list_devices. The description adds no parameter detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Tell a device to re-establish its VPN tunnel') and immediately distinguishes itself from move_device with 'at its current location, without moving it'. An agent can tell exactly what this does and how it differs from the closest sibling.

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

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

Gives explicit trigger conditions ('connected but not confirmed, or traffic seems stuck') and excludes the move case. Preconditions (control-scope token, Portveil-agent device) are spelled out. It stops short of naming when to prefer disconnect_device or rotate_device instead, so a 4 rather than 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 flag destructiveHint=true and idempotentHint=false; the description goes well beyond them by spelling out the blast radius (key stops working at every exit, slot is freed), irreversibility ("can't be undone; the device would have to be set up again"), and the auth requirement (admin-scope token). That is exactly the added context the annotation bar leaves room for.

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

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

Four short sentences: purpose and effect first, then irreversibility, then the confirmation requirement, then auth. Every sentence carries information an agent would otherwise have to guess, and nothing is repeated from the schema.

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

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

For a one-parameter destructive tool with no output schema, the description covers the outcome, the irreversibility, the human-confirmation safety step, and the token scope. An agent has everything needed to decide and to call it correctly.

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

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

Schema coverage is 100% and the schema itself explains name/partial-name/ID matching and points at list_devices, so the description is not obliged to re-document it. "Naming the device" reinforces the confirmation step but adds no new resolution semantics, so this 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?

States a specific verb and resource ("Permanently remove a device from the account") plus the concrete effect (VPN key stops working at every exit, slot freed). That wording implicitly separates it from the reversible siblings (disconnect_device, move_device), but it never names those siblings, so the differentiation is left to inference 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?

Gives real preconditions: confirm with the user first and name the device, and an admin-scope token is required. What is missing is an explicit exclusion or alternative — nothing tells the agent to use disconnect_device instead when the intent is temporary.

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 context beyond annotations: "Same checks and waiting as move_device" discloses a preflight-check plus async-wait pattern, and "Needs a control-scope token" discloses an auth requirement that appears nowhere in the structured fields. The non-idempotency note restates idempotentHint=false, and it does not say what happens when checks fail or how long the wait takes.

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?

Five short sentences, front-loaded with the action and effect, then constraints and the alternative. Every sentence carries distinct information; nothing is padding.

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 action, idempotency, auth scope, and sibling routing for a one-parameter tool. With no output schema, it would ideally state what is returned after the move (e.g., the new location), but the "traffic exits from somewhere new" framing covers the essential outcome.

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?

Single parameter with 100% schema description coverage; the schema already explains name/partial-name/device-ID matching, case-insensitivity, and where to obtain values. The description adds no parameter-level meaning, which is acceptable at this coverage level.

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

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

States a specific verb and resource ("Move a device once to the next location in the list") with the observable effect ("traffic exits from somewhere new"). It is clearly distinguishable from move_device (targeted move) and start_rotation (repeated moves) without needing to open 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?

Explicitly routes the agent to the alternative: "For repeated automatic moves use start_rotation instead," which is exactly the decision an agent faces among these siblings. It also implies a one-shot vs. targeted split against move_device via "same checks and waiting as move_device."

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 substantial context beyond the annotations: the schedule is executed server-side so the assistant need not stay running, a repeat call replaces rather than stacks schedules, and control-scope plus agent-device requirements must be met. These are non-obvious operational facts an agent could not infer from readOnlyHint/idempotentHint.

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

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

Three tight sentences front-loading what happens, then lifecycle (replace/stop), then prerequisites. No filler and no repetition of annotation-declared safety facts.

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 scheduling mutation with no output schema, it covers persistence semantics, replacement behavior, the stop path, and auth/device prerequisites. An agent has everything needed to decide to call it and what to expect afterwards.

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

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

Schema description coverage is 100% and each parameter already documents format, bounds (5–10080), and the 'at least two' constraint. The description only restates the interval and the optional location subset, adding no syntax or edge-case 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?

States a specific verb and resource: 'Make Portveil move a device to the next location automatically every N minutes'. The recurring/automatic framing plus 'optionally cycling through chosen locations only' clearly separates it from the one-off move_device and rotate_device 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 names the counterpart for teardown ('Stop it with stop_rotation') and states re-invocation replaces the schedule, plus prerequisites (control-scope token, Portveil-agent device). It stops short of directly contrasting with move_device/rotate_device, relying on 'automatically' to imply the distinction.

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

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

Annotations already declare idempotentHint and destructiveHint=false, but the description adds genuine extra context: the resulting state ('stays at its current location'), the no-op safety behavior, and an auth requirement ('Needs a control-scope token') that appears nowhere in the structured fields.

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

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

Three short sentences, front-loaded with the action, then the resulting state, then the safety and auth caveats. Every sentence carries actionable information with no padding.

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 state-change tool with no output schema, the description covers everything an agent needs: what it does, what the device state becomes after the call, that it's safe when already stopped, and that a control-scope token is required.

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 single 'device' parameter is fully documented with accepted formats, resolution guidance, and a pointer to list_devices. The description adds nothing beyond what the schema already says, 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: 'Turn off a device's automatic rotation,' which an agent can distinguish from start_rotation or rotate_device by the opposite effect. It stops short of naming those siblings explicitly, so the differentiation is implied rather than stated.

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

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

'Safe to call when no rotation is set' gives a clear condition under which the tool is still appropriate, which is useful negative-space guidance. It doesn't explicitly contrast with rotate_device or describe when a user would want to stop versus change rotation, leaving a small gap.

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 substantial context beyond the annotations: disabling remote control has an ongoing downstream effect (blocks move, rotate, reconnect, disconnect until re-enabled), only supplied fields are modified (partial update), and an admin-scope token is required. The 'safe to repeat' claim is consistent with idempotentHint=true and reinforces it rather than merely restating it.

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

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

Three tight sentences: action first, consequence second, operational constraints last. No filler, and the highest-risk behavior (disabling remote control) is surfaced early.

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

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

For a 3-parameter idempotent update with no output schema, the definition covers action scope, side effects, partial-update semantics, repeat safety, and auth requirements. Nothing an agent needs before invoking it 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, but the description adds real meaning to remote_control by spelling out what false blocks, and clarifies that omitted fields are left untouched. Name and device semantics are left entirely to the schema, which already documents them well.

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 concrete verbs (rename, turn remote control on/off) against a specific resource (device), which cleanly separates it from the mutating siblings move_device, rotate_device, reconnect_device and disconnect_device. An agent can pick this tool without opening the schema.

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

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

'Change only what's given' and the note that disabling remote control blocks move/rotate/reconnect/disconnect give clear context for when this tool is the right choice. There is no explicit 'use X instead' routing, but the sibling operations it gates are named, which is nearly as useful.

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