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

Annotations already declare readOnlyHint and destructiveHint. The description adds valuable behavioral details: it does not uninstall, it flags candidates, reports savings, and groups duplicates. It also warns about background logic. No contradictions.

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 relatively long but well-structured, with each sentence adding value. It could be slightly shorter, but it remains clear and informative.

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

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

Given zero parameters and no output schema, the description fully explains the tool's output: flags removal candidates, reports potential savings, and groups duplicates. It covers all necessary contextual information.

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 has zero parameters, so schema description coverage is 100%. Baseline is 4, and the description does not need to add parameter info. No issues.

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 cross-references installed apps against RAM usage, device count, and flow references, and flags removal candidates. This specific verb-resource combination distinguishes it from sibling tools like list_apps or get_memory_info.

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 it is read-only and advisory, and includes a caveat about background logic. It lacks explicit when-not-to-use instructions or alternative tools, but the context is clear enough for typical use.

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 mutation (readOnlyHint=false), idempotency (idempotentHint=true), and non-destructiveness. The description adds that it returns 'new flow id and broken status' with an explanation of broken status, which is helpful. However, it does not elaborate on idempotency implications or failure modes. Overall adequate but not rich.

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

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

Two sentences, front-loaded with purpose, no extraneous words. Efficiently conveys core behavior and card structure. Perfectly sized for the complexity.

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 no output schema, the description covers return values (id, broken status) and explains broken status. It specifies all required inputs and the structure of the complex 'cards' object. Missing mention of optional 'folder' and 'enabled' parameters, which are minor. Overall very good.

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?

Input schema has 100% coverage (all parameters described), but the description goes far beyond by specifying the internal structure of the 'cards' object: keyed by UUID, each card has properties (type with allowed values, id, args, coordinates, outputSuccess/outputError arrays). This compensates for the schema's 'additionalProperties': {} which lacks detail. Adds significant meaning.

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 'Create a new Advanced Flow' with specific verb and resource. It details the card structure (type, id, args, coordinates, links) distinguishing it from simpler 'create_flow' sibling. 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?

No explicit guidance on when to use this tool vs alternatives like 'create_flow'. The description focuses on input structure but does not explain scenarios where advanced flow creation is appropriate or when a simpler flow might suffice. Sibling differentiation is implied by the 'advanced' title and card complexity, 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 indicate non-readonly, idempotent, and non-destructive. The description adds that the backup runs in the background, providing useful behavioral context. However, it does not disclose potential conflicts (e.g., if a backup already exists) or any side effects beyond scheduling.

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 concise sentences with no redundant words. First sentence states the primary purpose, second clarifies the background execution.

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, the description adequately covers what it does and that it runs asynchronously. It could be more complete by referencing get_backup_status for monitoring, but this is not critical given the low 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?

Tool has zero parameters, so there is nothing to document. Baseline score of 4 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 action: 'Schedule a new backup of the Homey configuration.' It uses a specific verb ('schedule') and resource (backup), and distinguishes from the sibling tool get_backup_status which retrieves backup status.

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

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

No explicit guidance on when to use this tool versus alternatives. The description does not mention checking backup status via get_backup_status or any conditions that might warrant creating a backup. It only states the action without 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 indicate idempotent, not read-only or destructive. The description adds context about the flow structure (trigger, conditions, actions) beyond annotations, but does not discuss idempotency or return behavior.

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

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

The description is concise (two sentences), front-loaded with purpose, and contains no redundant 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?

Despite no output schema, the description provides sufficient context for a create tool by referencing external tool for shape details. Could benefit from mentioning return value or behavior on duplicates, but idempotency annotation covers that partially.

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 covers both parameters, but description adds meaning by explaining that 'flow' contains trigger (card object) and optional conditions/actions arrays, and references 'get_flow' for exact shape. This significantly enhances understanding.

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 'Create' and the resource 'standard WHEN/AND/THEN Flow'. It distinguishes from siblings like 'create_advanced_flow' by specifying 'standard' and provides guidance to use 'get_flow' for learning card shapes.

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 instructs to provide name and flow object with trigger, conditions, actions, and advises using 'get_flow' to learn the card shape. It implies usage for standard flows but does not explicitly mention when not to use or compare with 'create_advanced_flow'.

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 indicate a non-read-only, non-destructive, idempotent operation. The description adds useful behavioral context: the notification appears on the Homey timeline and is visible to all household members. There is no contradiction 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 concise, two sentences long, and directly states the purpose and audience. Every word adds value without unnecessary elaboration.

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 one-parameter tool, the description fully covers what the tool does, where the notification is delivered, and who can see it. No output schema is needed for this basic send operation, and the information provided is sufficient for an agent to invoke it correctly.

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

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

Schema coverage is 100% for the single 'excerpt' parameter, and the schema description already clearly explains its purpose. The tool description does not add any additional parameter semantics, but this is not necessary given the schema's clarity.

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 ('send a notification') and the specific target ('to the Homey timeline'). It effectively distinguishes itself from the sibling tool 'list_notifications' by describing a create/write action rather than a read/list action.

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: it sends a notification visible to all household members, which helps the agent decide when to use this tool. It does not explicitly mention alternatives or exclusions, but the context alone is sufficiently clear for a simple notification send.

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 indicate non-read-only, idempotent, and non-destructive. The description adds little beyond 'create' and optional nesting, providing no extra transparency about side effects, permissions, or error handling.

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

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

One concise sentence front-loaded with the verb. No wasted words, direct and clear.

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 2-parameter tool without output schema, the description covers the key aspects. However, it lacks mention of return value or error conditions, which could be inferred but is not 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 covers both parameters with descriptions. The description rephrases the schema's parent parameter but adds no new meaning. With 100% schema coverage, 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 clearly states the verb 'create' and resource 'zone (room/area)', and mentions optional nesting under a parent zone. This distinguishes it from sibling tools like list_zones or move_device_to_zone.

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

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

The description implies when to use (when creating a zone) but lacks explicit guidance on when not to use or alternatives. No contrast with other create tools or prerequisites for the parent zone.

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 set destructiveHint=true; the description adds 'Permanently delete... Cannot be undone,' reinforcing irreversibility. 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?

Single 7-word sentence, front-loaded with verb and resource, no unnecessary 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?

Sufficient for a simple delete operation with one parameter and clear annotations. Could mention scope of deletion but not essential.

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 'Advanced Flow ID.' The tool description adds no extra 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 clearly states the action (delete), resource (Advanced Flow), and method (by ID). It distinguishes from sibling tools like delete_flow and delete_alarm.

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

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

No guidance on when to use this tool versus alternatives like delete_flow, nor any prerequisites or 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?

With destructiveHint=true already in annotations, the description adds value by emphasizing 'Permanently delete', highlighting irreversibility. It also implies that an ID must be obtained from list_alarms, which is useful behavioral context. No contradiction 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 two short sentences, front-loaded with the action, and includes a helpful cross-reference to list_alarms. Every word earns its place; there is no padding 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 one-parameter destructive tool with no output schema, the description is sufficiently complete: it clarifies the irreversible nature, tells how to obtain the required ID, and is appropriately concise. No gaps remain for typical 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?

The schema covers 100% of the single parameter (id) with a description 'Alarm ID'. The tool description doesn't add any further parameter semantics beyond referring to the ID, so it adds no value beyond the schema baseline.

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

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

