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

With no annotations, the description carries the full burden and does disclose the key trait: a single GET, no POST, i.e. non-mutating and safe to call unauthenticated. It also names the diagnostic state it surfaces, but omits any note on rate limits, error behavior, or possible failure modes from a probing request.

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

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

Two tight sentences with zero filler. The scope-defining clause ('without logging in') is front-loaded and the behavior ('Makes one GET, no POST') is stated compactly at the end.

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-param, no-annotation, no-output-schema tool the description covers purpose and the key safety/behavior trait, which is enough to call it correctly. Minor gap: no indication of what the reported values look like or what happens if the probe fails.

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 takes zero parameters, so there is nothing for the description to clarify; baseline for a no-param schema is 4. The description correctly implies no input is needed.

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 (probe) and resource (switch auth) and enumerates exactly what is reported: session model, auth variant, login mode, breaker/cooldown state. This clearly separates it from siblings like switch_login, switch_logout, and the several switch_get_* readers, which do not probe auth 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 phrase 'without logging in' implies the use case — determine the auth/login model before authenticating — and rules out the login flow, but it never names an alternative tool or states an explicit precondition/dependency on switch_login. Clear context, no explicit when-not routing.

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

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

With no annotations, the description carries the safety burden itself, explicitly declaring 'Read-only' and 'Does not mutate' and disclosing derived output fields (fault_ports, unpowered_enabled_ports) and the '--' sentinel for missing PD class. It stops short of auth requirements or rate/scale notes.

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

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

Front-loaded with the read-only guarantee, then a compact enumeration of returned fields. Dense but every clause carries field-level information; no filler sentences.

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

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

With no output schema present, the description compensates well by naming the returned fields and derived values, including edge-case semantics. Only missing auth/permission context relative to siblings like switch_check_auth.

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 takes no parameters, so the 4 baseline applies; there is no argument semantics for the description to add.

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 read verb and resource (PoE budget/port state) and enumerates the exact fields returned, so it is clearly distinguishable from the write-side siblings switch_set_poe and switch_poe_cycle.

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

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

The read-only framing implicitly positions it against switch_set_poe, but no sibling is named and no condition for choosing it over switch_get_ports or switch_get_port_stats is given. Usage must be inferred.

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?

No annotations are supplied, so the description carries the full burden, and it does so well for the safety profile: 'Read-only' and 'Does not mutate' explicitly declare the operation is non-destructive. It also discloses what the call returns. It omits auth requirements, rate limits, and pagination behavior, which keeps it from a 5.

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

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

Three short sentences, zero filler. The read-only nature and returned fields are front-loaded, and the only_linked hint follows logically after the reader knows what a port record contains.

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 annotations and no output schema, the description covers the gaps that matter: it declares the operation non-mutating and enumerates the returned fields, so an agent knows both the safety profile and the response shape. Nothing essential for correct invocation 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 0% and the single parameter has no schema description, so the description must compensate, and it does: 'Set only_linked=true to list only ports with a live link' fully explains the flag's effect. It does not restate the default of false, a minor omission.

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

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

States a specific verb and resource (read per-port state) and enumerates the exact fields returned: admin state, link, configured/actual speed, flow control, LAG id, friendly name, protection status. That field list implicitly separates it from siblings like switch_get_port_stats and switch_get_vlans, but no sibling is named explicitly, so it stops short of a 5.

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

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

The description tells you to set only_linked=true for a live-link filter, but gives no guidance on when this tool should be chosen over switch_get_port_stats, switch_get_poe, or switch_get_vlans. Usage is only implied by the field list, with no exclusions or 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?

With no annotations, the description carries the full burden. It does disclose the safety profile ('Read-only', 'Does not mutate') and the derived semantics of error_ports (rx_bad+tx_bad > 0), which is genuinely useful. However, it omits permission/auth requirements (relevant given sibling switch_login/switch_check_auth) and any error or rate-limit behavior.

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

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

Three short sentences, front-loaded with the read-only safety statement, then the return content, then the argument contract. No filler; every clause carries information.

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

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

For a one-parameter read tool with no output schema and no annotations, the description covers purpose, argument contract, return content summary, and non-mutation. It is nearly complete, missing only auth/permission prerequisites that siblings imply may exist.

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

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

