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

Annotations already cover safety (readOnly, idempotent), yet the description adds substantive behavioral context the schema cannot: the robot has no fill gauge and only reports full/missing flags, and incomplete data may mean uncounted runs. The caveat about 'complete'/'counted_from' tells the agent how to interpret and warn about results.

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-load the contents list, then add the two interpretive caveats. Every clause carries information; the field enumeration is long but necessary because there is no output schema to describe it.

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

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

With no output schema, the description must carry the return-value burden, and it does: it lists the reported fields (swap date, days, runs, seconds, full/missing flags, previous bags, remaining-life estimate) and explains the data-completeness condition. Nothing an agent needs to call and correctly interpret this tool is missing.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing further for the description to clarify about 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 a specific report (dust bag usage since the last bag swap) and enumerates exactly what it contains, so the agent knows the resource and content. It does not distinguish itself from the adjacent matic_record_bag_swap, which is the one sibling an agent might confuse it with.

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 the content description (query bag status/life when you need that data), but there is no explicit when-to-use, when-not-to-use, or comparison against matic_status or matic_history. Nothing is misleading, but the agent must infer the trigger.

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

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

The annotations cover key safety aspects (not read-only, idempotent, not destructive), so the bar is lower. The description adds that this 'ends the current run,' clarifying a behavioral consequence beyond annotations. However, it doesn't detail physical movement or potential effects like interruption of cleaning, which could be useful.

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

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

The description is a single, front-loaded sentence that conveys the essential action and side effect without any waste.

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 the tool's simplicity (no parameters, clear annotations), the description is nearly complete. It might benefit from a brief note on when to use this versus stopping, but for a dock command, it's adequate.

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?

With zero parameters, the baseline is 4. The description doesn't need to explain parameters, and it doesn't, which is appropriate.

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

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

The description states a specific verb ('Send') and resource ('robot back to its dock'), making the action clear. However, it doesn't explicitly distinguish itself from siblings like matic_stop or matic_pause, which could be confused with ending operations.

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 tool's purpose implies it's used to end cleaning sessions by docking, but there's no explicit when-to-use guidance or comparison to alternatives such as matic_stop (which might halt without docking) or matic_pause. The parenthetical gives some context but leaves room for ambiguity.

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

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

Annotations already declare readOnlyHint, idempotentHint and closed-world behavior, so the safety profile is covered. The description adds genuine behavioral context beyond that: the robot retains roughly 20 runs and older entries are sourced from a local ledger, which tells the agent about data availability and provenance.

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, front-loaded sentence that leads with what is returned and then enumerates fields; no filler. The field list is long but every item is informative.

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

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

With no output schema, the description compensates by naming the returned fields and the retention model (about 20 runs plus local ledger). Combined with annotations, an agent has enough to call and interpret the tool, though ordering/pagination beyond 'newest first' is unspecified.

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

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

The single `limit` parameter is fully described in the schema (100% coverage), so the baseline is 3. The description adds nothing about the parameter or its default/maximum, but it needn't since the schema carries 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 resource (cleaning run history) and scope (recent runs, newest first) with an enumeration of what each run contains. An agent can tell it is a read-history tool, though it does not explicitly contrast itself with siblings like matic_status or matic_bag_report.

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 statement of when to use this tool versus alternatives, nor any prerequisite or exclusion guidance. Usage must be inferred entirely from the phrase 'recent cleaning runs'.

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

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, openWorldHint=false), so the bar is lower, and the description still adds real behavioral detail: the output format and dimensions, and the conditional rule that the route only appears when a run is active. It does not say how the image is delivered (inline/base64 vs URL), which is the remaining gap.

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 deliverable (PNG + dimensions), then the contents. Nothing is wasted and nothing essential is buried.

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

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

With no output schema, the description carries the return-value burden and does so well by enumerating what the image contains and when the route layer appears. Minor omissions are how the image is returned and whether the map is cached or regenerated per call.

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

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

Schema description coverage is 100% and the single 'route' parameter is already documented as 'Draw the current route when a run is active.' The description restates the same conditional rather than adding new syntax or defaults, so the baseline 3 applies.

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

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

The description names a concrete deliverable: a 1024x1024 PNG floor plan containing room names, the robot's position and its route. That is a specific resource and is distinguishable from siblings like matic_rooms (room data) and matic_status (state), though it never explicitly contrasts itself with 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?

There is no statement of when to reach for this tool versus matic_status or matic_rooms, and no preconditions or alternatives are named. The only conditional phrasing ('while a run is active') describes output content, not usage selection.

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

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

Annotations already declare this is a non-read-only, idempotent, non-destructive mutation, and 'Create or replace' is consistent with that. The description adds real value beyond the annotations by disclosing the validation rule that aliases can't collide with existing room/group names or 'all', and by naming the return payload since no output schema exists.

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 compact sentences, front-loaded with the action and effect, then constraints, then return shape. Every sentence carries information; only the trailing return-value sentence is arguably the least essential.

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 annotations covering the safety profile and no output schema, the description fills the remaining gaps well: it states what is created/replaced, the collision constraint, that one alias may cover multiple rooms, and what is returned. Only explicit guidance on when this tool is preferred over other naming or configuration approaches is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema doesn't: it clarifies that a single alias can point at several rooms ('downstairs'), and that alias strings must not collide with room names, group names, or 'all' — a constraint absent from the schema.

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

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

