transcription_status

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

With no annotations, the description carries the full behavioral disclosure burden. It discloses comparing with transcribe_status but never explains what the actual behavior is—such as what a status check returns, whether it is read-only, or if it can return not-found states. The deprecation and removal version are useful metadata, but they do not substitute for describing the operation's runtime behavior.

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 concise and front-loaded: the deprecation warning and replacement tool appear first, followed by the compatibility scope and removal version. Every sentence carries a distinct piece of information, with zero redundant phrases.

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?

This is a very simple deprecated alias with one parameter and no output schema, so the description does not need to explain complex return formats. However, because it says behavior is 'identical to transcribe_status' and does not describe that behavior, an agent that cannot read the sibling description would remain under-informed. It is sufficient for routing but not for understanding the tool's own contract.

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 provides 100% coverage for the single parameter transcription_id with the description 'The transcription ID.' The tool description adds no extra param semantic context, such as required format, source, or relationship to existing transcriptions, so it remains at the baseline without requiring special compensation.

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 identifies this tool as a deprecated alias for transcribe_status, contrasting it directly with its replacement sibling. It does not explicitly state the underlying operation (e.g., 'retrieves a transcription status'), but the tool name and 'Identical behavior to transcribe_status' make the resource unambiguous. It distinguishes itself from transcribe_status by specifying the deprecation and removal timeline.

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 instructs the agent to use transcribe_status instead: 'use transcribe_status instead.' It also provides context that this is only for backward compatibility with a specific package version and will be removed in 2.0.0, so the agent knows not to select this tool for new workflows.

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