speak

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses the most important behavioral trait—the call blocks until playback finishes—and the fallback mechanism (neural Voice Design vs macOS say). Minor undisclosed details like failure/error behavior and audio-device requirements prevent a 5, but the description covers the critical behavioral facts.

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 filler. The primary action is front-loaded, followed by the one behavioral qualifier that matters (blocking). 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 one-parameter tool with an output schema present, the description covers what the tool does, how it does it, and the key blocking behavior that differentiates it from its sibling. It falls just short of a 5 by not naming the alternative or noting edge cases, but the sibling's self-explanatory name largely mitigates that gap.

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

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

Schema coverage is 0%, so the description must compensate. "Speaks the provided message aloud" clarifies that the message parameter is the text to be converted to speech, which is the essential semantic. For a single self-evident parameter this is adequate, though the description adds no length limits or formatting requirements.

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?

"Speaks the provided message aloud using neural Voice Design or macOS say" gives a specific verb, resource, and mechanism. The explicit "Blocking" qualifier further distinguishes this tool from its speak_non_blocking sibling, so an agent can tell them apart without inspecting either further.

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's "Blocking: waits until playback has completely finished before returning" gives a clear decision criterion between this tool and the sibling speak_non_blocking. However, it never names the sibling or explicitly states when not to use this tool, so the routing 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.