Speechmatics MCP by usefulapi

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

Annotations only supply destructiveHint=true; the description goes beyond that by stating the deletion is permanent and that the transcript is destroyed along with the job, plus the running-job constraint. It does not mention auth requirements or rate limits, but the irreversible side-effect is the key disclosure an agent needs.

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 short sentences, front-loaded with the destructive warning, then the force condition and API endpoint. Every clause carries information, though the raw REST endpoint reference is marginally useful to an agent and is the only near-redundant element.

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 2-parameter destructive tool with no output schema, the description covers permanence, the destroyed transcript, and the force override, which is enough to call it correctly. It stops short of stating what the call returns or whether any confirmation is required, but 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 description coverage is 100%, so both parameters are already documented in the schema, including force's 'delete even if the job is still running.' The description restates the force semantics without adding format or edge-case detail beyond the schema, so baseline 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?

States a specific verb and resource ('Permanently deletes a job and its transcript') and adds the consequence of the operation. It is unambiguous against siblings like speechmatics_get_job, speechmatics_list_jobs, and speechmatics_transcribe_url, which are all read or create operations.

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 explains the condition under which the tool behaves differently: 'Set force=true to delete even while it is still running.' That gives concrete invocation context. It does not name alternatives or exclusions, but deletion is the only destructive sibling, so the gap is minor.

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, so the safety profile is covered. The description adds real behavioral context beyond that: the job state machine (running | done | rejected | deleted | expired), the polling loop, and the underlying Batch API route. It still doesn't say anything about timing/backoff for polling or what 'details' are actually returned.

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 compact clauses: what it does, the status values, the polling workflow, and the API route. Front-loaded with the purpose and 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?

