speak_text

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

With no annotations provided, the description carries the full burden and excels by detailing multiple behavioral aspects: it lists TTS backends with priority order, cost implications (OpenAI TTS pricing), platform dependencies (macOS fallback), configuration via environment variables, and return format specifics. This goes well beyond basic function description.

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

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

The description is well-structured with clear sections (purpose, use case, backends, configuration, args, returns) and efficiently conveys essential information. It could be slightly more concise by integrating some details (e.g., backend priorities) more tightly, but overall it's front-loaded and wastes no 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 tool with 3 parameters, no annotations, 0% schema coverage, but an output schema, the description is highly complete. It covers purpose, usage, behavioral details, parameter semantics, and return values, making the output schema redundant for understanding. No gaps remain given the complexity.

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?

Given 0% schema description coverage, the description fully compensates by explaining all three parameters: 'text' (text to synthesise), 'voice' (with specific voice names for each backend and default configuration), and 'output_path' (optional absolute path). It adds crucial context like default values and backend-specific options not in the schema.

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

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

The description clearly states the tool's purpose: 'Convert text to speech and return an OGG/Opus audio file path.' It specifies the exact action (convert text to speech), output format (OGG/Opus audio file), and distinguishes it from siblings like transcription tools by focusing on speech synthesis rather than recognition.

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 provides clear context for when to use this tool (for text-to-speech conversion) and mentions a practical use case ('Plays as a native voice note in Telegram when sent as an attachment'). However, it does not explicitly contrast with sibling tools like 'check_backends' or 'list_models', nor does it specify when not to use it (e.g., vs. transcription tools).

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