Voice Coach MCP

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

Annotations already cover safety (non-destructive, idempotent, closed-world), so the description correctly spends its words on tolerance behaviour an agent could not infer: octave-up/down singing, late starting points, tempo variance, and the fallback comparison path. It does not mention failure modes (polyphonic input, unreadable files) or processing cost.

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 purpose and parameter block are front-loaded and efficient, but the Returns paragraph is a dense run-on enumeration of summary and note fields that largely duplicates the output schema. An agent must parse a long comma-spliced sentence to extract the few novel semantics (cents sign, tempo ratio direction).

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 4-param analysis tool with an output schema, the description covers input formats, matching modes and result interpretation; the return-value detail is a bonus rather than a gap. Only edge-case behaviour and the constraint enforcement on polyphonic audio are unaddressed.

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 coverage is 0%, yet all four parameters are documented with real semantics: accepted audio formats and the link to record_audio names, the .mid expectation, key syntax with examples in two languages, and midi_track's default resolution rule. This fully compensates for the empty 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?

States a specific verb and resource ('Measures the pitch accuracy of sung audio') plus the scope constraint 'solo voice, one melodic line', which tells an agent immediately what input is valid. This is clearly distinguishable from recording, transcription or pronunciation siblings without opening a 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 conditional guidance on the two analysis modes: reference_midi when a score exists, key when there is no MIDI, and plain nearest-note comparison when neither is supplied. It stops short of explicitly naming alternatives (e.g. 'use transcribe for text output') or stating when not to use it.

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, the description discloses important behavior: audio is sent to Azure only when the backend environment variable is set, the scoring formula is given, allophonic variants are excluded from errors, and text_mismatch indicates a likely wrong text. These are substantial operational and privacy-relevant details.

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 front-loaded and well organized, with arguments first, then return details and behavioral notes. It is somewhat dense and explains return fields despite an output schema existing, but the information largely 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?

Given the output schema, annotations, and three-parameter schema with no descriptions, the description is complete enough to call the tool correctly. It covers inputs, output structure, scoring behavior, warnings, and backend-dependent privacy implications.

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 0%, so the description must carry parameter meaning. It fully documents all three parameters: audio source and duration, exact expected text, and language values en-US and en-GB.

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 and resource: it compares pronounced phonemes with expected phonemes for English text read aloud. The scope and purpose are clear, but it does not explicitly distinguish itself from siblings such as transcribe or speech_metrics.

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 gives clear usage context: audio can be a path or a name returned by record_audio, recordings up to 60 seconds work, and short sentences work best. It also explains the text_mismatch warning, though it does not explicitly say when to prefer this tool over transcribe or speech_metrics.

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 a non-read, non-idempotent, non-destructive write to a closed world. The description adds genuine value beyond them: the exact file path, the append semantics, and the conditional behavior where a missing '## ' prefix causes the date and time to be generated as the title.

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 purpose is front-loaded in one sentence, and the Args block adds only the format detail an agent actually needs. The docstring indentation and stray line break make it slightly less clean than it could be, but nothing is padding.

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?

An output schema exists, so return values need no explanation, and the one-parameter schema is fully explained in prose. Remaining gaps are secondary: behavior if the file or directory is missing, and confirmation that repeated calls create duplicate entries (consistent with idempotentHint=false but unstated).

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 coverage is 0% for the single `entry` parameter, so the description must carry the load and largely does: it specifies the markdown format, the required header pattern ('## YYYY-MM-DD · mode · exercise'), and the fallback title auto-generation. It omits whether trailing newlines are added or whether mode must match an enum-like value.

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?

States a specific verb and resource with the concrete target ('Appends a session to the progress log (~/VoiceCoach/progress.md)'), which implicitly distinguishes it from read_progress. It stops short of explicitly naming the sibling for contrast, but the append-vs-read distinction is 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?

Usage is only implied: an agent can infer this is for recording a completed session, and the sibling list contains read_progress. There is no explicit when-to-use statement, no mention of prerequisites (does the file need to exist?), and no exclusion of alternatives.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real context beyond that: the file location and the ordering of returned session markdown (oldest to newest), which is a behavioral detail an agent would otherwise have to guess.

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 short sentences: purpose and location first, the usage trigger second, the return shape last. Nothing is redundant and every sentence carries information.

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?

An output schema exists, so the description need not enumerate return values, yet it helpfully sketches them. The one real hole is the undocumented 'entries' parameter; otherwise an agent has everything needed to call this simple read tool 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?

Schema description coverage is 0% and the single parameter 'entries' (default 5) is never explained — the reader cannot tell whether it controls how many sessions are returned or how many markdown lines. Worse, the name collides with the returned 'entries' field, so the description actively muddies rather than clarifies the parameter.

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?