The description uses a specific verb 'Permanently delete' and a clear resource 'an alarm', making the tool's function unambiguous. It also distinguishes this tool from siblings like list_alarms and set_alarm by implying removal versus creation or listing.

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 tells the agent to use list_alarms to find the alarm ID, indicating a key prerequisite. However, it doesn't explicitly state when not to use this tool or mention alternatives beyond list_alarms, so it falls 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 indicate destructiveHint=true. The description adds 'Cannot be undone', explicitly stating irreversibility, which is not in the annotations. However, it does not disclose other behavioral aspects like authorization or effects on dependent objects.

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 consists of one concise sentence with no redundant words. It is front-loaded with the key action. However, it could be slightly more informative while remaining concise.

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 sibling 'delete_advanced_flow', the description does not clarify the difference between standard and advanced flows. It lacks information on preconditions, post-conditions, or dependencies. The tool is simple, but more context would improve completeness.

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

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

The input schema has 0% description coverage for the 'id' parameter. The description merely says 'by ID' without specifying the ID format, example, or source. It adds minimal meaning beyond the schema's type constraint.

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 'delete', the resource 'standard Flow', and the parameter 'by ID'. It distinguishes from sibling 'delete_advanced_flow' by specifying 'standard'.

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 mentions permanence ('Cannot be undone'), implying careful use, but does not explicitly state when to use this tool versus alternatives like 'delete_advanced_flow'. It provides minimal guidance beyond the destructive nature.

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 declare readOnlyHint=true and destructiveHint=false. Description adds behavioral details: reports health, notes battery device sleep behavior. 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?

Two concise sentences, no waste. Front-loaded with core purpose, followed by a valuable caveat.

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?

Despite no output schema, description enumerates all reported elements (controller status, node count, last-seen, issues, remediations). Complete for a read-only diagnostic 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?

No parameters. Baseline 4 applies as description provides all needed context without requiring parameter details.

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

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

The description clearly states the tool reads Zigbee mesh state and reports specific health metrics (controller status, node count, last-seen ages, issues, remediations). It distinguishes from the sibling diagnose_zwave_network 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?

Provides explicit context about battery nodes and last-seen being normal when stale, helping users interpret results. Does not specify when not to use, but the note is valuable 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 and destructiveHint=false, which the description does not contradict. The description goes beyond by detailing exactly what the tool reads and reports (controller state, network log, health metrics, issue remediation). This provides rich 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 a single, well-structured sentence that front-loads the action and lists specific output items. Every part is informative; no 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 no output schema, the description lists key output elements (controller readiness, transmit failures, unavailable devices, remediations), which is complete for a diagnostic report. However, it does not mention any timing or network access requirements, which could be useful for understanding tool behavior.

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

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

There are zero parameters, and schema description coverage is 100% (by default). The description adds nothing beyond the schema, but the baseline for zero parameters is 4, as no additional param info is 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 uses a specific verb ('Read') and resource ('Z-Wave controller state plus recent network log'), then lists concrete outputs: controller readiness/version, transmit failures, unavailable devices, and recommended remediations. This clearly distinguishes it from sibling tools like 'diagnose_zigbee_network' and 'get_zwave_log'.

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 context for use is implied by the diagnostic purpose, but no explicit guidance on when to use this vs alternatives (e.g., diagnose_zigbee_network) is provided. The wording clearly frames it as a health check, so it's easy to infer.

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

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

The description adds behavioral context beyond the annotations by explaining the runtime impact: disabled apps stop running and their devices become unavailable. This complements the idempotentHint and destructiveHint annotations, providing a fuller picture of side effects. No contradiction 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 only two sentences, with the primary action front-loaded in the first sentence and a meaningful consequence in the second. Every word earns its place; 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?

For a simple toggle tool with two fully documented parameters, the description is complete. It explains both the purpose and the practical effect on devices, and the annotations already cover idempotency and non-destructiveness. No output schema is needed, and the description suffices 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% with clear parameter descriptions ('App ID' and 'true to enable, false to disable'). The description adds no further parameter-level meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb phrase 'Enable or disable a Homey app' and reinforces it with a concrete consequence: 'Disabled apps won't run and their devices become unavailable.' This distinguishes it from sibling tools like restart_app (restart) and uninstall_app (remove), providing clear differentiation.

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 a clear context of use: to control whether an app runs and affects device availability. It doesn't explicitly mention alternatives or when-not-to-use, but the sibling tool names (list_apps, restart_app, uninstall_app) make the boundary intuitive. The effect on devices also implies caution, which is a subtle usage 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?

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds that the tool returns the full definition with cards and connections, offering behavioral context beyond annotations.

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

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

Two concise sentences, front-loaded with the main action and key details. No unnecessary words.

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

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

For a simple read tool with one parameter and no output schema, the description fully covers the return content, use case, and relationship to siblings.

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

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

Schema description coverage is 100% with one parameter 'id' described as 'Advanced Flow ID'. The description reinforces that the tool retrieves by ID but adds no new details 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 the tool retrieves the full definition of an Advanced Flow by ID, including all cards with their arguments, coordinates, and connections. This distinguishes it from sibling tools like get_flow and update_advanced_flow.

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 recommends using this tool before update_advanced_flow to see the current structure, providing clear context. Does not list when not to use, but the purpose is straightforward.

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, so the agent knows this is a safe read operation. The description adds the specific data returned (configuration and timestamp), which is useful context but does not disclose additional behavioral traits beyond annotations.

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

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

The description is a single, front-loaded sentence that directly states the tool's function. Every word earns its place, with no redundancy or vague 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?

Given the tool's simplicity (no parameters, no output schema), the description fully covers what the tool does and what it returns. It is complete for the purpose of an agent selecting and invoking 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 tool has zero parameters, and the schema is empty. Baseline for 0 parameters is 4. The description does not need to explain parameters, and none are missing.

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

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

The description clearly states the verb 'Get' and the resource 'backup configuration and last successful backup timestamp.' It is specific and distinguishes from siblings like create_backup, which is for creating backups.

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 (when you need backup status), but does not explicitly state when to use it vs alternatives or any exclusions. No guidance is given beyond the core purpose.

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 the operation as read-only and non-destructive. The description adds behavioral context by specifying that the response covers 'all capability values, settings, and availability status,' which is beyond the annotation's safety profile. No contradictions are present.

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 long, front-loads the main action and resource, and includes a useful usage hint. Every word earns its place, with no fluff or repetition of schema fields.

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 has only one parameter, a read-only annotation, and no output schema, the description is sufficiently complete: it states what the tool does, what data is returned, and how to obtain the ID. No additional context is necessary for correct invocation.

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

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

Schema coverage for the single parameter 'id' is 100%, with the schema already describing it as a UUID. The description merely repeats 'by ID' and references finding the ID, adding no new semantic meaning. Since schema coverage is high, the baseline score of 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 uses a specific verb ('Get') and resource ('detailed information about a specific device by ID'), and enumerates the content ('capability values, settings, and availability status'). It clearly distinguishes from siblings like list_devices and search_devices, which are for listing/finding devices rather than retrieving details for a single known device.

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 the prerequisite: 'Use list_devices or search_devices first to find the device ID.' This names the exact alternative tools and gives a clear when-to-use directive, which is strong guidance for an agent selecting between options.

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, so the safety profile is established. The description adds behavioral detail about the return data (watts) and granularity (zone/device), enhancing transparency 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 three short sentences, each contributing value: the operation, the return unit, and the use case. It is front-loaded and free of fluff, earning every sentence.

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

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

For a parameterless read-only tool without an output schema, this description covers the operation, return value, and when to use it. It is sufficiently complete for an agent to select 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 tool has zero parameters, and schema coverage is 100% (empty object). The description does not need to explain parameters, and with 0 params the baseline score is 4. No further semantics required.

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

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

