oruk Speech

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.

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial beyond-annotation context: nothing is transcribed (privacy implication), it runs only the Resonance encoder and affect head, it bills at the affect rate, it caps at 30 MB/60 min/English-only, and outputs are explicitly framed as "calibrated acoustic annotations of delivery, not claims about inner state." No contradiction with annotations.

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 dense and front-loaded — the core capability and key differentiator ('without transcribing it') appear in the first clause. Every sentence adds a distinct fact (billing, limits, diarization behavior, epistemic caveat, sibling routing), though the length is at the high end of what's needed.

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 7-parameter tool with no output schema, the description covers inputs, limits, cost, model behavior, language restriction, and return semantics sufficiently via the detail parameter ('top label scores and condensed segments' vs 'every label score and word-level timings'). A more explicit response-shape sketch would be the only remaining gap, but the detail option descriptions largely fill it.

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 baseline is 3 — every parameter is already documented in the schema. The description reinforces input constraints (public URL or base64, 30 MB/60 min) and adds diarization cost context, but it doesn't need to compensate for schema gaps because there are none.

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 opens with a specific verb and resource — "Score how speech sounds without transcribing it" — and enumerates concrete output categories (emotion: happy, frustrated, worried; style: sarcastic, confident, hesitant, warm). It explicitly differentiates from siblings by noting the transcription decoder is never invoked and routing word-needing users to oruk_analyze_speech. An agent cannot confuse this with its siblings.

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 explicit trigger conditions — "Use this when the user asks about mood, delivery, sentiment, sarcasm, or emotional dynamics in audio" — and an explicit exclusion with alternative: "Need the words too? Use oruk_analyze_speech." It also adds a cost-based selection signal (affect rate vs analysis rate), which helps agents choose correctly.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description is consistent, framing the operation as verification/reporting. It adds useful context about key sources (Authorization header vs. trial api_key) and clarifies the trial/permanent key distinction, which goes beyond annotations.

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 two sentences, direct and front-loaded with the purpose. It doesn't waste words, covering purpose, usage context, and key requirements in a compact form.

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 diagnostic tool with one optional parameter and no output schema, the description tells what it checks (plan, balance, usage), when to use it, and how to provide the key. It doesn't specify the response format, but the content is adequately covered, and sibling tools are clearly unrelated.

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?

The single parameter api_key already has a detailed schema description stating it's only for temporary keys. The tool description repeats this but adds context about the Authorization header. With 100% schema coverage, the description adds marginal value beyond 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 verifies an API key and reports plan, credit balance, and recent usage. This is a specific verb+resource pair that distinguishes it from sibling tools like oruk_transcribe_audio or oruk_list_models.

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?

It explicitly says 'Use this as the first call after setup' and 'when a billing/auth error needs diagnosing,' giving concrete when-to-use context. However, it doesn't explicitly name alternative tools or state when not to use it, so it falls short of a full 5.

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

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

Beyond the annotations, it discloses the temporary nature, precise quota of 3 requests, 30-minute expiry, capped shared budget, no-account requirement, and the need to share a signup link. This is rich behavioral context for a mutating, non-destructive tool.

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?

Four sentences, each adding distinct value: key constraints, target use case, output usage, and follow-up action. No filler or repetition of the title.

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 description covers selection, invocation, and follow-up, including the exact quota/expiry and where to pass the returned key. The only minor gap is that it instructs the agent to share a signup link without stating where that link comes from or its URL.

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?

With zero parameters the schema is empty, but the description explains what to do with the result: pass the returned key as the api_key argument to audio tools. That adds useful semantic guidance beyond the empty schema, meeting the zero-parameter 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 pins down exactly what the tool does: mints a temporary, account-less oruk API key with a 3-request/30-minute scope. This clearly distinguishes it from the sibling audio-processing and account-checking tools.

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?

