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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral context beyond annotations: it states the accepted input formats (public URL or base64 bytes), size limits (≤30 MB / ≤60 min), and default output behavior ('Returns compact summaries by default'). It also mentions the diarization behavior adds cost per minute and switches model automatically, which is transparent about side effects. One gap: it doesn't explicitly say whether audio data is retained or processed in the cloud, but the provided details already go beyond baseline.

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 five sentences, front-loaded with the core value proposition and output list, then usage context, then input constraints, then default behavior, then sibling routing. No filler or repetition. Every sentence 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?

The tool has 7 optional parameters with 100% schema coverage, an output schema is absent, but the description sufficiently explains the purpose, input constraints, default behavior, and alternatives. For an AI agent deciding whether and how to call it, this covers the key decision points: what it returns, when to use it, what formats are accepted, and defaults. The lack of an output schema is mitigated by the description listing return components.

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 7 parameters with descriptions. The description adds value by clarifying high-level behavior: 'Returns compact summaries by default' aligns with the detail parameter default, and the mention of 'calibrated emotion (15 labels)' maps to the model enum semantics. It doesn't need to repeat every param detail, but it could have linked the two models to their exact output differences more explicitly. Still, given full schema coverage, this is above baseline.

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 ('Analyze speech') and resource ('transcript + tone'), and lists concrete outputs: transcript, tagged transcript, calibrated emotion (15 labels), speaking-style (16 labels), and time-local segments. It clearly distinguishes itself from siblings by naming oruk_transcribe_audio and oruk_analyze_tone as alternatives for words-only or tone-only needs.

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 gives explicit usage context: 'Use this when the user cares about both the words and the delivery — meetings, support calls, interviews, voice notes.' It also explicitly states when not to use it and which siblings to pick instead: 'For words only use oruk_transcribe_audio; for tone only use oruk_analyze_tone.' This is a textbook usage guideline.

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