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

No annotations are provided, so the description carries the full behavioral burden. 'If any' usefully discloses that the call is a no-op when nothing is running, but it says nothing about what happens to partial results, whether cancellation is immediate, or any auth requirements. Output schema covers the return value, softening the gap.

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?

A single front-loaded sentence with no filler; every word 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 zero-parameter cancel tool with an output schema documenting the response, the description covers the essential purpose and the idle no-op case. Only minor behavioral detail about the fate of an in-flight transcription 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 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?

Specific verb ('Cancel') plus resource ('the currently running transcription'), so an agent immediately knows the operation. It is implicitly distinct from sibling transcribe_audio, but the description never names or contrasts with any sibling, keeping it short of a 5.

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 phrase 'if any' implies the tool is safe to call whenever a transcription might be running, which is a usable invocation cue. However, it gives no explicit when-to-use guidance relative to siblings like transcribe_audio or start_watch, leaving the agent to infer the 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?

With no annotations, the description carries the full burden and does disclose the critical non-obvious trait: calling it CLEARS the queue, i.e. a destructive side effect that consumes results. It does not mention auth requirements, idempotency, or behavior when no transcriptions are ready, but the key destructive behavior is surfaced.

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?

Two tight sentences, front-loaded with the action and the destructive queue-clearing side effect before the return fields. The second sentence duplicates the output schema slightly but is short and useful for a quick scan.

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 needn't be explained, and with zero parameters the description's main job is behavioral context — which it partly delivers by flagging the queue clearing. The main gap is workflow context (that it pairs with start_watch/stop_watch) rather than call mechanics.

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 takes zero parameters, so the schema leaves nothing to interpret and the baseline of 4 applies. The description's enumeration of return fields is redundant with the output schema but not harmful.

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+resource combination: returning completed watch-folder transcriptions. The 'watch-folder' qualifier distinguishes it from sibling transcribe_audio, though no sibling is named explicitly.

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: 'completed watch-folder transcriptions' signals this is called after start_watch to harvest output, but there is no explicit when-to-call, polling guidance, or statement about what to do when the queue is empty. No alternatives are named.

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?

With no annotations, the description carries the full disclosure burden. 'Return' implies a non-mutating read, but it does not explicitly state read-only behavior, permission requirements, or whether results are cached/static. For a zero-parameter listing call the risk is low, so the gap is moderate rather than severe.

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?

A single front-loaded sentence naming the resource and its scope, with zero filler. Nothing could be removed without losing meaning.

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 explain return values, and the tool is parameterless and simple. The only missing element is a note on when this read-only inspection is appropriate relative to siblings, which is minor for a tool of this 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?

The tool takes zero parameters, so the baseline is 4. There are no parameter semantics that could be clarified further, and no input-side ambiguity exists.

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 (Return/List) and resource (directories the server may read audio from), which is concrete and unambiguous. It is distinguishable from siblings like transcribe_audio or list_models by content, though it never explicitly contrasts itself with 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?

There is no guidance on when to call this versus alternatives such as list_models, nor any mention of prerequisites or context of use. The agent must infer that this is a configuration-inspection call.

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?

With no annotations, the description carries the full burden and does useful work: it discloses that whisper-cpp entries only appear when MACWHISPER_WHISPERCPP_MODEL_DIR is configured and warns that the MacWhisper CLI must be reachable even if only the whisper-cpp engine is intended. It does not cover failure modes or what happens when the CLI is unreachable, so not a full 5.

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 and the two engine formats are clearly separated, but a large share of the text re-describes the output string format even though an output schema already exists, making it longer than the tool's single-action nature warrants.

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 zero-parameter, read-only listing tool with an output schema, the description is more than complete: it explains the engine-specific formatting, the environment-variable dependency, and the CLI reachability requirement an agent needs in order to use results 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 tool takes zero parameters, which sets a baseline of 4, and the description appropriately uses its space to explain how the returned identifiers feed the parameters of other tools rather than inventing input semantics that do not exist.

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 ('Return') and resource ('the transcription models available across all engines'), with the scope made explicit. An agent can immediately distinguish this discovery tool from the sibling action tools like transcribe_audio and cancel_transcription.

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 clearly explains the context of use by tying the returned strings back to the 'model' and 'engine' arguments needed for transcription, so an agent knows this is a prerequisite discovery step. It stops short of naming alternative tools or explicit when-not-to-use conditions, so it does not reach 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?