It names a concrete trigger: use when no Authorization header is configured and the user wants an immediate transcription or tone-analysis trial. It lacks an explicit 'when not to use' statement, but the trigger condition and follow-up instructions are clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds useful behavioral context by noting 'No API key required' and describing the kind of guidance returned. It does not go into depth about the exact output format, but that is not essential for an informational quickstart.

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 a tight two sentences. The first sentence front-loads the tool's role and lists the contents; the second adds usage timing. No wasted words.

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 parameterless, read-only informational tool, the description covers what the tool does, what it returns, and when to use it. It is complete on its own without needing an 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?

The schema has zero parameters, so the description does not need to explain any. The baseline of 4 is appropriate because the tool takes no input and the description correctly omits parameter details.

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 opens with 'Quickstart for the oruk Speech API and this MCP server' and lists specific deliverables (API key, MCP config snippets, SDK install commands, routing rule), making its purpose unmistakable. It clearly distinguishes itself from sibling tools that analyze speech, check credits, or create trial keys.

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?

Provides explicit guidance: 'Use this when setting oruk up for the first time or when the user asks how oruk works.' This is direct and actionable, leaving no doubt about when to invoke this tool versus the analysis or transcription tools.

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

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

The description adds useful behavioral context beyond the annotations by stating that no API key is required and by detailing the contents (lifecycle, pricing per audio minute, tasks, labels, audio limits). This gives the agent a clear picture of what the tool returns and its accessibility, though it doesn't describe the exact response format.

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 two sentences, front-loads the main action, and every clause adds value: what is listed, pricing details, auth requirement, and use cases. No filler or redundancy.

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?

Even though there is no output schema, the description covers purpose, content, use cases, and authentication status. For a zero-parameter list-oriented tool with readOnlyHint true and no destructive behavior, this is fully complete for an agent to select and invoke it appropriately.

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?

The tool has zero parameters, so the baseline is 4. The description doesn't need to explain parameter semantics, and the empty schema is fully consistent with the description's 'no input needed' implication.

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 uses a specific verb ('List') with a clear resource ('oruk's speech models') and enumerates the exact scope: lifecycle, per-task pricing, tasks, labels, and audio limits. This clearly distinguishes it from sibling tools like oruk_analyze_speech or oruk_transcribe_audio, which perform different actions.

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 explicit use cases: 'choose a model, estimate cost before analyzing long audio, or see which labels exist.' It also notes 'No API key required,' which helps with pre-auth usage. However, it doesn't explicitly mention when not to use it or name alternative tools, so it stops short of a full when/when-not guide.

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

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

The description adds useful context beyond the annotations: output structure, accepted input types, size limits, and a capability boundary ('Does not score emotion or tone'). However, that boundary is contradicted by the schema's model and detail parameters, where oruk-fourier is described as returning 'transcript plus native 15-label emotion' and detail='full' adds 'every label score and word-level timings.' This false claim significantly undermines transparency.

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 four sentences, each earning its place: purpose, when-to-use, input constraints, and alternative routing. It is front-loaded with the primary action and contains no filler or redundant phrasing.

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 description is reasonably complete for a read-only transcription tool: it covers purpose, input, format, and sibling routing. However, it omits any guidance on the model/detail parameters and, more importantly, makes a misleading claim about emotion scoring that contradicts the schema, so an agent could be misled about the tool's full capabilities.

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% and each parameter already has a detailed explanation (model options, detail options, audio_url constraints, etc.). The description's repetition of 'public audio URL or base64 bytes (wav/flac/mp3/m4a/ogg/webm, ≤30 MB / ≤60 min)' duplicates what the schema states, so it adds no meaningful parameter semantics. The baseline of 3 applies.

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 ('Transcribe'), a specific resource ('prerecorded English audio'), and the output format ('time-ordered segments and word timings'). It clearly differentiates from siblings by saying 'Use this when only the words matter' and explicitly contrasts with oruk_analyze_speech and oruk_analyze_tone.

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?

It provides explicit when-to-use guidance: 'Use this when only the words matter.' It names alternatives with conditions: 'use oruk_analyze_speech for transcript + tone together, or oruk_analyze_tone for tone alone.' It also states input constraints (URL or base64, formats, size/length), leaving little to inference.

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