alexa_run_builtin

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.