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

With no annotations, the description carries the full burden, but it does disclose a concrete behavioral trait: the output is capped at the last 50 lines, so there is no pagination or full-log option. It omits whether the read requires permissions, where the log lives, and what happens if the log is empty or missing.

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

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

One sentence, front-loaded with the action and the resource, and the scope limit is included inline. Nothing is wasted and nothing is padded.

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

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

For a simple one-parameter read tool with no output schema, the core intent is covered, but the description does not resolve the only open question an agent has — the accepted form of the 'agent' identifier — nor the log's location or error behavior.

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% for the single 'agent' parameter, so the description must compensate. It implies the parameter identifies which agent's log to read, but gives no format guidance (name, ID, or alias), leaving the agent to guess a valid value.

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

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

States a specific verb ('Read'), resource ('server log file'), and an exact scope ('last 50 lines'), which no sibling covers — restart/upgrade/list are distinct operations. An agent can identify the tool's function 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 'last 50 lines' framing implies a diagnostic/troubleshooting use, but the description never states when to reach for this versus mcp_agent_restart or mcp_agent_upgrade, nor any prerequisites. Usage is inferable but not directed.

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 behavioral burden. It usefully discloses that this is a mutating operation and that reboot is platform-conditional (honored only on real Raspberry Pi, silently ignored on Mac/dev where a process restart occurs instead). It does not mention downtime, whether in-flight work is lost, permissions, or reversibility.

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, front-loaded with the primary action and immediately followed by the optional parameter's special semantics. 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?

With no annotations and no output schema, the description should carry more: it omits what happens to the agent's connections/state during restart, whether the call waits for the process to come back, and any return or error behavior. Adequate for a simple 2-param tool but not complete.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the `reboot` boolean well, including its platform-dependent semantics and fallback behavior, but says nothing about the format or expected value of the required `agent` parameter (name vs. id).

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

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

