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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the agent knows this is a non-read, non-idempotent operation. The description adds the level enum semantics (1=Normal, 2=Status, 4=Error) and a cross-reference to `domoticz://logs`, which is useful context. However, it doesn't disclose what happens on success/failure, whether the message is truncated, or any side effects beyond writing to the log.

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 very short and front-loaded: 'Log message' immediately states the action. The level mapping is compact and useful. The cross-reference is a single extra detail. No wasted words, though it could arguably be even more informative without becoming bloated.

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 with 100% schema coverage and an output schema, the description is mostly adequate. The main gap is that it doesn't explain the behavior of the log (e.g., whether messages are visible immediately, any rate limits, or what the output schema contains). The cross-reference to `domoticz://logs` hints at where to view results, which helps, but the description could be more complete about the operation's effect.

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. The description adds the level mapping (1=Normal, 2=Status, 4=Error) which is also in the schema's enum descriptions, so it's redundant. The cross-reference to `domoticz://logs` adds a small amount of context but doesn't meaningfully enhance parameter understanding beyond the schema.

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

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

The description states a clear verb+resource: 'Log message' with level semantics. It distinguishes itself from siblings by being the only logging tool among the listed siblings, though it doesn't explicitly name an alternative. The title 'Add Domoticz log message' 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 implies usage: it's for adding a log message to Domoticz, with level values explained. It doesn't explicitly state when to use this vs alternatives, but the sibling list contains no other logging tool, so the context is clear enough. No exclusions or alternative routing are 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 indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=trueikuha. The description does not explicitly state that this tool creates a new variable (which is a write operation), but the verb 'Add' implies mutation . It does not add context beyond the annotations, such as potential side effects or authentication needs. Since annotations already cover the safety profile (non-destructive, not read-only), the description adds some value but not rich behavioral context. No contradiction with annotations is 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 very short and to the point, with the core action stated first. It includes the vtype mapping which is useful. It is not overloaded with unnecessary content, but it could have added a bit more context on usage without harming conciseness.

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

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

Given the simplicity of the tool (3 parameters, no nested objects, all required) and the existence of an output schema, the description is adequate for basic usage. However, it lacks any mention of potential error conditions, naming constraints (though schema specifies min/max length), or behavioral notes like whether the variable will be overwritten if the name exists. The annotations cover safety, and the schema covers parameters, so the description is sufficient but not comprehensive.

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%, meaning the schema documents all three parameters (name, value, vtype) with descriptions. The description adds the vtype mapping (0-4) which is redundant with the schema's enum description, but it does provide the parameter list in a compact form. The description does not add significant meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description states the verb 'Add' and the resource 'user variable', making the core purpose clear. It does not explicitly differentiate from sibling tools like update_user_variable or delete_user_variable, but the resource type is distinct enough that an agent can infer the operation. The description is concise but could be more explicit about the specific action compared to alternatives.

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

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

The description implies the tool is for creating new user variables, which is clear from the name and description. It does not provide explicit when-to-use guidance or mention alternatives (e.g., update_user_variable for existing variables), but the context of sibling tools and the schema (required name, vtype, value) makes the usage reasonably inferable. It lacks explicit exclusions or conditions, so it is adequate but not strong.

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 destructiveHint=true and readOnlyHint=false, so the agent already knows this is a high-impact operation. The description adds the requirement 'Requires confirm=True', which provides actionable behavioral context beyond the schema (the schema has default false). It does not contradict annotations and adds modest value.

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

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

The description is two short sentences with zero fluff. The core purpose ('Raw API call') is front-loaded, followed by usage guidance and a critical requirement. Every word 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 raw fallback tool, the description is minimal but sufficient for an expert, especially with an output schema present. It does not explain the expansive power of the API or potential misuse beyond the confirm requirement, but the annotations already signal destructiveness. It's adequate but could warn more explicitly about the breadth of operations.

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

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

The schema covers 100% of parameters with descriptions, but those descriptions are generic ('Domoticz command parameter', 'Additional Domoticz query parameters'). The description adds the semantic guidance that confirm must be true, which is valuable. However, it does not clarify the meaning of param or kwargs further, so it only marginally improves on schema.

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

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

The description states a clear verb ('call') and resource ('raw Domoticz API'), distinguishing it as a generic fallback from the sibling-specific tools. It's more specific than a tautology, but it doesn't describe what kinds of operations it can perform beyond being a raw API call. The title 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 says 'Use if dedicated tools fail', giving a clear condition for when this tool should be invoked. It implies the alternative (dedicated tools) but doesn't list them; the sibling list provides that context. It does not state explicit exclusions, but the fallback role 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 convey that the tool is not read-only, is destructive, and is idempotent, so the description carries a low bar. Yet it adds no behavioral context beyond restating the command values already present in the schema pattern, and it does not describe physical movement, side effects, or what 'Stop' does. It does not contradict the annotations, but it also does not enrich them.

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 terse and front-loaded, with no filler or redundant explanation. It loses the fifth point because the fragments add little beyond what the schema already provides and omit the critical identifier requirement.

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?

