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

Goes well beyond the annotations by disclosing the confirmation protocol, the phase-1 "confirmation-required" preview, the confirmToken contract, and the two-mode fallback behavior. It leans on an unexpanded external reference ("see MCP_CONFIRM_MODE") and says nothing about failure/error behavior, which keeps it below a 5.

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

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

Two efficiently written sentences, front-loaded with the primary action before the confirmation detail. The dangling reference "(see MCP_CONFIRM_MODE)" adds a minor bit of unsupported pointer 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 mutation tool with no output schema, the description covers the critical conditional behavior (elicitation vs. two-step token flow) an agent needs to call it correctly. Return/preview contents and error handling are not described, leaving a small 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 all three parameters (item, list, confirmToken) are fully documented in the schema itself. The description adds no syntax, format, or meaning beyond what the schema already provides, so the 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 ("Add") plus resource ("an item to an Alexa shopping or to-do list"). Easily distinguished from siblings like alexa_get_list_items, alexa_update_list_item, and alexa_remove_list_item, and the list scope is 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?

Explains the invocation context clearly: a confirmation prompt is attempted where supported, otherwise a two-step preview/confirmToken flow is required. It does not explicitly name alternatives or state when-not to use it, but the workflow guidance for this mutation tool is clear and actionable.

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

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

Annotations only declare readOnlyHint=false, destructiveHint=false, openWorldHint=false; the description adds substantial context beyond that: the tool is non-destructive but initiates a multi-step out-of-band auth flow, the password never transits the server, and the link expires in 15 minutes. It also discloses the return values and the landing-page behavior the agent must expect.

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 return values, then the hand-off instructions, then the constraint. The single dense paragraph is justified by a multi-step flow, though the parenthetical browser advice is slightly more detail than strictly needed.

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

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

No output schema exists, and the description compensates fully by naming both returned fields and explaining what the user will see next. For an auth-initiating tool with no parameters, this is complete: an agent knows what it gets back and what to do with it.

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

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

The tool takes zero parameters, so there is nothing for the schema to document and no ambiguity to resolve. The description instead clarifies the outputs (signInUrl, loginId), which is more than required; baseline for 0 params is 4.

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

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

States a specific verb+resource ('Start signing in to Amazon Alexa') plus a second explicit mode ('re-connect a revoked session'). It clearly names the sibling it pairs with (alexa_finish_login) and the return payload (signInUrl, loginId), so an agent can distinguish it from alexa_session_status or alexa_finish_login 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?

Gives explicit when-to-use (initial sign-in or revoked session), the exact next step and tool to call with which argument ('call alexa_finish_login with it and the loginId'), and operational handling of the returned URL (hand to user, own browser, private tab). Nothing about sequencing is left to inference.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, but the description adds material context beyond them: that a recurring alarm is deleted entirely rather than just its next occurrence, and that a confirmation prompt (or a two-step preview/confirmToken fallback per MCP_CONFIRM_MODE) gates the 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?

The core action is front-loaded in the first clause, and the disambiguation and confirmation details follow in order of importance. It is dense but nearly every clause carries information the agent needs; only the parenthetical explanation of the fallback is slightly verbose.

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, no-output-schema tool, the definition covers the action, the two addressing modes, the irreversibility of recurring deletions, and the full confirmation protocol. Nothing required to call it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: id provenance, case-insensitive label matching, and the disambiguation role of 'device'. The confirmToken flow is also explained in prose, reinforcing the schema's warning against inventing or reusing tokens.

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 precise verb+resource pair ('Cancel (delete) an Alexa alarm, timer or reminder') and immediately names the sibling tool that supplies the id (alexa_list_alarms_reminders), so it is distinguishable from alexa_create_reminder and alexa_create_timer without opening any schema.

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

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

Gives explicit selection rules: use 'id' from alexa_list_alarms_reminders, or fall back to 'label' (adding 'device' when a label collides). It also describes the two invocation modes for confirmation, which is the key procedural guidance an agent needs before calling.

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 supply generic hints (readOnly=false, destructive=false, openWorld=true); the description adds genuinely new behavioral facts: an offline device surfaces as an error rather than a silent no-op, and the tool always asks for confirmation first, with a concrete two-step fallback and a confirmToken that must never be invented or reused. That is materially more than the annotations convey.

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

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

Purpose and action list are front-loaded, then sibling exclusions, then the confirmation protocol in a compact final sentence. It is dense for a single paragraph and the confirmation detail partially duplicates the confirmToken schema description, which costs a point, but no sentence is 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 still covers the two response shapes an agent will encounter (error on offline devices, and confirmation-required preview/confirmToken), which is the critical missing piece. It stops short of describing success-response contents or idempotency of repeat calls, a minor residual 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 the schema already documents every parameter, including the confirmToken rules and enum values. The description's parameter-related content (brightness 0–100, colorName/colorTemperatureName examples, target sourced from alexa_list_smart_home) largely restates the schema, so baseline 3 applies.

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

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

States a specific verb (control) plus resource (Alexa smart-home device, group or scene) and enumerates the action set (on/off, brightness, colour, white temperature, scene activation). It also explicitly names what it is NOT for, routing thermostats, device modes and doors to their own tools, so it is distinguishable from siblings without opening the schema.

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

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

Explicitly names alternatives and the conditions selecting them: 'Thermostats use alexa_set_thermostat; other device modes (fan mode, vacuum) alexa_set_device_mode; doors have their own tools.' It also spells out the confirmation workflow (client prompt vs. two-step preview/confirmToken), which is exactly the guidance an agent needs before invoking.

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

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

Beyond annotations (which only mark it non-readOnly, non-destructive, openWorld), the description discloses the confirmation behavior: a client prompt where supported, otherwise a two-phase preview/confirmToken round-trip governed by MCP_CONFIRM_MODE. This is exactly the operational context an agent needs before calling a mutating 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?

Front-loaded with the core action and time formats, then the sibling routing, then the confirmation flow. Every sentence carries distinct information, with the confirmToken warning living appropriately in the schema rather than bloating the description.

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 mutating tool with no output schema, the description covers the critical unknowns: the mutual-exclusivity of the time inputs, the timezone resolution rule, and the exact confirmation protocol including the fallback token loop. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it frames 'at' vs 'inMinutes' as alternative time inputs (a relationship the schema does not express), and clarifies that the time resolves against the device's time zone rather than the caller's.

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 specific verbs and resources ('Set an Alexa reminder ... or an alarm on an Echo device') and explicitly distinguishes itself from a sibling by naming alexa_create_timer for the countdown case. An agent can separate this from other siblings without opening the schema.

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

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