The description clearly states the tool's function: 'Get real-time power consumption' with specific scope ('broken down by zone and device'). This distinguishes it from siblings like get_energy_report, which likely provides historical data, making 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?

The description gives a clear use case: 'what is using power right now?' This implies when to use the tool, but it does not explicitly mention alternatives or exclusions. Context is clear, but no explicit when-not guidance is provided.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds the return format ('kWh consumed per device') and a period constraint, which is useful beyond the annotations. It doesn't disclose other behavioral traits (e.g., pagination, default date handling) but the annotations reduce the burden.

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, no filler. The first sentence states the action and result, the second provides a concrete usage example. Every sentence earns its place and there is no 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?

With only 2 parameters and no output schema, the description sufficiently covers purpose, return content, and use cases. It could mention response structure or edge cases, but for a simple report tool, the combination of schema, annotations, and description is adequately complete.

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

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

Schema description coverage is 100%, so the schema already documents both parameters (date with default, period with enum). The description reinforces the concept of a 'specific period' but doesn't add syntax or format details beyond the schema, matching the baseline of 3.

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 states a clear verb ('Get') and resource ('energy consumption report'), with a specific scope: 'for a specific period' and 'Returns kWh consumed per device.' This distinguishes it from siblings like get_energy_live (likely real-time) and get_insight_entries by focusing on period-based consumption reporting.

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

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

The description gives clear usage context via the example query 'how much energy did I use today/this week/this month?', implying periodic historical usage. However, it does not explicitly compare with alternatives like get_energy_live or state when not to use it, so it's clear but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds that the tool returns the full definition including trigger, conditions, and actions, which provides useful behavioral context but does not go beyond that.

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

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

The description is a single sentence, front-loaded with the purpose, and contains no unnecessary words. Every part is informative.

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

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

Given the simplicity of the tool (get by ID), the presence of annotations covering safety, and the schema covering the parameter, the description is complete. It explains what the flow definition includes, which is sufficient for an agent to understand the output.

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 covers the single parameter 'id' with description 'Flow ID' (100% coverage). The tool description does not add any extra semantic information about the parameter, so it 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 the verb 'Get' and the resource 'standard (WHEN/AND/THEN) Flow by ID', and specifies what is included (trigger, conditions, actions cards). This distinguishes it from siblings like get_advanced_flow and list_flows.

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

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

The description does not explicitly state when to use this tool versus alternatives. It implies usage for retrieving a specific standard flow's definition, but lacks guidance on when not to use it or mentions of sibling 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 destructiveHint=false, so the safe read nature is known. The description adds that the tool returns argument details (names, types, dropdown values, ranges), offering some behavioral context but no additional traits like auth or rate 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?

Two sentences, no filler, the first sentence immediately states the purpose and second provides usage motivation. 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?

For a simple get operation with 2 parameters and no output schema, the description explains the returned information (arguments with details) adequately. Missing potential error behavior or return format specifics, but overall sufficient for its 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 50%, with id and type described generically. The description only repeats 'by type + id' without adding meaning such as format, constraints, or examples. It does not compensate for the schema's limited descriptions.

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 retrieves the full definition of a flow card by type and id, including arguments. This precisely identifies the resource and action, and distinguishes it from sibling tools like list_flow_cards or get_flow.

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 recommends using this tool to learn what arguments a card needs when building a flow. While it doesn't formally exclude when not to use it, the guidance is clear and contextually sufficient.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that it returns 'timestamped values', which is useful context about the return format, but does not disclose other traits like pagination or limits. With annotations present, this is adequate but not exceptional.

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 verb and resource. Every word earns its place, including the example and the prerequisite. 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 with only two parameters, one required, and the schema covers them fully. Annotations declare it read-only. The description explains the return type (timestamped values) which is essential. Minor omission: does not mention the resolution parameter, but that is fully documented in the schema. Overall, 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 description coverage is 100%, with both 'id' and 'resolution' having clear descriptions. The description reinforces the 'id' parameter by mentioning list_insights, but adds no additional semantic value beyond what the schema already provides. 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 uses the specific verb 'Get' and resource 'historical data points for an insight log', clearly distinguishing it from list_insights which lists logs. The example 'temperature readings over time' makes the purpose concrete and 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 explicitly instructs to 'Use list_insights first to find the log ID', providing a clear prerequisite and sequence. While it doesn't contrast with alternative tools like get_energy_report, the guidance is sufficient for correct usage.

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, and the description adds no additional behavioral context such as side effects, permissions, or return format details. It merely restates the purpose without enhancing transparency 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 a single, front-loaded sentence of about ten words. Every word carries meaning, with no redundancy or unnecessary detail.

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 no params and no output schema, the description provides the core information: it retrieves LED ring screensaver options and the current setting. While 'options' could be slightly ambiguous, overall it adequately covers what the tool returns.

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

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

There are zero parameters, and the schema is empty, so the baseline of 4 applies. The description does not need to explain parameter semantics; it only hints at what the tool returns, which is sufficient for a getter with no inputs.

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

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

Description uses specific verb 'Get' with resource 'LED ring screensaver options and current setting', clearly stating what the tool does. It distinguishes from sibling set_ledring, which is the corresponding write operation.

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

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

The read-only purpose is evident, and the sibling set_ledring implies the alternative for modifications. However, it does not explicitly state when not to use this tool or name alternatives, missing the highest bar.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by specifying that the tool returns address and GPS coordinates, which is the output content. It also explains the purpose, providing useful behavioral context beyond the annotations.

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

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

The description is two concise sentences. It front-loads the verb and resource in the first sentence, and the second sentence adds purpose. Every word earns its place with 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?

For a zero-parameter read-only tool with no output schema, the description is fully adequate. It states what the tool does, what it returns (address and GPS coordinates), and its use case. Nothing essential is missing.

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

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

The tool has zero parameters, so the schema is trivially fully described. Per the rubric, the baseline for 0 params is 4. No parameter documentation is needed, and the description doesn't need to compensate for any gaps.

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: 'Get Homey's configured geographic location (address and GPS coordinates).' It uses a specific verb and resource, and distinguishes itself from sibling tools like get_weather or get_system_info by focusing on the location.

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 for when to use the tool: 'Used for sunrise/sunset calculations and weather.' This implies appropriate usage scenarios but doesn't explicitly mention alternatives or exclusions. However, for a simple zero-parameter read-only tool, this is sufficient and clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds the breakdown scope (by app and system component) but does not disclose additional behavioral details such as data freshness or output format. With annotations covering safety, this is adequate but not rich, thus a 3.

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

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

Two concise sentences; the first states the action, the second provides a practical use case. No wasted words.

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

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

For a parameterless, read-only tool with no output schema, the description fully covers what it does and why it is useful. The mention of breakdown by app and system component hints at the return content, making it 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?

No parameters exist, and schema description coverage is 100%. The description appropriately omits parameter details, and with 0 params the baseline is 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 states 'Get Homey memory usage breakdown by app and system component' with a specific verb and resource, and adds the use case 'identifying memory-hungry apps.' This clearly distinguishes it from sibling tools like get_system_info and get_storage_info.

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 use case ('Useful for identifying memory-hungry apps') but does not explicitly mention alternatives or when not to use it. This is clear context without exclusions, earning a 4.

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, so the agent knows this is a safe read. The description adds context about the scope ('all household members') and the type of statuses ('home/away and awake/asleep'), but does not disclose additional behavioral traits like response format or potential delays. It adds some value beyond annotations but not extensively.

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 short sentences, front-loaded with the core action and purpose. Every word earns its place, with 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?

