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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered structurally. The description adds that the activation is broad ("all of its channel settings"), but omits whether existing manual channel settings are overwritten, whether only one mode can be active, or how to revert.

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 short sentence, front-loaded with the verb and resource, with the operative effect in the trailing clause. Nothing is redundant or padding.

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

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

For a one-parameter tool with full schema coverage and annotations that cover the safety profile, the description is close to sufficient. The main missing piece is the state transition: whether activation replaces current channel settings and how it interacts with other modes, which matters for a non-destructive-looking but system-wide mutation.

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

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

Schema description coverage is 100% and the single parameter already documents "Mode uid or exact name", so the schema carries the load. The description adds no syntax, format, or lookup guidance (e.g., where to get the uid) beyond what the schema states, which is the expected baseline 3.

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

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

Specific verb+resource ("Activate a saved mode") with a stated effect ("applying all of its channel settings"), and it cross-references list_modes as the discovery path. It does not, however, differentiate itself from the sibling apply_profile, which could plausibly be the same kind of 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 parenthetical "see list_modes" gives an implied prerequisite for obtaining a valid mode identifier, which is useful. But there is no explicit when/when-not guidance, and no indication of how this differs from apply_profile or what happens to currently active modes.

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

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

Annotations already declare the safety profile (non-destructive, idempotent, closed-world), so the bar is lower; the description adds value by disclosing the return payload ('the previous setting'), which lets an agent plan a revert. It doesn't state that the current channel setting is overwritten or what happens on a profile/channel mismatch.

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

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

Two short sentences, front-loaded with the action and followed by the return behavior; nothing is padded or redundant.

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

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

With no output schema, the description usefully states the return value, and the fully documented schema covers the inputs. Only minor gaps remain (overwrite semantics, error behavior on a nonexistent profile), which are small for a simple assignment 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 coverage is 100% and all three parameters carry their own descriptions (device uid/prefix/name, channel name or label, profile uid or name), so the schema does the heavy lifting. The description only adds the 'fan/pump channel' framing and 'existing profile' constraint, which is baseline-level added 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 (assign) and resource (an existing profile) with the target (fan/pump channel), so the effect is unambiguous. The word 'existing' implicitly separates it from create_profile, though no sibling is named as an alternative.

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?