Explicitly routes the agent: use this for reminders/alarms, use alexa_create_timer for a countdown timer. It also states the time can be given two ways and that the time is applied in the device's own zone, so the selection conditions are clear.

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

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

Annotations only declare that this is a non-read-only, non-destructive, open-world write; the description adds the materially important behavioral fact that the tool is gated behind a user confirmation, and details both confirmation modes including the fallback token flow. That is exactly the kind of trait an agent must know before calling.

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

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

Two sentences with the purpose front-loaded and the confirmation caveat following, so the reader gets the primary action first. The second sentence is long and parenthetical (MCP_CONFIRM_MODE reference, nested conditions), which costs some readability.

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 covers the phase-1 'confirmation-required' response and the token handshake, and the schema ties 'device' back to alexa_list_devices. It stops short of describing failure modes (unreachable device, unsupported device) or whether an authenticated session is a prerequisite.

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

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

Schema description coverage is 100%, so the baseline is 3: the schema already documents label, device, minutes, and confirmToken thoroughly, including the token's restrictions. The description restates the confirmToken lifecycle in flow terms but adds no new per-parameter meaning beyond what the schema text already provides.

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

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

States a specific verb and resource ('Start an Alexa countdown timer on an Echo device') with a concrete example ('10-minute pasta timer'), which is far more specific than a tautology. It does not, however, differentiate itself from the sibling alexa_create_reminder, which an agent could plausibly confuse with a timer.

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 explicit procedural guidance for the confirmation flow: confirm in-client where supported, otherwise expect a preview plus confirmToken and only proceed on the repeat call. What is missing is routing guidance against alternatives such as alexa_create_reminder or alexa_run_builtin for timer-like behavior.

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

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

Annotations declare the write/destructive/openWorld profile, and the description adds substantial context beyond that: it registers the server as an 'alexa-mcp' device on the Amazon account, saves the session, and verifies by reading the device list. It also discloses the single-use nature of the sign-in link, which the annotations do not convey.

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

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

Front-loads the purpose, then parameters, then side effects, then failure handling. Four tight sentences with no filler; every clause earns its place.

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

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

For a 2-param write tool with no output schema, the description covers the trigger, inputs, side effects, and failure recovery. An agent has everything needed to invoke it correctly and understands the resulting state change.

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

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

Schema description coverage is 100%, so the schema already documents both required parameters including the 'or its authorization code' alternative. The description restates the same information without adding format or syntax beyond the schema, warranting the 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?

States a specific verb+resource ('Finish an Alexa sign-in') and explicitly ties it to its counterpart alexa_begin_login, so an agent can distinguish this from the ~35 other alexa_* siblings. The scope (completing a login flow) is unambiguous.

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

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

Explicitly states the prerequisite ('started by alexa_begin_login'), what must be passed, the one-time-use constraint ('Each sign-in link can be finished once'), and the recovery path ('if it fails, start again with alexa_begin_login'). This covers when-to-use and the fallback alternative.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the mutation risk is known. The description adds genuinely new behavioral context not in annotations: that every invocation requires user confirmation, and the exact two-phase token protocol when the client lacks elicitation support.

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

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

Purpose is front-loaded in one sentence, then the confirmation mechanics in a second. Both earn their place, though the parenthetical '(see MCP_CONFIRM_MODE)' points at an env var an agent cannot read and adds little actionable value.

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

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

Covers purpose, required params via a complete schema, and the confirmation/return-token behavior in lieu of an output schema. It stops short of describing failure modes (e.g., device unreachable) or overlapping-action boundaries with alexa_stop/alexa_playback.

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 device, command enum, and confirmToken are already fully documented in the schema. The description reinforces the token flow but adds no syntax, format, or constraint details beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb set and resource: 'Control a Fire TV through Alexa' followed by an explicit enumeration of the five supported actions (on/off, pause/resume, home). This distinguishes it from siblings like alexa_playback, alexa_stop, and alexa_speak, which handle other device/action domains.

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 clear conditional guidance for the confirmation flow: use the elicitation prompt where supported, otherwise two-step preview + confirmToken. It does not say when to choose this tool over alexa_stop or alexa_playback for overlapping actions (pause/resume), leaving some sibling routing to inference.

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

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

Annotations already flag destructiveHint=true, but the description adds substantial context beyond them: the security rationale for confirming, the exact confirmation handshake (prompt vs. phase-1 preview + confirmToken), and a pointer to MCP_CONFIRM_MODE. This is exactly the superset of behavioral disclosure a destructive tool needs.

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-loads the action and resource, then escalates to the safety warning and confirmation flow. Slightly dense in the final clause (MCP_CONFIRM_MODE parenthetical), but every sentence contributes and none is 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?

For a destructive, open-world tool with no output schema, the description covers the action, the risk, the confirmation requirement, and both confirmation mechanisms. Nothing critical to invoking it correctly is missing.

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

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

Schema coverage is 100% and the schema already documents action, target, and confirmToken in detail (including 'never on the first call, never invented'). The description restates the two-step flow but adds little parameter-level detail the schema does not already carry; 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 (open/close) and a specific resource (a garage door connected to Alexa), which is unambiguous even among the smart-home siblings like alexa_control_smart_home or alexa_lock. An agent can identify the operation without opening the schema.

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

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

Gives clear context — garage doors connected to Alexa, and that opening is a security-sensitive action requiring user confirmation — plus the two invocation paths (client elicitation vs. preview+confirmToken). It does not, however, contrast with sibling tools (e.g. alexa_control_smart_home) or state when-not to use it.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered without the description. The phrase 'right now' adds a useful temporal cue that this is live state rather than configuration, but nothing is said about which devices are included, what identifies them in the result, or whether the call can fail when no session is active.

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

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

A single short sentence with no wasted words, and the key qualifier ('switched on right now') is front-loaded. It reads as a sentence fragment rather than an imperative verb phrase, which slightly weakens immediate recognizability as an action, but the compactness is otherwise good.

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

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

