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

Beyond the readOnly/idempotent annotations, it discloses exactly what is detected (ungrouped actions, wrong token separators, autocomplete strings, text-typed numbers, stale trigger args), that one case is 'report only', and that results are grouped by kind with flow names and ids. This is unusually rich behavioral context for a scanner.

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?

Purpose is front-loaded in the opening clause and every defect class listed is substantive rather than filler. However, the long comma-chained enumeration in a single sentence is heavy to parse and would read better as a list; it is dense but slightly overstuffed.

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, and the description compensates by saying results are grouped by kind with flow names and ids, plus a remediation hint. For a zero-parameter read-only tool with safety annotations, this is close to complete; only the exact finding record shape is left unstated.

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 no parameter meaning to add or omit. The description correctly implies a full-scope scan with no filtering options available.

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

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

States a specific verb ('Scan') and resource ('every simple and advanced flow') for a well-defined purpose: silent defects Homey does not flag. The defect enumeration makes it unmistakable versus siblings like list_flows or get_flow, which read flow configuration rather than validate it.

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 makes clear when this applies (finding latent flow defects) and includes an actionable follow-up ('fix token references by re-saving the flow with ownerUri|tokenId'). It stops short of explicitly contrasting with list_flows/get_flow or stating when not to run it, so not quite 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 readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the write/non-idempotent profile is covered. The description earns some credit by adding that the backup 'runs in the background,' i.e. the call returns before completion — useful async context. It does not say whether prior backups are replaced, whether there is a backup-count limit, or what the call returns (no output schema either).

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, and the async behavior is front-loaded right after the action. Nothing to trim.

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

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

For a zero-param mutation with annotations covering safety, the description is adequate but leaves practical gaps: how to observe completion (the get_backup_status sibling exists but is never referenced) and whether repeated calls accumulate or overwrite backups — an important point given idempotentHint=false.

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. The 'Homey configuration' scope note does confirm what gets backed up.

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 ('Schedule a new backup of the Homey configuration'), which is unambiguous and clearly distinct from the sibling get_backup_status. It stops short of naming that sibling or otherwise differentiating, but the action itself is unmistakable.

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

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

Usage is only implied by the verb — an agent can infer 'call this to make a backup,' but there is no explicit when-to-use, no prerequisites, and no pointer to get_backup_status for checking progress. Nothing misleading, but nothing routing either.

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, non-idempotent, non-destructive, so safety is covered. The description adds the material consequence that the message is broadcast and visible to all household members in the Homey app — decision-relevant context beyond the annotations. It does not mention return value or any persistence/expiry behavior of timeline entries, 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?

Two short sentences, zero waste, with the action front-loaded and the audience/visibility constraint immediately after. 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?

For a single-parameter, non-destructive side-effect tool with full schema coverage and annotations, the description gives enough to call it correctly. The only shortfall is the absence of any note on what a successful send returns or whether timeline entries expire, which matters slightly since no output schema exists.

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?

Only one parameter, and schema description coverage is 100% ("Notification message text"), so the schema carries the semantics. The description adds that this text is rendered on a shared household timeline, a marginal but real clarification of what the excerpt is for.

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: "Send a notification to the Homey timeline." That clearly separates it from read-side siblings like list_notifications or delete_alarm, though the description 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?

There is no explicit when-to-use or when-not-to-use guidance, and no alternative is mentioned. The visibility note implies this is for user-facing announcements rather than logging, but the agent must infer that.

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 and idempotentHint=true, so the safety profile is known. The word 'permanently' reinforces irreversibility but is largely redundant with the annotation; nothing is said about permissions required, whether an actively ringing alarm can be deleted, or what the response is.

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 waste, with the destructive nature and the ID-discovery hint both front-loaded. Nothing needs trimming.

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 destructive tool whose annotations already cover destructiveness and idempotency, the description supplies everything needed to invoke it correctly: what it does, that it is permanent, and how to get the ID. No output schema exists, and none is needed here.

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% with a single UUID-patterned 'id' parameter, so the schema carries the format burden. The description adds practical meaning by telling the agent where to source that ID (list_alarms), which is value beyond 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?

States a specific verb and resource ('Permanently delete an alarm'), which an agent can easily distinguish from siblings set_alarm and list_alarms. It does not explicitly contrast deleting with disabling via set_alarm, but the operation itself 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?

Explicitly routes the agent to list_alarms to obtain the alarm ID before calling, which is actionable usage context. It lacks a when-not clause (e.g., 'use set_alarm to temporarily disable instead of deleting'), so it falls short of the 5 bar.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is structured. The description adds genuinely new behavioral context the annotations do not: the blast radius that flows referencing the script will break, and that deletion is permanent. It does not mention permissions or whether the script ID must come via list_scripts first, keeping it at 4 rather than 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?

Two short sentences, no filler, with the permanence caveat and the collateral-damage warning both front-loaded. Every clause earns its place.

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

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

For a one-parameter destructive tool with annotations covering safety and no output schema, the description supplies exactly the missing piece a caller needs — that this breaks dependent flows. Nothing required to invoke it correctly is absent.

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 a single required parameter with 100% schema description coverage ('Script ID to delete'), which carries the semantics already. The description adds nothing about the ID's format or where to obtain it, so 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?

States a specific verb ('Permanently delete') and resource ('a HomeyScript'), which is unambiguous against siblings like get_script, list_scripts, and upsert_script. An agent can identify this as the destructive removal path without opening the schema.

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

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

The description warns of consequences but gives no explicit when-to-use or when-not guidance, and names no alternative (e.g., upsert_script to modify rather than remove). Usage is implied by the verb, which is the definition of a minimum-viable 3.

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 and idempotentHint=true, so the safety profile is covered. The description earns credit by spelling out the real-world blast radius — the app stops running and dependent devices go unavailable — which an agent cannot derive from a boolean 'enabled' flag alone. It stops short of noting effects on flows that reference those devices or what happens with an unknown app id.

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: the action comes first, the impact second. Nothing redundant with the schema or annotations.

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

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

For a two-parameter, fully documented toggle with annotations covering safety and idempotency, the description supplies the one thing structured data cannot: the service impact of disabling. Slightly incomplete in not addressing reversibility/re-enable behavior explicitly or failure modes for invalid app IDs.

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% and both parameters are documented inline ('App ID' and 'true to enable, false to disable'), so the schema carries the parameter burden. The description adds no format, id-validation, or error-behavior detail beyond that, which is the expected baseline when schema coverage is complete.

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?