With no annotations, the description carries the full load and does well: it discloses the auto-transcription side effect, that files are moved to a done directory, the default done path, the env-var override, and that out-of-allow-list paths cause rejection. It omits what happens if a watch is already running on the same folder or how to stop it (stop_watch).

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, front-loaded with the core action and effect, then constraints, then the follow-up call. No filler and each sentence adds an actionable fact.

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 one-parameter tool with an output schema (so return values need no explanation), the description covers purpose, side effects, directory constraints, and the results-retrieval path. It leaves minor gaps around duplicate/conflicting watches and error semantics.

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 100%, so baseline is 3, but the description adds real meaning for the single parameter: the folder must be inside the configured allow-list or the call is rejected, and it explains the related done-directory path and its override. That is more than the schema's path-format description 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?

States a specific verb (start watching), resource (a folder), and outcome (auto-transcribe new audio files), which cleanly separates it from stop_watch, get_watch_results, and one-shot transcribe_audio. An agent can identify the operation 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?

It routes the agent forward explicitly ('Call get_watch_results() to retrieve completed transcriptions'), giving clear post-invocation context. It does not, however, state when to prefer this persistent watch over the sibling transcribe_audio for a single file, so the exclusion guidance is incomplete.

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?

No annotations are provided, so the description carries the full burden of disclosure. It does not say whether stopping preserves or discards watch results, whether the operation is reversible, or what happens if no watcher is running — meaningful gaps for a state-changing 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?

A single front-loaded sentence with no filler. It is appropriately brief, though it is so short that it leaves behavioral questions unanswered rather than being maximally informative per word.

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 output schema covers return values and there are no parameters to document, so the description needn't explain results. However, with no annotations and only one sentence, the state transition (what stopping does to watch results) is underspecified for a tool sitting alongside get_watch_results.

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 takes zero parameters, so there is nothing for the description to disambiguate; the schema already declares an empty object with additionalProperties=false. Baseline of 4 applies for a parameterless tool.

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 (Stop) and resource (the active folder watcher), which cleanly distinguishes it from the sibling start_watch. It does not explicitly name siblings or restate scope, but the action 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 infers it should call this to halt an already-running watcher. There is no guidance on behavior when no watcher is active, nor any reference to alternatives like get_watch_results for retrieving accumulated output.

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?

With no annotations, the description carries the full behavioral burden and does well: it discloses the local-file allow-list constraint, the inaccessibility of chat uploads, and the required behavior after an access-denied error. It does not describe whether transcription is cancellable or synchronous beyond implying a direct return, but the operational warnings are substantive.

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 with the core action, followed by two focused paragraphs that each add necessary operational guidance. There is no filler, and the emphasis on path constraints and error handling is well placed.

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 five parameters, full schema coverage, and an output schema, the description is largely complete for invoking the tool correctly. It covers the critical local-path limitation and failure mode, though it could mention preparatory sibling tools such as list_allowed_paths or list_models for model discovery.

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 five parameters including path, model, engine, persist, and language. The description adds practical meaning to path by emphasizing local allow-list access and ruling out uploaded files, which is useful but only covers one parameter beyond the schema 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 and resource: transcribe a local audio file and return the transcript. It also establishes scope through the local-filesystem allow-list requirement, making it easy to distinguish from sibling tools such as start_watch or 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 provides clear usage context and prerequisites: the file must be on the Mac filesystem inside the allow-list, uploaded chat files are not accessible, and access-denied errors should not be worked around. However, it does not explicitly compare this tool to siblings like start_watch or suggest list_allowed_paths as a preparatory step.

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