For a no-parameter read-only query this is close to sufficient, and annotations carry the safety profile. Since no output schema exists, the description would ideally hint at the return shape (e.g. a list of device names with DND enabled), which it only gestures at with 'which Alexa devices'.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to disambiguate, and it correctly implies the query is global across all devices rather than parameterized.

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 resource (Alexa devices' Do Not Disturb / quiet mode state) and scope ('switched on right now'), so an agent knows this is a status query rather than a mutation. It does not explicitly name the sibling alexa_set_do_not_disturb as the write counterpart, so sibling differentiation is left to inference.

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

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

Usage is implied by the phrasing: use this to read DND status, as opposed to alexa_set_do_not_disturb to change it. However, there is no explicit when-to-use statement, no mention of the setter alternative by name, and no prerequisites or context (e.g. whether a login session is required, as alexa_begin_login suggests).

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=true), so the bar is lower. The description usefully adds the shape and units of the reading (bass, mid, treble in dB), which matters because there is no output schema — this is genuine added context rather than repetition.

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 operation front-loaded and the returned fields trailing; nothing is redundant or padded.

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

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

For a simple one-param read with readOnly/openWorld annotations and a fully described parameter, the definition covers the essentials and compensates for the absent output schema by naming the returned bands. It lacks only minor operational context such as error/offline behavior.

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

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

Schema description coverage is 100% and the single 'device' parameter is fully documented there (name or serial, case-insensitive, partial match). The description only adds that the target is an Echo speaker or soundbar, a marginal widening beyond the schema's 'An Alexa device', 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 ('Read ... equalizer') and even enumerates the returned bands with units (bass, mid, treble in dB). It is distinguishable from alexa_set_equalizer by the 'Read' verb, but it never explicitly names or excludes a sibling, so it stops just short of a 5.

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

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

There is no when-to-use guidance, no prerequisites (e.g. device online/authenticated), and no mention of the counterpart tool alexa_set_equalizer for modifying the same settings. The read-vs-write intent is only implicit in the verb.

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=true, so safety is partly covered, but the description adds genuinely new behavioral context: the default omission of completed items and a prompt-injection warning that returned text is third-party and untrusted. It does not disclose return structure or whether results are 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?

Three short sentences, each load-bearing: what it reads, the default filtering rule, and the untrusted-content warning. The purpose is front-loaded and nothing is padded.

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

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

With no output schema, the description should ideally sketch what comes back; it hints at third-party text but does not mention item ids or completion status that the update/remove siblings would need. Given the annotations cover the safety profile and the injection warning covers the riskiest aspect, this is close to complete but leaves a modest return-shape 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 the 'list' selector and includeCompleted are already documented in the schema; the description only restates the includeCompleted default behavior. Baseline 3 is appropriate when the schema does the heavy lifting and the description adds no extra semantics such as accepted list-name formats.

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 ('Read the items on an Alexa shopping or to-do list') that cleanly contrasts with the write siblings alexa_add_list_item, alexa_update_list_item, and alexa_remove_list_item. The scope (shopping or to-do list) and the default filtering behavior are stated up front, so an agent can pick this tool without opening the schema.

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

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

Usage is only implied: the description notes completed items are omitted unless includeCompleted is set, which tells the agent how to widen the result set, and the schema points to alexa_list_lists for list names/ids. But there is no explicit when-to-use guidance or statement of when a sibling (e.g. alexa_add_list_item) would be the right call instead.

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=true, so the safety profile is covered. The description adds useful context that the data comes 'from its player', implying live device state rather than cached metadata, but says nothing about what happens if nothing is playing or if the device is unreachable.

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

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

A single front-loaded sentence that identifies the resource, the scope ('right now'), and the payload fields, with no filler. Nothing needs trimming or reordering.

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-only tool with full schema coverage and no output schema, the description enumerates the returned fields (media state, title, artist, provider), which compensates for the missing output schema. Only edge-case behavior (nothing playing, offline device) is unaddressed.

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

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

Schema description coverage is 100%, and the schema itself documents the single 'device' parameter thoroughly (name from alexa_list_devices, case-insensitive partial match, or serial number). The description contributes no additional parameter meaning, 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 states a specific verb+resource: reading current media playback state from an Alexa device's player, enumerating the returned fields (media state, title, artist, provider). It is clearly distinct from control-oriented siblings like alexa_playback, though it never names an alternative 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?

Use is implied by 'right now' — this is a point-in-time read rather than a playback command — but there is no explicit when-to-use guidance, no exclusions, and no pointer to the related control sibling (alexa_playback) or to alexa_list_devices for discovering device names.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuinely useful behavioral context beyond them: 'An unreachable device is reported on its row, not as a failure' tells the agent partial results are normal, and the view field's field-dropping behavior is surfaced. Auth, rate limits, and pagination remain unstated.

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 verb and resource, then the returned readings, then the targeting rule and the unreachable-device caveat. The long enumerative opening sentence is dense but each listed reading earns its place by pre-empting 'what will I get back' questions given there is no output 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?

There is no output schema, so the description carries the return-value burden and does so thoroughly by enumerating the fields per device type, plus the unreachable-device edge case. Combined with full schema coverage of the inputs, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, including the targets provenance and the compact/full enum. The description's mention of naming devices or passing a kind restates the schema rather than adding syntax or format detail, 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 ('Read the live state of Alexa smart-home devices') and enumerates exactly which readings are returned — thermostat mode/setpoints, light on/brightness/colour, lock, contact/motion, reachability. This clearly separates it from listing tools like alexa_list_smart_home, but no sibling is named explicitly, so it stops short of a 5.

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

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

The description explains how to scope a read ('Name the devices, or pass a kind ... to read every one of that kind'), which implies usage, but it never says when to choose this tool over alexa_control_smart_home, alexa_set_thermostat, or alexa_list_smart_home, and gives no exclusions. Usage is inferred 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 cover readOnly, idempotent and openWorld, but the description adds substance beyond them: it performs one authenticated request, never returns the credential itself, and enumerates exactly what is reported. The security-relevant behavior (credential never exposed) is a genuinely useful disclosure the annotations do not carry.

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 mechanism, then the reported outputs, then the call condition, so the ordering is good. It is slightly repetitive ("alexa.amazon.com" three times) and contains a typo ("a alexa.amazon.com-side problem"), which keeps it out of 5 territory.

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 takes on the return-value burden and does so: it lists credential source, acceptance, round-trip time, and the diagnostic hint categories. Nothing an agent needs to choose or call this zero-param tool is missing.

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

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

Zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly implies the tool is called with no inputs.

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

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

States a specific verb chain (resolves credential, makes one authenticated request) and the exact resource (alexa.amazon.com), and reads as a diagnostic distinct from action siblings like alexa_speak or alexa_session_status. An agent can tell this is a pre-flight/breakage-locator rather than a functional Alexa control.

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?

"Call this when a real tool fails and you want to know which hop broke" gives a clear trigger condition and framing relative to the other tools. It does not name a specific sibling alternative (e.g. vs alexa_session_status) or state when-not-to-use, so it falls short of a 5.

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

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

Annotations cover the safety profile (readOnlyHint, openWorldHint), but the description adds genuinely valuable context beyond them: the returned text is third-party authored and must be treated as data, not instructions. It also discloses the return fields. It doesn't cover pagination or empty-result behavior, 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 sentences, zero waste, and the core purpose plus the security caveat are front-loaded. Every clause earns its place.

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

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

There is no output schema, so enumerating the returned fields (id, label, device, date/time, on-state, recurrence) is necessary and present. The prompt-injection warning completes the picture for a read-only, open-world list tool; only minor behaviors like empty results are unaddressed.

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 enum for type is documented in the schema itself. The description's 'Optionally filter by type' adds no syntax or meaning beyond that, 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?

