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

The description discloses several non-obvious behaviors: the flow is created switched OFF, placed in the 'AI' folder, and read back/compared after creation. It also explains that labels are replaced with real generated ids and references are rewritten, going beyond what the annotations (all false) or schema reveal.

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 dense but every sentence delivers important information: graph model, labeling behavior, token syntax, standard-flow difference, and creation side effects. No filler or redundancy.

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 complex graph-creation tool, the description covers the core model, label/token mechanics, and post-creation verification, and the schema thoroughly documents card fields. However, since there is no output schema, a brief mention of what the tool returns (e.g. the created flow or comparison result) would make it 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?

The schema covers 100% of parameters, so the baseline is 3; the description adds extra meaning by explaining how to reference card outputs with the advanced-flow token syntax and clarifying that card labels are placeholders replaced by real ids. This is meaningful guidance beyond the raw schema, though much of the card structure is already documented in 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 clearly states it creates an advanced Homey flow and distinguishes it from a standard flow by defining it as a graph of cards with branches, parallel paths, joins, delays, and error handlers. The title and description use a specific verb (create) and resource (advanced flow), making it distinct from sibling homey_flow_create.

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

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

It implies when to use this tool by contrasting advanced flows with standard flows and explicitly noting that the [[owner|token]] syntax from standard flows will not work here. It does not name the sibling tool homey_flow_create directly, but the distinction is clear enough for an agent to choose between them.

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 description goes well beyond the annotations by disclosing the destructive replace-all semantics, the label-to-real-id rewriting, and the ethical constraint that enabling an off flow requires owner confirmation. This gives the agent a clear model of side effects that the schema and annotations alone do not fully 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?

The description is dense but not wasteful; every sentence contributes essential information about advanced flow semantics, syntax, replacement behavior, or confirmation requirements. It could have been slightly easier to scan with bullets, but it is appropriately sized for the complexity of the tool.

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

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

Given the tool's complexity and the rich input schema, the description is remarkably complete: it explains the graph model, token references, replace semantics, prerequisite reading, and confirmation requirements. No output schema exists, but the description does not need to explain return values because the critical invocation context is fully covered.

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?

