oruk Speech

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

The annotations already mark this as a read-only, non-destructive operation, and the description adds meaningful behavioral context: accepted formats, base64 input limit, decoded size caps, default compact return, and the combined transcript-plus-analysis behavior. It demonstrates what the tool actually does beyond the declarative annotations, though it does not disclose possible errors or rate limits.

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 tight, focused sentences cover the tool's purpose, output, usage context, and applicable exceptions. The content is front-loaded, with no repetitive phrases or unnecessary verbiage; every sentence directly contributes to selecting and invoking the tool.

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 without an output schema, the description names the return categories and explains the compact by default behavior, which gives the agent the necessary expectation of what comes back. Input constraints, supported formats, size and duration limits, and alternate routes for narrow requests are all present. For a read-only audio analysis tool, this is complete enough to call correctly on the first attempt.

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 parameters are fully explained in the input schema itself. The description reiterates the audio URL/base64 and file-format constraints but does not add new semantic meaning beyond the schema. A 3 is the appropriate baseline when the schema already does the heavy lifting.

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 names a specific verb and resource ('Transcribe English audio AND score how it was said') and enumerates concrete outputs: transcript, tagged transcript, emotion and style label scores, and time-local segments. It also explicitly distinguishes the tool from its siblings by inviting the user to choose alternatives when only words or only tone matter, so there is no ambiguity about scope.

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 an explicit when-to-use signal ('Use when the user cares about both the words and the delivery') and tangible examples (meetings, support calls, interviews, voice notes). It also names the exact alternatives for the narrow cases: oruk_transcribe_audio for words only and oruk_analyze_tone for tone only.

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, so the safety profile is covered. The description adds meaningful behavioral transparency beyond that: it discloses scope limits (≤30 MB / ≤60 min, English), states that predictions are 'calibrated acoustic annotations of delivery, not claims about inner state,' and clarifies it does not transcribe. This is exactly the kind of context that shapes an agent's expectations.

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 front-loaded: it leads with the central claim, then the use-case, then constraints, then the sibling routing. Three sentences earn their place with no filler. It avoids listing what's already in the schema and keeps the important disambiguation near the top.

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 purpose, scoping, constraints, and sibling routing, and the schema fully documents the six parameters with 100% coverage. The only area it does not cover is the return format, but there is no output schema and the tool's outputs are simple enough that the 'calibrated labels per segment' description is sufficient. The missing details are already captured in the schema and semantics it does not need the description to repeat.

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. The description adds value by explaining the tradeoff between audio_input and audio_url, the consequence of choosing one over the other ('Prefer audio_url for anything larger'), and the language constraint. It doesn't deeply explain the model or detail args, but the schema already does that well. The description complements the schema without being redundant.

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 a specific verb and resource: 'Score how speech sounds without transcribing it' — this is not a tautology. It explicitly distinguishes itself from a sibling tool (oruk_analyze_speech) by saying 'Need the words too? Use oruk_analyze_speech.' The agent can understand exactly what this tool does and what it does not do.

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?

Explicit usage guidance is provided: 'Use this when the user asks about mood, delivery, sentiment, sarcasm, or emotional dynamics in audio.' It also explicitly names an alternative and the condition for choosing it ('Need the words too? Use oruk_analyze_speech'). This is a model example of routing the agent to the right tool.

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?

Annotations already provide readOnlyHint=true and destructiveHint=false, so safety profile is covered. The description adds valuable behavioral context: it does not score emotion or tone, returns time-ordered segments and word timings, and places constraints on input size/format. It does not fully explain pagination or return structure, but with readOnlyHint covering side-effect transparency and the description covering output structure, this exceeds the baseline for annotation-covered tools.

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?

Three sentences, each earning its place: what the tool does, when to use it, and constraints/formats. It is front-loaded with the core purpose and routes to siblings at the end. 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 6-parameter tool with no output schema, the description covers input format, size limits, duration limits, and output shape (time-ordered segments, word timings) and differentiates from siblings. It doesn't explicitly describe the exact response JSON structure, but without an output schema and with rich schema/annotations, this is well above minimum viability. Returning exact response fields might be a small gap, but it does not compromise safe invocation.

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. The description adds value by mapping parameters to behavior: compact vs full detail, audio_url vs audio_base64 size limits, and clarifies that api_key is only for trial keys. It reinforces parameter meaning beyond the schema's per-parameter text, earning a 4.

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 ('Transcribe prerecorded English audio to text') plus resource (audio) and output specifics (time-ordered segments, word timings). It explicitly differentiates from siblings by stating when to use transcription vs. tone/analysis, so an agent can distinguish it from oruk_analyze_speech and oruk_analyze_tone without opening the schema.

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 usage direction: 'Use this when only the words matter,' and names alternatives with conditions ('use oruk_analyze_speech for transcript + tone together, or oruk_analyze_tone for tone alone'). This is clear when-to-use and when-not-to-use guidance, beyond anything in the schema.

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