Both idx and name are optional in the schema, and the description never states that at least one identifier must be supplied; an agent could attempt to invoke the tool with only command and fail. The description also does not explain the operational context of controlling blinds (e.g., physical motion, stopping mid-travel), leaving the annotations and schema to carry nearly the full burden.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's 'Preferred: idx' merely restates the schema's own note that idx is 'preferred over name when known', adding no new semantic meaning. The command list likewise duplicates the schema's command description and pattern.

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

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

The title 'Control blinds' plus the explicit command list 'Open'/'Close'/'Stop' makes it clear the tool operates blinds. It is distinguishable from sibling switch/dimmer/API tools because those handle different resources or use different action verbs. However, the description is a fragment rather than a full statement of the tool's purpose, so it falls short of a 5.

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

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

The description offers no guidance on when to select this tool over alternatives; it only says 'Preferred: idx', which is a parameter preference, not a tool-selection rule. With many sibling control tools, the absence of any when-to-use or when-not-to-use guidance is a clear gap.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the agent knows this is a non-idempotent write operation. The description adds no behavioral detail beyond 'Create script' – it does not mention failure modes, duplicate name handling, or side effects. The cross-reference is about syntax, not behavior. 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 extremely concise – two short sentences, with the core action 'Create script' front-loaded and the cross-reference as a secondary note. No wasted words, though it could be seen as under-specified rather than efficiently concise. It is structured well for a quick scan.

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 5 parameters (4 required) including a complex xmlstatement field, the description is inadequate. It does not explain what an event script is, what event_type options exist, how to construct xmlstatement, or what the tool returns (though an output schema exists). The cross-reference to docs may help, but the description is not self-contained and leaves the agent to infer too much. Given the schema and annotations, it is still not complete enough to use confidently.

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

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

Schema description coverage is 100%, so each parameter already has a description. The tool description adds no extra meaning about parameters, such as how event_type and interpreter relate, or what a valid xmlstatement looks like. Since the schema covers the basics, a baseline of 3 is appropriate; the description does not compensate beyond that.

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

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

The description states a clear verb ('Create') and resource ('script'), and the title clarifies it is an event script. It is distinguishable from siblings like update_event (create vs. update) and search_scripts_tool (create vs. search), though it does not explicitly mention those distinctions. The cross-reference to dzvents_syntax adds context about what kind of script is created.

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

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

No guidance is provided on when to use this tool versus alternatives. It does not mention that this creates a new event as opposed to updating an existing one, nor does it reference any prerequisites or related tools. The only hint is the cross-reference to syntax docs, which is not usage guidance.

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

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

Annotations already declare the operation is mutating, non-idempotent, and non-destructive, so the description doesn't need to repeat those. However, the description adds no behavioral context of its own, such as whether a new device appears immediately or what side effects creation has. There is no contradiction with annotations, but no additional transparency either.

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

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

The description is short but under-specifies rather than being effectively concise. The cross-ref is cryptic, and the text does not front-load useful context an agent can act on. This is more under-specification than intentional conciseness.

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

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

For a tool with three required parameters, an output schema, and many similar siblings, the description leaves the agent to infer what a 'dummy' is, how sensortype numbers work, and what the hardware cross-reference means. Output schema covers return values, but prerequisites and operational effects are absent. The definition is too thin to be contextually 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%, with meaningful descriptions for hw_idx, sensorname, and sensortype. The tool description adds no semantic value beyond those field descriptions. Baseline 3 is appropriate because the schema already carries the parameter 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 'Create dummy' is essentially a colloquial restatement of the title 'Create virtual sensor' rather than a precise explanation. It doesn't clarify what a dummy/virtual sensor is or how it differs from siblings like add_user_variable or create_event. The cross-ref to hardware hints at scope but doesn't specify the action's outcome.

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

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

There is no guidance on when to use this tool versus sibling tools, nor any prerequisites such as requiring an existing hardware index. The cross-ref to domoticz://hardware implies a relationship but does not explain it. No alternatives, exclusions, or typical use cases are 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 destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the safety profile is covered. The description adds value beyond these by stating the hard requirement 'Requires confirm=True', flagging the confirmation gate, and reframing the operation as non-destructive 'hide' rather than a hard delete. 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?

Five words convey purpose, parameter preference, and a hard requirement, with purpose front-loaded. Zero filler; every clause earns its place and the structure is exemplary for a low-complexity destructive tool.

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

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

For a low-complexity 3-parameter destructive operation backed by an output schema and full annotations, the description covers the essential facts: what it does, the preferred parameter, and the confirmation requirement. Nothing an agent needs to invoke it safely is obviously missing; irreversibility is implied by 'hide' and 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%, so the baseline is 3. The description's 'Preferred: idx' reiterates what the schema already states ('preferred over name when known'). It adds the notion that confirm must be true, a requirement not explicit in the schema's default, which is mildly useful, but overall the description mostly repeats schema-provided 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?

States a specific verb and resource: 'Hide device'. Notably, it reframes the tool name 'delete_device' as a hide operation, which is a materially different action and distinguishes it from destructive siblings like 'delete_user_variable' and 'restart_system'. Purpose is unmistakable.

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

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