Even though schema coverage is 100%, the description adds crucial cross-parameter semantics: card labels are user-provided keys replaced by real ids, token references use [[trigger::label::token]] syntax, and confirmEnable is not just a flag but a deliberate owner-approval step. This meaningfully clarifies how the cards array and confirmation parameters interact.

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 title and description clearly state this tool changes a Homey advanced flow, and the description explains that an advanced flow is a graph of cards rather than a simple trigger/action list. It also distinguishes the advanced flow syntax from standard flow syntax, so an agent can tell this apart from homey_flow_update or homey_advancedflow_create.

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 guidance on when to use the tool: it says to read the current flow with homey_flow_get first, warns that the whole graph is replaced, and explains when confirm and confirmEnable are needed. It does not explicitly name homey_flow_update as the standard-flow alternative, but the advanced-flow framing and token syntax warning effectively imply the distinction.

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 and idempotentHint=true, so the safety profile is covered. The description adds valuable context: it does not ask for a password/token and never handles one, the user signs in via Athom directly, and the tool picks up the result. It also explains what to do if sign-in fails: read instructions verbatim. This goes beyond annotations by explaining the authentication mechanism and fallback, but doesn't fully describe error states or side effects beyond what's mentioned. No contradiction with annotations (idempotent and read-only are consistent with 'confirms that it already 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?

The description is a single paragraph with no wasted words. Each sentence adds value: purpose, when to call, session expiry, no credential handling, and failure instructions. It's front-loaded with the primary purpose first. One minor issue: the sentence 'It does not ask for a password or a token and never handles one' could be combined with the following, but overall it's efficient and well-structured.

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 simplicity (0 params, no output schema, clear annotations), the description is complete. It covers the purpose, usage trigger, session behavior, credential handling, and failure procedure. It doesn't explain the return format (no output schema), but that's not necessary for an auth tool—the agent just needs to know success/failure. It also doesn't elaborate on the exact routes after 24 hours, but it references the instructions returned on failure, which is sufficient. Slight room for improvement: could mention what the typical response looks like (e.g., a success confirmation), but not critical.

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, and the schema is empty (100% coverage because there are no params). The description clearly states that no password or token is handled, which is essential for the agent to understand that no parameters are needed. It explains the authentication flow without needing parameter details. Baseline for 0 params is 4, and the description exceeds that by explaining why there are no parameters (user signs in directly via Athom).

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 explicitly states the tool's purpose: 'Signs this server in to the Homey, or confirms that it already is.' It uses a specific verb ('Signs in') with a clear resource ('this server' and 'Homey'). It also distinguishes from sibling tools by being the authentication entry point, while siblings are operations like flow/script management, device control, etc. The description clearly establishes this is an authentication tool, which none of the siblings are.

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?

Provides explicit when-to-use guidance: 'Call this when any other tool reports that the server is not signed in.' It also explains when not to use (or when it's needed): 'A Homey session lasts 24 hours, so a server that has been running for a day needs this rather than a restart.' This gives clear context for the agent to invoke it appropriately, and no alternatives are needed since it's a unique auth tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so the description's job is to add context. It explains parameter flexibility (device id or name), the logId linkage to insights, and the unit/range nuance for capabilities. This adds useful behavioral detail beyond the annotations, though it could mention that it returns a single device object (implied).

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, each packed with relevant information—return contents, linkage to other tools, and practical warning about fractional values. No filler words, front-loaded with the core purpose, and tightly structured.

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

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

For a read-only tool with no output schema, the description provides a thorough preview of the response (capabilities, values, range, energy, logs) and how it connects to related tools. It covers parameter usage and a unique data nuance, making it complete for agent decision-making.

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 described. The description adds that the two parameters are interchangeable ('Send either one'), which clarifies their relationship beyond the schema. It also reiterates the accepted forms. This adds marginal value but does not significantly enhance understanding 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 specific action: fetching full detail for a single device, listing exactly what is returned (capabilities, values, range, energy block, Insights logs). It clearly distinguishes from siblings like homey_devices_search (search) and homey_device_set_capability (set).

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?

Provides explicit guidance on when to use this tool: before calling homey_device_set_capability to read min/max, and as the route to device history via homey_insights_query. It does not explicitly state when not to use it, but the context is clear from the alternative tool names. The guidance is actionable and specific.

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 far beyond the annotations (readOnlyHint:false, destructiveHint:true, idempotentHint:true) by disclosing the percentage vs. fraction trap for specific capabilities, the clamping behavior with reporting, and the physical impact of the operation. This enriches the agent's understanding of side effects well beyond what structured fields 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?

Approximately 100 words arranged in front-loaded fashion, leading with the core purpose and following with important caveats. Each sentence carries distinct weight — physical impact, unit warnings, clamping, and preconditions — though the collection of caveats could arguably be tightened.

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?

Comprehensively covers purpose, safety, input semantics, and preconditions for a mutating tool without an output schema. It addresses a complex real-world domain (Homey device capabilities) well, though it leaves the exact return value on success implied rather than explicit.

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%, meeting the baseline of 3. The description meaningfully elevates this by documenting the crucial value-format gotcha (dim takes 0.6 not 60) that the schema's generic 'number/boolean/string' type union cannot express. Though it misses a complete return-value contract, it adds significant value for the trickiest parameter.

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

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

The description uses a precise verb+resource structure: 'Changes one capability of one device', providing concrete examples (onoff, dim, target_temperature). This unambiguously distinguishes the tool from siblings like homey_device_get (read) and homey_variable_set (variables), making its purpose immediately clear.

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 names an alternative tool and the condition for its use: 'Call homey_device_get first when unsure of a range or of which capabilities can be set.' It also warns about physical consequences, implicitly covering when-not-to-use by advising caution. This is exemplary usage 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds valuable behavioral context: the API cannot paginate, so paging happens here (offset/limit and `truncated`), and results are projected down to omit protocol settings/icons/images/interface layout for reasoning efficiency. This goes beyond the annotations and gives the agent useful operational expectations.

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 concise (three sentences) and front-loaded with the core purpose. Every sentence adds value: the first covers function and filters, the second provides a concrete use case and the AND semantics, the third explains paging and result projection. No fluff or repetition.

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 has 9 parameters, no output schema, and rich annotations. The description covers the key nuances: AND combination of filters, result projection, paging behavior (since the API can't paginate), and the use of includeCapabilitySummaries. It also cross-references sibling tools (homey_device_get, homey_home_overview). While it lacks explicit details about the output structure, given that the output schema is absent and the description clearly explains the key behavioral aspects, this is near complete for typical use.

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 baseline is 3. The description adds extra meaning beyond the schema: it explains that all filters are combined with AND, gives usage examples ('what is the state of the living room'), and clarifies the projection behavior. This enhances parameter understanding, especially that includeCapabilitySummaries fills a specific field and points to homey_device_get for full records. The 'Projected' note adds context on what parameters do not control.

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

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

The description clearly states what the tool does: 'Finds devices by zone, class, capability or name' and mentions returning live values optionally. It distinguishes from siblings by explicitly referencing the alternative `search_calls_extensive` and other device-related tools (homey_device_get), and clarifies scope (no user/workspace filtering). The verb 'Finds' and resource 'devices' make the purpose 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?

Provides explicit guidance on when to use it: 'Set includeCapabilitySummaries to answer a question like "what is the state of the living room" in one call.' It also explains when not to use it and alternatives: 'For the full record of one capability, with its type, decimals and allowed range, call homey_device_get instead.' Mentions paging behavior and cross-reference to homey_home_overview for zone tree. This is explicit and actionable.

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?

Beyond the readOnlyHint/idempotent annotations, the description discloses important behavior: no credential is ever exposed, output is safe for public issues because it redacts names/addresses/IDs/paths, and each check provides a next step. It also clarifies the role of CLI auth in flow creation.

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 dense and packed with useful specifics, but it is structured as one long run-on paragraph. Every clause adds value, so it is not wasteful, yet front-loading with short labeled sections would improve scannability.

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 there is no output schema, the description thoroughly covers what the tool reports, why it is safe to share, when to use it, and what each check includes. It satisfies the diagnostic use case without leaving major 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?

The main description does not address the two parameters, but the input schema already describes both with 100% coverage, including defaults and cost implications. The description adds no parameter-level meaning, so the schema-based 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 uses a specific verb ('Reports') and identifies a clear resource scope ('what is and is not working between this server and your Homey'). It also distinguishes itself from the sibling tools by framing itself as the diagnostic entry point before reporting problems.

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 explicit usage timing: 'Call this when another Homey tool fails, or before reporting a problem.' It also names a concrete alternative, the terminal command 'npx homey-mcp doctor', for the version that includes more detail.

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, destructiveHint=false, so the safety profile is caught. The description adds value by noting 'Instantaneous only' and explaining what data is returned (breakdown, unattributed load), plus the hardware limitation. This goes beyond mere read-only flags, though not exhaustive on response format since no output schema exists.

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

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

The description is two sentences, front-loaded with the core purpose. The first sentence is concise; the second adds necessary context about history and device limitations. Slightly dense but no wasted words, earns a solid 4.

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

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

For a read-only tool with 2 parameters and no output schema, the description explains what it returns (watts, breakdowns, unattributed load), clarifies the instantaneous nature, offers alternative history tools with specific guidance, and mentions a hardware-specific caveat. This is complete for an agent to decide when to use it.

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 schema covers both parameters completely with descriptions (limit, includeItems). The description does not add parameter-specific details beyond what the schema already provides, so it relies on the schema. This meets the baseline for high schema coverage.

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

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

The description clearly states it reads current power draw in watts with a room/device breakdown, whole-home meter, and unattributed load. It distinguishes itself from the historical query tool by specifying 'Instantaneous only' and naming the alternative, so purpose is unambiguous.

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

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

Explicitly states when to use this tool versus alternatives: 'for history use homey_insights_query' with specific log types (meter_power vs measure_power). It also warns about Homey Pro (Early 2019) lacking historical endpoints, providing clear 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?

Annotations already declare the operation as read-only, idempotent, and non-destructive. The description adds meaningful behavior beyond that: returned objects contain app-specific fields next to id/name, and manually rebuilding the object loses those fields and breaks the card. This is valuable contextual warning, 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?

The description is three sentences with no filler. The primary action is front-loaded, and the two follow-up sentences deliver a critical caveat about object preservation. Every sentence earns its place.

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

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

For a tool with six parameters, rich annotations, and no output schema, the description is sufficiently complete. It explains what the tool returns, that results are structured objects with app-specific fields, and how the agent must consume them. Combined with the full schema coverage, an agent has enough context to invoke the tool correctly.

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

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

The input schema already provides descriptions for all six parameters (100% coverage), so the baseline is 3. The description focuses on the result object and storage semantics rather than adding per-parameter syntax or formatting details beyond what the schema already provides.

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

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

The description clearly states the tool's function: it asks Homey what a device-typed or autocomplete-typed argument can be set to and returns choices. It distinguishes itself from sibling inspection tools like homey_flowcard_describe and homey_flowcards_search by focusing on resolving argument values rather than describing cards.

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 provides clear context for when to use the tool—to resolve autocomplete arguments—and gives a strong usage directive: store the whole returned object as the argument value. It does not explicitly name alternatives or exclusion conditions, but the context is sufficient for an agent to choose it appropriately.

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, destructiveHint=false, and the description adds meaningful behavioral details beyond that. It clarifies the output structure ('arguments is the schema, args is what you fill in') and warns about the failure mode ('Guessing an argument name produces a flow that saves and then does nothing'). This adds value without contradicting 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 quite verbose, splitting across multiple long sentences without visual structure. While the information is relevant, it could be tightened. The front-loaded purpose sentence helps, but the latter half becomes dense and could overwhelm the agent. The 'save and does nothing' warning is valuable but 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?

Given the tool's moderate complexity (2 params, no output schema, good annotations), the description covers key aspects: what is returned, when to call, an important caveat, and the schema/args relationship. It doesn't include explicit error cases or examples, but the combination of annotations and description provides a complete picture for the agent to use the tool safely.

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% (both parameters described). The description adds context about the relationship between 'arguments' and 'args', which helps invoke the tool correctly. While it focuses more on output than input parameters, it does explain how the output maps to invocation, which enhances parameter understanding 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 clearly states 'Returns everything needed to use one flow card' – a specific verb+resource. It distinguishes itself from sibling tools like homey_flowcards_search by noting what additional fields are provided, and explains the exact purpose ('Call this for each card before building a flow'). The purpose is unambiguous and distinct from 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 explicitly instructs when to use the tool ('Call this for each card before building a flow') and contrasts with homey_flowcards_search ('the same field ... reports with only the name and type of each'). It implies a sequential workflow. However, it doesn't explicitly mention alternative tools by name or state 'when NOT to use', so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds value by disclosing that an unfiltered call is refused and that results are minimal (only cardId and argument names/types). It does not contradict annotations and provides behavioral context beyond what structured fields offer.

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 moderately long but well-structured, starting with the core purpose, then explaining flow cards, then filter requirements, then output format and next steps. Each sentence contributes to understanding, though the explanation of flow cards could be considered baseline knowledge for the domain. It is front-loaded and not wasteful.

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 7 parameters and no output schema, the description fully compensates by explaining the output structure (cardId and arguments) and directing to homey_flowcard_describe for full details. It covers the essential behavioral constraints (filter requirement, result limitation) and provides enough context for an agent to call the tool correctly, even without an output schema.

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% for all 7 parameters, so the baseline is 3. The description adds meaning by explaining the requirement of at least one filter and gives examples for owner, device, and query. It also clarifies that results are limited, which indirectly affects parameter choice. This goes beyond the schema's descriptive text.

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

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

The description clearly states the tool's purpose: to find flow cards on the Homey. It explains what flow cards are (trigger, condition, action) and distinguishes the tool from sibling tools like homey_flowcard_describe by explicitly directing users to call describe after selecting a card. This makes the purpose unambiguous and actionable.

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 specifies when to use this tool (to search and select flow cards) and provides the key constraint that at least one filter is required, with an unfiltered call refused. It also clearly guides the next step: call homey_flowcard_describe with the returned cardId for full argument details. This gives explicit usage context and differentiates from describe/autocomplete.

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 description provides rich behavioral detail beyond the annotations: the flow is created switched OFF, placed in an AI folder, validated first and refused if invalid, then read back from Homey and compared for correctness. It also tells the caller the result carries a link to the flow in the Homey app, which is especially 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?

The description is four sentences with no filler or redundancy. Every sentence contributes meaningful behavioral information: what is created, where it is placed, how it is validated, and what the result includes.

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 has a complex nested schema and no output schema, but the description covers the result link, safety behavior, and validation. It is not fully explicit about the need for prior authentication or how the caller should choose between homey_flow_create and homey_advancedflow_create, but it is otherwise complete for the most important outcomes.

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 input schema already covers all parameters with 100% description coverage, so the baseline is 3. The description itself does not add direct explanation about name, trigger, actions, or conditions as parameters, but this is unnecessary because the schema is already detailed enough.

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

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

The description clearly states it "Builds a new flow," identifying the specific action and resource. It goes beyond creating to explain the flow is created switched off in an AI folder, helping distinguish it from related flow tools like update, validate, delete, and start.

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 usage context: the tool creates a new flow, initially disabled and placed in the AI folder for owner review. It does not explicitly mention when to use homey_flow_create over homey_advancedflow_create or homey_flow_update, but the "builds a new flow" framing is sufficient for basic selection.

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

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

The description goes beyond the destructiveHint annotation by explaining the no-undo consequence and that the exact flow is returned in the result for reconstruction. It also clarifies the confirm requirement for externally created flows. This gives the agent clear expectations about side effects and return behavior, well beyond what the annotations provide.

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 sentences, front-loaded with the main action and scope, followed by critical behavioral notes. Every sentence adds value: the first defines the primary action and scope, the second warns about no undo and the confirm condition. No filler or redundancy.

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 description covers the essential context: what the tool does, the target scope (flows), the destructive consequence (no undo), the return vale for recovery, and the special condition for externally created flows. This is sufficient for an agent to use the tool safely and effectively without needing additional documentation.

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

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

The schema already specifies both parameters (flow string, confirm boolean). The description adds meaning by stating the flow can be 'standard or advanced', which clarifies the scope of the flow parameter. It also ties the confirm parameter to a specific condition, although that is already in the schema. Since schema coverage is 100%, the baseline is 3; the added clarification raises it to 4.

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 ('deletes') and explicitly states the scope ('flow, standard or advanced'), making the tool's purpose unambiguous. It even hints at the result (returns the flow) which further clarifies intent. This distinguishes it from other homey tools that start, update, or validate 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?

The description provides a clear usage condition: 'A flow this server did not create needs confirm: true.' This guides the agent on when to set the confirm parameter. It also implies the destructive nature (no undo) which is essential. However, it does not explicitly compare with alternative deletion tools (e.g., homey_script_delete) or mention when not to use it, so it is not perfect.

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 signal this as a non-read-only, non-idempotent mutation. The description adds meaningful context beyond the annotations: it returns an id for later use, supports nesting, and warns that names are not unique. It does not disclose error conditions or authorization, but for a simple creation tool with annotations, this is sufficient.

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 concise sentences with no wasted words. The core action leads, then nesting behavior, return value, and an important warning. Perfectly front-loaded for an agent to scan quickly.

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 create tool with high schema coverage and no output schema, the description effectively covers purpose, return value, and a key prerequisite. It stops short of giving examples or failure cases, but the tool is simple enough that everything is reasonable. Not quite a 5 because it could explicitly state the action is non-idempotent or mention name uniqueness confirmation, though it is fairly 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% and both 'name' and 'parent' are described in the schema. The description adds only minimal extra parameter context (e.g., 'optionally inside another one' for parent, and a warning about name uniqueness). It does not deeply enrich the parameters, so baseline 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?

Description opens with a specific verb+resource: 'Creates a folder to organise flows in'. It also clarifies the optional nesting behavior and distinguishes itself from sibling flow/script creators by noting it creates folders. The return-value mention ('Returns the id, which is what homey_flow_move takes') reinforces its role.

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?

Provides clear when-to-use guidance with the action itself, and notably warns to check homey_flow_folders_list first to avoid duplicate names. It does not explicitly list alternative tools (e.g., update/delete) or when not to use it, but the duplicate-name check is a strong pragmatic guideline.

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 destructiveHint=true, and the description reinforces this by saying 'Removes' and 'Deleting a folder never deletes a flow.' It adds useful context about the constraint that the folder must be empty and that flows are not deleted. This goes beyond the annotation, which just flags destructiveness, so it earns a 4.

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 extremely concise: three sentences, each adding value. It doesn't waste words and is front-loaded with the core action. The constraint and safety note are logically placed.

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 simplicity of the tool (one parameter, no output schema), the description is nearly complete. It provides the key behavioral detail (empty-only constraint) and a pointer to the alternative for moving flows. It could theoretically mention error behavior, but that's not necessary for this simple tool; it earns a 4.

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 input schema already provides a description for the 'folder' parameter: 'The folder id, or its exact name.' The description adds no further parameter detail, but with 100% schema description coverage, the baseline is 3; it gets a 4 because the tool has only one parameter and the description is adequately handled by 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 clearly states the tool's purpose: 'Removes an empty flow folder.' It uses a specific verb ('Removes') and a specific resource ('flow folder'), and it distinguishes itself from sibling tools like homey_flow_delete by clarifying it deletes folders, not 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?

The description explicitly states when to use the tool: deleting an empty folder, and when not to: when the folder still contains flows, in which case the user should move them out first with homey_flow_move. It names an alternative tool and provides a clear precondition.

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 meaningful context beyond that: the result is a tree, includes per-folder flow counts, reports flows outside all folders separately, and warns about non-unique folder names. It does not fully detail all return fields, but with no output schema it communicates the essential behavior well.

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, each earning its place: the first states the core output, the second clarifies an edge case, and the third gives actionable usage context. No filler or redundancy.

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 list tool with good annotations, the description is sufficiently complete. It explains the tree format, flow counts, handling of flows outside folders, and why the output matters (ID reliability), covering what the agent needs without an output schema.

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 and the schema coverage is effectively complete, so the baseline is 4. The description adds semantic context about the folder hierarchy and counts but does not need to explain parameter details since none exist.

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 ('Lists') and resource ('every flow folder'), adding concrete details like flow counts, tree structure, and reporting of flows outside folders. This clearly differentiates it from sibling tools like homey_flows_list and folder mutation tools.

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 states 'Use this before moving anything' and explains why: folder names are not unique and only IDs are reliable. This is clear when-to-use guidance, though it does not mention alternatives or when not to use the tool, so it stops 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 indicate a non-readonly, non-destructive mutation, and the description adds reassuring behavior: 'The flows in it are untouched and keep working.' This adds meaningful behavioral context beyond the annotations, though it does not disclose potential errors or 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?

The description is three concise sentences with no filler. It front-loads the core action, then adds key behavior and a specific usage nuance, every sentence contributing useful 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?

Given the tool's moderate complexity, the description covers the essential operation, non-destructive nature towards flows, and top-level move behavior. It omits details like duplicate-name handling or invalid-parent errors, but the schema and annotations fill in enough context for most invocation scenarios.

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 schema already provides 100% coverage for the three parameters, so the description need not repeat the semantics. It adds only an operational hint about parent null moving a folder to top level, which is also in the schema. Thus a 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 clearly states the tool's dual purpose: 'Renames a flow folder, moves it inside another one, or both.' It also distinguishes itself from sibling tools like homey_flow_folder_create/delete and homey_flow_move by focusing on folder update operations.

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

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

The description provides practical usage context, such as 'Send parent as null to move a folder back to the top level,' making the move behavior explicit. It does not explicitly mention when not to use it or name alternatives, but the context of 'update folder' is clear enough for a competent agent.

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?

Beyond the readOnly/idempotent annotations, the description reveals that cards are resolved to titles and non-existent cards are marked. This adds behavioral context not present in 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?

Two sentences, front-loaded with the core purpose and then enriched with relevant behavioral details. No fluff or redundancy.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers what it returns, how cards are presented, and edge behavior for missing cards. Complete for its purpose.

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 schema already describes the sole parameter as 'The flow name or id' (100% coverage). The description doesn't add syntax, examples, or disambiguation beyond this, 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?

The description clearly states the tool reads a single flow and details the content returned (trigger, conditions, actions, or graph of cards). This is specific and distinguishes it from write/delete siblings, though without naming alternatives.

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 ('read' a flow), but there's no explicit guidance on when to choose this over alternatives like homey_flow_start or homey_flows_list. Adequate but not explicit.

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?

Beyond the annotations (destructiveHint: false), the description adds valuable behavioral details: it does not change what a flow does ('keeps its cards'), running flows stay running, and the previous folder is reported for undo purposes. This gives the agent a richer understanding of the operation's persistence and side effects.

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 compact and well-structured: sentence 1 states the primary action, sentence 2 clarifies input format, and sentence 3 explains side effects and reversibility. Every sentence adds value with no redundancy or fluff.

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 (move flows) and has no output schema. The description covers all essential aspects: what changes (location only), what stays the same (cards and running state), and recoverability (old folder reported). This is complete for the tool's complexity, especially given the sibling landscape.

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 input schema already describes both parameters with 100% coverage: flows by id or exact name, folder by id or exact name with null meaning removal. The description reiterates these points but does not add significant new meaning beyond the schema, so the baseline of 3 for high schema coverage 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 clearly states the action: 'Moves one or more flows into a folder, or out of every folder when folder is null.' It identifies the resource (flows) and destination (folder), and distinguishes itself from sibling tools like homey_flow_delete or homey_flow_folder_update by focusing solely on relocation.

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 provides clear context on when to use the tool (for moving flows between folders) and mentions input format (ids or exact names), but it does not explicitly state when not to use it or mention alternative tools for other operations. This meets the level of 'clear context, no 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 disclose the read-only, idempotent, and non-destructive profile, so the description does not need to repeat that. The description adds some scope context ('standard and advanced together') but no deeper behavioral details such as pagination or return shape.

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 focused sentences: the first states the main action and scope, and the second summarizes filtering and directs to the more detailed sibling. There is no filler or redundancy.

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 list tool with fully documented optional parameters and clear annotations, the description is sufficient. It states what is listed, how to filter, and which sibling to use when more detail is 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 each parameter already has a clear description. The description's 'name, folder, kind or state' maps loosely to query/folder/kind/enabledOnly/brokenOnly but does not add meaning beyond what the schema provides.

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: 'Lists the flows on this Homey' and explicitly states that standard and advanced flows are included together. It also distinguishes itself from homey_flow_get by indicating that sibling is used to see what one flow actually does.

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?

Clear context is provided for using this tool: list flows and filter by name, folder, kind, or state. The description also names homey_flow_get as the alternative for deeper detail, though it does not explicitly state when not to use this tool.

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

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

The description goes beyond the annotations in crucial ways. The annotations state destructiveHint=true and readOnlyHint=false, but the description explains the real-world consequences: 'a flow can unlock a door, open a window covering, turn on the heating or send a message.' It also clarifies that it is 'a real execution and not a preview,' which is a critical behavioral trait not captured by the annotations. This fully informs the agent of the potential impact.

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 sentences, front-loaded with the main action ('Runs an existing flow immediately'), followed by essential warnings and scope. Every sentence earns its place: the execution nature, the consequence examples, the precaution, and the coverage of standard and advanced flows. No fluff.

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 straightforward with a single parameter and no output schema, so the description is largely complete. It covers what the tool does, its side effects, and a safety precaution. However, it doesn't explicitly state the return value (though without an output schema, it may be minimal), and it doesn't mention error conditions (e.g., flow not found), but these are minor gaps given the simplicity. No annotations like openWorldHint would suggest further context, so a 4 is justified.

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 schema already has 100% coverage for the single parameter 'flow', describing it as 'Flow id or flow name.' The description does not add additional syntax or format details beyond what the schema provides, but it does imply that the flow must exist and be a valid flow. Since the schema is fully descriptive, 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 clearly states the tool's purpose: 'Runs an existing flow immediately.' It uses a specific verb ('Runs') and resource ('existing flow'), and distinguishes itself from sibling tools like homey_flow_validate (which presumably only checks validity) and homey_flow_create (which creates new flows). The phrase 'exactly as if its trigger had fired' provides precise semantics.

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

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

The description provides explicit guidance on when to use this tool: when you want to execute a flow immediately. It also warns against using it without knowing the flow's actions: 'Read the flow with the flow tools before starting it if you are not certain what it does.' This is direct advice on a precautionary alternative, effectively telling the agent when not to use it (i.e., without prior inspection).

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, so the safety profile is covered. The description adds behavioral context beyond that by explaining that tokens include device capabilities, logic variables, and tags, and by describing the id format ('[[<ownerUri>|<ownerId>]]') which is crucial for using the result. No contradictions with 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 four sentences, each adding value: definition, purpose, use case, and relationship to validate. It is well-structured and front-loaded with the primary action, though it could be slightly more concise without losing clarity.

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 list operation with no output schema, the description covers the essential context: what tokens are, what is returned (values and ids), the reference syntax, and how it connects to validation. It does not enumerate all return fields, but it is sufficient for an agent to understand the tool's behavior and results.

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%: both limit and query have descriptive comments. The description itself does not add parameter-specific details beyond what the schema provides, so it meets the baseline but does not exceed 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?

The description clearly states 'Lists every token on this Homey with the value it holds right now', identifying the specific resource (tokens) and action (list). It also distinguishes the tool by explaining what a token is and giving a unique use case ('read back a tag a script has written'), which separates it from other list tools like homey_flows_list.

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 provides a concrete use case ('This is how to read back a tag a script has written, which is otherwise only visible in the Homey app') and explicitly references homey_flow_validate as a complementary tool. However, it does not explicitly state when to avoid this tool or mention alternatives beyond the validate tool, so it stops short of full 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?

Beyond the annotations, it reveals key behaviors: it reads the current flow and returns it for rollback, replaces arrays wholesale, and prevents enabling an off flow without confirmEnable. It also explains the safety rationale for that step. No contradiction with the annotations was found.

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 dense but not bloated; the first sentence is action-focused and each following sentence explains an important behavioral guardrail. A few sentences are long and combine different concerns, but the content is still relevant and the structure remains readable.

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 appropriately discloses that the previous flow version is returned in the result, enabling rollback. It also covers ownership confirmation, enabling semantics, and partial updates, making it sufficiently complete for a complex 8-parameter mutation 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 schema already documents all 8 parameters thoroughly, so the baseline is high; the description adds useful cross-cutting semantics by explaining partial-update behavior and the difference between omitting a field and sending an array. This meaningfully augments the schema rather than merely repeating 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?

The description opens with a specific action: 'Replaces the trigger, conditions and actions of an existing standard flow.' This clearly identifies the resource, the operation, and the scope, and distinguishes the tool from create, delete, and advanced-flow 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 gives practical usage guidance: untouched flow values are preserved, arrays sent replace the old ones, and the confirm/confirmEnable requirements are explained. It does not explicitly list alternative tools and when to prefer them, but the phrase 'existing standard flow' implicitly sets the boundary against advanced-flow and creation tools.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds meaningful behavioral detail: it lists specific checks, notes that invalid flows silently save with 'NO CARD' or 'Unavailable', and admits its limitation ('cannot judge whether the flow does what the owner meant'). This enriches the annotation baseline without contradiction.

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 dense sentence, front-loaded with purpose and covering essential behavioral details. It is efficient with no filler. It could be slightly better structured (e.g., breaking into two sentences), but it is well within acceptable conciseness for the content provided.

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 complexity of the tool (nested objects, multiple flow parts) and the lack of an output schema, the description adequately covers what it does, why it is valuable, and its limitation. It does not describe the return value format, but that is not critical since the description explains what validation catches. The reasoning about the Homey's lenient acceptance provides sufficient context for correct usage.

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 baseline is 3. The description does not add parameter-specific semantics beyond the schema; it focuses on the validation behavior. It does implicitly explain the structure (trigger, actions, conditions) through the checks, but not enough to raise the score above 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?

The description clearly states it 'checks a flow against this Homey without writing anything and without running anything' and enumerates specific validations: card existence/type, argument names/types, device/zone existence, and token references. This distinguishes it from flow creation/update tools by emphasizing it is a non-mutating validation step.

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 'Worth calling first, because the Homey itself accepts almost anything', providing clear when-to-use guidance. It implies using it before saving a flow, but does not explicitly name alternative tools or when not to use it. The sibling list includes flow_create/update, so context is strong but not 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=true, idempotentHint=true, destructiveHint=false. The description adds meaningful context: it returns counts and names rather than full records, and clarifies that it's an overview for orientation. This is consistent with annotations and adds value beyond them, though it doesn't mention any edge cases like pagination or rate limits (which may be unnecessary given readOnly).

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, information-dense paragraph that front-loads the core purpose ('Orients you in this Homey in one call') and then enumerates contents. It could be slightly more concise, but it avoids fluff and every clause adds value. It ends with actionable guidance (use include, use other tools for 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?

The description covers what the tool returns (counts and names), when to use it (before other tools), and what it does NOT return (full device records), directing to homey_devices_search and homey_device_get. It also mentions the `include` narrowing option. With no output schema, it clearly sets expectations for the response. The only minor gap is that it doesn't list specific section names beyond examples, but the include enum covers that.

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%: both 'limit' and 'include' have descriptions in the schema. The description adds a usage hint for `include` ('Narrow it with include when you only need one part'), which is helpful but not substantial beyond the schema's own definitions. Baseline 3 fits as the schema already documents parameters well.

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

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

The description clearly states the tool's purpose: 'Orients you in this Homey in one call' and lists specific resources it covers (zone tree, device counts, apps, variables, presence, flows, capabilities, etc.). It also distinguishes itself from siblings by explicitly directing to 'homey_devices_search or homey_device_get' for actual device records, making it clearly a high-level overview 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?

It explicitly says to call this before any other Homey tool, provides the rationale (orientation), and mentions using other tools for detailed device state. It also explains how to narrow scope with the 'include' parameter. This is exemplary usage guidance with clear alternatives and 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?

The description adds key behavioral context beyond the readOnly/idempotent/destructive annotations: gaps are skipped rather than filled, the hub returns the true window/step and coverage share, and energy logs are summarized differently by type (meter_power vs measure_power). This explains important edge semantics the annotations don't cover.

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 compact and information-dense: the first sentence conveys the core function and output, and each subsequent sentence adds a distinct, high-value understanding (coverage, comparisons, energy semantics, discoverability). No wasted words or repetition.

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?

Without an output schema, the description compensates by listing the statistics and explaining the hub-returned window, step, and coverage. It covers usage flow (search first), noteworthy edge cases, energy log behavior, and intended patterns, making it complete for an agent to select and invoke the 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 input schema already documents every parameter with 100% coverage, giving the baseline. The description adds extra meaning for key parameters such as compareWith (second window for difference queries), logs (candidates when ambiguous), and resolution (calendar windows in Homey's timezone). It doesn't explain every parameter in detail, but the schema covers those, so the overall semantics are strong.

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 precise verb and resource: 'Fetches up to five Insights logs at one resolution and returns statistics computed over them' and names the exact statistics and output fields. It clearly distinguishes itself from sibling tools by directing users to homey_insights_search for log discovery and homey_energy_live for live energy.

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 explicit when-to-use guidance: use compareWith for comparison queries like 'warmer than last week', and always find log ids with homey_insights_search first. It also guides on interpreting averages with coverage and correctly handling energy log kinds, which is decisive for choosing and using the tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context: fuzzy matching fields, the scale (well over a hundred logs), and the 'never guesses which one was meant' behavior, which is valuable 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 concise, front-loaded with the purpose, and each sentence adds value. It explains the problem (hundreds of logs in household language), the solution (fuzzy matching), and the behavior (candidates, never guesses) without waste.

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

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

Given the tool's simplicity (3 optional params, no output schema), the description fully covers the relevant context: what it does, how to use it, and what to expect (candidates with ids). The annotations and schema fill the remaining safety and parameter details, making the description 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 coverage is 100%, with each parameter (type, limit, query) having a description in the schema. The description adds minimal parameter-level detail beyond what the schema already provides, so it meets the baseline of 3 for high coverage.

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

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

The description clearly states the tool's purpose: 'Finds Insights logs' by fuzzy matching over multiple fields. It distinguishes itself from siblings like homey_insights_query by positioning itself as the entry point to translate natural language into log IDs, explicitly saying 'start here'.

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 provides strong usage context: 'start here' and 'this is how ... becomes a log id you can query' suggest when to use it. It also notes that omitting the query browses first logs. However, it does not explicitly mention alternatives or when not to use it, though the sibling tool homey_insights_query is implied.

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?

Beyond the annotations, the description discloses important runtime behavior: the script executes on the Homey with Homey API access, log() output goes to the HomeyScript app console and is not visible to this server, and the response is the script's return value. It also explains the script can return or tag() values back to the Flow, adding real behavioral context.

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 long but every sentence earns its place. It is front-loaded with the core purpose, then follows a logical flow from creation, to runtime behavior, to authoring best practices, to debugging and verification. There is no redundancy or 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?

There is no output schema, but the description clearly explains what is returned (the assigned id and, for scripts, the return value). It also covers runtime environment, Flow integration, logging limitations, and the recommended next step. This is complete for a create tool with 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?

Schema coverage is 100%, so the baseline is 3, but the description adds substantial meaning beyond the schema: code is JavaScript running on the Homey, name is shown in the app and Flow picker, scripts receive args[0] from the Flow card, and return values are observable while log() is not. This greatly enriches both parameters.

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: 'Creates a new script and returns the id the Homey assigned to it.' It clearly distinguishes creation from sibling tools like homey_script_update, homey_script_get, and homey_script_delete by emphasizing that the returned id is the address, not the name.

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 clear workflow context: use the returned id afterwards and run the script with homey_script_run once created. It also provides substantial guidance on how to write reusable scripts. It does not explicitly contrast with update/delete/alternatives, so it stops 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 mark destructiveHint=true and readOnlyHint=false, so the destructive nature is known. The description adds valuable context beyond annotations: 'no undo,' 'any Flow that started it stops working,' and that the code is returned in the result for recreation. These are meaningful behavioral disclosures that help the agent understand side effects and recovery.

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 three sentences: the first states the action, the second highlights irreversibility and side effects, the third explains a recovery mechanism. Every sentence carries essential information without fluff or redundancy.

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 delete tool with one parameter and no output schema, the description covers all critical aspects: what it does, irreversibility, impact on flows, and the returned code for recovery. This is sufficient for an agent to decide and invoke the tool correctly.

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

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

The schema covers the single parameter with a description ('The script id, or its exact name'), achieving 100% coverage. The tool description does not add any extra parameter-specific meaning. Since the schema already documents the parameter, 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 clearly states the action: 'Removes a script from the Homey.' It uses a specific verb ('removes') and resource ('script'), and it distinguishes itself from siblings like homey_script_get or homey_script_update by focusing on deletion. Additional consequences (no undo, flows stop) reinforce its unique purpose.

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 context is implied: use this tool to delete a script. However, there is no explicit guidance on when to prefer this over alternatives, or prerequisites like fetching the script first. It does mention the recovery option (code returned), but lacks clear when-to-use vs. when-not-to-use statements.

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. The description adds the key detail that it returns the full script code, and specifies the input must match the name from homey_scripts_list. This adds context beyond annotations, though it doesn't disclose additional side effects (none 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?

Two short sentences, front-loaded with purpose, no fluff.

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?

Simple get operation with clear schema and annotations. Description adequately conveys the one parameter and return content. No output schema, but guessing it returns the script object including code is reasonable. Missing exclusions or error cases, but not needed for such a simple tool.

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

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

Schema has 100% coverage with description: 'The script id, or its exact name.' The description repeats this and adds the caveat 'as reported by homey_scripts_list', which clarifies usage but doesn't add deep semantics beyond that. Baseline 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 the tool's specific purpose: 'Returns one script including its code.' It clearly identifies the resource (script) and the action (get/return), and distinguishes from siblings like homey_scripts_list (list all) and homey_script_delete (delete).

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 context: takes id or exact name as reported by homey_scripts_list, which guides usage. It doesn't explicitly state when not to use it, but the distinct purpose is clear compared to other script tools.

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

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

The description discloses that the script executes (implying potential side effects) and that the return value is reported. It also transparently notes that log() output is not visible to the server, which is a behavioral detail. The annotation destructiveHint: true aligns with the destructive nature of running arbitrary code, so no contradiction.

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 verbose and rambling, repeating the concept of returning values multiple times and using informal phrasing (e.g., 'so this is also how a script gets debugged', 'return whatever needs checking rather than logging it'). It could be condensed into a few clear sentences without losing meaning.

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 simplicity of the tool, the description covers the essential aspects: what it does, what it returns, and how to handle debugging. It does not explicitly mention error handling beyond noting errors are reported with the line, but that is sufficient for a basic understanding.

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 sole parameter 'script' has a clear description in the schema ('The script id, or its exact name.'). The tool description does not need to add further meaning, and the schema coverage is 100%. The parameter is well-defined and unambiguous.

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

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

The description clearly states that the tool runs a script and reports the returned value. It uses a specific verb (run) and resource (script), distinguishing it from other script-related tools like delete or get. However, it does not explicitly mention alternatives or when to use this over others.

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 provides practical guidance on how to use the tool, such as returning values instead of relying on log output, and suggests returning intermediate objects during development. It implicitly indicates that this tool is for executing scripts and obtaining results, which helps the agent decide when to invoke it.

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 and destructiveHint=false, covering the safety profile. The description adds useful behavioral detail: it returns no code and includes the last-run timestamp, which informs expectations about output. No contradictions with 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 three sentences, front-loaded with the primary action and outcome. Each sentence adds value: what it lists, what scripts are, and the alternative for code. No redundant or filler content.

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, parameterless tool with no output schema, the description is complete. It states exactly what is returned, what is not returned, and points to the relevant sibling tool for deeper detail. The context about scripts and Flows enhances understanding without being excessive.

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, and the schema is empty with 100% coverage vacuously. Per the guideline, a baseline of 4 is appropriate because there are no parameters to document; the description correctly implies no inputs are needed.

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

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

The description clearly states the verb ('Lists') and the resource ('every HomeyScript script') with specific returned fields (id, name, version, last ran). It also differentiates from the sibling tool homey_script_get by noting that this returns no code, making its purpose unambiguous.

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

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

The description provides context on when to use this tool (to get a list of scripts) and explicitly points to the alternative homey_script_get for reading a single script's code. It does not explicitly state when NOT to use it, but the clear alternative and contextual explanation (scripts as JavaScript run from Flows) give adequate 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?

Beyond annotations, the description discloses two critical behaviors: (1) the previous code is returned to allow undo, and (2) log() output is not visible to this server; only the return value is observed. These details are not available in annotations or schema, significantly enhancing transparency for agent decision-making and debugging.

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 long, extending well into script authoring best practices. While all sentences offer value, the length dilutes the tool's core mechanics. It is not concise; however, it is structurally front-loaded with the purpose sentence, and the guidance is organized logically. A more compact version could retain key points.

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 absence of an output schema, the description fully covers the return value (previous code) and the log limitation. It also provides extensive context on script design principles, making it complete for an agent to use the tool effectively. There are no major gaps in behavioral expectations or usage context.

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%, with both parameters (script and code) already described. The description adds context about the script parameter (id or exact name) but this duplicates the schema. While the extensive guidance on script writing informs the code content, it does not directly enrich parameter semantics beyond what the schema provides. Baseline 3 applies.

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

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

The description opens with a specific statement: 'Replaces the code of a script that already exists, found by id or exact name.' This clearly identifies the verb (replace), resource (code of an existing script), and the lookup method (id or exact name). It is immediately distinct from creation, deletion, or running, as seen in sibling tools.

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 usage for existing scripts by stating 'that already exists' and specifying lookup by id or exact name. However, it does not explicitly contrast with create or run tools, nor does it state when not to use it. The context makes the primary use case clear, but exclusions are omitted.

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 indicate readOnlyHint=false, destructiveHint=false, but the description adds important behavioral context: the type is fixed permanently, the value must match the type, the variable is created with a starting value that may be read immediately, and creating something the owner didn't ask for clutters their Homey. It also discloses the confirm requirement. This goes beyond the annotations, though it doesn't explicitly mention reversibility or deletion, but the description is strong.

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, well-structured paragraph that front-loads the core action and immediately provides usage context. Every sentence contributes: purpose, use case, comparison with alternative, type constraints, value guidance, and confirmation requirement. There is no filler or repetition of schema content.

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

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

Given the tool's complexity (4 required params, 1 enum) and the complete schema coverage, the description covers all necessary aspects: purpose, usage, type semantics, value semantics, behavioral guidance on confirmation, and even interpersonal considerations (cluttering the owner's Homey). No output schema means return format isn't expected; the description is complete for a creation tool.

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

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

Schema description coverage is 100%, so all parameters are already described. The description adds extra meaning: it explains the starting value selection rationale ('pick a starting value the house can live with') and reinforces type constraints. It also adds context about name non-uniqueness by pointing to homey_home_overview, which complements the schema's note. While it doesn't delve into formatting, it adds value over 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 purpose is clearly stated: 'Creates a new logic variable' with a specific verb and resource. It distinguishes itself from siblings by explaining the use case for logic variables versus tags, and it is distinct from homey_variable_set. The scope is explicitly bounded: only exactly three types exist, and the type is fixed once created.

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 explicitly states when to use it ('when an automation needs to remember something between runs, or to hand a value from one flow to another') and provides a clear comparison with an alternative ('a logic variable is the better choice over a tag published from a script'). It also advises against unnecessary creation and requires confirmation, which is guidance on when not to use it.

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 readOnly=false, and the description adds valuable context: the type-matching constraint, the side effect on flows ('changing one can change what the house does next'), and the fact that it operates on existing variables only. This goes beyond the annotations and provides meaningful behavioral disclosure without contradiction.

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 concise and front-loaded. The first sentence states the primary purpose, followed by necessary context (type rules, side effects, and non-creation). Each sentence earns its place, with no redundant or filler content. It maintains a clear, efficient structure.

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

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

For a simple tool with two parameters and no output schema, the description covers the essential aspects: the operation, type constraints, side effects, and the relationship to other tools. It could potentially mention error handling on type mismatch, but that is implied by the explicit type rule. Overall, it's adequately complete for the tool's 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?

Schema coverage is 100%, so both parameters are documented. The description adds crucial semantic detail: the value must match the variable's existing type, and the variable must already exist. This clarifies the 'value' parameter beyond the schema's generic description and provides a constraint that affects usage.

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

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

The description clearly states the tool's action ('Writes a new value to an existing Homey logic variable'), specifies the resource (logic variable), and emphasizes the 'existing' constraint, which differentiates it from homey_variable_create. It also explicitly states it never creates a variable, providing clear distinction from sibling tools.

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 clear context on when to use this tool (to change an existing variable) and when not to use it (it never creates variables), and points users to homey_home_overview to discover existing variables. However, it does not explicitly name the alternative creation tool (e.g., homey_variable_create), so it's not fully explicit about 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?

The description transparently explains output units and conversions (humidity percentage, temperature unit, pressure bar/millibar), forecast granularity dependence on hardware, and that sky description is in the Homey's language. It also mentions the absence of hourly forecast and that it's a single reading for one location. This aligns with the read-only and idempotent 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 overly verbose and repetitive, repeating the same clarifications multiple times, such as the explanation of units and limitations. While it is structured, the redundancy detracts from conciseness.

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 description provides comprehensive context, including relationship to other tools, limitations, and data specifics. It covers all necessary aspects for a user to understand and use the tool effectively, including when not to use it.

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 input schema provides clear descriptions for the two boolean parameters (includeForecast and includeHourlyForecast), including defaults and use cases. The tool description does not add additional parameter explanation, but the schema coverage is complete, 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 clearly states that the tool reads outdoor weather from Homey, listing specific data fields (temperature, humidity, air pressure, sky description, town name) and mentions the forecast. It also differentiates it from other tools by specifying it's the weather Homey itself uses and suggests pairing with indoor sensor tools.

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 provides explicit use cases: comparing outdoor to indoor (pairing with homey_device_get), answering if opening a window helps, and looking ahead to tonight's low. It also notes limitations, such as not being a substitute for an outdoor sensor and directing history queries to homey_insights_search.

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