The description gives a specific verb and resource (restart the agent's server process) and scopes the target agent via the `agent` parameter. It is clearly distinguishable from siblings like mcp_agent_upgrade, mcp_agent_logs, or mcp_agents_list 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?

The description explains the conditional use of reboot=true, which implicitly frames two modes of operation, but it never states when an agent should be restarted rather than upgraded or inspected via mcp_agent_logs. Usage is implied rather than guided.

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

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

With no annotations, the description carries the full burden and does so well: unreachable agents are still returned (online=false), the LAN is auto-scanned hourly with last_updated_at as the timestamp, and rescan forces a slow synchronous sweep. It also flags the security implication of has_default_key.

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 core purpose and return fields, then layers on rescan guidance and the security instruction. Every sentence is load-bearing, though the security-warning directive is slightly tangential to invoking the tool.

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

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

No output schema exists, yet the description fully documents return fields and their semantics (online via live /hello probe, type pi/pico, etc.), and covers the single param, caching cadence, and cost. 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?

Schema coverage is 0% (the boolean 'rescan' has no schema description), so the description must compensate, and it does: it explains what rescan=true does, its performance cost, and the condition under which it should be used. This is meaning well beyond the bare boolean type.

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 configured agents (Pi or Pico)') and immediately enumerates the returned fields. An agent can distinguish it from siblings like mcp_agent_restart, mcp_agent_upgrade, and mcp_agent_logs 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 states when to use the rescan parameter and, crucially, when NOT to ('avoid doing this unless the user explicitly asks to find new hardware'), citing the slow scan cost as the reason. It also prescribes a follow-up action (warn the user about has_default_key).

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 discloses the script run, the re-download of release files, dependency reinstallation, and the process restart. It stops short of consequences an operator would want, such as downtime, failure behavior, or irreversibility of the in-place upgrade.

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

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

A single sentence with the action front-loaded and the parenthetical reserved for mechanism detail; no filler. Slightly dense but every clause carries information about what the call actually does.

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 no annotations and no output schema, the description is adequate about what the tool does but incomplete about operational risk: nothing on downtime, what happens to the agent if the upgrade fails mid-way, or confirmation of success.

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

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

There is one parameter, 'agent', with 0% schema description coverage. The description refers to 'the agent' generically but never defines what identifier or selector the value must be, so it neither compensates for the coverage gap nor fully ignores it.

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

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

States a specific verb and resource ('Upgrade the agent in place') and goes further by naming the exact mechanism (install.sh --upgrade). An agent can tell this apart from mcp_agent_restart because the upgrade step is described, though the contrast 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?

Usage is only implied by the verb: you call it when you want the agent on the latest release. There is no explicit when/when-not guidance and no named alternative (e.g., use mcp_agent_restart for a plain restart), even though the sibling list contains a directly competing 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?

No annotations are provided, so the description carries the full burden. It discloses two important behavioral traits: a backup is saved first, and passing an empty dict resets settings while preserving the API key. This is valuable context beyond the schema. It does not mention permissions or what happens if the config is invalid.

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

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

Two sentences, front-loaded with the main action, and the special reset behavior is clearly stated. Every sentence 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 mutation tool with no annotations and no output schema, the description provides critical behavioral context (backup, reset semantics). It is almost complete, but a brief note on return value or failure modes would improve it further.

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%, so the description must compensate. It explains that the config parameter is a dict and what an empty dict does, adding meaning beyond the schema type. The agent parameter is not explained, but its purpose is relatively inferable from the tool name and context.

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 action and resource: load a full config onto an agent. It names the sibling mcp_config_read and mcp_config_write implicitly by being the operation that replaces the entire config, providing a scope distinction. However, it does not explicitly name how it differs from mcp_config_write.

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 implies usage when setting a complete configuration versus partial updates, and mentions the reset case specifically. But there is no explicit guidance on when to choose this tool over mcp_config_write or other config-related siblings.

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 must carry the behavioral burden. It usefully discloses that the `agent` block is computed live on every read and not stored, which is real added context. It does not state auth requirements, side effects, or whether other groups are persisted, but for a read-only tool the risk surface is small.

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

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

A single dense sentence, front-loaded with the verb and resource, with the enumerated groups following. No filler, though the nested parenthetical groupings make it slightly heavy to parse.

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 tool with no annotations and no output schema, the description compensates well by enumerating the config groups the caller receives and clarifying that the agent block is dynamically computed. Only the `agent` parameter's expected value remains 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?

One required parameter with 0% schema description coverage. The description implies `agent` selects whose configuration is read ('Read `agent`'s global application configuration'), which adds some meaning, but does not define the parameter's expected form or identifier source.

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 ('Read') and resource (the agent's global application configuration) and enumerates the groups returned (notifications, bridges, settings, sensors, gpios). This is clear, but it doesn't explicitly name the sibling it differs from (config_load/config_write), so the agent must infer the read/write/load distinction.

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

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

No when-to-use guidance is given versus config_load or config_write, and no prerequisites or context for calling a read are stated. The verb implies retrieval, but nothing routes the agent among the sibling config 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?

With no annotations, the description carries the full burden and does so well: it discloses the agent-side routing (webhook_url -> notifications.webhook, etc.), that reads afterwards show nested values, that log_days is clamped 0-30 and that 0 clears the log, that docs_enabled is Pi-only, and that changing api_key immediately re-authenticates and rewrites config.json. It omits permissions/auth requirements and whether omitted fields are preserved.

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

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

One dense paragraph, front-loaded with the core action and then the field semantics in a sensible order. It is long but nearly every clause carries information the schema does not.

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, no output schema, and 0% schema coverage, the description supplies routing, clamping rules, side effects, and platform restrictions. Remaining gaps (auth requirements, partial-update semantics, response shape) are real but modest.

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% across 8 params, so the description must compensate, and it explains the meaning and routing of webhook_url, webhook_key, docs_enabled, logs_enabled, log_days, and api_key — including value semantics and side effects. Only `name` and the `agent` target itself are left undefined.

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: 'Update `agent`'s global configuration dynamically.' That clearly separates it from the read/load siblings (mcp_config_read, mcp_config_load), though it never explicitly names them.

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

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

Usage is implied by 'dynamically' and by the field-by-field explanation of what each key affects, but there is no explicit statement of when to prefer this over mcp_config_read/mcp_config_load or what prerequisites exist.

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 disclose some behavior: 'watched' triggers a webhook and falls back to logging when notifications.webhook is unset, and 'remove' implies a destructive mode. It omits permissions required, whether reconfiguring resets existing pin state, and reversibility of a remove.

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 action, then a compact parameter reference. It is one long sentence, but nearly every clause carries information; only the trailing webhook parenthetical is slightly heavy.

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 9-parameter mutation tool with no annotations and no output schema, the description covers most parameters but skips name and never addresses the risks of the destructive 'remove' type or what the tool returns on success or failure.

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%, so the description must compensate, and it does: it enumerates valid values for type, init, pullup, and documents max, reversed, and watched with their applicability constraints. It leaves agent, gpio, and name undocumented, but the two required params are at least implied by 'on `agent` by number'.

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 (configure) plus resource (GPIO pin) and target (agent), so it is clearly distinct from gpio_read, gpio_write, and gpio_scan. It does not explicitly name a sibling to route against, but 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?

The parentheticals 'input only', 'output only', and 'input/output only' give implied usage rules per parameter, which is genuinely useful. However, there is no guidance on when to prefer this over gpio_write or gpio_read, and no prerequisites or exclusions are 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?

No annotations are present, so the description carries the full behavioral burden. It implies a safe read but omits whether the agent must be connected, permissions required, error behavior for an unknown pin name, and what 'all' returns — significant gaps for a tool with zero annotation coverage.

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

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

A single front-loaded sentence that states the action, target, and accepted inputs with no filler; 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 two-required-parameter read tool with no annotations and no output schema, the definition leaves out return shape (especially for 'all'), failure modes, and the source of the `agent` value, so an agent lacks enough to invoke it confidently.

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

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

Schema coverage is 0%, so the description must compensate. It usefully defines `name_or_gpio` (pin number, pin name, or the special value 'all'), which the schema cannot convey, but it never defines what `agent` accepts or where that identifier comes from.

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 a GPIO pin value") and identifies the target (`agent`), which cleanly separates it from mcp_gpio_write and mcp_gpio_config. It does not explicitly name a sibling it is not, so it falls short of the top band.

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: you read a pin when you need its value, and passing 'all' reads every pin. There is no explicit when-to-use versus mcp_gpio_scan or mcp_gpio_watched, and no prerequisites 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. It discloses the read-only nature implicitly via 'Scan...return', the exact return fields, and hardware gating, but never states side effects, permissions, or error behavior on unsupported hardware. Adequate but incomplete for a tool with zero structured behavioral 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?

One front-loaded sentence delivers the action, the return fields, and the platform-specific pin scope, followed by a short eligibility constraint. Efficient and dense, though the pin-range enumeration is long enough to slightly dilute the core action.

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 correctly enumerates return fields (value, type, pull resistor, name) and states hardware and pin-range scope. Only error/failure behavior on non-Pi/Pico targets is left unaddressed.

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% for the single required parameter, so the schema contributes nothing. The description compensates only partially by naming `agent` as the target of the scan, leaving its format (ID? hostname?) and valid values unspecified.

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 ('Scan') and resource ('all hardware GPIO pins'), plus the exact payload returned (value, type, pull resistor, name). The word 'all' plus the enumerated pin ranges distinguishes it from the single-pin sibling mcp_gpio_read without needing to open either 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 only guidance is a hardware eligibility constraint ('Only supported on Raspberry Pi / Pico hardware'), which is useful but is a precondition, not when-to-use-vs-alternative guidance. Nothing says when to pick this over mcp_gpio_read or mcp_gpio_watched for inspecting pins.

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 behavioral burden, but only 'List' implies a read-only operation and the parenthetical clarifies the semantic meaning of 'watched'. It does not disclose whether the agent must be running, permissions required, return format, or error behavior for an invalid agent.

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

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

A single front-loaded sentence with no wasted words, clearly leading with the verb and resource before the clarifying parenthetical.

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 one-parameter list tool with no output schema, the description is minimally adequate but leaves the required 'agent' parameter undefined and gives no sense of what the listing returns or how it relates to watched-pin configuration.

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 required 'agent' parameter is entirely undocumented in both schema and description. The description adds no meaning about what an 'agent' identifier is or how it scopes the watched-pin list.

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

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

States a specific verb (List) and resource (GPIO pins) with a clear scope qualifier ('currently being actively watched'). The parenthetical explains what 'watched' means (interrupts/webhooks), implicitly distinguishing it from siblings like mcp_gpio_read or mcp_gpio_scan, though it never names them explicitly.

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

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

No guidance on when to use this versus mcp_gpio_read, mcp_gpio_scan, or mcp_gpio_config. There are no exclusions or prerequisite conditions stated; the agent must infer usage from the purpose alone.

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose non-obvious semantics: the pin reverts to its previous state after the duration, duration is clamped to a configured 'max', and 'max' is used as a default. However, it omits error behavior for invalid pins, idempotency, hardware risk, and permission requirements for a write operation.

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

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

Two dense sentences, front-loaded with the core action and value options before the conditional duration rules. Every clause adds information, though the second sentence is long and could be split for readability.

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 no annotations, no output schema, and 0% schema coverage, the description covers the main behavioral semantics well but leaves gaps: no return/confirmation info, no error handling, and no indication of whether the write is persistent or stateful beyond the duration rule.

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%, so the description must compensate, and it does for the key parameters: it enumerates the valid 'value' strings ('0','1','on','off','toggle') that the bare string schema leaves unconstrained, and explains 'duration' semantics including clamping and defaulting. It does not clarify 'name_or_gpio' beyond naming.

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 ('Write') and resource ('a value to a GPIO pin') and enumerates the accepted value strings, so an agent can immediately distinguish this mutation tool from siblings like mcp_gpio_read or mcp_gpio_config.

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 explains the duration parameter's behavior and clamping, which implies intended usage for timed pulses, but it never says when to prefer this over mcp_gpio_config or other variants, nor any prerequisites such as pin validity or permissions.

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 discloses the platform-dependent execution model (`sh` on a Raspberry Pi vs in-process .py exec on a Pico), the sandbox constraint (scripts/ folder is the only allowed location, no paths), the argument charset restriction, and that remove=true deletes the sensor. It omits what happens when reconfiguring an existing sensor name and any error behavior, keeping it 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?

Four sentences, all front-loaded and information-dense: identity, what a sensor is, the script contract, then the delete flag. Nothing is repeated from the schema and every sentence 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 4-param mutation tool with no annotations and no output schema, the description covers creation semantics, the script contract, and deletion. Missing only overwrite/reconfiguration behavior on an existing name and error outcomes, which is a modest gap rather than a blocking one.

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%, so the description must compensate, and it does for the hardest parameter: `script` gets its exact grammar ('<script-file> [args...]', bare filename, letters/digits-only args) plus platform semantics. `remove` is defined as deletion. `agent` and `name` are only implied by 'a named sensor on `agent`', leaving two parameters without explicit definitions.

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

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

States a specific verb+resource ('Configure a named sensor on `agent`') and immediately disambiguates from the read-side sibling by describing the script/execution model rather than readings. An agent can tell this apart from mcp_sensor_read without opening either 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: the description explains what a sensor is and that remove=true deletes it, but never states when to call this versus mcp_sensor_read, nor any prerequisites or when-not-to-use conditions. The delete path is the only explicit routing signal.

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 provided, so the description carries the full burden. It details the return-shape semantics (nesting rules) which is valuable, but omits error handling, whether readings trigger any device activity, and any auth/permission requirements.

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, then the two modes, then the nesting rules. Well-structured and efficient, though the nesting explanation is dense and could be terser.

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 sensor tool with no output schema, the description covers the input semantics and the return shape well. Missing only ancillary details like error cases or side effects, which limits it from 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 description coverage is 0%, so the description must compensate. It explains the meaning of `name` (which sensor to read) and `agent` (target), clearly stating the no-name fallback behavior. Adds real value over 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?

Clear verb+resource: 'Read sensors on `agent`'. States the two operating modes (all sensors merged versus a single named sensor). Reasonably distinguishable from mcp_sensor_config, though it doesn't explicitly name that 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?

Explains the behavior difference between providing `name` and omitting it, which implicitly tells the agent when to use each mode. However, it does not name alternatives or state exclusions (e.g., contrast with mcp_sensor_config for setup).

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