No guidance on when to use this tool versus alternatives. 'Preferred: idx' is parameter-preference advice, not usage-context guidance. There is no mention of when to favor this over rename_device, delete_user_variable, or other device tools, nor any exclusions or prerequisites. The 'hide' framing implies context but nothing 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 destructiveHint=true and readOnlyHint=false. The description adds the critical requirement 'Requires confirm=True', which is a behavioral condition not fully captured by annotations. This is valuable context for the agent to know the operation will not proceed without explicit confirmation, beyond what the schema or annotations alone provide.

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

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

The description is two short sentences with zero filler. It front-loads the purpose, then adds the key usage notes. Every word earns its place, and it is immediately scannable.

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 deletion operation, the description covers the necessary points: what it does, the preferred identifier, and the confirmation requirement. Annotations cover the destructive nature, and the schema details each parameter. The presence of an output schema means return values need not be explained. It misses edge cases like what happens if both idx and name are provided, but these are minor and likely handled by the system or output schema.

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

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

Schema coverage is 100%, so each parameter is already described in the schema. The description adds the explicit requirement that confirm must be true, which is not stated as a requirement in the schema (only as 'Explicitly confirm this high-impact operation'). It also reinforces that idx is preferred over name, matching the schema's note but adding a clear directive. This elevates the description above 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 title clearly states 'Delete user variable', and the description 'Delete var' is a concise shorthand that identifies the verb and resource. The addition of 'Preferred: idx' distinguishes it from name-based deletion, though it doesn't explicitly differentiate from other delete tools. Clear enough for an agent to understand the 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 description implies usage by stating 'Preferred: idx' and 'Requires confirm=True', which give conditional guidance. However, it does not explicitly state when to use this tool over alternatives like delete_device or update_user_variable, nor does it mention scenarios where deletion should be avoided. The 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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered by structured data. The description adds a behavioral detail about setting include_instantaneous=False to obtain daily totals, which is useful context beyond the annotations. No contradiction exists, but the description does not go further in disclosing other behaviors (e.g., error cases), which is acceptable 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 two sentences with zero waste. The primary purpose is stated first, followed by a parameter preference and a usage tip. Every word earns its place—there is no filler 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 simple read-only tool with an output schema and readOnly/idempotent annotations, the description covers all essential details. The output schema handles return values, and the annotations cover safety. The description provides the key operational nuance (daily totals vs. instantaneous), so nothing needed to invoke the tool correctly is missing.

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

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

The input schema fully documents all three parameters, so the baseline is 3. The description adds value by indicating that `idx` is preferred over `name`, and by explaining the purpose of the include_instantaneous flag for daily totals. These details go beyond the schema's per-parameter descriptions and help the agent make better parameter choices.

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

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

The description states a specific verb ('Read') and resource ('today's counter history'), making the tool's purpose unmistakable. It naturally distinguishes itself from the weekly and monthly history siblings by the temporal qualifier. The 'Preferred: idx' note also clarifies how to identify the target entity.

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 useful usage tip for the include_instantaneous parameter but does not explicitly mention alternatives like get_weekly_energy_history or get_monthly_energy_history. The word 'today's' implies daily usage, but no direct when-to-use vs sibling tools is given. This qualifies as implied usage rather than explicit guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the read-only safety profile is well covered. The description reinforces this with 'Read' and adds the 'this month's' scoping, but does not describe return behavior or other side effects; with annotations present, this is acceptable.

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, purposeful sentences with no filler. The action and scope are front-loaded, and the parameter preference is given as a concise, actionable instruction.

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 zero required parameters, full schema coverage, an output schema, and strong read-only annotations, nothing needed to invoke it correctly is missing. The scope, parameter preference, and safety profile are all available to the agent.

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

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

The schema covers both parameters at 100%, and the idx schema already states it is 'preferred over name when known.' The description's 'Preferred: idx' mostly echoes the schema rather than adding new semantic information, so 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 ('Read') and resource ('counter history') with a clear time scope ('this month's'), making it easy to distinguish from the sibling tools get_daily_energy_history and get_weekly_energy_history. No ambiguity remains about what this tool fetches.

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: use this tool to read the current month's counter history. It also provides parameter preference ('Preferred: idx'), but it does not explicitly state when not to use it or name the daily/weekly 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 the tool read-only and idempotent, so the safety profile is covered. The description adds value by revealing that the status may be incomplete and requires polling — a behavioral trait not in annotations. However, it doesn't describe what a 'complete' status looks like or any error conditions, leaving some behavioral uncertainty.

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

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

Two short sentences with zero padding. The purpose is front-loaded, and the usage guidance follows immediately. Every word earns its place; there is 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 single-parameter polling tool with rich annotations (read-only, idempotent) and an output schema, the description is fairly complete. It captures the core behavior and next action. Minor omissions like specific status values or authorization requirements are likely covered by the output schema and sibling context, so the description suffices without being exhaustive.

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

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