The single parameter has 0% schema description coverage, so the description must compensate. It does so well: it maps the anyOf integer|string|null to 'port number' / 'PORT_MAP name' / omit-for-all. The only gap is that 'PORT_MAP name' is not defined and its source (possibly switch_resolve_port) is left implicit.

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 precise verb+resource combination ('tx/rx good/bad packet counters' for switch ports) and defines the scope (one port vs. all ports plus error_ports). This is clearly distinguishable from siblings like switch_get_ports, switch_get_poe, or switch_status.

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

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

The description explains how to invoke it (pass a port number, a PORT_MAP name, or omit for all) and what the omission yields, but gives no guidance on when to choose this tool over siblings such as switch_get_ports or switch_status. Usage context is implied 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?

With no annotations, the description carries the full burden, and it delivers two non-obvious facts: the operation is non-mutating and it 'logs in lazily', which tells the agent it need not call switch_login first. It does not cover auth failure behavior, error modes, or rate limits, so it is not complete.

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

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

Two sentences, zero filler, with the safety profile front-loaded and the returned fields listed compactly. 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?

Because there is no output schema and no annotations, the description must supply both the return contents and the safety profile, and it does both. It stops short of describing failure or timeout behavior, but for a zero-parameter read tool this is nearly sufficient.

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 takes zero parameters, so the schema cannot be improved by parameter documentation and the baseline is 4. The description instead documents the return surface, which is a reasonable substitute given there is no output 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 enumerates exactly what is returned (model, hardware revision, firmware, MAC, IP, netmask, gateway, session model), which makes the tool's purpose unambiguous and clearly separates it from siblings like switch_get_ports or switch_get_vlans. It lacks an explicit verb framing ('returns switch system information'), but the field list communicates the same thing.

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

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

The 'Read-only' and 'does not mutate anything' notes imply this is a safe introspection call, but there is no explicit statement of when to reach for it versus switch_status or switch_check_auth. Usage is inferable rather than stated.

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

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

With no annotations, the description carries the full burden and does well: it declares the operation read-only and non-mutating, and discloses a concrete failure mode (NOT_SUPPORTED on firmware without a VLAN page). It stops short of stating authentication requirements, which matters given the switch_login/switch_check_auth siblings.

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

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

Three tight, front-loaded sentences that lead with the safety profile and then the failure mode. Minor redundancy between 'Read-only' and 'Does not mutate' costs a point but nothing is wasted otherwise.

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, no-output-schema read tool this is nearly complete: purpose, safety profile, and a known error condition are all covered. The only real gap is whether prior authentication is required, which the presence of login/auth siblings makes relevant.

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 takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter syntax or format details are needed here.

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

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

States a specific read verb and the exact resource: the 802.1Q VLAN table plus per-port PVIDs. This clearly separates it from siblings such as switch_get_ports, switch_get_port_stats, and switch_get_poe, so an agent can pick it without opening any schema.

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

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

Usage is only implied - an agent infers it should call this to inspect VLAN membership and PVIDs. There is no explicit when-to-use, no statement of prerequisites (e.g. whether switch_login is required first), and no routing to alternatives, though the resource is narrow enough that alternatives are unlikely.

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

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

With no annotations, the description carries the full burden and does so: it discloses the exact side-effect sequence, what is returned (session model, hardware/firmware), what is deliberately withheld (cookies), and two refusal/blocking conditions including the circuit breaker needing human reset. This is unusually rich behavioral disclosure.

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

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

Three tight sentences with the action sequence front-loaded, then returns, then refusal conditions. Every clause carries operational information; nothing is padded or redundant.

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

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

No output schema exists, yet the description explains the return payload (session model, hardware/firmware, no cookies) and the failure modes. For a 0-param, no-annotation tool this covers everything an agent needs before invoking.

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 takes zero parameters, so there is nothing to disambiguate; baseline for a 0-param tool is 4. The description adds no parameter detail, which is appropriate here.

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

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

States a specific verb and resource ('Perform exactly one login') plus the full composite sequence (confirm via data GET, then log out). It is clearly distinguishable from siblings like switch_logout and switch_check_auth, which do only one of those steps.

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 conditions under which the tool will not act ('Refuses (no POST) in restored-account or encrypted-variant modes') and notes the breaker blocks it after a prior failure until a human clears it. It does not explicitly contrast with switch_check_auth or switch_status, but the precondition context is clear.

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

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