With no output schema, the description carries the burden of telling the agent what comes back, and listing the status enum plus the transcript-fetch handoff covers the essential decision points. It stops short of describing the payload shape (e.g., which detail fields are populated per status), which would fully close the 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 description coverage is 100% and the sole parameter job_id is already documented in the schema as 'returned by speechmatics_transcribe_url'. The description adds nothing beyond that baseline, so a 3 is appropriate for a single well-documented 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 ('Get a single job's details and status') and enumerates the possible status values. The word 'single' plus the status enum cleanly separates it from speechmatics_list_jobs, which returns many jobs.

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 concrete workflow guidance: 'Poll this until status is "done", then fetch the transcript,' which tells the agent both the calling pattern and the handoff to speechmatics_get_transcript. It does not explicitly name the sibling to use for the alternative case (e.g., list_jobs for enumerating), so it stops short of a full when/when-not statement.

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 readOnlyHint annotation already establishes that this is a safe read operation. The description adds that the return is a plain-text processing log, which is useful behavioral context. It does not mention authentication needs, rate limits, or behavior when logs are unavailable.

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 compact clauses that front-load the core purpose and then the debugging use case. Every phrase adds information without 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?

For a simple one-parameter read tool with annotations and a complete schema, the description covers what the log contains and why to use it. It lacks details like pagination or log availability, but those are minor for this operation.

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 the schema already documents the single job_id parameter. The description adds no parameter syntax or format details beyond what the schema provides, making the baseline 3 appropriate.

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 (Get) and resource (job's plain-text processing log), and describes the log as plain-text. An agent can distinguish this from siblings like get_job or get_transcript because the resource is explicitly the processing log.

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 a clear usage context ('useful for debugging a rejected job'), which tells the agent when to reach for this tool. It does not name alternatives or state when not to use it, so it falls short of 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?

readOnlyHint already covers the safety profile, and the description adds genuine beyond-annotation context: the status=='done' precondition and the underlying Batch API endpoint. It doesn't mention auth requirements, size limits, or whether the transcript is returned inline vs as a link, which keeps it from a 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?

Front-loads the core action, then packs format choices and the precondition into two tight sentences. Every clause carries information; 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?

With no output schema, the description does the work of explaining what each format returns, and states the status precondition. It omits how the payload is delivered (inline text, file, or URL) and any error behavior when the job isn't done, so it is strong but not fully complete.

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 beyond the schema: it expands srt as 'subtitles' (the schema only lists it in the enum) and details json-v2 contents (words, timings, speakers, translations, summary). Only job_id gets no added semantics, which it doesn't need.

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 (Get) and resource (a completed job's transcript), and the phrase 'completed job's transcript' distinguishes it from siblings like get_job (metadata) and get_job_log (logs). An agent can route correctly without opening any 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?

Explicitly states the precondition 'Only works once the job status is "done"', which is real usage guidance. It stops short of naming alternatives (e.g., use get_job to poll status first), so it is clear context without full when-to-use routing.

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, so safety is covered. The description adds useful context by naming the underlying Batch API route (GET /usage) and clarifying that the figures are transcription minutes, but says nothing about rate limits, default window, or aggregation granularity.

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 short sentences, front-loaded with the purpose. The trailing 'Batch API: GET /usage' is mildly extraneous for an agent that does not need the raw route, but it is compact and not harmful.

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?

There is no output schema, so the description should convey more about what is returned; it only hints at 'transcription minutes'. It also omits default date-range behavior for the optional parameters, leaving the agent to infer results when no range is supplied.

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%, with both parameters documented as YYYY-MM-DD dates, so the schema carries the semantics. The description only restates 'date range' and adds no format, default, or inclusivity details beyond it, making the baseline 3 appropriate.

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 ('Get usage statistics'), names the unit of measurement ('transcription minutes'), and scopes it to 'the account over a date range'. No sibling tool deals with usage, so the agent can separate it from job/transcript tools without ambiguity.

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 date-range framing implies when the tool applies, but there is no explicit when-to-use or when-not-to-use guidance, and no statement about what happens if since/until are omitted (both are optional).

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, so the safe-read profile is covered. The description adds genuinely useful behavior beyond that: result ordering (most recent first) and the exposed field set (status/data_name/duration), but it omits pagination behavior and the default treatment of deleted jobs.

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 sentences, front-loaded with the resource and ordering, with no wasted words. The endpoint note is compact rather than 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?

With no output schema, the description usefully names the returned fields, which is what an agent most needs for a read-only list tool. Minor gaps remain around pagination mechanics and the default visibility of deleted jobs, but nothing critical 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 description coverage is 100% and all three parameters (limit, created_before, include_deleted) are documented in the schema, so the baseline is 3. The description adds no parameter-level detail such as default limit or whether deleted jobs are hidden by default.

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 (list transcription jobs) plus ordering and the fields surfaced, so an agent immediately knows what it returns. It does not explicitly differentiate from the singular sibling speechmatics_get_job, leaving the list-vs-single distinction to inference.

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 never says when to use this tool versus alternatives such as speechmatics_get_job or speechmatics_get_usage, and lists no prerequisites or exclusions. The listing intent is only implied by the word 'List'.

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 only declare readOnlyHint=false, so the description carries most of the burden and does disclose key behavior: ASYNC submission, immediate job-id return, and the batch endpoint. It does not cover auth requirements for the API call, rate limits, or what happens when the URL fetch fails, so it stops short of full 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?

Three compact sentences, front-loaded with the core action before the async workflow. The trailing "Batch API: POST /jobs" is a minor implementation detail but is short and arguably useful for an agent choosing an integration path.

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 15-parameter, no-output-schema tool, the description supplies the critical missing piece: the async result-retrieval contract via get_job/get_transcript. The parameter surface is fully covered by the schema, and the return contract is summarized, leaving only auth/error handling 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 description coverage is 100%, so all 15 parameters (including diarization, summarize, translation_target_languages) are already documented. The description's mention of diarization/translation/summarization merely echoes the schema and adds no syntax or defaulting detail beyond it, so baseline 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?

States a specific verb (submit/transcribe) and resource (publicly reachable audio/video URL) plus the optional capabilities. It is immediately distinguishable from siblings like speechmatics_get_transcript or speechmatics_list_jobs, which are named in the routing guidance.

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 describes the orchestration: returns a job id immediately, poll speechmatics_get_job until status is "done", then call speechmatics_get_transcript. This names the downstream alternatives and the condition that selects each, leaving nothing to inference.

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