The schema description fully covers the only parameter flow_id ('Opaque flow identifier returned by start_oauth_login'), so the description doesn't need to add param details. With 100% schema coverage, the baseline of 3 applies; the description doesn't provide additional parameter meaning beyond what's already in the schema.

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

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

The description 'Check a browser login' states a specific verb and resource, and the phrase 'Retry the original operation only after status is complete' clearly ties it to the login flow initiated by the sibling tool start_oauth_login. This distinguishes it from all other siblings and leaves no ambiguity about its function.

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

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

The description gives explicit guidance on when to use it: to check status and only proceed after completion. It implies the prerequisite of starting a login flow via start_oauth_login, though it doesn't name that tool directly. The guidance is clear for the immediate call pattern, but doesn't address alternative tools or failure handling, so it's slightly below perfect.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds domain context about action URLs/scripts and the idx preference, but does not disclose additional behavioral details such as fallback behavior when neither parameter is provided.

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 carry all essential information with no filler. The primary purpose is front-loaded, the parameter preference is stated, and the sibling cross-reference is included economically.

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 rich annotations, full schema coverage for both parameters, and an output schema, the description is sufficient for an agent to select and invoke the tool. The only minor gap—behavior when both idx and name are absent—is already implied by the schema defaults and openWorldHint.

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 idx and name clearly. The description adds only the preference for idx, which is marginal value beyond the schema.

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

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

The description states a specific verb ('Get') applied to a specific resource: the On Action and Off Action URLs or scripts for a switch. This clearly distinguishes it from sibling tools like toggle_switch, set_switch_state, and set_switch_actions.

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

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

The description gives practical guidance by preferring the idx parameter and cross-referencing set_switch_actions, which implies the get-vs-set distinction. It does not explicitly state when to avoid this tool, but the clear sibling reference provides adequate context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds the 7-day window and the idx preference but does not describe other behavioral details, which is acceptable given the output 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?

Two short sentences convey the operation and key parameter guidance with no filler. The action and scope are front-loaded, and every word 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?

Between annotations, full schema coverage, and output schema, the description covers selection and invocation needs. A minor gap is not explaining what a 'counter' is, but the title and schema make it recoverable.

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 descriptions already document both idx and name, including the 'preferred over name' guidance, making schema coverage 100%. The description's 'Preferred: idx' restates the schema rather than adding new 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?

States a specific action ('Read') and resource ('last 7 days of counter history'), which clearly differentiates from daily/monthly siblings by time window. The scope is immediately understandable without opening the schema.

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

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

The description makes the temporal scope explicit, so an agent can route weekly requests here vs daily/monthly alternatives. It does not explicitly name alternatives or exclusions, but the context 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 declare destructiveHint=true, readOnlyHint=false, idempotentHint=true, and openWorldHint=true, so the safety profile is structured. However, the description adds zero behavioral context beyond that — it does not mention that the rename overwrites the existing name, any side effects, or authorization needs. With the annotation burden already covering the basics, a 2 reflects that the description contributes no extra transparency.

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 terse sentences with zero filler. The core action is front-loaded and the only added guidance ('Preferred: idx') is placed immediately, making the description maximally efficient.

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 an output schema exists, all three parameters are documented in the schema, and annotations carry the destructive/mutation/idempotent profile, the description is largely adequate. A fully destructive tool could arguably use one sentence flagging that renaming overwrites the current name, but with the structured fields already covering safety, the short description 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?

Schema description coverage is 100%, so the schema documents idx, new_name, and old_name fully. The description's 'Preferred: idx' guidance does add a minor prioritization signal, but the schema itself already states idx is 'preferred over name when known', so this largely duplicates existing schema information. Baseline 3 is appropriate since the schema carries the load and the description adds little beyond it.

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

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

The description states a specific verb ('Rename') and resource ('device'), making the core purpose unambiguous. It is clearly distinct from siblings like delete_device, create_virtual_sensor, and toggle_switch, though it does not explicitly call out its relationship to update_device_value, which also modifies a device. The purpose is clear but sibling differentiation is left implicit.

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 is given on when to use this tool versus alternatives, and no exclusions are stated. The only hint, 'Preferred: idx', is parameter-selection guidance rather than usage context. An agent is given no indication of when renaming is appropriate compared to, say, update_device_value or delete_device.

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

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

The annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so the description needs only add context. It adds the invocation guardrail 'Requires confirm=True', but does not explain the impact on running processes or expected side effects beyond what the annotation indicates.

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 zero verbiage. The action is front-loaded, and the only extra detail is the essential confirmation constraint. Every word contributes.

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

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

For a one-parameter, destructive tool with a full input-schema description, annotations, and an output schema, the description provides the one thing an agent cannot infer elsewhere: that confirm must be true. No additional rules or hidden context are needed for a correct call.

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

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

The schema covers 100% of the single parameter with its own description/default, but the description's 'Requires confirm=True' is a meaningful addition: it tells the agent the default false is not enough and the value must be true for the operation to proceed.

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 'Reboot server', a specific verb and resource, and the title clarifies it restarts Domoticz. None of the sibling tools perform a system reboot, so an agent can distinguish this tool without opening its schema.

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

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