'see list_profiles' explicitly routes the agent to the discovery tool needed to obtain the profile argument, which is the main prerequisite. It stops short of stating exclusions (e.g. use create_profile when the profile doesn't exist yet), so it's clear but not fully prescriptive.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, but the description adds two pieces the annotations can't: that non-GET calls 'change daemon state' and that they require a token 'with Write Access.' That auth prerequisite is genuinely useful behavioral context. It does not describe error behavior or response format, but with annotations covering the safety profile a 4 is warranted.

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

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

Three short sentences, front-loaded with the core action and the routing rule, and the behavioral warning last. Zero filler; every sentence earns its place.

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

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

For a generic API passthrough with a moderately rich schema and no output schema, the description covers the key decision (when to use this vs dedicated tools) and the critical write-access warning. It omits any guidance on constructing the body/form/query payloads, but the schema covers most of that and annotations cover safety.

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 67%, with body, form.files, path, and text documented inline but query and method essentially undocumented. The description's reference to 'Non-GET calls' vaguely contextualizes the method enum, but it adds no detail on body/form/query/text usage. The schema does the heavy lifting, so baseline 3 is appropriate.

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

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

States a specific verb and resource: 'Call any endpoint from list_api_endpoints directly.' The phrase 'Prefer the dedicated tools when one fits' differentiates it from the numerous specialized siblings without ambiguity. It lacks a crisp statement of its unique role (power-user escape hatch) but an agent can distinguish it from the dedicated tools.

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

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

Explicitly directs the agent to prefer dedicated sibling tools 'when one fits' because 'they validate inputs,' which is a clear routing rule. The fallback case (use this for unlisted/unsupported operations) is implied rather than stated, so it stops short of full when/when-not coverage.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false. The description adds no behavioral context beyond field names—nothing about activation semantics, notification firing, validation failures, or whether creation is immediate—so with annotations carrying the safety profile it provides little extra behavioral 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?

The description is front-loaded with "Create a alert" and then groups required vs optional fields, so an agent can scan it quickly. It is dense and slightly run-on, but every clause carries payload information.

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

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

For a nested create operation, it covers the semantically important fields and channel source structure, but it does not clarify that they must be supplied inside the single "fields" object or give units/types for several optional fields. With no output schema and only annotations covering safety, this is adequate but not fully complete.

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

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

The schema exposes only a generic "fields" object, but the description supplies the actual required members (name, min, max, warmup_duration, channel_sources), the channel_source object shape, the Temp|Duty|Load|RPM|Freq enum, and examples like temp1/fan1. It loses a point because optional fields (cooldown_duration, repeat_interval, etc.) lack types/units and the top-level "fields" wrapper is not restated.

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

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

The description opens with a clear verb+resource ("Create a alert") and names the required/optional payload members, so the action is unambiguous. It does not explicitly contrast with update_alert/delete_alert, but the verb makes the sibling distinction obvious.

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 create an alert versus updating one, no prerequisites such as existing devices/channels, and no pointer to list_alerts or list_devices. It only enumerates payload fields.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the description does not need to establish the basic safety profile. It adds useful behavior such as id being unique and becoming the sensor name, but omits duplicate-id handling, error behavior, permissions, and what creation returns.

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

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

The description is front-loaded with the action and then moves into required fields and variant rules. It is dense and telegraphic, but every clause carries construction information and there is no filler.

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

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

For a complex nested create operation, the description covers most of the domain-specific field construction needed to call the tool. However, it does not explain the relationship to the fields wrapper, duplicate-id behavior, or return value, which matters more because no output schema exists.

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

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

The schema is only a generic fields object, so the description adds substantial meaning by documenting required id and cs_type and by defining the mix, file, offset, time-average, and exponential-moving-average variants. It stops short of explicitly tying these fields to the fields wrapper and does not cover every possible field.

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 specific verb and resource: create a custom sensor. It is distinct from update_custom_sensor and delete_custom_sensor by name, though it does not explicitly call out sibling 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?

It gives required fields and variant-specific construction rules, but does not explain when to use this tool versus update_custom_sensor, list_custom_sensors, or other alternatives. There is no explicit prerequisite or exclusion guidance.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the description is free to add context — and it does, disclosing the important default behavior that unset fields are copied from the Default Function, plus which fields apply per f_type. It doesn't address duplicate-name handling or what happens on invalid field names.

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

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

Front-loaded with the action and the one required key ('Required: name'), then a dense but purposeful field inventory. The compound field list is terse yet earns its space because the schema is an untyped bag.

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 mutation tool with annotations covering safety and no output schema, the description supplies the essentials: required key, default-copy behavior, and valid field vocabulary. Remaining gaps (conflict behavior on an existing name, whether the created object is echoed back) are minor given no output schema exists.

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

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

The schema's single 'fields' parameter is a free-form object bag, so nominal 100% coverage conveys almost nothing. The description compensates heavily by enumerating the valid field names, the enum values for f_type (Identity | Standard), step-size semantics, and units (%). This is exactly the value-add that the schema cannot provide.

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

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

Opens with a specific verb+resource ('Create a function') that clearly distinguishes it from siblings like update_function, delete_function, and list_functions. It stops short of naming those alternatives explicitly, so differentiation is by verb only.

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?

Creation vs. update is implied by the verb and by the statement that unset fields copy the Default Function, but there is no explicit 'use this instead of update_function when...' guidance or mention of prerequisites such as name uniqueness.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description usefully adds that it captures live channel state rather than creating from scratch and that the result is restorable, but says nothing about name-collision behavior, whether an existing mode with the same name is overwritten or rejected, or what happens if a channel has no settings.

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

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

A single sentence with no filler, front-loading the action and then the payoff. Nothing repeats the tool name or the annotations.

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

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

For a one-param create tool with safety annotations and no output schema, the core behavior is conveyed. Missing pieces that matter for correct invocation are name-conflict semantics and whether the newly created mode is returned/identifiable afterwards.

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 0% and the single required 'name' parameter is never named or constrained in the description. It only implies a new mode gets labelled; agents get no signal about uniqueness, allowed characters, or whether an empty/duplicate name fails. With one obvious parameter the gap is moderate but real.

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

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

States a specific verb+resource (save ... as a new mode) and adds scope the name alone doesn't convey: it snapshots 'the current settings of every channel'. It links forward to activate_mode, which separates it from sibling readers like list_modes/get_mode, though it does not disambiguate from duplicate_mode.

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

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

Usage is implied by 'save the current settings ... as a new mode' plus the note that activate_mode restores it later, giving an agent a sense of the snapshot/restore workflow. However, there is no explicit when-to-use statement and no guidance on when duplicate_mode or create_profile would be the better 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 declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, so the write-but-non-destructive profile is covered structurally. The description adds real value by mapping each type to its required parameters and flagging the two-step create-then-apply workflow, but says nothing about name-collision behavior, idempotency, or validation failures.

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?

Four compact clauses, one per profile type, then the follow-up action. Zero filler and the core purpose is front-loaded in the first clause.

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 9-parameter tool with nested objects and no output schema, the description covers the type-conditional parameter usage and the required next step well. It omits what is returned (a profile id vs name) which matters because apply_profile later needs an identifier, but that is a modest gap given the otherwise thorough coverage.

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 78%, so most parameters are already documented, but the description adds the crucial conditional semantics the schema cannot express: which fields apply per type (Fixed→duty, Graph→curve+one sensor, Mix→members+function, Overlay→offset+one base profile). It leaves the default for function and the exact accepted identifier forms to the schema.

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

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

States a specific verb+resource ("Create a fan profile") and then defines all four profile types with their distinguishing semantics. An agent can tell this apart from update_profile/list_profiles immediately, and understands what kind of object is being produced.

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

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

Explicitly routes the agent to the follow-up tool: "Assign it to a channel afterwards with apply_profile," which clarifies this tool alone does nothing useful. It doesn't state when to prefer create_profile vs update_profile, nor that a target function must already exist, so it stops short of full when/when-not 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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered by structured data. The description adds nothing about what is destroyed, whether deletion is irreversible, whether the alert's history or associated notifications are removed, or what happens if the name matches multiple alerts — exactly the context that matters for an irreversible mutation.

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

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

It is a single four-word sentence with zero waste, but the brevity is under-specification rather than efficient communication — there is no front-loaded scoping, warning, or return information to justify the omission.

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 no output schema, the annotations cover the safety flag, but the description still omits confirmation semantics, irreversibility, and identifier disambiguation. An agent could call it, but not confidently or safely.

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

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

Schema coverage is 100% and the single parameter documents 'alert uid or exact name', so the schema does the work. The description does not clarify resolution behavior when an exact name is ambiguous or whether a UID is preferred, but baseline 3 applies when the schema is fully documented.

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 is a bare restatement of the tool name and title ("Delete a alert") with no added scope, and it does not distinguish this from the many sibling delete_* tools (delete_profile, delete_mode, delete_function, delete_custom_sensor). It does signal a delete verb on an alert resource, but nothing beyond the name field.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives such as update_alert (to modify) or list_alerts (to find the identifier first). The only cue is the word "delete" itself, which the agent would already know from the name.

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, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: the tool refuses while the sensor is in use, and force=true overrides the refusal. It does not mention irreversibility or what cascades from deletion, keeping it short of a 5.

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

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

Two short sentences with the destructive precondition front-loaded immediately after the purpose statement. Nothing is wasted and nothing important is buried.

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

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

For a two-parameter destructive tool with full schema coverage and no output schema, the description covers the one non-obvious risk factor (in-use refusal and the force escape hatch). A brief note that deletion is permanent would close the last gap, but the destructiveHint annotation already signals that.

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

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

Schema coverage is 100%, and the schema already documents both force ("Delete even if in use") and custom_sensor ("id or exact name"). The description only echoes the force semantics already present in the schema, adding no syntax or edge-case detail, so baseline 3 applies.

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

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

States a specific verb and resource ("Delete a custom sensor") that maps directly to the tool name and cannot be confused with create_custom_sensor, update_custom_sensor, or list_custom_sensors. It stops short of explicitly naming those siblings, but the verb alone does the disambiguating work.

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

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

The second sentence implies a use condition by describing when the call fails, which implicitly tells the agent when to set force. However, it never states the alternative action (e.g., update or deactivate instead of delete) or any prerequisites, so the guidance is inferential 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 destructiveHint=true, so the safety profile is known; the description adds the non-obvious guard behavior (refuses when in use) and the override mechanism. It stops short of describing consequences for dependents or whether the deletion is recoverable.

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

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

Two short sentences, zero filler, with the primary action front-loaded and the guard condition immediately after.

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?

Covers the core action and the main failure mode, but leaves open what "in use" means, what happens to dependent objects, and whether the deletion is permanent. For a destructive operation these are meaningful gaps despite the destructiveHint annotation.

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

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

Schema coverage is 100%, so both parameters are already documented, and the description only restates force's effect at a high level without adding format or dependency details. Baseline 3 is appropriate given the schema does the work.

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 ("Delete a function") that clearly separates it from create_function/update_function/list_functions. It does not explicitly name siblings, but the verb makes selection unambiguous.

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

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

Gives a concrete usage condition: the call fails when the function is in use unless force is set. It does not reference alternatives, but the precondition tells the agent when this call will be rejected and how to proceed.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful context the annotations cannot: removing the saved mode does NOT alter the channel settings currently applied, which prevents an agent from assuming a destructive reset. It omits irreversibility and permission requirements.

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

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

Two short sentences, both front-loaded with the action first and the scoping caveat second. No filler and nothing redundant with the schema.

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

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

For a one-parameter destructive tool with full annotation coverage and no output schema, the definition supplies everything needed to call it correctly plus the key non-effect. A note on irreversibility or the failure mode for unknown names would make it complete.

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

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

With a single parameter at 100% schema description coverage ("Mode uid or exact name"), the schema already carries the semantics. The description adds nothing about the identifier format or resolution behavior, so the baseline 3 applies.

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

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

States a specific verb and resource ("Delete a saved mode"), which distinguishes it from sibling delete_* tools for profiles, alerts, functions and sensors without opening a schema. It stops short of naming an alternative explicitly, so 4 rather than 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?

Usage is only implied — an agent can infer this is the call to remove a mode by uid or name, but the description never says when to prefer it over update_mode, reset_channel or deactivate flows, nor what prerequisites exist. The clarification about channel settings is effect information, not selection 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 only declare destructiveHint=true; the description goes well beyond by disclosing the refusal condition, that the error lists the exact dependents, and precisely what force does (channels fall back to default, modes drop the profile). This is exactly the consequence-level detail an agent needs before a destructive call.

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 dense sentence that front-loads the base action and then the conditional behavior; every clause carries information. It is slightly compressed into a single run-on structure that could be split for scanning, but nothing is wasted.

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

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

For a destructive two-parameter tool with no output schema, the description covers inputs, failure modes, and side effects. It stops short of stating whether the deletion is permanent/irreversible and what a successful response contains, which are the remaining gaps.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning to 'force' beyond the schema's terse 'Delete even if in use' by spelling out the downstream fallback effects. 'profile' is passed through unchanged with no added detail on uid vs name resolution.

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 ('Delete a profile') and immediately scopes it against the other delete_* siblings by naming what a profile is entangled with (channels, Mix/Overlay profiles, modes). An agent can tell this apart from delete_mode or update_profile without opening a 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?

Explains the two operating contexts clearly: default behavior refuses when the profile is referenced, and force=true proceeds with defined fallbacks. It does not explicitly name a sibling alternative (e.g. update_profile or reassigning channels first), so a 5 is not warranted, but the when-to-use-force decision is fully specified.

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

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

Annotations already declare non-read-only, non-destructive, and closed-world behavior. The description adds that saved settings are copied, which is useful context, but it does not state permissions needed, whether the copy is independent, or what the response returns.

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

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

The description is a single front-loaded sentence with no wasted words. It states the action and the key scope detail immediately.

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

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

For a simple one-parameter mutation tool with no output schema, annotations covering safety, and fully documented parameters, the description is mostly sufficient. It could mention what is returned, such as the new mode identifier, but the core behavior is clear.

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

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

The single parameter has full schema coverage and is documented as 'Mode uid or exact name.' The description adds no additional parameter semantics, so the baseline of 3 is appropriate when the schema does the work.

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

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

The description gives a specific verb and resource: 'Copy a mode, including its saved settings.' This distinguishes it from create_mode (which would create a blank mode) and get_mode (which retrieves), though it does not explicitly name those siblings.

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

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

It implies usage through 'Copy a mode' but does not say when to choose duplicate_mode over create_mode, get_mode, or activate_mode. No exclusions or prerequisites are stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: the result spans all devices unless narrowed, and each channel resolves into one of three setting kinds, which tells the agent what to expect in the payload. It omits error behavior for an unknown device identifier, which is acceptable given annotation coverage.

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

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

Two short sentences, no filler, and the front-loaded clause states what is returned before the scoping caveat. Every sentence earns its place.

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

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

With no output schema, the description carries the burden of describing return values, and it does so by enumerating the three setting kinds. What it does not convey is the result shape (e.g. how channels are keyed or ordered), leaving a small gap for an agent constructing downstream logic.

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 contributes beyond the schema: it discloses that omitting the device parameter defaults to all devices, a default the schema's device description does not state. That closes the only real ambiguity in a single-parameter tool.

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

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

The description states precisely what the tool returns: the current setting of each speed-controllable channel, enumerated as profile-by-name, fixed duty, or default. That is a specific resource with its value domain spelled out. It does not explicitly contrast itself with siblings like get_status or list_profiles, so the differentiation is inferred rather than stated.

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

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

"Covers all devices unless one is given" gives scoping guidance, implying when to pass the device parameter versus omitting it. However, there is no explicit statement of when to reach for this tool versus get_status, list_profiles, or get_mode, and no 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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds value by disclosing the returned fields (version, uptime, warning/error counts), which is the main thing annotations cannot convey; it does not mention cost, freshness, or whether the counts are cumulative.

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 short sentence, front-loaded with the resource and immediately followed by the returned fields. No filler, though the phrasing is compressed enough that 'version' and 'uptime' are not clearly scoped (daemon vs. host).

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

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

With no output schema, the description must carry the return-value burden and it does name the payload fields. A zero-parameter read-only health check is a simple tool, so this is close to sufficient; only the shape/meaning of the warning and error counts is left ambiguous.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter semantics are needed here.

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

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

Names the specific resource (CoolerControl daemon health) and enumerates what it reports: version, uptime, warning/error counts. However it does not differentiate itself from the sibling get_status, which an agent could easily confuse with a health/diagnostic call.

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

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

There is no statement of when to call this versus get_status or list_api_endpoints — no conditions, prerequisites, or exclusions. The agent must infer that this is the diagnostic/summary endpoint from the field list alone.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the useful detail that the payload includes channel settings plus resolved device and profile names, but with no output schema it does not describe the shape, completeness, or error behavior (e.g., unknown mode name).

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 short sentence with no waste, but it is not front-loaded with an action verb, so the reader must reconstruct the operation from the tool name. Brevity here reflects under-specification rather than efficient structure.

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

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

For a one-parameter read tool whose safety is fully covered by annotations and whose parameter is fully documented in schema, the description supplies the key missing piece — what the returned object contains (channel settings, device and profile names). Only lookup-failure behavior is unaddressed, which is minor here.

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

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

Schema coverage is 100% and the single parameter's schema already says 'Mode uid or exact name'. The description adds nothing about matching semantics (case sensitivity, ambiguity between uid and name), so it neither compensates nor detracts — baseline 3.

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

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

The description is a noun phrase ('The channel settings saved in a mode...') with no verb, so the retrieval action is only implied by the tool name. It does hint at scope (a single mode's saved settings plus device/profile names), which distinguishes it loosely from list_modes, but it never explicitly contrasts with siblings like get_channel_settings or list_modes.

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

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

There is no statement of when to call this versus list_modes, get_channel_settings, or activate_mode. The only implicit cue is the singular 'mode' in the schema, which the agent must infer means 'fetch one mode's detail'.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered by structured data. The description usefully adds that these are 'latest' snapshot readings in named units, but says nothing about volume of data, refresh cadence, or what happens when a device is offline — which matters for a polling-style tool.

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

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

Two tight sentences with no filler — the metric list and units come first, the scoping caveat second. Slightly dense, but every phrase carries 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?

With no output schema, the description carries the burden of describing return values and does so by naming every metric and its unit, which is exactly what an agent needs to interpret the payload. What is missing is the response structure (per-device grouping) and default scope when no device is given.

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 all three parameters are documented in structured data, including the device/channel dependency and the raw flag. The description reinforces the optional device/channel scoping but adds nothing about the raw output flag, so the baseline 3 applies.

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

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

The description names a specific resource (latest sensor readings) and enumerates exactly which metrics come back — temperatures, fan rpm, duty, power, frequencies — with units. That is far more informative than the title alone, though it never contrasts itself with close siblings like get_health or get_channel_settings.

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?

'Optionally limited to one device and channel' implies the default is all devices and sketches a scoping choice, but there is no explicit statement of when to reach for this over get_health or get_channel_settings, and no note of prerequisites or cost.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds only that two kinds of data come back (configured alerts plus a log), with no word on how much 'recent' covers, ordering, or result limits — meaningful gaps for a log-reading tool.

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

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

It is short and front-loaded with no filler, but it is an under-specified sentence fragment rather than a tight, self-contained statement. Brevity here comes at the cost of clarity, not from efficiency.

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

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

With no output schema present, the description carries the burden of explaining what comes back, and it does so only vaguely — 'recent alert log' with no scope, count, or structure. For a simple zero-param read this is thin rather than wrong.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the schema is trivially complete. Baseline 4 applies.

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

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

The phrase 'Configured alerts and the recent alert log' names the resource but is a noun fragment with no verb, so it reads more like a return description than an action statement. Against siblings like create_alert, update_alert and delete_alert the listing intent is inferable from the name, but the description itself does not commit to 'list'.

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

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

There is no guidance on when to call this versus the CRUD alert siblings, and no mention of prerequisites or exclusions. The agent must infer usage entirely from the tool name.

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 and openWorldHint=false, so safety is covered. The description adds genuinely useful context beyond that: the version pin (5.1.1), the fact that results are permission-scoped to the caller's token, and a preview of the endpoint categories returned. It doesn't describe the shape of each returned entry or pagination, so not a 5.

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

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

Two sentences, front-loaded with the core purpose and filter hint last. The long category enumeration costs some space but doubles as a coverage preview that helps an agent decide whether this tool is relevant.

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

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

A simple two-parameter read tool with no output schema and full schema coverage; the description supplies purpose, scope, and the downstream consumer (call_api). It leaves the shape of each returned endpoint entry unspecified, but that is a minor gap for a discovery list.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description's 'Filter by tag or text' mirrors them without adding format, combination, or default behavior. Baseline 3 applies when the schema carries the 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?

Names a specific verb and resource ('Every CoolerControl 5.1.1 REST endpoint a token can call') and immediately ties it to its companion tool, call_api. The enumerated categories make clear it is a discovery catalog rather than an execution tool, which distinguishes it from every sibling in the list.

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

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

The phrase 'for use with call_api' establishes the workflow: browse here, invoke there. Filtering by tag or text is also stated. What's missing is an explicit 'when not to use' (e.g., if you already know the endpoint, call call_api directly) or a note that results are limited to what the current token can access, though that is implied.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds no behavioral context beyond that — no mention of ordering, whether disabled sensors are included, whether it requires a configured controller connection, or anything about what comes back.

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 short parenthetical sentence with no waste, but it is a bare fragment that front-loads a resource definition rather than the action or return behavior.

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

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

For a zero-param lister with no output schema and no annotation on return shape, the agent still lacks any idea of what a result entry looks like (name, id, type) or how many to expect. The definition of a custom sensor helps interpret results but does not fill that gap.

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

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

Zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. Schema coverage is 100% on an empty object.

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 is a noun phrase that defines the resource ('user-defined custom sensors') but never states the action; the verb 'list' exists only in the tool name. The parenthetical distinguishing mixes-of-temps from file-based sensors adds real domain meaning, but the purpose statement itself is a fragment rather than a specific verb+resource claim.

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 call this versus alternatives such as list_devices or the create/update/delete custom sensor siblings. An agent must infer from the name alone that this is the read path for custom sensors.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds useful behavioral context by specifying the returned content (channels and sensors per device). It does not describe what the raw flag changes or how large the payload is, but with annotations present the bar is lower.

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, both earning their place: the first defines scope and payload, the second routes the agent onward. Front-loaded with the primary noun and zero filler.

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

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

With no output schema, the description carries the burden of describing returns, and it sketches the shape (devices with channels and sensors). It leaves the raw vs condensed distinction entirely to the schema and doesn't hint at nesting depth, a minor gap for a discovery tool.

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

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

Only one parameter exists and schema description coverage is 100% – the schema already explains that raw returns the daemon's raw JSON instead of the condensed summary. The description adds nothing about raw, so baseline 3 applies.

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

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

States a specific verb (List) and resource (hardware devices CoolerControl knows about), then enumerates device categories and what each entry carries (speed-controllable channels, temperature sensors). This clearly distinguishes it from sibling listers like list_profiles, list_functions, and list_custom_sensors.

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?

"Use the uids and channel names here for other tools" gives a clear downstream-usage cue that links this tool to the rest of the toolset. It offers no explicit when-not or alternative comparison (e.g., vs list_custom_sensors), so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuine domain context about what the returned objects represent (duty-shaping rules), but says nothing about completeness, ordering, or whether the list is global — with annotations carrying the safety burden, this is adequate but not rich.

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

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

A single short sentence with zero padding and the key concept front-loaded. It is slightly under-specified rather than verbose, which costs it little here.

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

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

For a parameterless read-only list with no output schema, the description gives just enough to know the subject matter, but leaves open whether the result spans all profiles or a subset, and gives no hint of volume. It is minimally sufficient but not complete.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the description's domain gloss on the returned entities is a mild bonus.

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 is a noun-phrase definition of what a 'function' is (duty-shaping rules with min/max duty, step sizes, hysteresis) rather than a statement of what the tool does — no verb like 'list' or 'return'. It does helpfully differentiate the resource from profiles/modes, and the title supplies 'List', but on its own it stops short of a clear action statement.

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

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

There is no guidance on when to call this versus siblings such as list_profiles or list_devices, nor any precondition or exclusion. The agent must infer from the name alone that this enumerates all function definitions globally (there are no parameters to scope 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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context by saying the result includes saved modes and which one is active, including that modes are snapshots of all channel settings.

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

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

A single compact sentence that front-loads the resource and immediately clarifies what a mode is. There is 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 zero-parameter read tool with annotations covering safety, the description is largely complete: it says what is listed and highlights the active mode. It could mention ordering or whether all modes are always returned, but no output schema exists and the core behavior is adequately conveyed.

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

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

There are zero parameters, so there are no parameter semantics to explain. The empty schema matches the description, and the baseline for a no-parameter tool is 4.

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

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

States a specific verb and resource: lists saved modes, described as snapshots of all channel settings, plus the active one. It is clear what the tool returns, but it does not explicitly distinguish itself from siblings like get_mode or activate_mode.

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 explicit guidance on when to use this tool versus get_mode, activate_mode, or other mode-management tools. Usage is only implied by the name and the word 'list'.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful detail about what profile types and temperature source are returned, but it does not mention how the optional raw parameter changes output behavior or whether results are ordered or paginated.

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 compact sentence that front-loads the resource and its important subtypes. Every part earns its place, with no filler or redundancy.

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

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

For a simple read-only listing tool with one optional parameter and no output schema, the description gives enough context about what is returned. It omits the raw-mode behavior, but that is already documented in the schema.

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

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

Schema description coverage is 100%, and the single optional raw parameter is fully documented in the schema. The description does not add anything about the parameter, so baseline 3 is appropriate.

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

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

The description identifies the resource precisely: fan profiles, including fixed, graph curve, and mix types, plus their temperature source. It does not explicitly say 'list' or name the sibling tools it differs from (create_profile, delete_profile, apply_profile), but the title and content make the purpose unambiguous.

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

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

There is no guidance on when to use this tool versus alternatives such as apply_profile, create_profile, or update_profile. Usage is only implied by the tool name and the read-only annotation, with no explicit exclusions or 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 cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds real value on top: the result is a hardware default, prior profile/fixed speed is discarded, and the previous setting is returned. It stops short of saying whether the reset can be undone or what errors occur for a bad channel, so it is strong but not exhaustive.

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

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

Two short sentences with no filler; the action and its effect come first and the return-value note trails as a useful addendum. Nothing could be cut without losing information.

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

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

For a simple two-parameter mutation, the description covers the effect, the side effect on existing profiles/speeds, and the return value, which compensates for the missing output schema. Only edge behavior on invalid devices/channels is unstated, a minor gap.

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 `device` and `channel` are already documented, including the accepted uid/uid-prefix/name forms and the fan1-or-label channel format. The description adds no parameter meaning beyond the schema, which is the baseline 3 case.

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 (reset) and resource (fan/pump channel), plus the exact effect: restoring the hardware default and removing any profile or fixed speed. That removal clause implicitly separates it from siblings like apply_profile and set_fixed_speed, so an agent can pick it out without opening either schema.

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

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

The phrase 'removing any profile or fixed speed' implies the situation that calls for this tool, but no sibling is named and no condition is given for when to reset versus re-applying a profile or calling set_fixed_speed. Usage is inferable rather than stated.

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

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

Annotations already declare non-read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds genuine value beyond them: a hard validation floor with a named error code (COOLERCONTROL_MIN_DUTY) and disclosure that the previous setting is returned, which matters for a mutation an agent may need to undo.

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

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

Three short sentences with no waste, front-loaded with the action and immediately following with the constraint and return behavior. Every sentence earns its place.

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

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

For a 3-parameter mutation tool with annotations present and no output schema, the description covers the validity constraint and what gets returned, which is sufficient to call it correctly. It stops slightly short on the restore workflow (which sibling to use), the one remaining gap.

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 goes beyond the schema by disclosing that duty values below 20% are rejected despite the schema advertising a 0–100 range — a constraint invisible in the structured fields — which is exactly the kind of semantic detail an agent needs.

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

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

States a specific verb and resource ('Set a fan/pump channel to a fixed duty %'), which is clearly distinct from read-oriented siblings like get_channel_settings. It does not explicitly name the sibling it supersedes (e.g. reset_channel) for returning to auto control, so 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?

The purpose strongly implies when to use it, and the 20% floor gives practical usage context. However, there is no explicit when-to-use vs. alternatives guidance, and the restore path is only hinted at ('so it can be restored') without naming reset_channel or any sibling.

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

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

The annotations already disclose that this is non-destructive, idempotent, and not read-only. The description adds useful partial-update behavior: omitted fields retain their values, but it does not explain allowed fields, clearing semantics, or permission requirements.

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

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

The definition is a single front-loaded sentence with no wasted language. It conveys the core operation and partial-update behavior efficiently.

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 mutation tool with a nested arbitrary "changes" object and no output schema, the description is only minimally sufficient. It omits what alert fields can be changed and how values should be cleared or represented, leaving meaningful gaps for an 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?

Schema description coverage is 100%, so the schema already defines both parameters. The description adds that unspecified fields in "changes" keep their values, but does not provide further field-level semantics or clarify the arbitrary nested object structure.

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

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

The description states a specific verb and resource: "Change fields of an existing alert." It distinguishes update from create/delete implicitly via "existing" and "change fields," but does not explicitly name sibling tools or contrast alternatives.

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

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

Usage is implied by "existing alert," making clear this is for modification rather than creation or deletion. However, it does not state prerequisites, exclusions, or when to prefer a different alert tool.

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

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

Annotations already establish readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds one genuinely behavioral fact beyond that – unspecified fields retain their values (true partial update) – but says nothing about how a field is cleared, whether unknown keys are rejected, or what errors occur on a bad id.

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

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

A single compact sentence with the resource front-loaded and the merge behavior trailing as supporting detail – no filler anywhere. It is arguably too terse for the free-form `changes` bag, but nothing written is wasted.

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

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

This is a mutation over a nested, entirely free-form `changes` object with no output schema. The description never says which fields can be changed, how to unset a value, or what is returned, so an agent must call list_custom_sensors or guess to learn the valid key set. Annotations only supply the read-only/idempotency profile.

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

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

Schema coverage is 100% and both parameters are described ("custom_sensor id or exact name", "Fields to change"), so the baseline is 3 under the high-coverage rule. The description's patch phrasing clarifies that `changes` is a partial bag, but neither schema nor description enumerates which keys are valid inside an object typed as additionalProperties: {}.

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

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

The description names a specific verb ("Change fields") and resource ("existing custom sensor"), so an agent can distinguish this mutation from create_custom_sensor and delete_custom_sensor. It does not, however, contrast itself with sibling update_* tools, so the differentiation stop-point is generic rather than explicit.

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

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

Usage is only implied: "existing custom sensor" tells the agent the target must already exist, and "fields not given keep their values" implies patch semantics rather than replacement. There is no explicit statement of when to use this instead of create/delete, and no prerequisites or failure conditions are named.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact beyond them: unspecified fields are preserved (patch semantics). It says nothing about permissions, failure modes, or what happens if the function uid/name does not resolve.

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

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

A single sentence with no filler, and the core behavior is front-loaded before the partial-update caveat. Nothing could be cut without losing information.

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

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

Adequate for a two-parameter mutation with full schema coverage and no output schema, but the `changes` object is `additionalProperties: {}` with no enumeration of valid field names in either the schema or the description. An agent still does not know what can actually be changed.

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 ('function': uid or exact name, 'changes': fields to change) are already documented, making 3 the baseline. The description's 'fields not given keep their values' clarifies patch semantics for `changes`, but it never enumerates which field names are legal inside that free-form object.

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

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

States a specific verb and resource ('Change fields of an existing function'), and 'existing' implicitly separates it from create_function and delete_function in the sibling list. It is clear without needing to open the schema, though it never names a sibling explicitly.

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

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

There is no explicit when-to-use guidance, no prerequisites (e.g. that the function must already exist), and no routing to alternatives such as create_function or delete_function. Usage is only implied by the word 'existing'.

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 idempotent=true, destructiveHint=false and non-read-only, so safety is partly covered. The description's main added value is disclosing that saved settings are replaced (prior saved settings are lost) — useful, but it does not say what happens when no name and no save flag are supplied or what errors are returned.

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

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

A single well-formed sentence with the primary action front-loaded and zero filler. It is slightly terse for a two-purpose mutation, but nothing is wasted.

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

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

For a 3-parameter mutation with annotations and no output schema, the description covers both operations adequately, but leaves open the all-optional-parameters case and failure behavior. Adequate minimum viable rather than complete.

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

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

Schema description coverage is 100%, so all three parameters (mode, name, save_current_settings) are already documented in the schema. The description restates the same semantics at a higher level and adds no format or edge-case detail beyond it, so baseline 3 applies.

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

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

States a specific verb pair (rename, overwrite) and the resource (mode), plus the exact source of the new settings (current channel settings). An agent can distinguish it from create_mode/duplicate_mode/delete_mode by the mutation described, though siblings like update_profile are not explicitly contrasted.

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 versus activate_mode or the other mode/profile tools, and no statement of prerequisites (e.g., that the target mode must already exist, or whether name and save_current_settings can both be omitted). Usage is only implied by the sentence.

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

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

Annotations already cover safety (readOnlyHint=false, idempotentHint=true, destructiveHint=false), but the description adds genuinely useful behavioral context: it is a partial update ('only the fields given change'), curve/offset values are replaced wholesale, type changes require new type-specific fields, and channels using the profile update immediately.

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?

Four short sentences, no redundancy, and the core semantic constraint (partial update) is front-loaded immediately after the purpose statement.

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?

Covers the essential behaviors for a 10-parameter nested-object mutation with no output schema: partial update semantics, replacement semantics, type-change dependency, and immediate propagation. It omits only minor details such as discovery of profile identifiers, which the schema partially covers.

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 90%, so the baseline is 3. The description goes beyond the schema by explaining cross-parameter semantics: conditional requirements on type changes and the replace-not-merge behavior for curve and offset, which the schema does not state.

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

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

States a specific verb and resource: 'Change an existing profile.' The word 'existing' implicitly contrasts with create_profile and delete_profile, but the description never names those siblings directly.

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

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

Usage is only implied by 'Change an existing profile.' There is no explicit guidance on when to use this versus create_profile or apply_profile, or how to locate the profile (e.g., via list_profiles) before updating it.

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