speak

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

The annotations already state readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the agent knows this is a side-effecting but harmless, non-idempotent action. The description adds real behavioral context beyond the annotations: the 300-character limit and the fact that speech is rendered locally with no cloud dependency. It doesn't say whether calls block until speech finishes, what happens if text exceeds 300 characters, or what the tool returns.

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

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

Two short sentences, and the length cap and delivery target are front-loaded in the first sentence. Every clause adds information: what is spoken, where, how long, and via which backend. There is no filler.

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

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

For a one-parameter action tool with meaningful annotations and no output schema, the description covers the essentials: target device, backend, and length limit. It leaves only minor gaps, namely over-length behavior and whether playback is synchronous. It doesn't need to describe return values because no output schema exists and the effect is audible.

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 0%, so the single 'text' parameter has no documentation in the schema and the description must compensate. It contributes meaningfully by defining the content as the utterance and by capping it at 300 characters, but it never says whether the input is plain text or accepts SSML/markup, or how over-limit input is handled. The description adds useful partial semantics, not full coverage.

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

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

The description names a concrete verb (speak) and a concrete target (the AIY speaker), and it scopes the action with a 300-character cap. The phrase 'configured local speech backend' further narrows what 'speak' means so the agent doesn't mistake it for a cloud TTS tool. Siblings such as speak_on_echo and character_speak are distinct targets, but the description never says so explicitly, so it stops short of full sibling differentiation.

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

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

The agent can infer usage (make the local AIY speaker say some text), but the description gives no explicit when-or-when-not guidance. It never mentions the near-neighbor siblings speak_on_echo (Echo hardware) or character_speak (character voice), even though choosing among them is the main selection problem. That makes the guidance 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.