With no annotations provided, the description carries the full burden and delivers real behavioral facts: the HTTP method used (GET /Logout.htm), idempotent behavior when unauthenticated, and explicit non-mutation of switch settings. It omits auth prerequisites and error/failure behavior, which keeps it from a 5.

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

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

Three tight sentences, front-loaded with the action, followed by the idempotency caveat and the mutation disclaimer. Every sentence earns its place; none restates the name or 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 zero-arg, no-output-schema lifecycle tool, the description covers action, idempotency, and side-effect profile adequately. Remaining gaps (auth requirement, behavior on failure) are minor but real for a session-management operation.

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

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

Zero parameters, so the baseline is 4 and there is no parameter semantics to add or omit. The description correctly introduces no phantom arguments.

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

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

Specific verb+resource ("End any lingering session") with the underlying endpoint named, making it trivially distinguishable from switch_login and switch_check_auth. An agent knows exactly what this 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?

The description gives a clear behavioral condition for use ("no-op if not currently logged in"), which is effectively guidance on when calling it is meaningful. It does not explicitly name a sibling alternative or an exclusion, so it stops short of the full when/when-not/alternatives bar.

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

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

With no annotations present, the description carries the full burden and does so well: it declares the write nature up front, enumerates the exact refusal conditions by error code, describes the partial-failure mode and its safety warning (naming the port that may be UNPOWERED), and discloses the dry-run gate and the dual write-gate requirement. This is behavior an agent could not derive from the schema 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?

The mutation warning is front-loaded in the first word and the sentence ordering follows the operation's lifecycle (what it does, what it accepts, what it refuses, how it fails, what gates it needs). It is dense and error-code heavy, but essentially every clause carries information an agent needs, so little is wasted.

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

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

For a three-parameter mutation tool with no output schema and no annotations, this covers the critical ground: operation semantics, input resolution, authorization gates, dry-run behavior, and the concrete failure outcomes an agent must handle. Nothing needed to call it correctly appears to be 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 only 33% (confirm_write is the sole documented parameter), so the description must compensate. It does: "wait off_seconds" defines the timing parameter's role and "Resolve a PORT_MAP camera name or port number" defines the required identifier's accepted forms, adding real meaning beyond the bare anyOf integer|string 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 an explicit verb and resource ("MUTATES: power-cycle one PoE camera") and spells out the exact sequence off/wait/on/wait. It is unambiguous what the tool does, though it never names the neighboring switch_set_poe to say how a power-cycle differs from a plain PoE state change, so sibling differentiation is left to inference.

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

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

Usage context is implied rather than stated: the refusal list (NOT_POE_PORT, PROTECTED_PORT, ALREADY_OFF, CYCLE_IN_PROGRESS) and the "requires both write gates" clause tell an agent the preconditions, and the PORT_MAP note tells it what input to resolve. However, there is no explicit statement of when to choose this over switch_set_poe or switch_resolve_port, which is the main routing decision an agent faces here.

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

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

With no annotations present, the description carries the full behavioral burden and does so well: it declares read-only, 'Does not mutate,' spells out type-stable resolution rules (integer/digit-string is always a port, never a shadowing name), and enumerates the failure modes UNKNOWN_PORT, AMBIGUOUS_NAME, and INVALID_PORT.

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

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

Front-loaded with the purpose and return shape, then rules, then error codes, then the no-mutation guarantee. Every sentence carries information, though the middle passage on type-stability is dense and could be slightly tightened.

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

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

No output schema exists, but the description specifies the returned object fields and the error identifiers, covering both success and failure paths. Only auth requirements are unaddressed, which is minor for a read-only resolver.

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

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

Schema description coverage is 0% and the single parameter name_or_port has no inline documentation, so the description must compensate — and it does, explaining the anyOf(integer|string) semantics in detail, including case-insensitivity, digit-string equivalence, and that names cannot shadow numeric ports.

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 (resolve) and resource (port number or PORT_MAP name) plus the exact return shape {port, name, is_poe, protected, max_port}. It is clearly a distinct utility from the get_* siblings, though it does not name any sibling to differentiate itself explicitly.

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

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

Implies usage as a read-only resolution helper and usefully notes that UNKNOWN_PORT 'lists the known names,' which hints at a discovery workflow. However, it never states when to prefer this over switch_get_ports or switch_get_port_stats, nor any prerequisites, so the routing guidance is only implied.

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

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