For a simple, parameterless, read-only tool, the description is complete: it states what the tool returns, the scope, and a practical use case. No output schema exists, but the description adequately hints at the output nature without overexplaining.

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

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

There are zero parameters and the schema description coverage is 100%, so the baseline is 4. The description does not add parameter-specific semantics because there are none, but it is clear that the tool takes no arguments, which is sufficient.

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: 'Get home/away and awake/asleep status for all household members.' This is a specific verb+resource combination that distinguishes it from sibling tools like set_presence, which writes presence data.

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 use cases ('Useful for 'is anyone home?' or 'who is home?'') but does not explicitly mention when not to use it or name an alternative tool for changing presence. It implies usage context without exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds what fields are returned (user, role, permission scopes) but doesn't disclose additional behavioral traits such as authentication requirements or rate limits. This is adequate given the annotations.

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

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

The description is a single, front-loaded sentence with no redundancy or filler. Every word adds value.

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 explains the key return values (authenticated user, role, permission scopes) sufficiently. For a simple read-only tool with no parameters, this is complete enough, though it could optionally mention the exact response format.

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

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

The tool has zero parameters, so schema coverage is 100% trivially. The baseline for 0-param tools is 4, and the description appropriately doesn't need to explain any 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 clearly states 'Get current API session details' with a specific verb and resource, and lists the specific contents (authenticated user, role, permission scopes). It distinguishes itself from sibling tools as the only session-related endpoint.

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 checking the current session, and there are no sibling tools covering session info. However, it lacks explicit 'when to use' or 'alternatives' phrasing, so it falls short of a perfect score.

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, so the safety profile is known. The description adds context about the breakdown by apps, insights, and system, which is useful but does not disclose additional behavioral details like response format or units. This is comparable to the baseline in the calibration examples.

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, consisting of two short sentences that directly state the purpose and the key breakdown categories. Every word earns its place with 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?

Given the low complexity (no params, no output schema) and the annotations that cover safety, the description is complete enough. It tells the agent what the tool does and what data it returns, which is sufficient for a simple read-only storage info tool.

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

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

The tool has zero parameters, so the input schema is trivially covered. According to the rules, the baseline for 0 params is 4. The description doesn't need to explain parameters, and it doesn't.

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 with a specific verb and resource: 'Get Homey storage usage breakdown.' It further distinguishes itself from siblings like get_memory_info and get_system_info by specifying that it covers apps, insights, and system disk space.

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 appropriate usage by focusing on storage breakdown, but it does not explicitly mention when to prefer this over alternatives or exclude other tools. There is no direct guidance on choosing get_storage_info versus get_memory_info or get_system_info.

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, and the description is consistent with that. It adds value by listing the kind of content returned, but it does not disclose additional behavioral traits like response format, pagination, or rate limits. Given the read-only nature, this is adequate but not rich.

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

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

The description is a single, well-structured sentence that front-loads the main action ('Get Homey system information') and then lists relevant details. Every word adds value with no redundancy or unnecessary 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?

With no parameters, no output schema, and read-only annotations, the description is mostly sufficient. It names key information categories, which gives a clear picture of the returned data. However, without an output schema, a bit more detail on the exact structure (e.g., whether it returns a flat object or nested fields) would improve completeness, but the description still provides a solid baseline.

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

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

The tool has zero parameters, so the input schema is empty and schema coverage is effectively 100%. There is no parameter meaning to add beyond what already exists, and the baseline for zero parameters is 4. The description does not need to elaborate on 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 clearly states the tool's purpose: 'Get Homey system information' and lists specific data categories (software version, hostname, Wi-Fi network, hardware details). This distinguishes it from sibling tools like get_memory_info and get_storage_info by its broad system-level scope while being specific about the resource.

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

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

Usage is implied: use this when you need general system information. The description does not explicitly state when not to use it or mention alternatives like get_memory_info or get_storage_info, so it provides only implied guidance rather than explicit exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds specificity about what is checked (available updates and channel/auto-update settings), which is useful context. However, it does not go deeper (e.g., return format, any network implications, or conditions that might slow the call), so it adds some but not rich behavioral context beyond annotations.

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

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

The description is a single, front-loaded sentence with no redundancy. Every element ('available updates', 'settings', 'channel', 'auto-update') adds meaning, and there is no filler or repetition of the title.

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, has no parameters, and has clear annotations. The description fully explains its purpose and the type of information it retrieves, which is sufficient for an agent to invoke it correctly. No output schema is present, but for a read-only check tool, this level of description is adequate.

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

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

The tool has zero parameters, so no parameter documentation is needed. Per the rubric, a tool with no parameters gets a baseline of 4. The description compensates for the lack of schema coverage by explaining what the tool returns conceptually.

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 'Check for' and names the exact resource ('Homey system updates') plus the specific aspects covered ('current update settings (channel, auto-update)'). It clearly distinguishes itself from sibling tools, none of which mention updates.

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 clearly implies when to use the tool: whenever the agent needs to check available updates or update settings. It does not explicitly state exclusions or alternatives, but since no sibling tool covers updates, the context is unambiguous. A 5 would require explicit 'use this when' or 'instead of' language.

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, openWorldHint=true, and destructiveHint=false. The description adds value beyond these by specifying the exact return fields and example weather states, which is useful for an agent to interpret results. It does not cover units or potential caching, but the added context is meaningful.

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 front-loaded, stating the purpose in the first clause and then listing return values in a clear, scannable format. Every sentence adds useful information with no 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 weather tool with annotations covering safety, the description is fully adequate. It explains what the tool returns, where the location comes from, and gives examples of weather states. No output schema exists, but the description fills that gap sufficiently.

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

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