Specific verb+resource ('List the alarms, timers and reminders set on the account's Alexa devices') and it enumerates the returned fields. An agent can distinguish it from siblings like alexa_create_reminder, alexa_cancel_alarm_reminder, and alexa_list_routines without opening any schema.

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

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

It notes the optional type filter, which implies when to narrow results, but it never names an alternative tool or states when not to use this one (e.g., vs. listing routines or lists). Usage is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful non-schema context: the returned text is third-party authored and untrusted, and must be treated as data rather than instructions — an injection-safety disclosure the annotations do not convey.

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

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

Two sentences, no filler, with the functional scope front-loaded and the safety caveat following it. Every clause 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?

For a zero-parameter, read-only listing tool with no output schema, the description is sufficient: it enumerates the returned facets (paired devices, connection state, streaming status) and adds the untrusted-content handling rule. Nothing an agent needs to call it correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate at the input level.

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 a precise resource (Bluetooth devices paired with each Alexa device), and further specifies the returned facets: pairing, connection state, and whether the Echo is streaming. It is readily distinguishable from siblings like alexa_list_devices or alexa_get_now_playing.

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

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

The description makes the tool's scope evident (Bluetooth pairing/streaming status), so intended usage is implied, but it never states when to reach for this tool versus alexa_list_devices, alexa_get_now_playing, or alexa_session_status, nor any preconditions. Adequate but with a clear routing gap.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description goes beyond them by disclosing what is returned: both the current value of each mode and the set of values it accepts, which is genuinely useful for planning a subsequent write. No pagination, auth, or failure behavior is mentioned, 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?

One front-loaded sentence carries the purpose, and a second short sentence routes to the setter. The parenthetical device examples are dense but each illustrates a distinct mode domain, so little is wasted; the inline enumeration is the only mild drag.

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 correctly compensates by stating that both current settings and accepted values are returned, and it names the complementary tool for acting on them. Nothing essential for calling this read-only list tool is missing.

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

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

Schema description coverage is 100%, so the single 'target' parameter is already documented as a device name or id from alexa_list_smart_home. The description adds device-type context but no additional syntax or constraints for the parameter, 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 (List) and resource (device mode settings) scoped to Alexa smart-home devices, and concretizes it with examples across device classes (thermostat fan, Roomba state, light effect, washer/purifier). It also implicitly separates itself from the setter counterpart by framing output as current values plus accepted values.

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

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

Gives a clear downstream workflow: read the setting/value names here, then pass them to alexa_set_device_mode. It does not, however, state when to prefer this over overlapping readers such as alexa_get_smart_home_state or alexa_control_smart_home, so the routing guidance is good but not exhaustive.

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=true, so the safety profile is covered. The description adds real value by disclosing the returned fields (name, serial, device family, online status), which matters since there is no output schema. It does not cover pagination or edge cases, but it exceeds the minimum the annotations require.

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 dense sentences with no filler: scope and returned fields first, then the cross-tool usage hint and the explicit exclusion. Every clause earns its place.

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

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

Although there is no output schema, the description compensates by naming the returned fields, and it fully disambiguates against the nearest sibling. An agent has everything needed to select and call this tool correctly.

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

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

Schema coverage is 100% and the single 'view' parameter is fully documented with its enum and default in the schema. The description adds nothing about the parameter, so baseline 3 is correct when the schema does all 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+resource ('List the Echo speakers, Echo Shows, Fire TVs and other Alexa devices') and enumerates the device categories covered, letting an agent tell it apart from alexa_list_smart_home without opening either schema.

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

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

Explicitly routes the agent in both directions: use name/serial from this tool with other alexa_ tools, and use alexa_list_smart_home for thermostats, lights, plugs, switches and locks. The exclusion and the named alternative make the boundary unambiguous.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered without the description. The description adds one useful behavioral fact beyond that: the output includes a count of active items per list. It says nothing about auth requirements, rate limits, or account-scoping behavior, which is acceptable given the annotations but not additive beyond payload shape.

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

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

A single sentence with no filler. The core action and scope are front-loaded, and the one extra clause (item counts) earns its place by describing the return payload in the absence of an output 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 zero-parameter read operation whose annotations already cover the safety profile, the description is nearly sufficient: it names the resource and hints at the return shape. With no output schema, it could go one step further and mention the identifiers/names returned that feed alexa_get_list_items, but nothing needed to invoke it correctly is missing.

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

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

The tool takes zero parameters and the description correctly introduces no non-existent arguments, so there is nothing to mis-document. Baseline for a zero-parameter tool is 4; there is no argument syntax the description could meaningfully add.

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

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

Specific verb ("List") plus a precisely scoped resource ("shopping and to-do lists on the account"), and it even discloses the payload detail of per-list active item counts, which no sibling provides. It is not confused with alexa_list_devices, alexa_list_routines, or alexa_list_volumes. However it never explicitly contrasts itself with alexa_get_list_items, the closest sibling, so it stops short of full sibling differentiation.

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

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

There is no explicit when-to-use statement, no prerequisites, and no named alternative. Usage is only implied by the surrounding toolset: an agent can reasonably infer this is the discovery call that precedes alexa_get_list_items. Adequate but leaves the ordering/allowed-argument context to inference, since get_list_items probably needs a list identifier that must come from here.

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=true, so the safety profile is covered. The description adds the return-shape breakdown (what each routine carries), but says nothing about auth requirements, pagination, or result limits. With annotations carrying the safety burden, a 3 fits – additive but modest.

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 tight sentence with the resource front-loaded and the field breakdown following the em-dash. Every clause earns its place; no filler or repetition.

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

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

There is no output schema, so the description must carry the return shape – and it does, listing name, id, enabled state, and trigger types. This makes the tool callable with confidence, though it omits pagination/limit behavior that a full inventory of returns might include.

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 ('view') and schema coverage is 100%, so the schema already documents both enum values fully. The description does not mention 'view' or when to pick compact vs full, so it adds nothing over the schema – baseline 3 is correct.

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

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

States a specific verb ("List") plus resource ("Alexa routines") and enumerates the returned fields (name/trigger phrase, id, enabled, trigger type). The verb 'list' clearly separates it from the sibling alexa_run_routine without needing 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?

A listing/read tool whose usage is largely self-evident, but the description offers no explicit when-to-use framing and names no alternative. It never says e.g. "use this to discover an id before calling alexa_run_routine," so the routing to the obvious sibling is only 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=true, so safety is covered; the description still adds real value by disclosing the scope of the entity inventory and which capabilities this server supports per device, information not present in the annotations. It stops short of describing pagination or response size behavior for large device fleets.

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

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

Front-loaded with the core purpose and the alexa_list_devices exclusion, then the action-routing map, then the optional filter. The action mapping is dense but each clause earns its place by preventing a wrong sibling call. Slightly long, but 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?

With no output schema, the description carries the burden of explaining coverage and does so well, including the entity classes returned and the actions available per entity. Response shape is delegated to the view parameter in the schema, which is a reasonable division, though no return-shape detail is given beyond 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 description coverage is 100% – both parameters, including the compact/full view enum, are already documented in the schema. The description repeats the kind filter withexamples (THERMOSTAT, LIGHT, SMARTPLUG, SMARTLOCK, GARAGE_DOOR) but adds no syntax or semantics beyond what the schema already provides. Baseline 3 applies.

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

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

States a specific verb (list) and a precisely scoped resource (smart-home devices, groups and scenes Alexa controls), enumerating entity types such as thermostats, locks, garage doors and scenes. It also explicitly contrasts itself with the similarly named sibling alexa_list_devices, so an agent can disambiguate 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?

Provides an explicit when-not clause ("These are NOT in alexa_list_devices, which only lists Echo speakers...") and routes each entity type to the correct follow-up tool (setTemperature via alexa_set_thermostat, lock/unlock via alexa_lock, open/close via alexa_garage_door, modes via alexa_set_device_mode, the rest via alexa_control_smart_home). This is a full decision map, not implied 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=true, so the safe-read profile is covered structurally. The description adds useful scope context — the 0–100 range, that mute state is included, and that not all devices report a value — but says nothing about result shape, grouping, or whether devices that don't report are omitted or null.

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; the key scope constraint (all devices that report a value) is packed in without padding. Nothing could be trimmed 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 zero-parameter read tool with annotations covering the safety profile, the description is mostly adequate, but with no output schema in existence the return structure (per-device mapping of volume and mute) is left entirely to inference. A brief note on the response shape would close the 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?

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate, and it correctly implies a global, unfiltered read with no inputs to specify.

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 the resource (speaker volume and mute state of Alexa devices) and its scope (every device that reports one), which is enough to distinguish it from the mutating sibling alexa_set_volume. It is phrased as a noun fragment describing returned data rather than a verb+resource action, so the read/list intent is implied rather than stated.

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

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

There is no when-to-use guidance and no reference to alternatives such as alexa_set_volume or a per-device lookup. The qualifier 'every device that reports one' hints at scope but does not tell an agent when this tool is the right choice over its many siblings.

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

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

Goes well beyond the annotations (destructiveHint/openWorldHint) by disclosing the security impact of unlocking, the Amazon-side voice PIN/app requirement, how refusal surfaces (as an error), and the full two-phase confirmation protocol including preview plus confirmToken. This is exactly the extra behavioral context the structured fields cannot carry.

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-loads the core action, then layers the security warning and the confirmation mechanics in a logical order with no filler. It is dense but every sentence carries operational weight; only the parenthetical MCP_CONFIRM_MODE pointer is slightly cryptic without a reference.

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, open-world mutation with no output schema, the definition covers the risk, the external-auth failure mode, and the exact retry contract. Nothing an agent needs to invoke it correctly — including how to handle a confirmation-required response — is missing.

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

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

Schema description coverage is 100%, so action, target and confirmToken are already fully documented, including the confirmToken's phase-1 provenance and non-reuse rule. The description reinforces the confirmToken flow but adds no syntax or format detail beyond the schema, making the baseline 3 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 pair and resource ("Lock or unlock a smart lock (door lock) connected to Alexa"), immediately disambiguating it from close siblings such as alexa_garage_door and alexa_control_smart_home. An agent knows exactly what operation this performs without opening the schema.

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

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

Gives clear conditional guidance: confirm with the user before unlocking, and expect a possible voice PIN / app challenge. It lacks explicit sibling routing (e.g. when to prefer alexa_control_smart_home or alexa_get_smart_home_state), so it stops short of the 5 benchmark, but the caution and prerequisites are well 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 only declare it is a non-read-only, open-world, non-destructive action. The description adds substantial context beyond that: a mandatory user confirmation gate, a client-dependent two-path protocol, and the existence of a preview response carrying a confirmToken. That is exactly the behavioral disclosure the annotations do not provide.

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

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

Two sentences with the capability front-loaded and the confirmation protocol second. No filler; the parenthetical pointer to MCP_CONFIRM_MODE is compact and points to deeper detail rather than restating it.

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 an action tool with no output schema, the description covers the non-obvious parts of the call flow, including the shape of the phase-1 response. It stops short of describing the successful result (e.g., playback-state change confirmation), but nothing critical to invoking it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning about parameter lifecycle: confirmToken is only for the fallback path, is never used on the first call, and is ignored under elicitation. It clarifies when the parameter is meaningful rather than just what it is.

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

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

States a specific verb set (play, pause, next, previous) against a specific resource (an Alexa device's current media), matching the command enum exactly. An agent can tell this apart from alexa_stop and alexa_get_now_playing from the description alone.

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 explicit operational guidance: the confirmation prompt applies when the client supports one, otherwise a two-step preview/confirmToken flow is required. It does not name sibling alternatives (e.g., alexa_stop for halting playback), so it falls short of full when/when-not routing.

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

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

Annotations already declare destructiveHint and openWorldHint, but the description adds the concrete consequence (quantity or note on the item is lost) and fully documents the confirmation protocol, including that the first call may only return a preview plus confirmToken. That is substantial context beyond the structured fields.

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-loads the action, then the destructive warning, then the confirmation mechanics in a compact three-sentence flow. Every clause earns its place and the highest-risk information arrives early.

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?

Even without an output schema, the description explains what phase 1 returns (a preview and a confirmToken) and under which client conditions, so an agent can handle either confirmation path correctly. Nothing essential for a destructive three-parameter tool is missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the schema already documents list, item, and confirmToken. The description adds routing value by tying item ids to alexa_get_list_items and reiterating that the token must never be invented or reused, which reinforces the schema's guidance rather than merely restating it.

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

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

States a specific verb (Delete) and resource (an item from an Alexa shopping or to-do list) and immediately distinguishes itself from the update/add siblings. An agent can tell it apart from alexa_update_list_item or alexa_add_list_item 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?

Names the accepted identifier sources (item name or item id from alexa_get_list_items, list id from alexa_list_lists) so the agent knows the prerequisite calls. It also states the exact confirmation branch conditions (elicitation-capable client vs. two-step token fallback), leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=true, but the description adds substantial context beyond them: the audio is audible to everyone in the room, a confirmation is required, and the two-step confirmToken fallback is spelled out with explicit warnings not to call it on the first attempt, invent it, or reuse it. That is exactly the operational detail an agent needs for a state-changing, audible action.

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 dense sentences, purpose front-loaded before the confirmation caveat. The long enumeration of features is justified by the enum width, though it is slightly repetitive with the schema's command list.

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

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

For a three-parameter tool with no output schema, everything needed is present: audience impact, required confirmation semantics, the two-phase token workflow, and the relationship to MCP_CONFIRM_MODE. The phase-1 'confirmation-required' response is even described, compensating for the absent output schema.

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

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

Schema description coverage is 100%, so device, command and confirmToken are already fully documented in the schema, including the enum values and the device naming rules. The description's mention of the command list and the confirmToken flow largely restates what the schema already provides, so it sits at the baseline rather than adding new meaning.

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

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

Specific verb+resource ('Have an Echo play one of Alexa's built-in features out loud') with the full command set enumerated, so an agent can immediately distinguish it from alexa_speak (arbitrary text), alexa_playback (media control) and alexa_run_routine (user routines). The scope is unambiguous.

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

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

Gives clear context for when this tool applies by naming the built-in features it covers and describing the mandatory confirmation step. It stops short of explicitly naming alternatives (e.g. 'for custom spoken text use alexa_speak'), so the routing decision is implied 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 flag destructive=true and openWorld=true, but the description adds real context beyond them: the breadth of possible side effects (lights, locks, messages, purchases) and the full confirmation protocol including the two-step preview + confirmToken fallback and MCP_CONFIRM_MODE. This is exactly the extra behavioral disclosure a mutation tool needs.

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 most important constraint (runs arbitrary side effects; confirm first) is front-loaded, and each sentence carries distinct information. It is dense rather than padded, though slightly long for three parameters.

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 helpfully explains the phase-1 'confirmation-required' response shape and the confirmToken round-trip. It covers behavior thoroughly; only the exact response payload fields are left implicit.

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

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

Schema description coverage is 100%, so the schema already documents routine, device, and confirmToken with defaults and constraints. The description reinforces the confirmToken usage rules but adds no syntax or format detail beyond the schema, 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+resource ('Run an Alexa routine now') and clarifies the exact semantics ('exactly as if its trigger fired'), which distinguishes it from siblings like alexa_run_builtin or alexa_speak. An agent can tell what this does without opening the schema.

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

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

Gives a clear precondition ('check what it does before running it') and describes the confirmation behavior the agent must follow. It does not explicitly name a competing sibling (e.g. alexa_run_builtin) to route between, so it stops just short of an explicit when/when-not/alternatives statement.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered structurally. The description adds genuinely useful behavior context beyond that: it enumerates the reported fields and states that no network call is made, which reinforces and clarifies the openWorldHint=false annotation rather than contradicting it.

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

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

Two sentences, no filler, with the core purpose front-loaded and the disambiguation against the sibling immediately after. Every clause 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?

For a zero-parameter, read-only tool with no output schema, the description tells the agent what will be reported (registration, origin, Amazon site, cookie age) and that the call is purely local. Nothing an agent needs to invoke it correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4 per the rubric; there is nothing for the description to disambiguate. The description's enumeration of reported fields adds some value, but it is about output, not parameters.

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

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

The description uses a specific verb (report) on a specific resource (this Alexa server's configuration) and enumerates exactly what is reported: registration presence, its origin, the Amazon site, and session cookie age. It also names the sibling it must not be confused with (alexa_healthcheck), so an agent can distinguish the two 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?

It explicitly contrasts itself with the nearest alternative: this tool makes NO network call, whereas alexa_healthcheck verifies Amazon still accepts the session. That contrast gives the agent a clear selection rule (inspect local configuration vs. validate live session) rather than leaving usage to inference.

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

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

Annotations only say non-readonly, non-destructive, idempotent, open-world; the description goes well beyond by disclosing the two-phase confirmation behavior: a client-side confirmation prompt where supported, otherwise a preview response carrying a confirmToken that must be echoed on a repeat call. It also clarifies the token must never be invented or reused, which is exactly the kind of behavioral detail annotations cannot convey.

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

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

Front-loads the what and the examples, then the alternative tool, then the confirmation caveat - a sensible ordering. It is dense and slightly long, but nearly every clause carries operational weight (the confirmToken sentence is partly redundant with the schema description).

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 no output schema and an unusual two-call confirmation path, the description supplies everything an agent needs: valid value sources, sibling routing, and the exact token round-trip contract. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: `setting` disambiguates which mode control when a device has several, and `mode` accepts a name or an id as surfaced by alexa_list_device_modes. The confirmToken lifecycle is also explained beyond the schema's warning text.

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

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

States a specific verb+resource (change a mode setting on an Alexa smart-home device) and immediately enumerates concrete instances: thermostat fan mode, robot vacuum mode, light effect. It also names the siblings it is NOT (alexa_garage_door, and implicitly alexa_list_device_modes for value lookup), so an agent can separate it from alexa_control_smart_home or alexa_set_thermostat without opening schemas.

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

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

Explicit when (changing a mode-type setting), explicit when-not (garage doors - go to alexa_garage_door), and names the dependency tool for valid values (alexa_list_device_modes). The guidance is actionable and leaves nothing to inference about routing.

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

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

Beyond the annotations (write, idempotent, non-destructive), it discloses the non-obvious behavioral protocol: a client-side confirmation prompt when available, otherwise a preview-plus-confirmToken two-step fallback that must not be reused. This is exactly the kind of interaction contract that annotations cannot express.

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 action before the confirmation mechanics. The second sentence is dense and packs several clauses, but every clause carries necessary protocol 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 mutation tool with no output schema, the description covers what matters: the write semantics and the full confirmation/token lifecycle, plus a pointer to MCP_CONFIRM_MODE. Return-shape detail is absent but the confirmation-required response is described, leaving only minor gaps.

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

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

Schema description coverage is 100%, so each parameter is already documented in the schema, including the confirmToken's phase-1 origin and single-use rule. The description echoes the two-step flow but adds no parameter detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource (switch Do Not Disturb on or off) for a specific device, and clarifies the DND/quiet-mode synonym. It implicitly separates itself from the read sibling alexa_get_do_not_disturb via the on/off switch semantics, but never names that sibling explicitly.

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

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

The description thoroughly explains the confirmation flow but gives no guidance about when to prefer this over alternatives such as alexa_get_do_not_disturb or device-mode tools. Usage is implied by the verb rather than stated as a routing rule.

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?

Discloses behavior well beyond the annotations: partial-update semantics ('bands you leave out keep their current value'), the confirmation requirement, the preview+confirmToken fallback, and the constraint that the token must never be reused or invented. This is exactly the kind of mutation-safety context the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) cannot carry.

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-loads the action and range in the first sentence, then the confirmation mechanics. Dense but every clause earns its place; the parenthetical reference to MCP_CONFIRM_MODE is a slight compaction rather than padding.

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

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

For a mutation tool with no output schema, this covers everything an agent needs: the target, the band range, partial-update behavior, and the full confirmation handshake including the failure mode of a client without elicitation.

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 adds the partial-update rule (omitted bands retain current value), which is not stated anywhere in the schema and materially changes how the agent should fill the optional parameters.

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

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

States a specific verb (set) and resource (an Echo speaker or soundbar's equalizer), names the exact fields (bass, mid, treble) and their range, and is trivially distinguishable from the sibling alexa_get_equalizer by the verb alone.

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?

Clearly explains how to invoke the tool, including the confirmation protocol and the two-step fallback, which is the critical usage context. It does not explicitly name when-not-to-use or point at alternative siblings, so it stops short of a 5.

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

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

Adds substantial behavior beyond the annotations: it reads the thermostat first, refuses out-of-range setpoints, defaults units to the device scale, and requires user confirmation via either elicitation or a preview+confirmToken two-step flow. This is exactly the kind of interaction semantics annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) cannot convey, and nothing conflicts with them.

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

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

One dense, front-loaded paragraph ordered by importance: what it does, then per-mode parameter rules, then safety behavior, then confirmation. Every clause is load-bearing; it is slightly long for a single block but has no filler sentences.

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 7-parameter mutation tool with no output schema, it covers the mutation model, unit defaults, validation/refusal behavior, and the full two-phase confirmation contract including token handling. Nothing an agent needs to invoke it correctly, including the easy-to-mishandle confirmToken, is left unstated.

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

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

Schema coverage is 100%, but the description still adds real semantic value the schema does not: in AUTO the omitted bound is retained from the current setting, and HEAT/COOL consume the single temperature rather than the bounds. That clause alone raises it above the baseline-3 case for fully documented schemas.

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

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

States a specific verb+resource ('Set an Alexa-connected thermostat') and enumerates exactly what is controllable: setpoint (heat-to/cool-to) and mode. An agent can distinguish this from sibling all-purpose tools like alexa_control_smart_home 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?

Gives mode-conditional usage rules ('in AUTO mode pass lower/upper', 'in HEAT or COOL mode pass temperature') and explains the confirmation prerequisite. It stops short of naming alternative tools or stating when not to use this one versus alexa_control_smart_home, so it is clear context rather than 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?

With annotations declaring readOnlyHint=false and destructiveHint=false, the description goes far beyond them: it discloses that turning ON saves each thermostat's mode and setpoints before overwriting them, that OFF restores exactly what was saved, that OFF thermostats stay OFF, that a repeat ON is refused, and that a confirmation preview/confirmToken flow exists. This is unusually rich behavioral context for a mutation 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?

Purpose is front-loaded in the first sentence, and the following sentences each carry real information about side effects and confirmation. It is dense and contains a long parenthetical, but given the emulation and two-phase confirmation complexity the length is largely justified.

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

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

For a tool with no output schema and moderate complexity, the description covers side effects, reversibility, idempotency, defaults, targeting, and the full confirmation protocol, leaving no material gap an agent would need before invoking it.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including defaults and the confirmToken protocol. The description largely restates the same defaults (55/85 degrees, all thermostats) and adds little parameter detail the schema lacks, 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 states a specific verb and resource ('Turn thermostat vacation mode (away mode) on or off') and clarifies the emulation rationale, which separates it from siblings like alexa_set_thermostat and alexa_set_device_mode. An agent can identify exactly what this tool does without opening the schema.

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

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

It explains the context (no native vacation mode, so this emulates one) and the on/off semantics with defaults, which is clear when-to-use guidance. It does not explicitly name the alternative tools (e.g. alexa_set_thermostat) an agent might fall back to, so it stops short of full when/when-not routing.

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

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

Annotations already declare the mutation/idempotence/safety profile, and the description adds substantial behavior beyond them: the user-confirmation requirement, the elicitation-vs-token fallback, and the preview-plus-confirmToken response of phase 1. This is exactly the kind of operational detail an agent needs before calling a write 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 compact sentences: the core action is front-loaded and the confirmation mechanics follow. The parenthetical reference to MCP_CONFIRM_MODE is slightly indirect, but no sentence 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 mutation tool with no output schema, the description covers the essential operational unknowns: confirmation gating, the token fallback, and the phase-1 preview response. What remains (e.g., failure handling, device-not-found behavior) is minor and largely inferable.

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 required params (device, volume) and the confirmToken are already fully documented in the schema, including the token's "never on first call" rule. The description reinforces the range and token flow but adds little beyond the schema, so baseline 3 applies.

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

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

The description uses a specific verb+resource ("Set the speaker volume") and scopes it with a range (0–100) and target ("of an Alexa device"). It is immediately distinguishable from read-side siblings like alexa_list_volumes, but it never names a sibling tool, so it stops short of explicit differentiation.

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

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

It clearly tells the agent how invocation is gated (confirm first, or two-step token flow), which is useful context. However, it offers no guidance on when to choose this over adjacent tools (e.g., alexa_set_equalizer or alexa_list_volumes); selection guidance is only 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?

Goes well beyond the annotations by disclosing the side effect's reach ('Everyone in the room hears it, so it cannot be taken back'), which explains why destructiveHint=true matters here. It also documents the confirmation gate, the phase-1 'confirmation-required' preview, and how confirmToken must be handled (never on first call, never reused).

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-loads the core action and the destructive consequence before the procedural confirmation details. Four sentences, no filler, though the final sentence is dense and partially restates the confirmToken schema description.

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 supplies the missing return-path context itself: the confirmation prompt, the preview plus confirmToken, and the repeat-call contract. An agent has everything needed to invoke this destructive, open-world tool safely.

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

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

Schema coverage is 100%, so the structured fields already carry the constraints; the description nonetheless adds real meaning, notably that 'speak' takes exactly one device while 'announce' takes one or more, and that the confirmToken is only for clients without elicitation. Slight overlap with the schema's own confirmToken description keeps it from a 5.

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 concrete verb and resource ('Make Alexa say something out loud') and immediately decomposes it into the two real behaviors: 'speak' (one device, Alexa's voice) and 'announce' (one or more devices, chime first). That distinction is not derivable from the name alone and cleanly separates it from siblings like alexa_playback or alexa_run_routine.

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 clear mode-selection criteria (single device vs multi-device broadcast) and spells out the precondition that confirmation must come first, including the two-step fallback path. It does not name sibling tools as alternatives, but the when-to-use context is otherwise unambiguous.

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

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

Annotations already flag destructiveHint=true, but the description goes well beyond them: it discloses the mandatory two-step confirmation, the preview + confirmToken fallback for clients without elicitation, the MCP_CONFIRM_MODE reference, and the rule that confirmToken must never be reused or invented. That is exactly the behavioral context needed for a destructive, open-world operation.

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

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

Front-loaded with purpose, then scope, then the confirmation flow in a logical order; every clause carries information. The single dense final sentence packs multiple confirmToken constraints, though all are load-bearing.

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 still supplies the key runtime semantics an agent needs: dual confirmation paths, the confirmToken handshake, and the MCP_CONFIRM_MODE dependency. Nothing required to invoke it correctly is missing.

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

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

Schema coverage is 100% and per-parameter descriptions are already rich, so baseline would be 3. The description adds the either/or relationship between 'device' and 'allDevices' and frames confirmToken as the token from this same tool's phase-1 response, which sharpens how the params relate rather than merely restating them.

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?

Uses a specific verb (stop) plus the full set of affected resources (music, alarm, timer, speech) and anchors it to the familiar 'Alexa, stop' idiom. An agent can distinguish this from siblings like alexa_cancel_alarm_reminder or alexa_playback without opening any schema.

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

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

Clearly states the two scoping modes ('Pass a device, or allDevices to stop every device on the account') and the confirmation workflow. It gives solid when/how guidance but never names an alternative sibling (e.g. cancelling a specific alarm vs. a blanket stop), so the choice among cancel/stop tools is left to inference.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false; the description adds the substantial behavioral fact that the tool is gated by user confirmation, with two distinct flows (client-side elicitation vs. a preview + confirmToken two-step) and an external policy reference (MCP_CONFIRM_MODE). It also discloses the destruction-free semantics of un-checking ('mark active again').

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, purpose front-loaded, then the confirmation requirement. Dense but every clause carries information; the trailing '(see MCP_CONFIRM_MODE)' is a compact pointer rather than padding.

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

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

There is no output schema, and the description compensates by explaining what the two-phase confirmation returns (a preview plus confirmToken) and what the caller must do with it. Combined with 100% schema coverage, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, and the schema itself already explains item addressing, list targets, and the full confirmToken contract, so the baseline is 3. The description's mention of 'by its name or item id' and the confirmToken flow largely restates what the schema documents rather than adding new syntax or edge cases.

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

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

Names a specific verb pair (check off / un-check) on a specific resource (an item on an Alexa shopping or to-do list) and identifies both addressing modes (name or id). An agent can distinguish this from alexa_add_list_item, alexa_remove_list_item and alexa_get_list_items without opening any schema.

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

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

Clearly states the use context and points at alexa_get_list_items as the source of item ids for the 'item' and list arguments. It does not explicitly rule out the nearby alternatives (adding or removing an item, or reading the list), so the 'when not to use' case is left implicit rather than stated.

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