With no annotations, the description carries the full burden and does so well: it states the read-modify-write sequence, that only on/off changes while priority/limit are re-sent, the post-write verification, the WRITE_VERIFY_FAILED / NOT_POE_PORT / PROTECTED_PORT outcomes, the env-var gating that produces no network call, and dry-run behavior returning the exact form.

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 mutating nature and scope are front-loaded in the first clause, and every sentence adds operative detail (effects, error codes, gating, dry-run) rather than filler. It is dense flattened prose with several stacked clauses, so it is effective but not maximally scannable.

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 gated, no-annotation mutation tool with no output schema, it covers prerequisites, side effects, failure modes and dry-run semantics thoroughly. It stops short of describing the success return payload or pagination-style output expectations, which larger context would warrant.

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

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

Schema coverage is only 33% (port and enabled are undocumented in the schema), so the description must compensate. It clarifies that 'enabled' means on/off only and that confirm_write must be the JSON boolean true, but it leaves the port parameter's accepted formats (integer vs string/name) unexplained.

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

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

Opens with a specific verb+resource+scope: 'MUTATES PoE on one port.' The mutation framing and 'changes only on/off' clearly separate it from read siblings like switch_get_poe and from switch_poe_cycle, but no sibling is named explicitly, so it stops short of the top tier.

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 real preconditions and refusal conditions (non-PoE port, protected port, EASYSMART_ALLOW_WRITES, confirm_write), which is useful context. However it never says when to prefer this over switch_poe_cycle or switch_set_port, so the when-to-use-vs-alternatives guidance is only implied.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the read-modify-write sequence, that speed and flow control are re-sent unchanged, that only state changes, that the result is verified afterwards, the PROTECTED_PORT refusal, the two-write-gate precondition, and EASYSMART_DRY_RUN support. These are exactly the traits an agent needs to predict side effects and failure modes.

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

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

Front-loads the mutation and its scope, then sequences behaviour, refusals and gates in short clauses with no filler. Slightly telegraphic phrasing such as 'write gates' is undefined, but nothing is wasted.

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

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

For a mutation tool with no annotations and no output schema, it covers side effects, safety gates, refusal codes and dry-run behaviour. The main omission is not identifying what the second write gate is and not describing port-argument formats, but an agent could call this correctly from the description alone.

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

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

Schema coverage is only 33%: port and enabled carry no descriptions, and the description does not explain accepted port formats (integer vs string) or what enabled=false means operationally beyond 'disable the link'. The mention of 'both write gates' and dry-run partially compensates by signalling the confirm_write gate, but the gap is only partly closed.

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 (MUTATES) plus the exact resource and scope: one port's admin state, i.e. enable/disable the link. This cleanly separates it from switch_set_poe, switch_poe_cycle and the read-only switch_get_* siblings without needing their 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?

Gives clear conditions for use (toggling a port's admin state) and for refusal (protected port returns PROTECTED_PORT; missing write gates means no network call), plus dry-run behaviour. It stops short of explicitly naming alternative sibling tools, so it is clear context without exclusions.

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

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

With no annotations, the description carries the burden well: it discloses side-effect freedom (never logs in, never POSTs), the single reachability GET it performs, and a privacy guarantee (never returns the password or cookies). It stops short of stating rate limits, mutation of breaker state, or failure behavior, so it's strong but not exhaustive.

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?

Very short and front-loaded with the operative label "Healthcheck" followed by the specifics. Terms like "session-model guess" and "breaker state" are terse jargon but compact rather than wasteful.

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

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

There is no output schema, so the description must convey the return content, and it lists the four things the healthcheck reports. That covers the essentials for a zero-arg diagnostic, though the exact shape/values of each field remain unspecified.

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 takes zero parameters, so no parameter meaning is required and the baseline of 4 applies; the description correctly implies a no-argument call.

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

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

States a specific purpose ("Healthcheck") and enumerates what it probes/returns: policy, a credential-free reachability GET, session-model guess, and breaker state. This is distinct from data-retrieval siblings like switch_get_ports, but the boundary against switch_check_auth and switch_get_system_info is not drawn, so an agent can't fully disambiguate.

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

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

Usage is only implied: the emphasis on "credential-free" and "never logs in" suggests this is safe to call before authentication or when diagnosing connectivity, but no explicit when-to-use or when-not-to-use versus switch_check_auth is stated.

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