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

With no annotations, the description carries the full burden, and it does disclose one important behavioral fact: this is a write operation gated behind ROOMBA_ALLOW_WRITES=1. It does not say whether docking interrupts an in-progress cleaning mission, what happens if the robot is already docked, or what errors occur when the robot cannot find its dock.

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, action first and prerequisite second, with zero 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?

An output schema exists so return values needn't be explained, and there are no parameters to document. But for a mutation command with no annotations, the description should note side effects such as cancelling an active mission or behavior when already docked; those gaps matter 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?

The tool takes zero parameters, so the baseline of 4 applies; there are no parameter semantics to clarify beyond what the empty schema already conveys.

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+object action ("send the robot back to its dock") that is unambiguous and clearly distinct from sibling commands like start_clean, pause_clean, or stop_clean. It doesn't explicitly name a sibling alternative, but the action is unique enough in the toolset that no differentiation is needed.

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 prerequisite ROOMBA_ALLOW_WRITES=1 is a real usage condition that tells the agent when the call will succeed, which is more than nothing. However, it gives no guidance on when to dock versus when to stop or pause a mission, and no exclusions or preconditions about the robot's current state.

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 behavioral burden and does disclose two important traits: the audible side effect and the ROOMBA_ALLOW_WRITES=1 prerequisite. It does not explain what happens if the prerequisite is missing or whether there are constraints such as the robot needing to be connected, but the key write-gate behavior is surfaced.

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 with the core action first and the prerequisite second. Every sentence adds necessary information with no filler.

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

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

For a zero-parameter, side-effect tool with an output schema already defined, the description covers the action and the environment prerequisite. It could be slightly more complete by clarifying failure behavior when ROOMBA_ALLOW_WRITES is not set, but the essential information is present.

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, so the baseline is 4. There is no parameter semantics to explain, and the description appropriately does not invent any.

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 action and effect: making the robot play its locating sound. This clearly distinguishes it from siblings like get_status or get_robot_info, which retrieve data rather than trigger an audible locating behavior.

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 'locating sound' implies the use case of finding a lost robot, but there is no explicit guidance on when to use this versus alternatives such as get_status or get_robot_info. Usage is only implied by the tool name and description.

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 implies a read-only counter query via 'get' and 'counters' but never states that it has no side effects, requires no permissions, or reflects cached vs live device state. The presence of an output schema relieves it of explaining return shape, keeping this at an adequate 3.

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 that front-loads the resource and enumerates the covered parts and the two data points returned. No filler, no repetition of the tool name.

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 zero parameters and an output schema covering the return values, the description only needs to establish what the tool is for, which it does. The one remaining gap is the absence of any statement about read-only behavior or freshness of the counters.

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 and the baseline of 4 applies. The description correctly spends no words on inputs.

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

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

The description names the resource precisely (consumable counters for brush, filter, pads and other parts) and states what each entry conveys: remaining life plus a reset-due flag. It is distinguishable from the mutating sibling reset_consumable, though it never explicitly says 'retrieves/reads' or names 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?

Usage is only implied: an agent infers it should call this when it needs remaining consumable life or wants to know if a reset is due. There is no explicit when-to-use statement, no exclusion, and no pointer to reset_consumable as the follow-up action.

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 full burden: it doesn't say whether this is a read-only fetch, whether results are cached, what the 'refresh' flag actually triggers, or whether permissions/robot connectivity are required. Only the bare payload ('maps with their regions') is disclosed.

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 with no filler, but it is a fragment rather than a front-loaded sentence and omits the verb, leaving the agent to infer 'retrieve' from the name alone.

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 needn't be explained, and the tool is a single optional parameter. Still, the purpose of 'refresh' and the read semantics remain unexplained, which leaves a meaningful gap for even this simple tool.

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

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

Schema coverage is 0% for the single 'refresh' parameter, and the description never mentions it — the agent cannot tell whether refresh forces a re-fetch from the robot or returns stale cached maps. The description adds nothing beyond the property name.

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 the resource and its content ('smart maps with their regions'), which distinguishes it from the other read siblings like get_settings or get_robot_info. The verb is only implied by the name, but the payload is specific enough to select the tool.

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

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