The description gives no guidance on when this tool should be used versus alternatives, nor does it mention any preconditions beyond confirm=True. 'Requires confirm=True' controls invocation, but not when to call the tool or when not to choose it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the cross-reference to `domoticz://devices` and mentions search by name/status, which provides some context. It doesn't disclose pagination behavior or result ordering, but with annotations covering safety, a 3 is appropriate.

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 plus a cross-reference, which is efficient and front-loaded. The cross-reference is useful but could be considered extra. No wasted words, though the cross-reference format might be cryptic to some agents.

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 search tool with a full output schema and 100% parameter coverage, the description is mostly complete. The cross-reference to `domoticz://devices` adds context. It doesn't mention result ordering or exact matching behavior, but these are minor gaps given the schema and 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 description coverage is 100%, so the schema already documents all three parameters (query, limit, offset) with descriptions. The description adds the 'name/status' search scope, which aligns with the query parameter, but doesn't add significant meaning beyond the schema. Baseline 3 is correct.

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

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

The description states a clear verb and resource: 'Search devices by name/status.' It distinguishes the tool as a device search, which is distinct from sibling search_scripts_tool. However, it doesn't explicitly contrast with search_scripts_tool or other device-related tools, so it's clear but not fully differentiated.

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 searching devices by name/status, and the cross-reference to `domoticz://devices` hints at the data source. It doesn't explicitly state when to use this tool versus alternatives like search_scripts_tool or when not to use it. The context 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, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. However, the description itself adds no behavioral detail beyond a UI cross-reference; it does not mention case-insensitivity, pagination, or any side effects, relying entirely on schema and hints.

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 very short and front-loaded: the core purpose appears in the first sentence. The second sentence is a terse cross-reference that is arguably cryptic, but it is not wasteful. Overall it is appropriately concise for a simple search tool.

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

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

For a read-only search tool, the schema and annotations already convey most of what an agent needs. The main missing piece is guidance on when to use this tool relative to similar siblings like search_devices_tool, so the description is adequate but not rich.

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%: query, limit, and offset each have descriptions. The tool description adds no parameter-specific meaning beyond restating that a string is searched, so it sits at the baseline for fully documented schemas.

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

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

The description states a specific action ('Search') on a specific resource ('string in scripts'), and the title clarifies that scripts are event scripts. It is plainly distinguishable from the sibling search_devices_tool, but it does not explicitly name that alternative or otherwise call out the distinction.

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

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

There is no guidance on when to use this tool versus alternatives. The 'Cross-ref: domoticz://events' line points to a context, but it does not explain usage contexts, exclusions, or when another search tool such as search_devices_tool would be more appropriate.

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

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

The description discloses zero behavioral traits. Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, and the description adds nothing about side effects, delivery guarantees, whether sending is async or blocking, rate limits, or what the returned output schema contains. There is no contradiction, but the description is entirely vacuous on 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?

At three words, the description is short, but this is under-specification, not conciseness. There is no front-loaded value; the entire description merely echoes the tool name. A genuinely concise description would still convey purpose and scope in a sentence or two.

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 relatively simple (2 params, 100% schema coverage, output schema present), which lowers the bar somewhat. But the description provides no context about what a notification is, who receives it, delivery mechanics, or side effects. For a tool that mutates state (readOnlyHint=false), the absence of any behavioral context leaves the agent guessing.

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

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

Schema description coverage is 100%, so both parameters (subject and body) are documented in the input schema with titles and descriptions. Per the calibration baseline, the description need not re-explain them, and it doesn't. However, it also adds no operational meaning beyond the schema – e.g., format constraints, whether subject maps to a display header, or body length semantics beyond maxLength.

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 'Send notification' is a pure tautology – it restates the tool name and title with zero additional information. It does not specify the delivery channel, recipient, medium (email, push, SMS), or how this tool differs from its 30+ siblings. An agent gets nothing beyond the name itself.

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 exists about when to use this tool versus any alternative. None of the sibling tools are mentioned, and there is no context about prerequisites (e.g., whether a user must be logged in, whether a notification service must be configured) or situations where this tool would or would not be appropriate.

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 offers no behavioral disclosures. Annotations indicate readOnlyHint=false and destructiveHint=true, but the description itself adds nothing about side effects, required permissions, or what the operation affects. Since annotations carry the burden and the description does not build on them, this is a significant gap.

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

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

The description is extremely short ('Set RGB. Preferred: idx.'), which is concise but at the expense of substance. It lacks essential context and appears truncated. While no words are wasted, the brevity itself is a deficiency because it fails to convey necessary information.

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

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

Given the tool has 5 parameters and a destructive hint, the description is far from complete. It does not explain when to use it, what scenarios apply, or any behavioral effects. With no output schema details needed (since it exists), the description still fails to provide basic usage context, making it inadequate for an agent to decide when to invoke it.

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

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

The input schema has 100% coverage with descriptions for every parameter, so the baseline is 3. The description adds one useful hint: 'Preferred: idx' clarifies that idx should be used when known, which is helpful. However, it does not contribute anything else beyond what the schema already provides.

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

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