Names a specific verb pair (enable/disable) and resource (a Homey app), and adds the operational consequence that disabled apps stop running and their devices become unavailable. It does not explicitly distinguish itself from adjacent siblings such as restart_app or uninstall_app, and the tool name only mentions 'enable' while the description covers both directions.

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 consequence sentence implies when you'd use it (taking an app and its devices out of service, or bringing them back), but there is no explicit when-to-use guidance or exclusion such as 'use restart_app instead if the app is crashing but should stay available'. Usage must be inferred from effect 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 declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description earns credit for disclosing the return content (configuration plus last successful timestamp), which matters because there is no output schema — though it does not say what happens when no backup has ever succeeded.

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

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

A single front-loaded sentence with no filler; both retrieved items are named compactly with nothing redundant.

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

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

The tool is simple (no params, no output schema) and the description at least names the two return fields, which is the main thing an agent needs. It stops short of describing the shape of the configuration object or the no-backup-yet case, leaving a modest gap for an output-schema-less 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?

Zero parameters, so there is nothing to document and the baseline applies. The description correctly implies no input is needed by framing the call as a simple status fetch.

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 ('Get backup configuration and last successful backup timestamp'), making clear it is a read-only status lookup. It is implicitly distinct from the sibling create_backup, though the description never names that sibling to reinforce the split.

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 can infer this is the tool to check backup state before or after calling create_backup, but the description states no conditions, no prerequisites, and no alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by naming what the returned details include, though it does not cover error behavior for invalid or missing IDs.

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

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

Two sentences, front-loaded with the purpose and followed by the ID-discovery guidance. There is no redundant or wasted text.

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

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