The phrase 'for use with start_clean' hints at a prerequisite relationship, suggesting maps are retrieved to pick a target before starting a clean. It gives no explicit when/when-not or alternatives, so the guidance 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 does disclose useful traits: only finished missions (not in-progress), sourced from the cloud, with a bounded window of 1 to 100. It omits ordering, freshness, and any auth/rate-limit context, so the disclosure is partial rather than thorough.

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 short sentence with the key scoping facts front-loaded and no waste. The trailing parenthetical is slightly cryptic, which is the only blemish on an otherwise efficient structure.

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 needn't be explained. However, for a tool with zero annotations and an undocumented parameter, the description should say more about ordering, pagination, and what 'recent' means before an agent can call 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 for the single 'limit' parameter. The '(1 to 100)' parenthetical appears to describe the limit range but is ambiguous — it could read as the number of missions returned — and the default of 20 is never mentioned.

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: retrieving recent finished missions from the iRobot cloud. That clearly distinguishes it from siblings like get_status, get_schedule, and get_map. It doesn't explicitly name a sibling or contrast with one, keeping it 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?

The description says what the tool returns but gives no guidance on when to use it versus alternatives such as get_status or get_schedule, and no prerequisites or exclusions. Usage is only implied by the resource name.

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 that capability tiers and safety flags gate other operations, which is useful behavioral context. However, it never states that the call is read-only and side-effect free, nor whether results are cached or live, leaving the safety profile implicit in the 'get_' prefix.

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 compact sentences: the first front-loads the data inventory, the second delivers the one actionable directive. Nothing is repeated from schema or annotations, and there is no filler.

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

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

An output schema exists, so return-value detail is unnecessary, and with no parameters the description only needs purpose and routing context, which it supplies. The remaining gap is distinguishing this discovery call from get_status and get_settings, which the agent must still infer.

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 and the baseline is 4. The description correctly implies no input is needed to obtain the full robot profile.

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 the resource contents precisely (identity, transport, login state, capability tiers, safety flags), so an agent knows exactly what it retrieves. It lacks a verb and never contrasts itself with near-siblings like get_status or get_settings, which likely overlap on state reporting.

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?

"Call this first to see what is allowed" gives an explicit ordering rule and a reason to call it, which is genuine usage guidance. It stops short of naming alternatives or stating when NOT to call it (e.g., after a get_status call).

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, and it discloses almost nothing beyond the return shape: it does not say whether the call is read-only, whether refresh triggers a device round-trip, or whether results are cached. The per-region parameters note is useful context but is largely covered by the output schema.

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

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

It is a single short sentence with no filler, which is good, but the brevity is under-specification rather than efficiency — the sentence stops well before the agent has what it needs.

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 an output schema exists, return values needn't be described, but with zero annotations and an undocumented 'refresh' flag, the definition is not complete enough for an agent to call this confidently alongside set_schedule and get_settings.

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 'refresh' is never explained in the description — its default of false and the effect of setting it true are left undocumented. The description does not compensate for the coverage gap at all.

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?

It names the resource (the stored cleaning schedule) and adds that per-region parameters are included, which hints at the payload. But there is no verb and no explicit statement that this reads the current schedule rather than modifying it; only the name 'get_schedule' and the sibling 'set_schedule' let an agent infer the read semantics.

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 call this versus get_settings or set_schedule, and no mention of what 'refresh' implies (e.g., re-fetch from the robot vs. return cache). The agent must guess the retrieval context entirely.

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 disclosure burden and largely drops it: it never says whether values are cached locally or queried from the device, what the refresh parameter does to that behavior, or what happens when the robot is offline or busy. For a read tool this is lower-risk, but the caching/freshness semantics of a settings read are exactly the thing an agent needs and they are absent.

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 compact sentence with no filler, front-loaded on what the tool yields. It is efficient, though the field enumeration is somewhat list-like and pushes out any usage or parameter context.

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 field list usefully previews scope. However, with zero annotations and an undocumented refresh parameter, an agent still cannot tell whether the data is live or cached — a meaningful gap for a settings read.

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, refresh, and schema description coverage is 0%, so the description was the only place to explain it — and it is never mentioned. The enumerated fields describe the return payload, not the input, so they do not compensate for the parameter gap.

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 identifies a specific resource — current cleaning settings — and enumerates exactly which settings are returned (suction, carpet boost, edge clean, pad wetness, etc.), which clearly differentiates it from siblings like get_status or set_setting. The retrieval verb is only implied by 'Current...', not stated outright, keeping it 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?

There is no guidance on when to call this versus the obvious alternative set_setting, nor any mention of prerequisites or freshness expectations. The reader must infer from the name that this is the read counterpart to the writer 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 does real work by disclosing that responses are cached and that refresh bypasses the cache — a genuine behavioral trait an agent could not infer otherwise. However, it says nothing about freshness/staleness window, polling expectations, authorization, or any failure 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?