The description states 'Set RGB' which indicates it sets color, but fails to mention brightness explicitly, despite the title including it. It uses 'hue' rather than RGB components, which is slightly confusing. It does distinguish from sibling tools like set_dimmer_level (brightness only) and set_color_temperature (color temperature), but not clearly, as it doesn't specify that it sets both color and brightness.

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 no guidance on when to use this tool versus alternatives. It only says 'Preferred: idx' which is a parameter preference, not a usage context. There is no mention of when to use set_color_brightness over set_dimmer_level or set_color_temperature, nor any exclusions or scenarios.

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, idempotentHint=true, and readOnlyHint=false, covering the safety profile. The description adds minimal behavioral context beyond 'Set', which is expected. It doesn't contradict annotations, but also doesn't disclose additional traits like what happens to existing settings or response format. With annotations present, a 3 is appropriate.

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, front-loaded with the action and scale, and includes the key parameter preference. There is zero 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?

Given the presence of an output schema and annotations covering safety, the description is fairly complete for a set operation. It could mention the effect on the device or reversibility, but those are not essential given the annotation coverage. The scale (0-100) is clarified, and the preferred parameter is highlighted.

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

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

The schema already documents all three parameters with 100% coverage. The description adds value by stating that `idx` is preferred over `name`, which helps the agent choose between ambiguous identifiers. This extra guidance goes beyond the schema's static 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 ('Set') and the resource ('normalized white temperature'), with a specific range (0-100). It distinguishes itself from siblings like set_color_brightness by focusing on temperature, though it doesn't explicitly mention Domoticz or device context. It's clear enough for an agent to understand the core 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 offers only 'Preferred: idx', which is a parameter preference, not guidance on when to use this tool versus alternatives like set_color_brightness or other device controls. There is no mention of scenarios where this tool should be selected, nor any exclusions or prerequisites.

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

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

Annotations already indicate readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so the behavioral state-changing nature is covered. The description adds no extra behavioral context such as side effects, device state impacts, or error behavior. It does not contradict the annotations, so a mid-range score is appropriate.

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

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

The description is short, with each sentence serving a purpose: stating the action, noting the preferred parameter, and providing a cross-reference. It is front-loaded with the core function. It earns a high score for conciseness, though the cross-reference could be seen as slightly tangential.

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 setter tool, the description covers the essential action, value range, and preferred identifier. The output schema and full parameter descriptions fill most remaining gaps. A minor omission is clarifying that idx or name must be supplied, though this is inferable from the schema and the 'preferred' note.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's 'Preferred: idx' reinforces the schema's own note that idx is preferred over name, adding no new semantic content. The description does not explain the name parameter or clarify that at least one identifier is needed, but the schema already covers these 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 states a specific action ('Set brightness') and resource ('dimmer level') with a range (0-100), making the tool's purpose immediately clear. It does not explicitly differentiate from siblings like set_color_brightness, but the tool name and the brightness range help disambiguate. This is clear but lacks explicit sibling 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 offers no guidance on when to choose this tool over alternatives such as set_switch_state or set_color_brightness. The only usage hint is 'Preferred: idx', which concerns parameter selection rather than tool selection. There are no exclusions or alternative references.

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 communicate destructive and read-only traits, and the description adds value by requiring confirm=True and explaining the state values. It does not contradict the annotations and adds a useful guardrail, though it does not detail what happens when confirm is false or how destructive the arming action is.

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

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

The description is extremely compact, front-loaded with the core action, and every part earns its place: the action, the state mapping, the confirmation requirement, and the cross-reference. There is no redundant 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 rich schema, annotations, and output schema, the description is nearly sufficient for a correct call. It covers the critical confirm flag and state values, but lacks any guidance on failure behavior or external side effects beyond what the annotations imply. Still, an agent can invoke the tool correctly with what is provided.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning by explicitly requiring confirm=True and restating the secstatus enum values in a compact form. This goes beyond the schema's default value and helps the agent form a correct call.

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 names the action ('Arm panel') and the resource, and maps the three security states to their numeric values. It is distinct from sibling tools like set_switch_state, though it does not explicitly name any alternative, so it stops short of full sibling 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 direct invocation requirement ('Requires confirm=True') and a cross-reference, but does not state when to prefer this tool over related tools or mention exclusions. Usage context is mostly implied by the tool's purpose rather than explicitly explained.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds the crucial behavioral constraint that confirm=True is required, which goes beyond the raw annotation flags and helps the agent avoid a destructive mistake. It doesn't enumerate reversibility or overwrite semantics, but the annotations plus schema cover most of 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 only two short sentences. It front-loads the core purpose, then gives the two most decision-relevant details: idx preference and confirmation requirement. No filler or redundant restating.

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 destructive, confirmation-gated write tool, the description plus annotations and 100% covered schema are sufficient. The output schema exists, so return details need not be described. It could arguably name sibling alternatives more explicitly, but the definition is already enough to 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?