For a simple read-only getter with one fully described parameter and annotations covering safety, the description provides enough context. It explains the returned information and how to obtain the required ID, with no output schema needed.

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 id parameter is fully documented as a UUID. The description reinforces that retrieval is by device ID but does not add syntax or semantic detail beyond the schema baseline.

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 and resource: get detailed information about a specific device by ID. It also clarifies the returned content, including capability values, settings, and availability status, which distinguishes it from list/search siblings.

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 tells the agent to use list_devices or search_devices first to find the device ID, giving clear prerequisite guidance. It stops short of stating when not to use this tool, but the retrieval context is clear.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds genuinely useful behavioral context beyond that: it specifies the unit (watts), the current-time snapshot semantics, and the zone/device breakdown of the return value — valuable since no output schema exists. It stops short of noting refresh cadence or whether polling is expected.

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 with zero padding: purpose first, then return format, then the use case. Every sentence carries distinct information and the front-loading is correct.

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 read tool with annotations covering safety, the description covers what it returns (watts, by zone and device) and when it is the right call — enough to invoke it correctly. Only minor gaps remain (polling/refresh expectations, explicit contrast with get_energy_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. The description correctly implies no input is required and spends its words on the return shape instead, which is the right use of limited space.

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 ('Get real-time power consumption') with scope ('broken down by zone and device'). The 'real-time'/'currently' framing implicitly distinguishes it from the sibling get_energy_report, but it never names that sibling explicitly, so differentiation is inferred rather than stated.

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

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

The sentence 'Useful for answering what is using power right now?' gives a clear use case that selects this tool over a historical report. However, it provides no explicit exclusion or alternative ('for past periods use get_energy_report'), leaving the sibling routing to inference.

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 establish read-only, idempotent, non-destructive behavior. The description adds useful return context by saying the report contains kWh consumed per device, which is valuable because no output schema exists, though it does not describe response structure or edge cases.

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 front-loaded and compact: purpose, return value, and usage examples in three short sentences with no wasted text.

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

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

For a simple read-only reporting tool with a fully described two-parameter schema and annotations, the description covers purpose, return unit, and typical usage. It could be stronger by explicitly contrasting with get_energy_live, but it is largely complete.

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

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

Schema description coverage is 100%, so the period enum and date format are already fully documented. The description reinforces period-based usage with examples but adds no syntax or constraints beyond the schema, warranting the baseline score.

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 and resource: get an energy consumption report for a specific period, and clarifies that it returns kWh consumed per device. It is clear but does not explicitly distinguish itself from the sibling get_energy_live 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 description gives concrete usage examples ('how much energy did I use today/this week/this month?'), making the intended context clear. It does not explicitly state when not to use it or name get_energy_live as an alternative.

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 as read-only, idempotent, and non-destructive. The description adds useful behavioral detail: card-level fields, warnings for defects, resolved references, and the fact that advanced flows return their raw card graph.

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 front-loaded with the core purpose, then adds output details and the list_flows comparison. Every sentence contributes useful information without wasting space.

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

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

For a read-only one-parameter tool with annotations and no output schema, the description is sufficiently complete. It explains the returned structure, warnings, reference resolution, and the advanced-flow limitation.

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 id parameter is already documented as coming from list_flows. The description does not add parameter-specific semantics beyond the schema, so the baseline score of 3 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 and resource: getting a flow's full WHEN/AND/THEN definition, including resolved device, zone, and variable references. It clearly distinguishes this from list_flows by noting that list_flows only returns names.

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 a clear usage context: use this to audit what a flow actually does, because list_flows only returns names. It also notes the advanced-flow caveat, though it does not explicitly compare against all relevant siblings such as audit_flows.

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 it as read-only, idempotent, and non-destructive. The description usefully adds that it returns timestamped values such as temperature readings over time, though it does not discuss pagination or result limits.

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 core purpose and return behavior. Every sentence contributes useful context with no wasted wording.

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

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

For a simple read-only tool with complete schema descriptions and safety annotations, the definition covers purpose, prerequisite, and the nature of returned data. No output schema is needed because the return format is described.

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%, with both parameters documented and the resolution enum fully specified. The description reinforces the id parameter as coming from list_insights but adds little beyond 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?

States a specific verb and resource: retrieves historical data points for an insight log. It clearly distinguishes the tool from list_insights by explaining that list_insights is used first to find the log ID.

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 a clear prerequisite: use list_insights first to find the log ID. It implies this tool is for historical values, but does not explicitly state when not to use it or name other alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds only that the returned data covers 'options and current setting', with no detail on scope, freshness, or failure behavior — modest value beyond annotations.

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 short sentence with no filler, and the object of the read is front-loaded. It is efficient but so terse that it leaves the 'what you actually get back' underspecified.

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

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

There is no output schema, so the description is the only place where the return shape could be explained, and 'options and current setting' is vague about what fields come back. For a trivial zero-param getter this is adequate, but not fully self-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 no parameter semantics to document and the baseline is 4. The description correctly implies no input is required.

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 ('Get') and resource ('LED ring screensaver options and current setting'), which is clear enough on its own. It implicitly reads the counterpart of set_ledring among the siblings, but never names that relationship 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?

Usage is only implied: the 'Get ... current setting' phrasing suggests a read while the sibling set_ledring clearly handles writes. There is no explicit statement of when to call this versus set_ledring (e.g., 'read before modifying') or any prerequisite.

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 readOnly/idempotent annotations by disclosing data-fidelity behavior: coordinates are rounded to 2 decimals (~1 km) and the street address is suppressed unless HOMEY_MCP_PRECISE_LOCATION=1. This is exactly the kind of privacy/precision constraint an agent needs before reporting location data to a user.

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

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

Two sentences, zero filler, with the core purpose front-loaded and the precision caveat following. Every clause carries information an agent would otherwise lack.

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 no-parameter, no-output-schema read tool, the description covers purpose, expected return content (coordinates, optionally street address), and the privacy constraint that governs what is returned. Nothing material 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 the baseline of 4 applies; there is nothing for the description to disambiguate. No penalty given 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 ('Get Homey's configured geographic location') and immediately names its purpose domain (sunrise/sunset and weather). This distinguishes it cleanly from siblings like get_system_info or get_weather, which cover different concerns.

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 makes the use case explicit (sunrise/sunset calculations and weather context), which tells an agent when this tool is relevant. It never names an alternative or an exclusion, but for a parameterless read tool with no overlap the implied guidance is nearly sufficient.

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 destructiveHint=false, so the safety profile is fully covered and the description need not repeat it. The description adds a hint about result granularity (per app and per system component) but says nothing about snapshot freshness, cost, or failure modes, so it adds only modest value.

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 no filler: the capability statement comes first and the use case second. Every sentence earns its place, though the second is thin enough that it could have carried a routing hint instead of a restatement of usefulness.

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 parameters, no output schema, and annotations covering safety, the description does the remaining work: it says what is measured (memory) and at what granularity (per app, per system component). The only real gap is that return shape and freshness are left unspecified.

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

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

The tool takes zero parameters, so there is nothing for the description to document and the baseline of 4 applies. Nothing in the text contradicts or misdescribes 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 (Get) and resource (Homey memory usage) plus the shape of the result: a breakdown by app and system component. It is distinguishable from neighbors like get_storage_info and get_system_info only by the word 'memory' — no explicit contrast is drawn, so it stops short of the top score.

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 second sentence implies a use case ('identifying memory-hungry apps') but gives no explicit when/when-not conditions and never routes the agent between this tool and the very similar get_storage_info or get_system_info siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds what status dimensions are returned (home/away and awake/asleep) and that results cover all household members, but it does not describe permissions, rate limits, or return structure beyond that.

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 no wasted language. The core purpose is front-loaded, followed by useful example scenarios.

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 no-parameter read-only getter with annotations covering safety, the description is largely complete: it names the status types and scope (all household members). It could be slightly richer about the exact return shape, but no output schema exists and the current description is sufficient 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 has zero parameters, so there is no parameter semantics to explain and the baseline is 4. The description correctly does not discuss inputs, matching 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?

The description uses a specific verb and resource: it states that it gets home/away and awake/asleep status for all household members. This clearly distinguishes it from the sibling set_presence, which would be the mutating counterpart.

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 concrete usage examples ('is anyone home?' or 'who is home?'), which clearly signals when the tool is appropriate. It does not explicitly mention the alternative set_presence, but the get/set distinction is obvious from the tool name and siblings.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds that the result includes full source code and metadata, which is useful context given there is no output schema, but it says nothing about auth, size limits, or error 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, front-loaded with the capability and followed by the prerequisite. Every sentence earns its place.

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

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

A low-complexity single-parameter read tool with full annotation coverage; the description adds return-content context, which compensates for the missing output schema. Nothing critical is missing 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 100% and the 'id' parameter is documented as a slug or UUID with a pattern. The description only implies the id must come from list_scripts and adds no format detail beyond the schema, so 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?

States a specific verb ('Get') and resource ('HomeyScript') and clarifies the return content: full source code and metadata. This distinguishes it from siblings like list_scripts, run_script, and upsert_script, though it doesn't explicitly name what it is not.

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 list_scripts to discover IDs, which is the key prerequisite for calling this tool. No when-not guidance is given, but for a simple read tool that's a minor omission.

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 non-destructive behavior, so safety is covered. The description adds useful behavioral context by naming what the tool returns: authenticated user, role, and permission scopes, which is not conveyed by the annotations.

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 with no wasted text. It immediately states the action, resource, and returned details.

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

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

For a simple, parameter-free read tool with no output schema, the description is nearly complete because it names the returned fields. It could optionally clarify error or unauthenticated behavior, but no major gap remains.

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 are no parameter semantics to document. The schema is empty and requires no explanation, matching the baseline for parameter-free tools.

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 and resource: get current API session details. It also enumerates the key returned fields (authenticated user, role, permission scopes), making the tool's purpose clear, though it does not explicitly distinguish it from nearby get_*_info siblings.

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 implies when to use the tool by saying it retrieves current session details, but it provides no explicit guidance on when to prefer it over alternatives such as get_system_info or other info tools. No exclusions or prerequisites are stated.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds the breakdown categories (apps, insights, system), which is useful context, but says nothing about units, whether figures are totals or per-category only, or freshness.

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 verb and resource. Slightly redundant ('storage usage breakdown' then 'how much disk space is used') but nothing padding.

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 no-arg read-only tool with no output schema, the description conveys what the response contains (per-category disk usage). An agent can decide and call it correctly; only unit/return-shape detail 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?

Zero parameters, so baseline is 4. The description correctly implies no input is needed and spends its words on output content rather than fabricating parameter details.

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 ('Get Homey storage usage breakdown') and lists the categories included, which separates it from get_memory_info and get_system_info reasonably well. It doesn't explicitly name those siblings, but the resource 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?

No guidance on when to call this versus get_memory_info, get_system_info, or get_backup_status, all of which sit in adjacent territory. The agent must infer from the resource name that this is for disk/storage diagnostics.

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 destructiveHint=false, so safety is covered; the description adds a genuine behavioral trait beyond that with the negative-space disclosure that network identifiers are not returned, which prevents wasted calls and wrong assumptions. It does not describe the return shape or the cost of the call, but for a zero-parameter snapshot read those gaps are small.

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

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

Two sentences, zero padding. The positive content list comes first and the exclusion list follows, so an agent that reads only the first clause already knows what it gets.

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 parameters and no output schema, the description must carry the return-value burden, and it does so by enumerating the returned fields and the notable fields that are absent. Nothing else is needed for a correct 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?

The tool takes no parameters, so the schema carries no semantics to compensate for; this hits the baseline of 4. The description spends its words on return contents instead, which is the right allocation here.

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

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

States a specific verb and resource (Get Homey system information) and enumerates the exact fields returned: version, model, time zone, uptime, memory/load, network connectivity. The explicit exclusion of SSID, MAC, IP, gateway, DNS, hostname and cloud id draws a clear boundary. It stops short of naming overlapping siblings like get_memory_info or get_storage_info, leaving the agent to infer which snapshot to pick.

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

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

Usage is only implied by the content list – the agent can infer 'call this for a general overview of the hub rather than a targeted metric'. There is no statement of when to use this versus get_memory_info, get_storage_info, get_location, or get_updates, all of which appear as siblings and overlap partially with the fields listed.

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 destructiveHint=false, so the safety profile is covered. The description adds that it surfaces both pending updates and current settings, but says nothing about whether the call performs an active check against the vendor, how fresh the result is, or what the response structure looks like.

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

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

A single front-loaded sentence naming the primary result first and the secondary settings detail in parentheses. No filler, nothing to trim.

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 read tool with annotations and no output schema, the description covers both what is checked and the shape of the settings returned. Only minor gaps remain (no hint about update-availability fields or whether a re-check is triggered), which is acceptable at this complexity.

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 baseline rule this scores 4. There is nothing parameter-related the description could or does add.

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

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

States a specific verb ('check') and resource ('Homey system updates and current update settings'), and even names the settings sub-fields (channel, auto-update). It is clearly distinct from siblings like reboot_homey or get_system_info, though it never explicitly says so.

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 purpose: call it when the user asks about update status or update configuration. There is no explicit when-to-use framing, no prerequisite (e.g. auth/owner permission), and no named alternative such as get_system_info for general version data.

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 readOnly, idempotent, non-destructive, and open-world, so the safety profile is covered. The description adds value beyond them by disclosing the concrete returned fields and clarifying that the location is Homey's own (implicit, not a parameter) — though it omits units, staleness/caching, and what happens on network failure.

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: behavior first, return payload second, no filler. Every clause carries information an agent 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?

With no output schema and no parameters, the description correctly compensates by listing the return fields, which is the main thing an agent cannot otherwise learn. Minor gaps remain: units for temperature/pressure/wind, and no pointer to the hourly sibling for forecast needs.

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. It does helpfully explain that the location is implicit rather than an argument the agent 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?

Specific verb+resource ('Get current weather conditions') plus an enumeration of the returned measurements, which is more than a restatement of the name. It loses a point because the sibling get_weather_hourly is not acknowledged, so the 'current' vs 'forecast' distinction is only inferable from the names.

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 'current weather conditions' implies a present-tense snapshot and implicitly excludes forecast use, but the description never names get_weather_hourly or states when to prefer it. No prerequisites or failure conditions 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 readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered by structured data. The description adds that results cover 'upcoming hours' and include temperature and conditions — with no output schema this is meaningful — but it omits the number of hours returned, units, and refresh/caching 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, front-loaded with the verb and resource. The second sentence partially restates the first ('forecast' vs 'returns ... for upcoming hours') but does add the returned fields, so it largely earns its place.

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

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

For a zero-parameter, open-world tool with no output schema, the description carries the burden of describing the return, and it does so only loosely (temperature and conditions, unspecified horizon and units). An agent can call it safely but cannot predict how far ahead the data extends.

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. It correctly implies the location is fixed to Homey's own location rather than being a call-site argument.

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 ('Get hourly weather forecast') and narrows the return to temperature and conditions for upcoming hours. It implicitly distinguishes itself from the sibling get_weather by emphasizing 'hourly' and 'upcoming hours', but never names that sibling, so the differentiation is left to inference.

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

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

Usage is only implied: 'hourly' and 'upcoming hours' suggest this is for a multi-hour forecast rather than a current-conditions snapshot. There is no explicit statement of when to prefer this over get_weather, and no preconditions 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 readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds value by naming the kinds of entries returned, but omits the recency window, entry count and whether the result is a snapshot. For a zero-parameter log fetch, that missing scope information matters.

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 with zero waste. The function and resource come first, followed by content and the diagnostic use case.

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 should explain what is returned, and it does so at the level of log categories. It falls short only on size and time window, which an agent would need in order to interpret the result.

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

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

The tool takes no parameters, so the baseline is 4. The description implies the log is preselected and unfiltered, which anchors the agent's expectation that no arguments can narrow the query.

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 (get recent Z-Wave network log entries) plus the log's contents: transmit failures, routing issues, network events. No sibling tool retrieves Z-Wave logs, so the agent can identify it immediately.

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?

'Essential for diagnosing Z-Wave device connectivity problems' gives a clear usage context. It does not name alternatives or say when not to use it, but no sibling covers this data, so the gap is minor.

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 destructiveHint=false, so the bar is lower. The description adds that returned records carry schedule and repetition days, which is useful return-shape context, but says nothing about ordering, whether disabled/past alarms are included, or volume/pagination for a full unfiltered list.

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 short sentence with no filler, front-loading the verb and resource and appending only the one piece of detail an agent needs (what fields come back).

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, so the description must carry return expectations; it names schedule and repetition days but omits what other alarm attributes come back and whether results are filtered or ordered. For a trivial zero-param list tool this is minimally adequate rather than complete.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain beyond confirming the unfiltered, no-argument nature implied by 'List all'. Baseline 4 for a 0-param tool.

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

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

Specific verb+resource ('List all alarms and timers') with additional scope detail on what each entry contains ('schedule and repetition days'). It is clearly distinguishable from the mutation siblings (set_alarm, delete_alarm), though it never names them.

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

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

Usage is only implied: an agent can infer this is the read path to pair with set_alarm/delete_alarm, but the description never states when to choose it, whether it's the only listing option, or any prerequisites. No exclusions or alternatives 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 establish readOnly/idempotent/non-destructive, so the description adds value by disclosing the return shape (version, enabled status, origin appstore vs devkit) and clarifying that origin distinguishes sideloaded from store apps. It omits behavior such as ordering or how disabled apps appear, so it is good but not fully 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?

Two tight sentences with the resource and returned fields front-loaded. The trailing sentence about drivers/flow cards/integrations is brief supporting context rather than padding.

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 params and no output schema, the description correctly compensates by enumerating the returned fields. Only minor gaps remain, such as result size/ordering, which are unlikely to change how an agent invokes this 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?

Zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-param tool applies. No misleading parameter language is present.

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

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

Specific verb+resource ("List all installed Homey apps") plus the exact fields returned (version, enabled status, origin), which clearly separates it from mutating siblings like enable_app, restart_app, and uninstall_app. It stops short of naming those siblings explicitly, so it is clear but not fully differentiated in text.

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 can infer this is the discovery step before enable_app/restart_app/uninstall_app, but the description never states when to call it or what the alternatives are. No exclusions, prerequisites, or follow-up guidance 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 readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by enumerating the returned fields (ID, name, class, zone, availability, capabilities, live values) and clarifying that filtering is partial-match rather than exact.

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

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

Three tight sentences: purpose first, return shape second, filtering third. No filler, no repetition, and the most useful information is 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?

With no output schema, the description carries the burden of describing the return payload and does so adequately with a field enumeration. Minor gaps remain around volume (how many devices can be returned) and behavior when a filter matches nothing.

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%, so both parameters are already documented with identical examples. The description restates the same partial-match and class-example semantics rather than adding new meaning such as case sensitivity or fallback behavior when no match occurs.

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

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

States a specific verb and resource ('List all Homey devices') plus what data comes back (capability values). It does not name the closest sibling, search_devices, so the boundary between a full listing and a search is left for the agent to infer.

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

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

Explains how to use both filter parameters with concrete examples, which implies the read-all-then-filter workflow. However, there is no guidance on when to prefer search_devices or get_device instead, and no stated exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds only that it shows driver readiness, with no further behavioral detail such as return shape or whether disabled drivers appear.

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 core action and resource. Every clause adds information 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?

For a zero-parameter read-only tool with annotations covering safety, the description gives enough to call it correctly. A minor gap is that it does not say what fields each driver entry returns or whether the output is paginated.

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 for a parameterless tool.

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

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

States a specific verb and resource ('List all available device drivers') and disambiguates the term with '(protocol integrations)'. It does not explicitly differentiate itself from sibling list tools such as list_devices or list_apps, so it falls 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 phrase 'Useful for troubleshooting — shows which drivers are ready' implies a usage context, but it gives no explicit when-to-use vs when-not-to-use guidance and names no alternatives. An agent must infer the selection criteria from sibling names.

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 readOnly/idempotent/non-destructive, so the safety bar is low. The description still earns credit by disclosing the exact return fields (flow ID, name, enabled/broken status, type), which matters because there is no 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?

Three short sentences, front-loaded with the verb+resource and the return shape, with no filler. Each sentence contributes either scope, output fields, or domain grounding.

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 no-param, read-only list tool with no output schema, the description covers what it returns and what flows are. It falls short only on routing guidance relative to the flow-related siblings.

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

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

Zero parameters, so the baseline is 4; nothing is required of the description here and it correctly avoids inventing filter options. The noted scope 'simple and advanced' adds a small amount of semantic framing.

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

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

States a specific verb and resource ('List all automation flows') and adds a clear scope qualifier ('simple and advanced'). It does not, however, distinguish itself from sibling readers like get_flow or audit_flows, which an agent must choose between.

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?

Listing implies a discovery/enumeration use case, but the description never says when to prefer this over get_flow (single-flow detail) or audit_flows (health check). 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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations by listing the returned fields and explaining the intended follow-up call, though it does not mention pagination or ordering.

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 with no waste. Purpose is front-loaded, followed by return fields and the next-step integration hint.

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, read-only listing tool with annotations covering safety and no output schema, the description supplies the essential return shape and relationship to get_insight_entries. Nothing needed for correct invocation appears to be missing.

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

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

The tool has zero parameters, so parameter semantics receive the baseline 4. The description correctly does not invent parameter details.

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 uses a specific verb ('List') and resource ('insight logs'), with concrete examples ('sensor history, energy meters, etc'). It clearly distinguishes this discovery tool from the related retrieval tool by saying the returned log ID is used with get_insight_entries.

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: list logs first, then pass the log ID to get_insight_entries to retrieve historical data. The alternative is named explicitly, though there is no explicit 'do not use this for entries' exclusion, so it falls short of a full 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 readOnlyHint/idempotentHint/destructiveHint, so the safety profile is covered. The description contributes real domain context by explaining that a mood stores device states that are activated together, but says nothing about return shape, ordering, or whether zones affect grouping — which matters given the odd 'per zone' claim.

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

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

Two tight sentences with the core purpose front-loaded and the domain explanation in parentheses where it belongs. Nothing 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 output schema and no parameters, the description supplies enough concept-level grounding to invoke the tool correctly. The only soft spot is 'per zone', which hints at a grouping behavior the agent cannot verify or control.

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

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

Zero parameters, so the schema carries no burden and the baseline of 4 applies. The description's mention of 'per zone' neither introduces nor explains any parameter, so it neither helps nor hurts.

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 ('List all moods') and adds a clarifying gloss that moods are scenes/presets — useful since the term is domain-specific. It does not explicitly distinguish itself from the sibling set_mood, and the phrase 'per zone' is slightly puzzling for a tool that accepts no zone 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?

Usage is implied by the read-only naming ('List'), and the sibling set_mood would be the natural activation counterpart, but the description never says when to call this versus set_mood or list_zones. An agent must infer the routing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral facts: results are capped at 50, sorted newest first, with no pagination — telling an agent its view is truncated and how it is ordered.

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. The cap and content types come first, ordering second — exactly the information an agent needs, 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?

For a zero-param read tool with no output schema, it covers what is returned, how many items, and in what order. The only gap is how to obtain notifications older than the 50 shown, which is left unstated.

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 applies. The description correctly avoids inventing filters that the empty schema would not accept.

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

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

States a specific verb (List) and resource (Homey notifications), and adds concrete content examples (app updates, alerts, system messages) that tell an agent what data to expect. It is easily separable from create_notification, though it never explicitly contrasts with 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 by the verb 'List' — there is no statement of when to reach for this versus checking insights, flows, or alarms, and no note that it cannot retrieve older items beyond the 50 most recent. Adequate for an obvious read tool, but no explicit 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?

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the description's added value is the return shape: id, name, version, and last execution time. That is a concrete behavioral disclosure not present in any structured field, since there is no output schema. Pagination or ordering behavior is not stated, keeping it below a 5.

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

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

Three short sentences, front-loaded with purpose and return fields. The third sentence about what HomeyScript is adds mild domain context but is not strictly needed to invoke the tool, so it is a small amount of filler rather than 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?

With no parameters and no output schema, the description carries the burden of telling the agent what comes back, and it does so by listing the four returned fields. The remaining gap is that it says nothing about ordering, volume, or whether all scripts are always returned, which matters slightly for a 'list all' 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline of 4 applies; the description correctly makes no attempt to invent input semantics.

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 first sentence gives a specific verb and resource ('List all HomeyScript scripts'), which is enough to separate it from get_script, run_script, and upsert_script by name alone. It does not explicitly contrast itself with those siblings, and the third sentence is background about HomeyScript rather than a scoping statement.

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 explicit when-to-use or when-not-to-use guidance is given; with a parameterless listing tool the usage is strongly implied (enumerate scripts before get_script/run_script). The description never names an alternative or a condition that would select one, leaving the agent to infer.

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 non-destructive, so safety is covered. The description adds real context beyond them: that the response includes current values and that values are typed as boolean, number, or string — useful given there is no 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?

Two short sentences with the action front-loaded, followed by the minimum domain context needed to interpret results. No filler, though the second sentence is educational rather than operational.

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 read tool with full annotation coverage and no output schema, the description is sufficient: it says what is listed, what is returned, and what the values mean. Only ordering or whether unused variables are included is left unstated, which is minor.

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; nothing in the description misleads 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?

States a specific verb (list) and resource (logic variables) plus what is returned (current values). It is clearly distinguishable from set_variable by verb, but does not name the sibling or scope the listing (e.g., all variables vs. those in use).

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 usage is implied by 'List all ... ' and the note that variables are used in flow conditions/actions, which hints at why an agent would fetch them. There is no explicit when-to-use, no prerequisites, and no stated alternative (e.g., set_variable for mutation).

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 destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that: the return fields (zone ID, name, parent zone, icon) and the Home → Floors → Rooms tree structure, which tells the agent to expect a nested/hierarchical result set rather than a flat list.

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 resource, followed by return fields and hierarchy. Every sentence contributes new information and none restates the title or annotations.

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 read tool with no output schema, the description supplies exactly what's missing: the return fields and the hierarchical structure of the data. Nothing an agent needs in order to call it or interpret the response is absent.

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 correctly makes no parameter claims and instead spends its words on the return shape, which is the only semantic load a zero-arg tool can carry.

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 and resource ('List all zones (rooms/areas) in the home') and immediately clarifies the domain term with a plain-language gloss. It also states what the result contains and how zones relate, so an agent can distinguish it from siblings like list_devices or list_moods without opening any schema.

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

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

Usage is only implied: the tool lists everything and takes no parameters, so when to call it is fairly self-evident. However, it names no alternatives or exclusions (e.g., how to use the returned zone IDs elsewhere, or when search_devices would be the better entry point), leaving routing to inference.

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 flag this as destructive and non-idempotent, so the description's job is to add context — and it does, disclosing the 2-3 minute downtime before the hub is back online. It stops short of saying that in-flight flows and automations are interrupted, which is the main operational side effect.

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 with the action first, then the downtime cost, then the use case — the highest-value information is front-loaded and nothing is padded.

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

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

For a no-parameter action whose annotations carry the risk profile, the description covers purpose, latency, and motivation. The only meaningful omission is confirming that running flows/automations will be interrupted during the reboot.

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

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

Zero parameters, so there is no parameter semantics to document and the baseline of 4 applies. Nothing in the description conflicts with or unnecessarily restates 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 ("Reboot the Homey Pro"), which is the whole hub rather than a single app, distinguishing it from sibling restart_app. The scope is unambiguous even though restart_app is not named 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?

Gives a concrete trigger condition: resolving stale devices or Z-Wave/Zigbee mesh issues after firmware updates. It does not state when *not* to use it (e.g. preferring restart_app for a single misbehaving app), so it falls short of the explicit alternatives-and-exclusions bar.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds the symptom context for when a restart helps, but does not disclose side effects such as interrupted flows, brief device unavailability, or the response shape. Reasonable given annotation coverage, but not rich.

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, purpose front-loaded, followed by the motivating symptom and the dependency for obtaining the ID. No wasted text.

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 single-parameter action with annotations covering safety and a fully documented schema, the description supplies the missing decision context (symptom, ID source). Only minor gaps remain, such as side effects on running flows or app state after restart.

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 already includes the pattern and example IDs, so the parameter is fully documented structurally. The description's example ('com.fibaro') and list_apps pointer duplicate or only lightly extend the schema, so 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?

States a specific verb and resource ('Restart a Homey app') and is clearly distinguishable from siblings such as enable_app, uninstall_app, and reboot_homey. An agent can select it 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 a concrete trigger ('useful when devices from that app are unresponsive') and routes the agent to list_apps to obtain the ID. It stops short of explicit exclusions (e.g., when to prefer reboot_homey over an app restart), so it is clear but not fully comparative.

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 already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=true, so the safety profile is clear. The description adds useful return-shape details, including failure structure, but does not elaborate on what arbitrary script execution may affect or any permission requirements.

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

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

Two tightly written sentences with no waste. The purpose is front-loaded and the return contract follows immediately.

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, but the description compensates by explaining the success and failure return shapes. Combined with the schema and destructive annotation, an agent has enough to invoke it correctly, though more context on side effects would improve completeness.

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 both parameters are documented in the schema. The description adds no additional parameter meaning beyond what the schema already provides, so the baseline of 3 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 and resource: 'Execute a stored HomeyScript and return its result.' This clearly distinguishes it from sibling tools like list_scripts, get_script, upsert_script, and delete_script.

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 purpose implies when to use it, but there is no explicit guidance on when to choose this over alternatives such as trigger_flow or get_script. No prerequisites or exclusions are stated.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds that results include current values, which is useful given no output schema. It does not disclose matching semantics (substring vs exact, case sensitivity) or any result cap, which is the main behavioral unknown for a search 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?

Three short sentences, front-loaded with the searchable fields, then the return shape, then the motivating example. No filler, though the example sentence is somewhat longer than strictly necessary.

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?

It is a single-parameter read tool, so the bar is moderate, and it does the basics: what it matches on and what comes back. It leaves out matching semantics and result limits, which matter for an agent deciding whether a search is exhaustive.

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 and the schema already documents the matching targets. The 'temperature'/'kitchen' examples add illustrative value but do not clarify matching mode (substring, case-insensitive, multi-word) beyond what the schema states.

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 ("Search devices") and enumerates the searchable fields (name, device class, capability name), which separates it from a plain enumeration tool. It does not explicitly name list_devices or get_device as alternatives, so sibling differentiation is implied rather than stated.

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

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

"Useful for finding devices when you don't know the exact ID" gives a clear usage condition, and the 'temperature'/'kitchen' examples make the intent concrete. It stops short of explicitly routing the agent to list_devices for full enumeration or get_device for known IDs.

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 a non-readonly, non-idempotent, non-destructive mutation, and the description adds the time format. However, it does not explain update behavior, whether updates overwrite fields, timezone handling, or other side effects beyond the annotations.

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 two tight sentences with no wasted language, and the core action is front-loaded before the format details.

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 rich schema, annotations, and lack of an output schema, the description covers the essential action and format. It could be fuller about create-vs-update usage and update side effects, but the schema fills most parameter gaps.

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%, so the schema already documents all parameters including id semantics, defaults, and the repetition object. The description restates the time format and optional repeat days but adds little beyond 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 states a clear verb and resource: create/update an alarm. It is distinguishable from siblings like list_alarms and delete_alarm by the action, but it does not explicitly name alternatives or scope boundaries.

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 usage is implied by 'Create a new alarm or update an existing one,' but there is no explicit guidance on when to prefer this over list_alarms or delete_alarm, nor any exclusions or prerequisites.

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 only declare the mutability profile (readOnly=false, idempotent=true, destructive=false). The description adds genuine behavioral context beyond that: the value is validated against the capability definition with type, min/max and enum enforcement, and a whole class of capabilities is refused under a server flag. These are failure modes an agent needs before invoking.

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

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

Front-loaded with the core action, then capability examples, then the prerequisite, then the validation and security rules — a sensible order. The capability enumeration is slightly list-heavy, but each item carries distinct type/range information rather than 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 3-required-param mutation tool with no output schema, the description covers discovery, validation rules, failure/refusal conditions and type expectations. It does not state what a successful call returns or confirms, which is a minor gap given no output schema exists.

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 baseline would be 3; the description earns above baseline by enumerating capability IDs with their value types and ranges ('dim' number 0-1, 'onoff' boolean, 'target_temperature' setpoint, 'volume_set' 0-1), which the schema only gestures at with 'type depends on capability'. It does not explain deviceId format, but the schema's UUID pattern covers that.

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: 'Control a device by setting a capability value', which is unambiguous against siblings like get_device, list_devices, search_devices, set_variable or set_mood. The description makes clear it acts on a device capability rather than a system-level setting, so an agent can route correctly 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?

Explicitly says to call get_device first to discover available capabilities and current values, which is a concrete prerequisite step. It also states exclusion conditions (security-related capabilities such as locks, garage doors and alarms are refused unless HOMEY_MCP_ALLOW_SECURITY_CAPS=1), giving the agent a clear when-not-to-use signal.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=true. The description adds useful behavioral context by stating that disabled flows will not trigger, but it does not explain reversibility, permissions, or the destructive implication of disabling a flow.

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 short, front-loaded, and every sentence contributes useful information. It states the action, the effect of disabling, and how to obtain the required ID.

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

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

For a simple two-parameter toggle with full schema coverage and annotations, the description is largely complete. A minor gap is that it does not describe side effects beyond trigger suppression or whether disabling affects currently running flows.

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 schema already documents both parameters, including that id is the flow ID and enabled is a boolean toggle. The description adds only the practical note that the ID can be found via list_flows.

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

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

The description gives a specific verb and resource: enabling or disabling a flow automation. It clearly distinguishes the operation from siblings such as trigger_flow, get_flow, and list_flows.

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 provides clear usage context by stating that list_flows should be used to find the flow ID. It does not explicitly explain when to choose this over trigger_flow or get_flow, but the enable/disable framing is clear.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, so safety and repeat-call behavior are covered structurally. The description adds only the value-validation pointer to get_ledring; it does not say what happens on an invalid screensaverId or whether the change is immediate/persistent.

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 action statement is front-loaded ahead of the discovery hint.

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 single-parameter, non-destructive settable tool with full schema coverage and annotations, the description gives everything needed to invoke it correctly. Only failure behavior for an invalid ID is 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?

Schema coverage is 100%, so the single screensaverId parameter is fully documented. The description's examples ('spectrum', 'off') duplicate the schema's own examples and add no syntax or format meaning beyond it.

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

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

States a specific verb and resource ('Set the LED ring screensaver animation') and explicitly names the sibling reader (get_ledring), so an agent can distinguish it from get_ledring 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 get_ledring to discover valid values before calling, which is the key usage precondition. No explicit exclusions or failure-handling guidance, which keeps it below 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 and non-destructive, and the description adds real context beyond that: the mood is scoped to a zone and it overwrites all devices in the mood with their saved states. It stops short of saying what happens to devices not in the mood or on partial failure, so not a full 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?

Two tight sentences with the action first and the consequence second; no filler, nothing repeated from 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 two-parameter idempotent setter with full annotations, the description covers what the tool does and what changes as a result. Only edge-case behavior (partial application, devices outside the mood) is left unspecified, which is minor here.

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% with both parameters documented (Mood ID, Zone ID), so the baseline is 3. The description contributes the relationship between the two parameters — a mood is applied within a given zone — but no format or lookup guidance beyond the schema's UUID pattern.

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 ('Activate a mood (scene) in a zone') and clarifies the effect, so an agent knows this is a state-applying operation rather than a read like list_moods. It does not explicitly differentiate itself from other setters such as set_device_capability, leaving the sibling boundary to be inferred.

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

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

No when-to-use or when-not-to-use guidance; nothing tells the agent to look up a mood via list_moods or to prefer this over setting device capabilities individually. The only implicit cue is that both zoneId and moodId are required.

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-destructive, idempotent mutation, so safety is covered. The description adds real value with the side-effect note that it 'affects presence-based automations,' but it omits whether both parameters can be set at once, or what happens to a state that is omitted — important for an optional-two-parameter mutation.

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 action and value domain, with the consequence note second. Nothing is wasted or 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?

For a simple two-optional-boolean setter with no output schema, the description plus annotations and schema give an agent enough to call it correctly. The only meaningful gap is the behavior when one or both optional parameters are omitted.

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% and both boolean parameters already carry inline descriptions (true = home, false = away; true = asleep, false = awake). The description restates the same domain without adding syntax or interaction rules, 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?

States a specific verb (set) and resource (your own presence / sleep state), and parenthetically enumerates the value domain (home/away, awake/asleep). It is clearly distinct from the read-only sibling get_presence, though it never names that sibling 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?

Usage is implied: use this to change your own state rather than read it. However, it never says when to use this instead of get_presence, nor whether it applies only to the calling user versus other people or devices.

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, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds a genuine side effect the annotations don't: the name propagates to network discovery and the app. It omits whether admin/owner permission is required or whether the change briefly disrupts connectivity, so the addition is real but 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?

One sentence, front-loaded with the verb and resource, and the qualifier about visibility is tucked into a parenthetical. No wasted words.

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?

A low-complexity, single-parameter setter with full schema coverage and safety annotations needs little prose, and this covers the essential what and where-visible. It could add permission prerequisites and name constraints to be fully complete.

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

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

There is a single required parameter with 100% schema description coverage ('New system name'), so the schema carries the meaning. The description adds no constraints such as length limits, allowed characters, or uniqueness rules, so 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?

States a specific verb+resource: set the Homey system name. It also clarifies what the name affects (network discovery and the Homey app), which makes it distinguishable from read-only siblings like get_system_info or reboot_homey. No sibling is named explicitly, so it stops short of a 5.

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

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

The parenthetical about where the name is visible implies the use case (renaming the hub in discovery/app) but there is no explicit when-to-use, prerequisites, or guidance separating it from adjacent system tools. Usage is inferable rather than stated.

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

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

The annotations already disclose that this mutates state yet is idempotent and non-destructive, so the safety profile is covered. The description adds the meaningful behavioral constraint that the value type must match the variable's declared type, but says nothing about what happens on a type mismatch (error? coercion?) or on a nonexistent ID.

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 action and then the one non-obvious constraint. Slight redundancy with the schema's parameter description keeps it from being a perfect score, but nothing is wasted.

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

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

For a two-parameter mutation with full schema coverage and annotations carrying the safety profile, this is adequate: the agent knows what it does and the type rule. It is missing error behavior, whether a variable must pre-exist, and whether the new value takes effect immediately for running flows.

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 both 'id' (with UUID pattern) and 'value' are already documented, and the schema itself states 'must match variable type'. The description largely restates that constraint, adding only the enumeration of allowed types, which the schema's type union 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 ('Set') and resource ('value of a logic variable'), making it clearly distinct from the sibling list_variables, which reads rather than writes. It does not explicitly name the sibling or state the scope of variables it applies to, 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?

There is no guidance on when to use this versus alternatives, no prerequisite that the variable must already exist, and no mention of how to discover valid IDs (presumably via list_variables). The only constraint given is a type rule, which is about parameters, not usage context.

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?

Adds genuinely non-obvious internal behavior -- the simple-flow-then-advanced-flow fallback -- which the annotations cannot express. However, for a tool flagged destructiveHint=true and idempotentHint=false, the description never warns that running a flow executes real automations with side effects and is not repeat-safe; that disclosure is left entirely to annotations.

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, action stated first, fallback behavior second, prerequisite lookup last -- well ordered and free of filler. Not quite a 5 only because the fallback sentence could note what happens if both attempts fail.

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

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

There is no output schema, so the agent gets no information about what a trigger returns (run status, success/failure indication) or what happens when neither the simple nor advanced flow matches. The mutation semantics are covered only by annotations, leaving the description adequate but with meaningful gaps for an execution 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?

Only one parameter, and the schema already documents it at 100% coverage (including the UUID pattern). The phrase 'by its ID' in the description plus the pointer to list_flows adds a little practical meaning about where the value comes from, but no format or constraint detail beyond 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?

States a specific verb ('Trigger (run)') plus resource ('a flow') plus the identifier used, and is clearly distinguishable from siblings like get_flow or list_flows. An agent can tell immediately what this does without opening the schema.

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

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

Explicitly routes the agent to list_flows to obtain the required ID, which is real usage guidance rather than none. It does not say when NOT to use it (e.g., disabled flows, or preferring run_script for scripts), 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description still earns credit by specifying the collateral damage (all its devices) and irreversibility, which the annotations do not convey.

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 destructive effect and irreversibility front-loaded. Every clause carries information and there is no padding.

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 single-parameter destructive tool with rich annotations, the description covers the essential facts: what is removed, what is lost, and that it cannot be undone. Nothing an agent needs in order to invoke it correctly is missing.

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

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

Only one parameter, and the schema already describes it at 100% coverage as the App ID. The description adds nothing about the id format or constraints, so this sits at the baseline.

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 (uninstall) and resource (Homey app), plus the scope of collateral effect (removes all its devices). This clearly distinguishes it from siblings like restart_app, enable_app, and list_apps.

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 permanence warning implies this is a last-resort operation, but the description never names alternatives such as restart_app or enable_app, nor states when not to use it. Usage is implied rather than guided.

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

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

Annotations already declare `readOnlyHint=false`, `idempotentHint=false`, and `destructiveHint=true`; the description aligns by explicitly saying it can overwrite an existing script. It adds useful behavioral context about the sandbox, the global `Homey` API, `log()`, and returning values to the calling flow, though it does not elaborate on overwrite consequences beyond the annotation.

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, all front-loaded and information-dense: create/update distinction, `id` behavior, and runtime environment. No sentence is 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 three-parameter mutation tool with full schema coverage and annotations covering safety traits, the description is complete enough: it explains create vs update, server UUID assignment, code execution context, and return values. No output schema exists, but return behavior is addressed in the description.

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 schema already documents all three parameters. The description adds meaning beyond the schema by explaining the server-assigned UUID behavior for omitted `id` and the execution environment for `code`, including return-value propagation.

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 and resource: create a new HomeyScript or overwrite an existing one. It also distinguishes create vs update by explaining the `id` parameter, so an agent can differentiate it from `list_scripts`, `get_script`, `run_script`, and `delete_script` without opening schemas.

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

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

It gives clear conditional guidance: pass `id` to update an existing script, omit `id` to create a new one. It does not explicitly mention when to use `run_script` or other alternatives, but for this upsert operation the usage condition is unambiguous.

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