One front-loaded sentence naming the resource and its fields, followed by one short sentence on the parameter. Nothing is wasted and the essential information leads.

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-value explanation is not required, and the field enumeration plus cache note covers the core contract for a one-parameter read tool. Remaining gap is operational context such as how fresh the cached state is or how often polling is sensible.

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 carry the single parameter — and it does, explaining that refresh=true bypasses the cache (the schema only offers a boolean with a default). What it does not say is whether a stale read is acceptable or how old cached data might be.

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 ('Live robot state') and enumerates the fields returned: battery, mission phase, bin, tank, pad, position, raw shadow. This is concrete enough to distinguish it from static-info siblings like get_robot_info or get_consumables, though it never names those siblings 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?

The only guidance is 'Set refresh=true to bypass the cache,' which covers when to use the parameter but not when to choose this tool over get_robot_info, get_settings, or get_map. Usage is implied by 'live state' 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. It does disclose a real behavioral gate — the ROOMBA_ALLOW_WRITES=1 write-permission requirement — which is genuinely useful context. However, it says nothing about what happens if no mission is running, whether the pause is reversible, or any failure 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?

Two short sentences, action first and the write-gate requirement second. Nothing is wasted and it is fully 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?

An output schema exists, so return values needn't be described, and there are no parameters. The remaining need is behavioral context, and the description supplies the write-gate precondition, though failure modes and interaction with stop/resume are left implicit.

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 no parameter semantics for the description to explain; the baseline of 4 applies. Nothing is missing on this dimension.

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 (pause) and resource (the current mission), which cleanly distinguishes it from start_clean, resume_clean, and stop_clean by name and effect. It doesn't explicitly name those siblings, but the action 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 current mission" implies a prerequisite (an active mission must exist), but there is no explicit guidance on when to pause versus stop or resume, and no stated exclusions or error conditions. Usage is only inferable from the verb.

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 load. It usefully discloses the environment-variable gate, the local-transport restriction, and the set of allowed topics, but says nothing about whether payloads bypass validation, what errors occur when the gate is closed, or what the tool does on success.

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: the purpose and the gating prerequisites are both front-loaded, and no sentence is filler. Ideal length for a debug-only 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?

An output schema exists, so return values don't need explaining, and the critical constraints (env var, local transport, allowed topics) are covered. The remaining gap is payload expectations and failure modes, which is minor but noticeable for a tool that accepts arbitrary JSON.

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 has to compensate. It does clarify the topic parameter by enumerating the accepted values (cmd, delta, shadow, timeline, testcmd), which the schema lacks, but it gives no guidance on the shape or expectations for the required payload parameter.

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?

Uses a specific verb (publish) and resource (raw JSON payload to a local topic), and frames it precisely as a 'debug escape hatch'. That framing cleanly separates it from the normal command tools in the sibling list (start_clean, set_setting, etc.).

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 'debug escape hatch' label clearly marks this as a last-resort path rather than normal operation, and the required gating (ROOMBA_ALLOW_RAW=1 plus local transport) tells the agent when the tool is even callable. It doesn't explicitly name which sibling to use for normal control instead, so it falls one step short of 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?

With no annotations, the description carries the full burden. It usefully discloses the write-gate environment variable and that this is a mutation of existing counter state, but says nothing about reversibility, behavior on an invalid/unknown part id, or required robot state during the reset.

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, zero filler, with the action and scope front-loaded and the prerequisite following. Nothing redundant with the title 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 one-parameter mutation with an output schema already documenting return values, the description covers the essential operational facts: what it mutates, where the id comes from, and the env-var gate. The only gap is state/permission preconditions beyond the write flag.

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 for the single 'part' parameter — and it does by specifying that the value is a part id obtained from get_consumables, which is meaningful semantic guidance beyond the bare string type. It does not give the exact id format or an example.

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 (reset) and resource (one consumable counter), scoped to a single item, and names the sibling get_consumables as the source of the identifier. An agent can distinguish it from get_consumables and the other siblings 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?

Gives clear operational context: the part id must come from get_consumables, implying a read-before-write workflow, and the call requires ROOMBA_ALLOW_WRITES=1. It does not name when-not-to-use conditions or robot state prerequisites (e.g., docked/idle), so it stops short of full guidance.

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

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