With 100% schema coverage, the baseline is 3. The description enhances this by stating that idx is preferred (over name) and by elevating confirm from an ordinary boolean to a mandatory requirement. This adds invocation-level semantics that are not fully encoded in the schema's default values.

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

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

The description states a specific verb ('Configure') and a concrete resource ('switch On Action and Off Action URLs or scripts'). This clearly distinguishes it from sibling tools like get_switch_actions, toggle_switch, and set_switch_state, so the agent can infer its purpose without opening the schema.

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

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

It gives clear invocation context by specifying that idx is preferred and that confirm=True is mandatory for this high-impact operation. It does not explicitly name sibling tools to exclude, but the first sentence establishes the correct arena and the subsequent constraints guide correct invocation.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds the preference for `idx` and the cross-reference, but does not disclose any additional behavioral traits such as side effects, error conditions, or what happens when both idx and name are provided. With annotations covering the core safety profile, a 3 is appropriate.

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: one sentence plus a cross-reference. Every word earns its place, and the key preference (`idx`) is front-loaded. No wasted text.

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

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

For a simple 3-parameter tool with a full schema and an output schema, the description is nearly complete. The only minor gap is that it does not explain the relationship between `idx` and `name` when both are provided, but the schema and the preference statement cover most of what an agent needs.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds the preference for `idx` over `name`, which is useful, but it does not add meaning beyond what the schema provides for the `state` parameter. Baseline 3 is correct when the schema does the heavy lifting.

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

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

The description states a specific verb ('Set') and resource ('switch state') with the allowed values 'On'/'Off', which is clear. It does not explicitly distinguish from sibling tools like set_dimmer_level or set_color_brightness, but the 'switch state' phrasing and the cross-reference to toggle_switch provide enough 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 preference for using `idx` over `name` and cross-references `toggle_switch` as an alternative. It does not explicitly state when to use toggle_switch instead, but the cross-reference implies a related but distinct operation, which is adequate guidance.

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

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

The annotations already indicate destructiveHint, readOnlyHint=false, and idempotentHint, but the description adds no behavioral context beyond restating the action. It does not explain impact or side effects of changing a setpoint.

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 terse and front-loaded, with no filler. The brevity is acceptable because the schema is rich and carries the parameter details.

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

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

Schema and annotations provide most of the information needed to invoke the tool. However, the description lacks usage guidance and does not explain the potentially destructive nature of the operation beyond what the annotation flags.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's 'Preferred: idx' repeats the schema's own 'preferred over name when known' and adds no new 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 states a clear verb ('Set') and resource ('target temp'), and the tool name disambiguates it as a temperature setpoint. It is not a full 5 because 'temp' could momentarily be confused with the sibling tool set_color_temperature.

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

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

There is no guidance on when to use this tool versus alternatives like set_switch_state or set_dimmer_level. 'Preferred: idx' is a parameter preference, not usage guidance.

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

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

The annotations already mark the tool as idempotent and non-destructive, but the description adds tangible behavioral context: the login is 'bounded', occurs in a 'local browser', and a follow-up polling step is required. It does not explain what 'bounded' means in detail, but combined with the annotation profile it gives a reasonable operation model.

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 compact sentence carries the entire description: the action ('start or reuse'), the scope ('bounded'), the environment ('local browser'), and the next step ('poll get_oauth_login_status'). There is no filler or redundancy.

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

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

For a zero-parameter tool with an output schema and annotations, the description is nearly complete: it states the action, the environment, and the next step. Its only gap is leaving 'bounded' undefined, but the tool's role and flow are sufficiently clear 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?

The tool has zero parameters, so the baseline is 4. The description has no parameter responsibilities, and the empty schema confirms no arguments are needed.

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

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

The description explicitly identifies the action as 'start or reuse a bounded login in a local browser' and directly names the corresponding polling step ('then poll get_oauth_login_status'). This distinguishes the tool from every other sibling, making its role in the OAuth flow immediately clear.

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

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

The description implies when to use the tool: as the first step in an OAuth login, followed by get_oauth_login_status. It provides clear contextual sequencing but does not explicitly list alternatives or describe when not to use it. For a tool with no competing auth-related siblings, the implicit usage guidance 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 declare destructiveHint=true and readOnlyHint=false, so the mutation risk is known. The description adds the command semantics (On/Off/Toggle) and the idx preference, but doesn't disclose side effects like what happens to devices in the scene or whether Toggle is state-dependent. 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?

Three short sentences with no filler. The core action and command values are front-loaded, and the idx preference is stated early. The cross-ref is terse but 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?

For a 3-param tool with full schema coverage and an output schema, the description is mostly adequate. However, it doesn't explain the relationship between idx and name (e.g., what happens if both are provided), nor the behavioral difference between scenes and groups, which could matter for an agent deciding to call this tool.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds the preference for idx over name, which is useful, but doesn't add meaning beyond what the schema provides for command or name.

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

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