States a specific verb and resource ('Reads the latest sessions from the progress log') and even names the backing file path (~/VoiceCoach/progress.md). It is implicitly distinguishable from the sibling log_progress by the read/write naming pair, but it never explicitly contrasts with it.

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?

'Use it at the start of a session to pick up the previous focus' gives a clear triggering context, which is more than most read tools offer. It stops short of naming log_progress as the counterpart to use when writing, so the when-not guidance is left to inference.

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 cover mutation/idempotency/destructiveness, so the description is free to add real value — the 120-second cap and the meaning of the no_microphone_permission warning (macOS gave no audio; user must enable mic in System Settings). That is exactly the kind of recovery context annotations cannot carry.

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?

Front-loaded purpose sentence, then Args, then Returns — clean structure. The Returns paragraph restates some of what the output schema already exposes, but the warning explanation 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?

For a two-parameter capture tool with annotations and an output schema, the description covers the cap, naming behavior, and the one failure mode an agent cannot infer. Nothing essential is missing.

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 coverage is 0%, so the description must compensate, and it does: seconds is the recording length bounded at 120, name is an optional filename without extension that defaults to date/time. The 'max 120 by default' phrasing is slightly ambiguous about whether 120 is a default or a hard ceiling.

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?

Opens with a specific verb+resource+output format: records from the computer's microphone and saves a 16 kHz mono .wav. No sibling in the list captures audio, so the boundary is immediately obvious.

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?

States an explicit operational rule — 'Tell the user before calling' — and implies the when (capture live audio). It stops short of naming when-not or pointing to transcribe/analyze_pitch as downstream steps, so a 4 rather than a 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?

Annotations declare idempotent, non-destructive, closed-world, but the description adds genuinely non-structured behavior: filler words like 'like'/'so' only count when isolated by a comma or a pause, and monotone/low-variation are defined by numeric thresholds. It also clarifies that audio may be a name returned by record_audio, which explains the cross-tool dependency. It omits any note on cost/runtime for audio processing, which is the one behavioral trait still missing.

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 one-line purpose is properly front-loaded and the Args block is tight. The Returns block, however, is a long enumeration of output fields that an output schema already covers, so a substantial fraction of the text does not earn 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?

All three parameters are documented, the input source ambiguity is resolved, and threshold semantics are disclosed; annotations plus the output schema carry the safety and return-shape burden. The remaining gap is operational: no indication of processing expectations or audio-format constraints for what is likely a heavy analysis call.

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 0% and the description fully compensates: audio is 'path or a name returned by record_audio', language is constrained to 'en' or 'es' with the note that filler lists exist for both (an enum the schema lacks), and pause_threshold_s is defined as the minimum silence between words to count as a long pause. Each parameter gains meaning beyond its bare title.

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 first sentence gives a specific verb plus the exact measured dimensions (pace, pauses, fillers, pitch/volume variation), which is far stronger than a generic 'analyze speech'. It does not, however, name the overlapping siblings analyze_pitch and transcribe, so an agent must infer that this tool subsumes rather than replaces them.

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?

Usage is only implied by the purpose sentence – an agent can guess you call this when you want delivery metrics rather than a raw transcript. There is no explicit when-to-use/when-not, no mention of prerequisites (recording must exist first), and no routing to analyze_pitch or transcribe despite clear functional overlap.

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?

Adds genuinely useful context beyond annotations: the first call downloads a model (cost/latency, env var VOICE_COACH_WHISPER_MODEL), and output degradation policy (words dropped first, then segments, with everything preserved in full_details). Annotations already cover idempotency and safety, so this is a solid supplement; missing are rough latency/blocking 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?

Purpose is front-loaded in the first sentence, followed by Args and Returns sections; every line carries information. The embedded docstring formatting (indentation, 'Args:') is slightly noisy but does not obscure content.

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?

Covers the critical operational facts an agent needs: parameter forms, auto-detection default, model download on first use, and truncation behavior that the output schema alone would not reveal. A note on supported audio formats or expected duration limits would close the remaining gap.

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 coverage is 0%, so the description must carry the load and largely does: audio is either a path or a name from record_audio, and language accepts codes or names (en, en-US, Spanish) with auto-detect on omission. The exact accepted format set for language remains loose.

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?

States a specific verb and resource ('Transcribes audio') plus differentiating scope details: timestamps, engine (faster-whisper), and local execution. An agent can distinguish this from siblings like assess_pronunciation or speech_metrics, which analyze rather than transcribe.

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 audio parameter note ('a name returned by record_audio') implies the natural pipeline with that sibling, but no explicit when-to-use/when-not guidance versus speech_metrics or assess_pronunciation is given, and nothing says when to prefer this over another tool.

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