FieldTranscript

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

The description adds irreversibility ('This cannot be undone') and the refusal condition beyond the annotations. It reinforces the destructive nature and specifies the scope of deletion (job and stored text), providing valuable context that the annotations alone do not convey.

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 concise sentences with no redundant information. Each sentence adds value: the action, the condition, and the consequence, making it highly efficient and easy to parse.

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 deletion tool with a single parameter and existing annotations, the description covers the key behavioral aspects. It lacks details on error cases or return values, but these are not critical given the tool's simplicity and the presence of the output schema absence.

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 one required parameter, job_id, with no description, and schema coverage is 0%. The tool description references the job but doesn't explicitly explain job_id semantics, leaving the agent to infer it identifies the target job. This is insufficient given the complete lack of schema description.

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's function: permanently deleting a finished transcription job and its stored text. It distinguishes from siblings (get_job, list_jobs, submit_transcription) by specifying the delete action and the state constraint, making it 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?

The description explicitly states when the tool is applicable (finished jobs) and when it is refused (queued or running). This provides clear usage guidance, though it doesn't name alternative tools for checking job status, which would have made it fully explicit.

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 (readOnlyHint, idempotentHint), the description adds meaningful behavioral context: it specifies the exact status values returned, mentions that metadata is included, and discloses the potentially large payload size when include_transcript=true. This warning is valuable for an agent deciding whether to request the transcript.

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 concise sentences: the first states the purpose and return values, the second provides an actionable parameter guideline with a rationale. No waste, no repetition of schema details, and the most important caution (transcript size) is front-loaded in the second sentence.

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 simple two-parameter tool, no output schema, and present annotations, this description covers the essential aspects: what the tool does, what it returns, and a key behavioral warning about large transcript payloads. It is sufficiently complete for an agent to invoke the tool correctly and interpret the response.

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?

With 0% schema description coverage, the description fully compensates for include_transcript by explaining exactly when to set it to true and why (transcripts can be large). job_id is self-evident from the context of checking a specific job. This adds substantial meaning beyond the bare 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 opens with 'Check a transcription job,' which is a specific verb + resource pairing. It clearly distinguishes this tool from siblings (delete_job, list_jobs, submit_transcription) by focusing on retrieving a single job's status and metadata. The return value is explicitly enumerated (queued / working / done / error).

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 clear context for when to use the tool (checking a transcription job) and offers a specific parameter-level guideline: only include the transcript when status is 'done' and the full text is needed, warning about size. However, it does not explicitly contrast with sibling tools like 'list_jobs' for multiple jobs or 'delete_job' for removal, so alternatives are only implied.

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 idempotentHint=true, so the safety profile is covered. The description adds useful behavior beyond annotations by specifying the ordering ('newest first'), which is not conveyed in the structured data.

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 single, front-loaded sentence with no filler. Every word adds value: the action, the resource, the scope, and the ordering.

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 no-parameter, read-only list tool with annotations describing its safety and idempotency, the description is nearly complete. It could mention the return format (e.g., an array of job objects), but the absence of an output schema and the simplicity of the operation make this a minor 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?

The tool has zero parameters, so the schema carries no parameter semantics. Per rubric, 0 params warrants a baseline of 4. The description appropriately adds no redundant parameter information.

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 the specific verb 'List' with a clear resource ('transcription jobs') and scope ('on your account'), plus a meaningful detail ('newest first'). This clearly distinguishes it from sibling tools like delete_job, get_job, and submit_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 implies the use case (viewing all jobs) but does not explicitly state when to prefer this over get_job or other siblings. There are no exclusions or alternative guidance, making the usage only implicitly clear.

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 annotations already signal mutation, open world, and non-idempotence, and the description adds substantial behavioral context: immediate job_id return, 1–10 minute processing time, polling cadence, and the need for include_transcript when retrieving results. No contradiction with 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 three sentences, each adding critical information: action, return value, timing, polling procedure, and a constraint. It is front-loaded and free of filler.

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 input scope, immediate output, asynchronous timing, polling instructions, and final transcript retrieval, making it reasonably complete for a submit tool with no output schema. It omits error or rejection behavior, but the operational workflow is strong enough to guide an agent.

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?

While the schema has no description for the url parameter, the description compensates by specifying it must be a public video/audio URL (e.g., YouTube) and excludes private/internal URLs. It could be more detailed about supported platforms or formats, but for a single string parameter this is adequate.

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 the specific verb 'submit' with a clear resource ('public video or audio URL for verbatim transcription') and states the immediate return of a job_id. This fully distinguishes it from sibling tools like get_job, list_jobs, and delete_job.

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 when to use the tool (public URLs), when not to use it ('Not for private/internal URLs'), and provides a concrete workflow: poll get_job every 30–60 seconds until status 'done', then call get_job with include_transcript=true. This is strong, actionable guidance.

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