The description states a specific verb ('Activate') and resource ('scene'), and the command values On/Off/Toggle clarify the action. It doesn't explicitly distinguish from sibling tools like toggle_switch or set_switch_state, but the scene focus is clear enough.

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 scenes and mentions 'Preferred: idx' as a selection hint, but it doesn't explicitly say when to use this tool vs alternatives like toggle_switch or set_switch_state. The cross-ref to domoticz://scenes hints at context but doesn't provide 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 signal mutation and destructiveness, so the description adds little behavioral context beyond the word 'toggle', which is already in the title. It does not explain what happens with unknown device states, how the current state is determined, or any side effects beyond what annotations indicate.

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, with no filler. Each fragment serves a purpose, though the overall terseness limits the amount of useful guidance it conveys.

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

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

For a two-parameter toggle with an output schema and annotations, this is minimally viable. It lacks an explicit statement that at least one identifier is normally needed and does not clarify how toggling differs from set_switch_state, but the simple domain and rich structured metadata compensate somewhat.

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

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

Schema description coverage is 100% and already explains that idx is preferred over name and that name is case-insensitive. The description merely repeats 'Preferred: idx', adding no new 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 states a specific action ('toggle') and resource ('device'), and it indicates that idx is preferred. It does not explicitly contrast with set_switch_state, so it stops short of fully differentiating itself from a sibling tool.

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

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

The only guidance is 'Preferred: idx', which addresses parameter selection rather than when to use this tool versus set_switch_state. The 'Cross-ref' note points to a related tool but provides no condition or exclusion to help an agent choose between them.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, but the description adds no behavioral context such as side effects, permission requirements, or caution about overwriting device values. 'Manual update' provides no meaningful disclosure beyond the structured 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 short but under-specified rather than helpfully concise. 'Manual update' is filler that does not earn its place, and the two fragments provide no meaningful structure or front-loaded actionable information.

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

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

Given the tool's destructive annotation and large sibling set, the description is incomplete: it fails to explain when to invoke it, what behavior to expect, or how nvalue/svalue updates interact with the target device. The schema and annotations carry nearly all the useful context.

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

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

Schema description coverage is 100%, so parameters are already fully documented. The description's 'Preferred: idx' merely duplicates what the idx parameter description already states ('preferred over name when known'), adding no new semantic value.

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 'Manual update' is essentially a tautology that restates the title without specifying what device value is being updated or how. It does not distinguish this tool from siblings like set_switch_state, rename_device, or call_domoticz_api.

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

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

The only guidance, 'Preferred: idx', addresses parameter choice rather than when to use this tool. There is no mention of when to choose update_device_value over alternative sibling tools or what conditions make it the right choice.

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

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

Annotations already signal destructive and non-read-only behavior, so the description does not need to restate that. It adds a useful behavioral note: `confirm=True` is required despite the schema default of false. However, it does not disclose what is overwritten or any side effects beyond what the destructiveHint annotation already implies.

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 very short and front-loaded, but the opening sentence 'Update script' is redundant with the title and does not earn its place. The cross-reference and confirm requirement are useful, but the overall terseness feels like under-specification rather than deliberate conciseness.

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

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

Given this is a destructive, idempotent operation with 7 parameters, the description is too thin. It does not explain what the update does to the event, what values are expected for `interpreter`, `event_type`, or `xmlstatement`, nor how this relates to creating events. The output schema reduces the need to document return values, but other context needed for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema carries the parameter meanings. The description adds no real parameter semantics except implying that `confirm=True` is mandatory, which is a small addition. The `domoticz://event/{event_id}` cross-reference provides context for `event_id` but not meaningfully 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 simply says 'Update script,' which largely restates the title 'Update event script' without adding specificity about what kind of script or what updating entails. The cross-reference to `domoticz://event/{event_id}` hints at events, but the purpose is still vague and does not distinguish this from other script-related operations.

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

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

There is no guidance on when to use this tool versus alternatives like `create_event`, `update_user_variable`, or `update_device_value`. The instruction 'Requires `confirm=True`' is an invocation requirement, not a usage guideline. No context is given about prerequisites, sequencing, or situations where this tool is the right choice.

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 indicate destructive and non-read-only behavior, but the description adds almost no behavioral context beyond that. The only extra line is a cross-reference to domoticz://user-variables; it does not disclose side effects, type-change implications, or failure behavior.

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

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

The description is extremely concise and front-loaded, with no filler. The cross-reference line is short and potentially useful, though its value is limited since it is not elaborated.

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 destructive mutation tool with siblings for adding and deleting variables, the description lacks key context: no mention that the target variable must already exist, no guidance on type-change behavior, and no routing to alternative tools. The schema and output schema help, but the description alone is insufficient for safe invocation.

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

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

Schema description coverage is 100%, so the baseline is 3 even though the description itself adds no parameter-level detail. The description does not go beyond the schema to clarify parameter relationships or edge cases.

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

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

The description states a clear action ('Update') on a specific resource ('var value'), so an agent can tell it is an update operation. However, it does not explicitly differentiate it from sibling tools like add_user_variable or delete_user_variable, and the informal 'var' is less precise than the title's 'user 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?

No guidance is provided on when to use this tool versus alternatives such as add_user_variable or delete_user_variable. The description does not mention that the variable must already exist, nor does it exclude cases that belong to sibling tools.

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