The description opens with a specific verb+resource ('Create or replace a room alias') and immediately grounds it with concrete examples ('office' for 'Room 3', 'downstairs' for several rooms). No sibling tool in the list creates aliases, so the agent can route here unambiguously.

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 the examples rather than stated: an agent infers this is the tool for assigning human-friendly names to rooms or room groups. There is no explicit when-to-use framing or comparison against alternatives, though the naming-collision constraint ('can't reuse a room name, a group name or all') is a useful boundary.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=true, so safety and idempotency are covered. The description adds a trait annotations cannot express: that the run's state is preserved and recoverable via matic_resume. It stops short of describing what happens to an in-progress task, so a 4 rather than 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?

One sentence, front-loaded with the action, with the recovery path parenthetically attached. Every clause earns its place 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?

This is a zero-parameter control tool with no output schema, so the description carries little burden; action, reversibility, and the resume follow-up are all stated. Minor gaps remain around whether the current task finishes before pausing.

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 for a parameterless tool applies, and no parameter information is missing.

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 pairs a specific verb (pause) with a specific resource (the current cleaning run), so the action is unambiguous. It also names the companion tool matic_resume, which separates it from the destructive alternatives in the sibling set (matic_stop). It does not explicitly contrast against matic_stop, which keeps 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?

It gives clear context for use by stating the pause is reversible and pointing to matic_resume for the follow-up action. There is no explicit when-not guidance (e.g., use matic_stop to end the run entirely), so the routing is helpful but not exhaustive.

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?

Goes well beyond the annotations by disclosing a non-obvious side effect: a date earlier than the current swap removes the later swap record. It also reveals the return value (the bag report) and the requirement that relative dates be resolved by the caller. The only gap is that this removal behavior sits in slight, unreconciled tension with destructiveHint=false, which an agent could misread as 'nothing is ever deleted'.

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 sentences, front-loaded with the core action and return value, then the default behavior, then the correction edge case. Every sentence carries distinct, load-bearing information; nothing is restated from the schema.

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

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

There is no output schema, and the description compensates by stating that the bag report is returned. Combined with the date-format guidance and correction semantics, an agent has everything needed to invoke this two-parameter tool correctly.

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

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

Schema coverage is 100%, so the formats (YYYY-MM-DD / YYYY-MM-DDTHH:MM / ISO 8601) and the note example are already there, giving a baseline of 3. The description adds genuine meaning beyond that: the default-when-omitted behavior and the instruction to pre-convert relative dates, which the schema does not say.

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 ('Record that the user changed the robot's dust bag') and immediately names the return value, making it clearly distinguishable from the read-only sibling matic_bag_report. An agent knows this is the write counterpart to the bag report 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?

Explicit when-to-use rules: omit `when` for today/now, pass a concrete local date for an earlier day, and convert relative expressions like 'yesterday' yourself. It also adds an alternative use case ('use this to fix a wrong date too'), so both the normal and corrective paths are covered.

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

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

Annotations already declare this is a non-read-only, idempotent, non-destructive state change, so the safety profile is covered. The description adds the precondition that the run must be paused, but does not say what happens on failure (error vs no-op) or whether queued work is affected.

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 six-word sentence with the action front-loaded. No filler, nothing wasted.

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

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

For a parameterless state-mutation tool with annotations covering idempotency and safety, the description is essentially sufficient. It could be slightly richer by noting behavior when no run is paused, but nothing critical to correct invocation is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies.

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

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

Specific verb (resume) plus specific resource (a paused cleaning run). It is trivially distinguishable from sibling tools like matic_pause, matic_start_cleaning, and matic_stop 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 phrase 'paused cleaning run' implies the precondition for use, but there is no explicit when-to-use guidance and no mention of the alternative (e.g. matic_start_cleaning) or what to do if no run is paused. Usage 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?

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint=false), so the description's burden is lighter. It adds genuine context beyond them by disclosing the shape of the data — numbered segment groups and user-defined aliases — which matters because there is no output schema to document the return structure.

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, front-loaded with the resource definition and ending with the actionable usage instruction. Every clause carries information; nothing is redundant or 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?

With no input parameters and no output schema, the description carries the load of explaining what comes back, and it does describe the returned entities and their grouping. It omits finer details like whether results are paginated or the exact field names, but for a zero-arg read-only listing this is close to sufficient.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter-related confusion is introduced.

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 (rooms on the robot's map) and explains what a room actually is — a group of numbered segments plus user aliases — which is more than a restated title. The verb is implicit (retrieval/list) rather than stated, but the meaning is unambiguous and it is distinguishable from siblings like matic_map or matic_status.

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

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

It explicitly routes the agent downstream: 'Use these names with matic_start_cleaning.' That gives a clear when-to-use context and names the consumer tool. It does not state exclusions or contrast with alternatives such as matic_map or matic_name_room, so it stops short of a 5.

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

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

Annotations already declare non-read-only, idempotent, non-destructive, so safety is covered. The description adds genuinely new behavior: that the call returns all settings, and the accepted value ranges/units (0.5–2.0 in 0.1 steps, 1.0 normal). It stops short of saying whether changes apply immediately or persist across sessions.

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 action and return behavior, then a dense but waste-free semicolon list of settings. The list is long but every clause carries required semantic information; only minor loss from packing it into one run-on sentence rather than a structured list.

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

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

No output schema exists, but the description states the return ('all settings'), and the two parameters are fully explained. Missing pieces are error behavior for out-of-range values and whether the change takes effect immediately or requires a restart, which an agent might need for a write 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 description coverage is only 50% (the `setting` enum has no schema description), but the description fully compensates by defining every enum member and its meaning, plus the valid numeric range, step size, and the neutral value for water_flow. The `value` type ambiguity is resolved by the schema's own description ('number for water_flow; true/false or on/off otherwise').

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 ('Change one robot setting') plus the side effect ('return all settings'), which no sibling tool does. The sibling set is entirely cleaning-control and map/room tools, so there is no ambiguity about which tool changes configuration.

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 explicit when-to-use, when-not-to-use, or alternative tool named. Usage is only implied by the verb 'change', and nothing tells the agent whether to read current state first (e.g., via matic_status) or how the change interacts with an in-progress cleaning run.

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

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

Annotations already declare the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the bar is lower. The description usefully discloses the return payload ('the rooms accepted and the robot's activity a few seconds later'), which matters because there is no output schema. It does not warn that repeat invocation is non-idempotent or what happens if a clean is already running.

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 action, then walks parameters in a compact per-parameter format, closing with the return behavior. Every sentence carries operational information; nothing is restated from the schema for its own sake.

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

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

For a 5-parameter, zero-required mutation tool with no output schema, the description covers all parameters, the selection heuristics, and the response shape. The remaining ambiguity (precedence of rooms vs. whole_floor, behavior when a job is already active) is minor but real.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine interpretation the schema lacks: mapping user phrasing ('hoover', 'sweep', 'clean') onto the mode enum, and defaulting coverage to 'standard' unless a quick or thorough pass is requested. The only untouched edge case is what happens when both 'rooms' and 'whole_floor' are supplied, or when neither is.

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

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

Opens with a specific verb+resource ('Start the robot cleaning now') and is immediately distinguishable from siblings like matic_pause, matic_resume, and matic_stop, which handle the opposite direction. The scope (rooms vs. whole_floor) is stated in the same breath.

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 when-to-use rules for each parameter: choose 'rooms' or 'whole_floor', map the user's verb to 'mode', default to 'standard' coverage unless they ask for quick/heavy_duty, and set 'ordered' only for sequential requests. It stops short of naming sibling alternatives (e.g. use matic_resume to continue a paused job rather than starting a new one), so no explicit exclusion is provided.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, closed world), so the bar is lower, yet the description still adds real behavioral value: it discloses that the tool never fails on connectivity and that an unreachable robot surfaces as activity 'offline' with a message. It does not say whether status is cached or how fresh it is, which keeps 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?

Front-loaded with the purpose, then a dense but purposeful enumeration of returned fields, closed by a genuinely useful error-behavior sentence. The middle list is long, but with no output schema each item 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?

With no output schema, the description must explain the return value, and it does so thoroughly, including the complete activity enumeration, settings values, and the offline fallback behavior. An agent can call this and interpret the response without further documentation.

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 is 4. The description instead spends its budget describing the returned payload, which is appropriate given there is no output schema.

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

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

Opens with a specific verb+resource ('Current robot status') and then enumerates exactly what is reported: activity states, battery %, room, error codes, bag flags, firmware, and settings. This clearly separates it from the command siblings (matic_start_cleaning, matic_pause, matic_dock) and from matic_history.

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

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

The read-only status role is strongly implied by the name and content, but the description never states when to call it versus alternatives such as matic_history or the setting-specific readings. No prerequisites or exclusions are given.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: the run ends but the robot does not move, which clarifies the nature of the 'destruction'.

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, no filler, with the primary effect front-loaded and the follow-up tool named second.

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 command with no output schema and rich annotations, the description covers what happens and what to do next. Minor gaps remain around whether the run is resumable afterward or what state the status tool will report.

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 is 4; there is nothing for the description to disambiguate beyond the empty schema.

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

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

States a specific verb and resource ('Stop and end the current cleaning run') plus the resulting physical state ('the robot stays where it is'), which distinguishes it from matic_pause and matic_dock 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?

Explicitly routes the agent to matic_dock when the goal is to send the robot home, which is the key alternative. It does not contrast with matic_pause or state when stopping is inappropriate, but the context is clear.

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