list_jobsUse to find the user's recordings, e.g. 'my latest recording'. Newest first; no transcript text.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max jobs to return (default 20). |
| Name | Required | Description | Default |
|---|---|---|---|
| jobs | Yes | The user's jobs, newest first. |
Changes observed during successful MCP inspections.
Output schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "properties": {
+ "jobs": {
+ "description": "The user's jobs, newest first.",
+ "items": {
+ "additionalProperties": true,
+ "properties": {
+ "completed_at": {
+ "description": "ISO 8601 UTC time the job finished, or null.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "created_at": {
+ "description": "ISO 8601 UTC time the job was created, or null.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "duration_seconds": {
+ "description": "Audio length in seconds, or null until known.",
+ "type": [
+ "number",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Job id (UUID).",
+ "type": "string"
+ },
+ "status": {
+ "description": "queued, running, done or failed (more values may be added).",
+ "type": "string"
+ }
+ },
+ "required": [
+ "id",
+ "status"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "jobs"
+ ],
+ "type": "object"
+}Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only and closed-world safety, so the bar is lower; the description adds genuinely non-obvious behavior — result ordering (newest first) and the exclusion of transcript text, which tells the agent it must chain to get_transcript for content.
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 compact clauses; the selection trigger is front-loaded and the behavioral caveats follow without padding. Every clause 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?
An output schema exists, so return-value detail is unnecessary, and the description supplies the two facts an agent most needs (ordering, no transcript text). Only the missing differentiation from get_job keeps it short of a 5.
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 single 'limit' parameter is fully documented with its default of 20 in the schema. The description adds nothing about the parameter, 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?
The description states a concrete retrieval action ('find the user's recordings') and adds scope qualifiers ('Newest first; no transcript text'). Combined with the name/title it clearly identifies a jobs-listing tool, distinguishable from get_job/get_transcript, though it never explicitly says 'list 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?
The trigger example ('my latest recording') implies the discovery scenario — use this when you don't have a job ID. However, it never names the alternatives (get_job for a known ID, get_transcript for content) or states when NOT to use it, so the routing 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.
Add one secure layer between your agents and this server.