With no annotations, the description must carry the behavioral load. It usefully discloses the ROOMBA_ALLOW_WRITES=1 write-permission prerequisite, which the agent would otherwise miss, but says nothing about failure behavior when no mission is paused or whether the resumed mission continues from where it stopped.

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 with zero waste, and the core action is front-loaded ahead of the prerequisite. Nothing could be cut without losing 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?

An output schema exists, so return values need no explanation. But for a state-changing tool with no annotations, the definition omits what happens on an invalid state and the scope of the resume (which robot/mission), leaving a gap an agent must discover at call time.

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; the baseline of 4 applies. No misleading parameter hints are given.

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 ('Resume a paused mission'), and the word 'paused' implicitly separates it from start_clean, pause_clean, and stop_clean. It stops short of naming siblings explicitly, so it earns a 4 rather than 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?

Usage is implied by 'Resume a paused mission' – the agent can infer this applies after pause_clean – and the env-var line acts as a precondition. However, it never explicitly routes to alternatives (e.g. use start_clean if no mission is paused) or states what happens if nothing is paused.

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 and does deliver key facts: this is destructive full replacement of existing schedule state, and it requires an environment flag to be enabled. It stops short of describing failure behavior or whether the previous schedule is recoverable.

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 overwrite semantics, then the payload shape, then the prerequisite. 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?

The output schema exists, so return values need no explanation, and the description covers action, payload structure, and auth gate. Remaining gaps are the day/hour/min value ranges and timezone convention, which matter for a schedule tool.

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

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

Schema coverage is 0% and the parameter is an untyped array of loosely-typed objects with additionalProperties, so the schema alone tells an agent nothing. The description compensates well by naming the required entry shape: a start object with day, hour, min and a cmdStr string.

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 ('Replace the cleaning schedule'), and the word 'Replace' implicitly distinguishes it from the sibling get_schedule reader. It does not explicitly name the sibling, so a 4 rather than 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 'Replace' framing implies whole-schedule overwrite versus incremental edit, and the ROOMBA_ALLOW_WRITES=1 prerequisite gives a usable gate. However, there is no explicit statement of when to use this versus set_setting or get_schedule, and no note on whether an empty array clears the schedule.

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 and does disclose the key behavioral trait: a write-gating environment variable that must be set. It also discloses the mutation target and valid domains, though it doesn't say what happens on an invalid name/value or whether changes apply immediately to the device.

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-loads the action, enumerates valid settings compactly, and ends with the precondition. No filler sentences, and the notation is unambiguous.

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

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

The output schema covers return values, so the description only needed to cover the mutation surface and preconditions, which it does. The remaining gaps—error behavior for unsupported settings and whether the change is persisted immediately—are moderate but not blocking for a one-setting write.

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 largely does: it maps the 'name' parameter's allowed values to each 'value' domain (booleans, 1-3 integers, enumerated strings), resolving the anyOf ambiguity in the schema. It doesn't cover the name/value pairing mechanics or unknown-name behavior.

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 and resource ('Change one setting') and immediately enumerates the exact setting names and value domains, so the agent knows exactly what this tool mutates. The write scope is clearly distinguished from the sibling get_settings.

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 'Change one setting' and the explicit ROOMBA_ALLOW_WRITES=1 precondition tell the agent when this tool is applicable and that writes must be enabled. It does not explicitly contrast with get_settings (read counterpart) or say what to do when writes are disabled, so it falls short of a full when/when-not treatment.

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 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.

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

No annotations exist, so the description carries the whole burden; it does disclose the write-flag prerequisite, which is useful operational context. It does not disclose whether stopping is reversible, whether the mission can be resumed afterward, or what robot state results — the key behavioral facts for a mutation-style tool.

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, action first, prerequisite second, with zero filler. Nothing could be cut without losing 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?

An output schema exists, so return values need no explanation, and the zero-parameter surface keeps the tool simple. The one gap is that the effect of stopping (terminal vs. resumable) is left implicit for a control-flow tool where that distinction matters.

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 beyond the empty schema. Baseline 4 applies; the description neither adds nor misleads on inputs.

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 (stop) applied to a specific resource (the current mission), which is unambiguous on its own. It does not, however, distinguish itself from pause_clean or resume_clean, so an agent cannot tell from the description alone why it would pick stop over pause.

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 one real usage constraint — the ROOMBA_ALLOW_WRITES=1 gating requirement — which is more than nothing. But it offers no guidance on when to stop versus pause or resume, nor any note that stop terminates a mission rather than suspending it.

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