start_clean

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 important behavioral fact that this is a gated write operation requiring ROOMBA_ALLOW_WRITES=1, plus the experimental flag gate. It does not say what happens on failure, whether the call blocks until the robot starts, or what occurs to an in-progress clean, so coverage of the mutation's consequences is thin.

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

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

Three short sentences, front-loaded with the action and then the gating requirements. Every sentence carries information; only minor phrasing friction ('Region, pass, suction and edge arguments' versus the plural schema names) costs it a point.

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?

An output schema exists so return values need no explanation, and the env-var gating is covered. But for a four-parameter command tool with no annotations and zero schema descriptions, the description leaves the argument value space entirely undocumented, which is a real gap for correct invocation.

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 there are no enums, so the description is the only source of parameter meaning. It names the four arguments (region, pass, suction, edge) which maps them to regions, passes, suction and edge_clean, but gives no accepted values, formats, or ranges — an agent still cannot tell what strings are valid for suction or regions.

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: 'Start a whole-home clean.' It is distinguishable from siblings like pause_clean, resume_clean and stop_clean by being the initiating action, though it never names them explicitly and the 'whole-home' framing sits slightly awkwardly with the optional region parameter.

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 preconditions: the experimental region/pass/suction/edge arguments require ROOMBA_EXPERIMENTAL=1 plus a map from get_map, and any invocation requires ROOMBA_ALLOW_WRITES=1. That routes the agent to get_map first and tells it when the optional arguments are usable, but it does not state when to prefer this over alternatives such as raw_publish.

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