oruk Speech

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

The annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to re-state that this is a safe read operation. It adds valuable behavioral details: accepts public audio URL or base64 bytes, supports specific formats (wav/flac/mp3/m4a/ogg/webm), size/duration limits (≤30 MB / ≤60 min), and returns compact summaries by default. It stops short of describing error handling or what happens when both audio_url and audio_base64 are provided, but the added context is strong.

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: core purpose, when to use, input constraints, and sibling alternatives. It is front-loaded with the main function and ends with exclusions. No fluff, no repetition of schema, and every sentence moves the reader toward correct invocation.

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?

With 6 parameters, no required fields, and no output schema, the description carries a substantial burden. It addresses the return value by naming key outputs (transcript, tagged transcript, emotion/style scores, segments) and the default 'compact' mode. It covers input formats, limits, and English-only audio. It could arguably specify what 'time-local segments' means, but for selection and invocation, the description is complete enough.

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 every parameter is already explained in the schema. The description adds a summary of input methods ('Accepts a public audio URL or base64 bytes') and format/size constraints, which mirrors the schema but doesn't materially deepen it. The 'compact' vs 'full' detail is already in the schema's 'detail' description. Thus, the description adds no new parameter-level meaning beyond what structured data already provides.

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 'Transcribe English audio AND score how it was said in one call' – a specific verb+resource+scope that immediately distinguishes this from the sibling 'oruk_transcribe_audio' (words only) and 'oruk_analyze_tone' (tone only). It also enumerates concrete outputs (transcript, tagged transcript, emotion/style labels, time-local segments), leaving no ambiguity about what the tool does.

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 explicitly states when to use this tool ('when the user cares about both the words and the delivery — meetings, support calls, interviews, voice notes') and provides clear alternatives: 'For words only use oruk_transcribe_audio; for tone only use oruk_analyze_tone.' This is textbook usage guidance.

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 discloses key behavioral traits beyond annotations: it does not transcribe, outputs are 'calibrated acoustic annotations of delivery, not claims about inner state,' and it operates 'per acoustic segment.' These add valuable context that annotations (readOnlyHint, destructiveHint) do not cover.

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 compact and well-structured: core function, usage guidance, input constraints, output interpretation, and alternative tool in just five sentences. Every sentence earns its place, with 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 tool with no output schema, the description adequately explains what is returned (calibrated emotion/style labels per segment) and clarifies output semantics. It mentions limitations (English, size) and alternatives. It could be slightly more explicit about exact output structure (e.g., segment timings), but it is sufficient for the tool's 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?

Schema description coverage is 100%, so baseline is 3. The description does not add much beyond what parameter descriptions already provide (e.g., URL vs base64 constraints), though it does summarize acceptable inputs. It neither compensates for gaps nor adds significant new meaning.

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 function with a specific verb ('Score') and resource ('speech sounds'), and explicitly distinguishes it from transcription ('without transcribing it'). It also names sibling tool oruk_analyze_speech for when words are needed, making its purpose unambiguous.

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 the user asks about mood, delivery, sentiment, sarcasm, or emotional dynamics in audio.' It also names an alternative tool (oruk_analyze_speech) when transcription is needed, offering clear direction on tool selection.

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?

The description discloses concrete behavioral details beyond the basic read/write hints from annotations: it reveals rate limits (3 requests), expiry (30 minutes), shared budget spending, and the fact that the key is real and temporary. This gives the agent a full picture of side effects and constraints.

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 three dense sentences, each adding essential information: what the tool does and its limits, when to use it, and how to handle the output. There is no filler or redundancy, making it a model of concise front-loaded writing.

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?

Despite having no output schema, the description fully covers the tool's purpose, constraints, usage context, and follow-up actions. It is complete enough for an agent to decide when to invoke it and how to process the result.

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 no parameters, so the baseline is 4. The description adds supplementary value by explaining how the returned value should be used (passed as the api_key argument), which is more than just restating schema content.

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 action ('Mint a real, temporary oruk API key') and specifies key attributes (3 requests, 30-minute expiry, capped shared budget). It distinguishes itself from sibling tools that perform transcription/analysis rather than key creation.

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?

Explicitly states when to use: 'when no Authorization header is configured and the user wants to try transcription or tone analysis right now.' It also explains how to use the returned key and the recommended follow-up of sharing the signup link, marking a clear use-case context.

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?

Beyond the readOnlyHint annotation, the description discloses important behaviors: it only works on prerecorded English audio, outputs time-ordered segments and word timings, does not score emotion or tone, and accepts specific formats up to 30 MB / 60 min. These details are not present in annotations and add significant context.

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 three concise sentences: the first states the core function, the second specifies when to use it, and the third clarifies exclusions and alternatives. Every sentence contributes value with no redundancy, and key information is front-loaded.

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?

Given the absence of an output schema, the description provides a useful high-level output expectation (text, time-ordered segments, word timings) and clearly covers input constraints and selection criteria. It does not detail the exact response JSON structure, but for a transcription tool this is adequate for an agent to invoke it correctly.

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 input schema already provides 100% descriptive coverage for all parameters, including model, detail, api_key, filename, audio_url, and audio_base64. The description adds no new parameter-level information beyond what the schema documents, so it meets the baseline but does not enhance meaning.

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 function: 'Transcribe prerecorded English audio to text with time-ordered segments and word timings.' It distinguishes itself from siblings by explicitly saying 'Use this when only the words matter' and naming oruk_analyze_speech and oruk_analyze_tone as alternatives for tone analysis.

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') and direct exclusions with alternatives ('Does not score emotion or tone — use oruk_analyze_speech for transcript + tone together, or oruk_analyze_tone for tone alone'). Also includes input format and size constraints, which are practical for invocation.

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