With zero parameters, the description does not need to explain parameter behavior. The baseline of 4 is appropriate since there is no schema coverage gap to compensate for. The description clarifies that location is fixed to Homey's location, which is sufficient.

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 ('Get') and resource ('current weather conditions at Homey's location'), and explicitly lists the returned data fields (temperature, humidity, pressure, wind, weather state). This clearly distinguishes from the sibling tool get_weather_hourly by emphasizing 'current' conditions.

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 current weather but does not explicitly state when to use it over alternatives like get_weather_hourly. There is no mention of excluding forecasts or historical data, so guidance is implied rather than 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds that it returns temperature and weather conditions, which is useful but not a behavioral trait like rate limits or pagination. 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 a single, front-loaded sentence that states the action, scope, and return content. Every word is necessary, with 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?

Given the tool's simplicity (0 params, read-only, no output schema), the description sufficiently covers what the tool does and what it returns. The sibling list and annotations provide additional context, and the description is complete for an agent to select and invoke it 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 tool has zero parameters and the input schema is empty, so schema description coverage is 100%. The description does not need to explain parameters, and the baseline for 0 params is 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 clearly states the verb 'Get' with resource 'hourly weather forecast', specifies scope 'at Homey's location', and indicates return type 'temperature and weather conditions'. This distinguishes it from the sibling tool 'get_weather' by explicitly mentioning 'hourly'.

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

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

The description implies when to use it (when an hourly forecast is needed) and gives context about location and time frame, but it does not explicitly mention alternatives or when not to use it. The sibling tool 'get_weather' exists, but no comparison or exclusion is provided.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, which covers the safety profile. The description adds context by listing the types of events the log contains, which is helpful but not extensive behavioral disclosure.

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 action, and each sentence contributes essential information: what it does, what it contains, and when to use it. No wasted words.

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

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

For a simple read-only log tool with no parameters and no output schema, the description fully covers purpose, content, and usage context. It is complete enough for an agent to select 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 tool has zero parameters, and the schema is trivially complete with an empty properties object. With no parameters to document, the description doesn't need to add parameter semantics, so the baseline of 4 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 gets Z-Wave network log entries and specifies the content (transmit failures, routing issues, network events). This distinguishes it from siblings, which are unrelated to Z-Wave logs.

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 it is 'Essential for diagnosing Z-Wave device connectivity problems,' which provides clear context for when to use it. It does not mention exclusions or alternatives, but the purpose is well-defined.

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 indicate readOnlyHint=false and destructiveHint=false. Description adds that it is a raw call, which implies the behavior depends on the endpoint, and warns it's an escape hatch. Could mention potential side effects for specific endpoints but overall adequate.

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 with no wasted words. Front-loaded with the key concept 'Advanced escape hatch', followed by specifics. 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?

Given it's a generic raw API call tool, the description provides sufficient context for an agent to decide when to use it. Could mention expected response format or error handling, but not strictly necessary for this type of 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 covers 100% of parameters with descriptions. Description adds context: 'method is GET/POST/PUT/DELETE; path is the API path (e.g. /manager/zwave/state); body is an optional JSON object', going slightly beyond schema to clarify 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?

Clearly states it is an 'Advanced escape hatch' for calling any Homey Web API endpoint directly, with specific verb+resource (call endpoint) and distinguishes from dedicated 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?

Explicitly says 'Prefer the dedicated tools when one exists' and describes when to use this tool ('to reach endpoints not yet wrapped by a dedicated tool, including new firmware capabilities'), providing clear context and alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds that it returns schedule and repetition days, but does not disclose output format or ordering. With annotations, this is adequate but not deeply transparent.

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 concise sentence that leads with the verb and object, containing no redundant or extraneous information. It is appropriately sized for the tool's simplicity.

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 that there are no parameters, no output schema, and good annotations, the description fully specifies the tool's scope ('all alarms and timers') and the included fields. This is complete for a simple list operation.

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 (coverage 100% vacuously). The description doesn't need to explain parameters, and the baseline for 0 parameters is 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 clearly states the function with the verb 'List' and the resource 'alarms and timers', adding details about schedule and repetition days. This distinguishes it from sibling tools like set_alarm and delete_alarm, which have mutation purposes.

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

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

No explicit guidance is provided about when to use this tool versus alternatives. The read-only nature is implied by 'List' but there is no mention of set_alarm or delete_alarm for modifications, so the usage context is only implicit.

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 safety aspects. The description adds useful context about the returned fields and the domain purpose of apps, but does not detail return structure or edge cases like empty lists. This is sufficient for a simple list operation.

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, with the primary action and output fields in the first sentence and a brief domain context in the second. Every sentence adds value without unnecessary verbosity.

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 no parameters and no output schema, the description fully covers what the tool does, what it returns, and the scope ('all installed apps'). It is independently understandable and 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 input schema has zero parameters, so the baseline is 4. The description does not need to explain parameter semantics and correctly omits any invented details; it focuses on describing the output.

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 identifies the action ('List all installed Homey apps') and specifies the output fields (version, enabled status, origin). It distinguishes this tool from siblings like list_devices and list_flows by focusing on apps.

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

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

The description provides clear context for when to use the tool: to see installed apps and their metadata. It does not explicitly mention alternatives or exclusions, but since no sibling tool lists apps, the usage context is unambiguous.

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

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

With annotations already declaring readOnlyHint=true and destructiveHint=false, the description adds useful behavioral context by noting that it returns live sensor/state values and that filters use partial matching. This goes beyond the annotation baseline, though it does not disclose every potential behavior (e.g., pagination).

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 concise sentences, front-loaded with the core purpose and followed by useful filter instructions. Every sentence earns its place with 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?

Given that there is no output schema, the description appropriately enumerates the returned fields. The tool is simple (two optional filters), and the description covers purpose, filters, and output, making it complete for this low-complexity 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 provides 100% coverage for both parameters with descriptions, giving a baseline of 3. The tool description adds extra value by giving concrete examples (e.g., 'kitchen', 'light') and explicitly stating the partial match behavior, which enriches the meaning 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 the tool lists all Homey devices with current capability values, using a specific verb and resource. It also specifies the returned fields, making it distinct from a generic listing. Although it doesn't explicitly mention sibling tools, its scope is unambiguous.

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

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

The description provides clear context on how to use the optional filters ('zone' and 'class') and even explains partial matching behavior. However, it does not mention when to prefer this over the sibling 'search_devices' tool, so it lacks explicit alternatives or exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description adds the behavioral detail that it 'shows which drivers are ready,' which gives some output context. However, it does not elaborate on the return format or meaning of 'ready,' providing only marginal value beyond annotations.

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

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

The description is two sentences, front-loaded with the core action ('List all available device drivers') and then a brief usage context. Every word earns its place, making it highly concise 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?

For a zero-parameter list tool with strong annotations (readOnly, non-destructive), the description is sufficiently complete. It states the resource type, the scope ('all'), and the practical use ('shows which drivers are ready'). The lack of an output schema is not a gap because the description gives a reasonable expectation of the result, and the tool is simple.

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 rule for 0 params is a baseline of 4. The description adds no parameter information (none needed), and with schema coverage at 100% (empty schema fully covers the parameter space), the score appropriately reflects that no additional meaning is required.

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

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

The description clearly states the verb 'List' and the resource 'all available device drivers' with the clarifying parenthetical '(protocol integrations)'. It differentiates from sibling tools like list_devices and list_apps by specifying the resource type precisely.

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 context: 'Useful for troubleshooting — shows which drivers are ready.' This tells the agent when to use the tool, though it does not explicitly name alternatives or conditions when not to use it, so it falls 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 mark readOnlyHint and destructiveHint. Description adds that there are hundreds of cards and that it returns id+title, which helps the agent understand the scope and result structure.

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

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

Two sentences with examples, no fluff. Front-loaded with purpose and alternatives.

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 3 parameters, 100% schema coverage, and annotations, the description is sufficient. It mentions return fields and filtering but could hint at pagination or limit default, though schema already states limit default 60.

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 covers all parameters, but description adds real-world usage context with filtering examples (device UUID, 'windowcoverings', etc.), giving meaning 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?

Description clearly states the tool lists flow cards of a given type (trigger/condition/action), distinguishing it from siblings like list_flows. It uses specific verb 'list' and resource 'flow cards' with a filter on type.

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 tells when to use (for listing cards of a specific type) and when not to use (use get_flow_card for full args). Provides concrete filtering examples like device UUID or keywords.

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, so the safety profile is covered. The description adds value by disclosing the return payload (flow ID, name, enabled/broken status, type) and the domain definition of flows. This is useful behavior context beyond annotations, especially 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 three sentences and each earns its place: the first states the action and scope, the second lists the returned fields, and the third defines flows in Homey context. It is front-loaded with the action and concise, with no redundant or vague wording.

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

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

For a zero-parameter, read-only list tool with no output schema, the description is complete: it states what is listed, what is returned, and what flows are. The annotation covers safety, and no additional information is needed for an agent to select and invoke this 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 has zero parameters, and schema description coverage is 100% (vacuously). The baseline for 0 parameters is 4. The description does not need to explain parameters because there are none; it focuses on the listing behavior and return data.

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 'List all automation flows' with the specific verb 'list' and resource 'automation flows'. It also specifies the scope ('simple and advanced') and the return fields (ID, name, enabled/broken status, type), distinguishing it from sibling tools like list_devices and list_variables. The added explanation of flows as Homey's automations with WHEN/AND/THEN logic further clarifies the resource.

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 as the go-to tool for listing all flows, but it does not explicitly mention when to use this tool versus alternatives. There is no guidance about using trigger_flow or set_flow_enabled for flow actions, nor any exclusions. The context is clear enough for a simple list operation, but alternatives are not addressed.

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. The description adds value by stating the return fields ('log ID, title, data type, and units') and its scope ('all available'), which helps the agent understand the output without an output schema. 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 two sentences, front-loaded with the action ('List all available insight logs'), and every part contributes useful information. No unnecessary detail 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?

For a zero-parameter, read-only list tool with good annotations, the description is sufficiently complete. It explains what is returned and how to proceed, making it fully usable for an agent without needing additional 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?

The tool has zero parameters, and the input schema is fully covered, so the baseline is 4. The description doesn't need to add parameter details, but it does mention the log ID in the context of retrieval, which is slightly helpful for downstream 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 function: 'List all available insight logs' with specific types in parentheses. It distinguishes itself from siblings like get_insight_entries by focusing on listing logs rather than retrieving entries, and from other list tools by specifying insight logs.

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 usage guidance by explaining the follow-up action: 'Use the log ID with get_insight_entries to retrieve historical data.' This implies when to use this tool (to get an overview of logs) and what to do next. It lacks an explicit exclusion or alternative, but the workflow is well-defined.

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. The description adds value by explaining that moods are per zone and provides an example, enriching the semantic understanding beyond the annotations. No contradictions exist.

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 concise, well-structured sentences immediately convey the tool's purpose and meaning, with no wasted words. The example is helpful and directly supports comprehension.

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

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

Given the tool's simplicity (no parameters, no output schema) and strong annotations, the description fully covers the concept, scope, and typical use case. It is complete for an agent to understand and invoke 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 tool has zero parameters, so the baseline is 4. The description adds context about what the list contains (moods per zone) and what moods represent, which is sufficient for a parameterless tool.

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

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

The description clearly states the tool lists all moods (scenes/presets) per zone, using a specific verb ('List') and resource ('moods'). It distinguishes itself from sibling tools like set_mood by focusing on listing rather than activation, and clarifies what moods are with an example.

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 that moods are device-state presets that can be activated together, implying this tool is used to discover available moods. It does not explicitly mention alternatives or exclusions, but the context is strong enough for an agent to infer appropriate usage.

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, so the safety profile is covered. The description adds extra behavioral details: the fixed limit of 50, the 'newest first' order, and the types of notifications included, which go beyond the annotations.

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

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

The description is two short sentences, immediately states the action and resource, and includes only essential details (limit, types, ordering). No wasted words, front-loaded with the core purpose.

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 list tool with no parameters and no output schema, the description gives enough context for the agent to know what it returns (notifications, limited to 50, newest first). It stops short of describing the fields in each notification, but this is a minor gap given the simplicity of 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 tool has zero parameters, so the schema coverage is 100% and there is nothing to explain. The baseline for zero params is 4, and the description does not need to add further parameter semantics.

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

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

The description clearly states the verb 'List' and the resource 'notifications', with specific scope (50 most recent), content types (app updates, alerts, system messages), and ordering (newest first). This distinguishes it from sibling tools like list_devices or create_notification.

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

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

The description implies when to use this tool (to view recent Homey notifications) and provides context about the 50-item limit and sorting. It does not explicitly mention alternatives or exclusions, but no other sibling tool lists notifications, so the guidance is adequate.

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, so the safety profile is covered. The description adds behavioral context beyond annotations: variables hold typed values and are used in flow logic, which clarifies the nature of the returned data and the tool's purpose.

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: the first states the action and result, the second provides useful background on logic variables. Every word earns its place, with 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?

For a simple no-parameter list tool with readOnly annotations and no output schema, the description fully covers what the agent needs: what is listed, what the values are, and how variables are used. The combination of description and annotations is sufficient.

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

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

The input schema has zero parameters, so there is nothing to document. The baseline for 0 parameters is 4, and the description doesn't need to explain parameter behavior. It correctly focuses on what the list returns.

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 'List all logic variables with their current values' — a specific verb (list) and resource (logic variables). It distinguishes itself from siblings like set_variable by focusing on reading variable state, not modifying it.

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

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

The description gives context on what logic variables are ('store state (boolean, number, string) that can be used in flow conditions and actions'), implying it's for inspecting variable state. It doesn't explicitly exclude alternatives or name set_variable, but the sibling list makes the use case clear.

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

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

Annotations already indicate a safe read operation (readOnlyHint=true, destructiveHint=false). The description adds value by disclosing what data is returned (zone ID, name, parent zone, icon) and the tree structure (Home → Floors → Rooms), which is useful contextual behavior beyond the annotations.

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

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

The description is two sentences, front-loaded with the core purpose, and every word earns its place. It efficiently conveys the action, resource, return fields, and hierarchy without any 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?

Despite lacking an output schema, the description specifies the return fields and hierarchy, which is sufficient for a simple list tool with no parameters. The agent can predict exactly what to expect, making the description complete in 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?

The tool has zero parameters, and the input schema is empty with 100% schema coverage. Per baseline rules, a score of 4 is appropriate since there is no parameter information needed; the description appropriately does not try to invent parameter details.

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

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

The description uses a specific verb ('list') and resource ('zones') while clarifying that zones are rooms/areas in the home. It further specifies the hierarchical structure and return fields, making its purpose unmistakable and distinct from sibling tools like list_devices or list_apps.

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

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

The description clearly implies when to use this tool (when you need zone information like rooms/areas and their hierarchy), but it does not explicitly mention alternatives or exclusions. The context is clear enough for the agent to infer usage without needing an explicit 'use this instead of list_devices' statement.

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 indicate idempotent and non-destructive. Description adds no further behavioral context (e.g., side effects or constraints), so it's adequate but not enhanced.

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, no unnecessary words. First sentence states purpose, second gives usage guidance. Perfectly concise and front-loaded.

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

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

Given the simple action with two well-described parameters and no output schema, the description is sufficiently complete. Could mention success/failure or constraints, but not essential.

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?

Both parameters have schema descriptions (Device ID, Target zone ID). The description adds value by telling the user to use list_zones and list_devices to obtain these IDs.

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 ('Move a device to a different zone (room)') with specific verb and resource. It distinguishes from siblings like rename_device or set_device_capability.

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 obtaining prerequisite IDs using list_zones and list_devices. Lacks explicit when-not-to-use or alternatives, but the guidance is clear.

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

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

Annotations already indicate destructive and idempotent behavior. The description adds valuable context about the 2-3 minute downtime and typical problem scenarios. It does not contradict the annotations and improves transparency beyond the structured data.

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

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

Three short sentences, each adding distinct value: what it does, how long it takes, and when to use it. No filler or redundancy. Perfectly front-loaded with the action.

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 no-parameter tool, the description is complete. It covers the operation, downtime, and use case. No output schema exists, so no return-value explanation is needed. The context is sufficient for an agent to select 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 tool has zero parameters, so the baseline is 4. The description does not need to explain any input semantics. It correctly omits parameter information, and the empty schema is fully covered.

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?

Clearly states the action ('Reboot the Homey Pro') and the specific resource. Differentiates from sibling tools like restart_app (which restarts an app, not the whole device). The description adds 'Pro' and purpose context, going beyond a mere restatement of the title.

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 use cases: 'resolve stale devices or Z-Wave/Zigbee mesh issues after firmware updates.' Also conveys the downtime expectation. No explicit exclusion or alternative is mentioned, but the context is clear enough for a tool with no close sibling (restart_app is distinct).

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 indicate idempotentHint=true and destructiveHint=false, so the description adds no additional behavioral context (e.g., effects, prerequisites, error conditions). This is a missed opportunity to clarify the rename behavior.

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

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

Two sentences, front-loaded with the core purpose and a useful prerequisite hint. 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 is complete for a simple mutation tool with two parameters and no output schema. It covers the action and ID sourcing. Could mention return type or side effects, but not necessary given the low 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%, and the descriptions in the schema are clear. The tool description adds value by directing the agent to use list_devices to find the device ID, which goes beyond the schema's property descriptions.

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 ('Rename') and resource ('a device'), and suggests using list_devices to find the ID. However, it does not explicitly differentiate from sibling tools like set_device_capability for changing other properties.

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 usage hint by referencing list_devices to get the device ID, which is helpful. However, it does not explain when to use this tool versus alternatives (e.g., set_device_capability for other changes) or 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 idempotentHint=true and destructiveHint=false, and the description's 'restart' is consistent with these. The description adds a bit of context about unresponsive devices, but doesn't disclose further behavioral details like temporary disconnection of devices during restart. With annotations covering the safety profile, this is adequate but not exceptional.

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 action, then usage context and a helpful hint. Every sentence earns its place 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?

For a simple tool with one parameter, no output schema, and clear annotations, the description covers the purpose, when to use it, and how to get the required ID. It is sufficiently complete for an agent to select 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 provides full coverage of the single 'id' parameter with a clear description and examples. The description repeats the example ('com.fibaro') and adds a reference to list_apps, but this is more of a usage guideline than new parameter meaning. Since schema coverage is 100%, 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 ('Restart a Homey app') with a specific verb and resource. It distinguishes itself from sibling tools like enable_app and uninstall_app by focusing on restarting an app, not enabling/disabling or removing it.

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

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

Provides a clear use case: 'Useful when devices from that app are unresponsive.' It also tells users how to find the app ID via list_apps. However, it does not explicitly mention when not to use it or name alternative tools (e.g., enable_app if the app is disabled), so it misses the full top score.

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 the operation as read-only, but the description adds valuable behavioral context: matching occurs across name, class, and capability names, and the result includes current values. This goes beyond the schema and annotations, though it does not specify details like case sensitivity or match type (exact vs partial).

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 primary action, and includes practical examples without wasted words. It is succinct 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?

With a single parameter, read-only annotations, and no output schema, the description fully covers the necessary context: search scope, return content, and usage examples. It is complete for an agent 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 fully describes the query parameter with the same matching criteria. The description adds examples but no new parameter attributes (format, constraints). Given 100% schema coverage, a 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 verb ('Search devices') and the specific searchable attributes (name, device class, capability name), distinguishing it from sibling tools like list_devices and get_device. It also states the return value (matching devices with current values), making 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?

The description explicitly states the use case: finding devices when the exact ID is unknown. It provides concrete examples ('temperature' for sensors, 'kitchen' for name matches), which gives clear guidance on when to use this tool rather than alternatives that require an ID.

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 indicate readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description aligns with these by stating create/update behavior, but adds no further behavioral context about side effects, permissions, or edge cases. It meets the baseline but does not exceed it.

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 primary purpose, and contains no superfluous information. Every phrase 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?

The tool has a nested repetition object and 5 parameters, but the schema fully documents each field, including the id behavior (omit to create new). The description covers the core purpose and format, and no output schema is needed. It is complete enough for a simple create/update tool, though it could theoretically mention id-based updates more explicitly (but schema already does).

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 already documented. The description mentions 'time in HH:MM format' and 'which days to repeat,' which are redundant with the schema. It adds no new semantic meaning beyond what the schema provides, so a 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 'Create a new alarm or update an existing one,' specifying the verb (create/update) and resource (alarm), distinguishing it from list_alarms and delete_alarm. It also adds useful detail about time format and optional repeat days.

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 (when you want to create or update an alarm) but does not explicitly contrast with alternatives like list_alarms or delete_alarm. The sibling context makes the intent clear, but no direct exclusion or prerequisite guidance is provided.

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

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

Annotations already state readOnlyHint=false and idempotentHint=true. The description adds behavioral context by explaining capability value types (boolean for onoff, number ranges for dim/volume_set) and directing users to inspect current values via get_device. It does not contradict annotations and provides useful usage context beyond the 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 two sentences, front-loaded with the primary action and immediately followed by actionable examples and a usage hint. No wasted words; 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 simple set operation with three parameters and no output schema, the description covers the essentials: what it does, common capabilities, value types, and how to discover available capabilities. It lacks explicit error-handling details, but these are not critical for this tool's basic use case.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by mapping capabilities to concrete value types and ranges (boolean for onoff, number 0-1 for dim, target_temperature as number), enriching the meaning of the 'value' 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 clearly states the tool's function: 'Control a device by setting a capability value.' It names specific capability examples (onoff, dim, target_temperature, volume_set) and provides value types, distinguishing it from siblings like get_device (read) and set_variable (variables).

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: 'Use get_device first to see available capabilities and their current values.' This establishes a clear prerequisite. It does not explicitly contrast with alternatives like set_variable, but the domain-specific focus and the get_device hint make the intended use clear.

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

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

Annotations already indicate a non-readonly, idempotent, non-destructive operation. The description adds behavioral context beyond that by stating that disabled flows won't trigger, which clarifies the real-world effect of the operation. It does not fully detail error conditions or return values, but for this simple setter, the added context 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?

The description is two sentences long, with every sentence contributing meaning: the first states core functionality, the second provides a key behavioral consequence and a practical reference to list_flows. 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?

For a tool with only two simple parameters and no output schema, the description covers what the tool does, the behavioral effect, and how to obtain the required ID. It is complete for an agent to correctly select and invoke the tool without additional ambiguity.

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 'id' described as 'Flow ID' and 'enabled' as 'true to enable, false to disable'. The description adds value by telling users to use list_flows to find the flow ID, and the phrase 'Enable or disable a flow automation' reinforces the enabled parameter's semantics. This goes beyond the schema's minimal descriptions.

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 with a specific verb ('Enable or disable') and resource ('flow automation'), and distinguishes it from siblings like list_flows and trigger_flow by focusing on the enabled state. It also adds a clarifying consequence ('Disabled flows won't trigger') that reinforces the 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 description explicitly directs users to list_flows to find the flow ID, covering the prerequisite. It implies the use case (enabling/disabling a flow) but does not explicitly name alternatives like trigger_flow for manual execution. The context is clear and practical, but lacks an explicit when-not-to-use statement.

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

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

Annotations already cover safety (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description adds useful context by mentioning the screensaver animation and suggesting get_ledring for valid values. This goes slightly beyond the schema and annotations.

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

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

The description is two concise sentences, front-loaded with the action, and includes a helpful pointer to get_ledring without any wasted words.

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

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

For a simple one-parameter setter with robust annotations and no output schema, the description provides sufficient context: what it does, how to find valid values, and the safety profile is covered by annotations.

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% for screensaverId, but the description adds extra meaning by pointing users to get_ledring for valid options, which helps understand the parameter's domain. This adds value beyond the schema's basic examples.

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 ('Set the LED ring screensaver animation') with a specific verb and resource, and distinguishes it from get_ledring by telling users to use get_ledring for available options. This is a clear, specific 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 description advises using get_ledring to see available options before setting, which is a clear usage guideline. It doesn't explicitly say when *not* to use it, but there are no competing siblings for this action, so this is sufficient.

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

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

Annotations already indicate the tool is non-read-only, idempotent, and non-destructive. The description adds the behavioral effect that it sets all devices in the mood to their saved states, which is useful context but not a deep disclosure beyond what the action itself suggests.

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 long, front-loaded with the verb 'Activate', and contains no unnecessary words. Every sentence contributes meaning, and the structure is clean.

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, no output schema, and annotations provided, the description is adequate. It explains what the tool does and the effect on devices. It could mention return behavior or prerequisites, but the schema and annotations cover most essentials.

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 both parameters (Mood ID, Zone ID) with 100% coverage. The description adds minimal extra meaning by clarifying that a mood is a 'scene' and that it's zone-specific, but it doesn't delve into parameter formats or relationships.

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 a specific action ('Activate') applied to a specific resource ('mood (scene) in a zone') and explains the effect ('sets all devices in the mood to their saved states'). This distinguishes it from sibling tools like list_moods or set_variable.

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

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

The description implies when to use the tool: when you want to activate a mood in a zone. However, it doesn't explicitly mention alternatives or provide exclusions (e.g., 'use list_moods to see available moods'). Usage is implied but not elaborated.

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

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

Annotations already declare non-read-only, idempotent, and non-destructive. The description adds behavioral context beyond annotations by explaining that this affects presence-based automations, which is valuable for understanding consequences. No contradiction 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?

Two concise sentences front-load the purpose and then add the important consequence. No wasted words, every sentence serves a clear purpose.

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 simple tool with two optional boolean parameters, strong annotations, and full schema descriptions, the description covers the essential selection and invocation context. It could mention what happens if both parameters are omitted, but this is not critical for basic 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%, with both parameters (asleep and present) fully described. The description adds high-level meaning by framing them as 'presence (home/away)' and 'sleep state (awake/asleep)', but this largely restates the schema, 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?

The description clearly states it sets presence (home/away) or sleep state (awake/asleep), using a specific verb and resource. This distinguishes it from sibling tools like get_presence and other set_ 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 when to use this tool: to set your own presence or sleep state, and notes that it affects automations. While it doesn't explicitly list alternatives or exclusions, the context is unambiguous given the sibling tool names.

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

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

Annotations already indicate this is a non-read-only, idempotent, non-destructive operation. The description adds useful behavioral context by stating the name is visible in network discovery and the Homey app, informing the agent of the impact of the change. It doesn't contradict annotations and provides additional value beyond the safety profile.

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 sentence that front-loads the action and includes only relevant context. Every word earns its place, 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?

For a simple one-parameter setter with annotations and no output schema, the description sufficiently covers what the tool does and the effect of the parameter. It could mention return values or permission requirements, but given the tool's simplicity, it is complete enough. Score 4 as it is not exhaustive but adequate.

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

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

Schema coverage is 100%, with the 'name' parameter described as 'New system name'. The description reinforces that the parameter sets the system name and adds visibility context, but does not add new parameter-level details beyond the schema. Baseline of 3 applies given 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 the action ('Set the Homey system name') and the resource affected, with context about where the name is visible (network discovery and the Homey app). This is a specific verb+resource pair that distinguishes it from all sibling tools, none of which handle system name changes.

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 the use case (renaming the Homey system) and adds context about visibility, which helps the agent decide when to use this tool. It doesn't explicitly mention alternatives or exclusions, but no direct alternatives exist among the sibling tools. Clear context without explicit exclusion earns a 4.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=true, so the write and idempotent nature is disclosed. The description adds the type-matching constraint, but this is also present in the schema property description ('must match variable type'). No additional behavioral context (e.g., error handling, permissions) is provided, which is acceptable for a simple setter but does not exceed baseline.

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 short sentences, front-loaded with the action, and contains no filler. Every word contributes to understanding the tool's core purpose and constraint.

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

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

For a simple two-parameter tool with no output schema and strong annotations, the description is adequate. It covers the purpose and the key type constraint. A minor gap is not stating behavior if the variable does not exist or the type mismatch handling, but this does not significantly hinder 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 coverage is 100%, with both parameters described ('Variable ID' and 'New value (must match variable type)'). The description repeats the type constraint and lists allowed types, but adds no new meaning beyond what the schema already provides. 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 clearly states the action ('Set') and the resource ('logic variable'), which is specific and unambiguous. It distinguishes from siblings by focusing on variable mutation, while list_variables is the only related sibling and covers reading, not writing.

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: use when you need to set the value of a logic variable. There are no exclusions or alternatives mentioned, but the tool's purpose is self-evident given the name and sibling set, so no when-not guidance is necessary.

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

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

Adds behavioral detail beyond annotations: 'Tries simple flow first, then advanced flow' and 'immediately' describe execution order and immediacy. Annotations already cover read-only/destructive/idempotent hints, so this extra context enriches understanding 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?

Two concise sentences with no filler. The purpose is front-loaded, followed by a useful behavioral note and a direct lookup instruction, making every sentence earn 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 a single parameter, no output schema, and existing annotations, the description fully covers purpose, prerequisite, and key behavior. Sibling context reinforces that this is the only flow-triggering tool, so no further details are necessary.

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 describes 'id' as 'Flow ID' with 100% coverage, and the description reinforces it by stating 'by its ID' and pointing to list_flows for lookup. This adds practical guidance on how to obtain the value, going beyond the schema's minimal label.

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 'Trigger (run) a flow immediately by its ID' – a specific verb and resource that clearly conveys the action. It distinguishes from sibling tools like list_flows and set_flow_enabled by focusing on execution rather than listing or toggling.

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 instructs 'Use list_flows to find the flow ID,' providing prerequisite guidance for obtaining the required parameter. No alternative trigger tool exists among siblings, so context is clear, though it lacks an explicit 'when not to use' statement.

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 value beyond the destructiveHint annotation by disclosing that it removes the app's devices and that the operation is irreversible. This gives the agent crucial context about 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 one concise sentence that conveys the purpose, scope, and irreversibility without waste. It is front-loaded and easy to parse.

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 one parameter and no output schema, the description is complete. It specifies the action, the target, the side effect (device removal), and the irreversibility. It does not mention permissions or other edge cases, but these are not critical given the tool's simplicity.

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 has one parameter 'id' with a description 'App ID', which fully covers the parameter. The description adds no additional parameter semantics, so the baseline of 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's verb ('uninstall'), the resource ('Homey app'), and the scope ('and remove all its devices'). It distinguishes itself from sibling tools like restart_app or enable_app by emphasizing permanent removal.

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 context is clear: this is for permanently removing an app. The phrase 'cannot be undone' implicitly warns against using it for temporary actions, but it does not explicitly name alternatives or 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 provide readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds that replacing cards replaces the entire flow graph and returns 'broken status', which is useful context. However, it does not explain idempotency implications or potential side effects (e.g., if cards is omitted, are other fields reset?). The return value 'broken status' is ambiguous without further clarification.

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: first states the action, second provides partial update guidance, third warns about replacement and mentions return status. No redundant or filler content. Front-loaded with purpose. Excellent conciseness for the complexity involved.

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 parameters, nested object, no output schema), the description covers key pitfalls: partial updates, full replacement of cards, need to fetch first, and return status. However, it lacks explanation of error states, validation rules, or what 'broken status' entails. The idempotency annotation is not leveraged. Still, it provides sufficient context for an agent to use the tool correctly in most cases.

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