Plori

Official

by plori-ai

Overview Schema Source Related Servers Discussions Admin

JavaScript

Remote

List runs

list_runs

Read-only

Lists the newest runs for a Plori Workspace or agent, showing status, timing, cost, and session, with cursor paging for more results.

Instructions

List the runs of a Workspace or an agent, most recently started first, with each run's status, timing, attributed cost and session_id (its conversation). Returns 20 runs unless limit is given (at most 100). When more runs exist, the result has next_cursor; passing it as cursor returns the next page, and its absence means the list is complete. tool_progress is null for an ended run and for a run without recorded tool progress. input_expired:true marks a run paused on a question that a later completed run in the same conversation has superseded.

Input Schema

Name	Required	Description
`limit`	No	How many runs to return, newest first (default 20, maximum 100).
`cursor`	No	The next_cursor from a previous list_runs result, to continue where it stopped. Omit for the newest page.
`agent_id`	No	The agent UUID (agent_id in a run result). Give this or workspace_id.
`workspace_id`	No	The Workspace UUID. Give this or agent_id; with both, agent_id is used. Lists the runs of its main conversation and of the Workspace's agent: the 100 newest, plus runs still running or paused. list_workspace_workers lists the workers' runs.

Output Schema

Name	Required	Description	Default
`items`	Yes	One page of the agent's runs, most recently started first.
`next_cursor`	No	Pass this back as cursor to read the next page. Absent when this page is the end of the history.

Schema Changelog

Changes observed during successful MCP inspections.

Changed9 schema fields changedv0.17.1Oct 18, 2026

changedInput schema / properties / agent_id / description

Previous value: -"The agent's UUID."New value: +"The agent UUID (agent_id in a run result). Give this or workspace_id."

addedInput schema / properties / workspace_id

Added value: +{
+  "description": "The Workspace UUID. Give this or agent_id; with both, agent_id is used. Lists the runs of its main conversation and of the Workspace's agent: the 100 newest, plus runs still running or paused. list_workspace_workers lists the workers' runs.",
+  "type": "string"
+}

removedInput schema / required
```
Removed value: -[
-  "agent_id"
-]
```
addedOutput schema / properties / items / items / properties / events_expired_at
```
Added value: +{
+  "type": [
+    "null",
+    "string"
+  ]
+}
```
addedOutput schema / properties / items / items / properties / history_error
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / items / items / properties / private_history_expired_at
```
Added value: +{
+  "type": [
+    "null",
+    "string"
+  ]
+}
```

addedOutput schema / properties / items / items / properties / retention_policy

Added value: +{
+  "description": "Extra data recorded with the request; not needed to use it."
+}

addedOutput schema / properties / items / items / properties / save_failure

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "code": {
+      "type": "string"
+    },
+    "content_refusals": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "cause": {
+            "type": "string"
+          },
+          "path": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "cause",
+          "path"
+        ],
+        "type": "object"
+      },
+      "type": [
+        "null",
+        "array"
+      ]
+    }
+  },
+  "required": [
+    "code"
+  ],
+  "type": [
+    "null",
+    "object"
+  ]
+}

changedOutput schema / properties / items / items / properties / session_id / description

Previous value: -"The conversation this run belongs to; pass it to invoke_agent as session_id to continue it. Identical to thread_id."New value: +"The conversation this run belongs to; pass it to send_workspace_message as session_id to continue it. Identical to thread_id."

Changed9 schema fields changedv0.16.2Sep 21, 2026

addedOutput schema / properties / items / items / properties / advisor

Added value: +{
+  "additionalProperties": false,
+  "description": "Gross advisor consumption for the turn; the cap compares against this amount.",
+  "properties": {
+    "calls_allowed": {
+      "type": "integer"
+    },
+    "calls_used": {
+      "type": "integer"
+    },
+    "spend_cap_micro_usd": {
+      "type": [
+        "null",
+        "integer"
+      ]
+    },
+    "spend_micro_usd": {
+      "description": "Gross advisor consumption for the turn; the cap compares against this amount.",
+      "type": "integer"
+    }
+  },
+  "required": [
+    "calls_used",
+    "calls_allowed",
+    "spend_micro_usd"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / items / items / properties / credits / description
```
Added value: +"The net charge after any refund."
```

addedOutput schema / properties / items / items / properties / error / properties / upgrade

Added value: +{
+  "additionalProperties": false,
+  "description": "Which plan lifts the limit this run ended at, when it ended at one.",
+  "properties": {
+    "anonymous": {
+      "type": "boolean"
+    },
+    "limit": {
+      "type": "string"
+    },
+    "message": {
+      "type": "string"
+    },
+    "offer": {
+      "additionalProperties": false,
+      "properties": {
+        "discount_code": {
+          "type": "string"
+        },
+        "first_period_price_micro_usd": {
+          "type": "integer"
+        },
+        "message": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "discount_code",
+        "first_period_price_micro_usd",
+        "message"
+      ],
+      "type": [
+        "null",
+        "object"
+      ]
+    },
+    "plan": {
+      "type": "string"
+    },
+    "remedies": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "kind": {
+            "type": "string"
+          },
+          "limits": {
+            "additionalProperties": false,
+            "properties": {
+              "disk_gb": {
+                "type": "integer"
+              },
+              "max_active_workflows": {
+                "type": "integer"
+              },
+              "max_agents": {
+                "type": "integer"
+              },
+              "max_concurrent_runs": {
+                "type": "integer"
+              }
+            },
+            "required": [
+              "max_concurrent_runs",
+              "max_agents",
+              "max_active_workflows",
+              "disk_gb"
+            ],
+            "type": [
+              "null",
+              "object"
+            ]
+          },
+          "message": {
+            "type": "string"
+          },
+          "offer": {
+            "additionalProperties": false,
+            "properties": {
+              "discount_code": {
+                "type": "string"
+              },
+              "first_period_price_micro_usd": {
+                "type": "integer"
+              },
+              "message": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "discount_code",
+              "first_period_price_micro_usd",
+              "message"
+            ],
+            "type": [
+              "null",
+              "object"
+            ]
+          },
+          "plan": {
+            "type": "string"
+          },
+          "url": {
+            "type": "string"
+          },
+          "usd_cents_per_month": {
+            "type": "integer"
+          }
+        },
+        "required": [
+          "kind",
+          "message"
+        ],
+        "type": "object"
+      },
+      "type": [
+        "null",
+        "array"
+      ]
+    },
+    "url": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "limit",
+    "plan",
+    "message",
+    "remedies"
+  ],
+  "type": [
+    "null",
+    "object"
+  ]
+}

addedOutput schema / properties / items / items / properties / gross_micro_usd

Added value: +{
+  "description": "Gross consumption before any refund.",
+  "type": "integer"
+}

addedOutput schema / properties / items / items / properties / refund_reason
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / items / items / properties / refund_withheld_reason
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / items / items / properties / refunded_micro_usd

Added value: +{
+  "description": "The refund reported once for this run.",
+  "type": "integer"
+}

addedOutput schema / properties / items / items / properties / usage_by_role

Added value: +{
+  "additionalProperties": false,
+  "description": "Gross consumption by role; credits sum to gross_micro_usd and refunds appear only in refunded_micro_usd.",
+  "properties": {
+    "advisor": {
+      "additionalProperties": false,
+      "properties": {
+        "calls": {
+          "type": "integer"
+        },
+        "credits": {
+          "type": "integer"
+        },
+        "tokens": {
+          "type": "integer"
+        }
+      },
+      "required": [
+        "credits",
+        "tokens",
+        "calls"
+      ],
+      "type": "object"
+    },
+    "executor": {
+      "additionalProperties": false,
+      "properties": {
+        "calls": {
+          "type": "integer"
+        },
+        "credits": {
+          "type": "integer"
+        },
+        "tokens": {
+          "type": "integer"
+        }
+      },
+      "required": [
+        "credits",
+        "tokens",
+        "calls"
+      ],
+      "type": "object"
+    },
+    "reviewer": {
+      "additionalProperties": false,
+      "properties": {
+        "calls": {
+          "type": "integer"
+        },
+        "credits": {
+          "type": "integer"
+        },
+        "tokens": {
+          "type": "integer"
+        }
+      },
+      "required": [
+        "credits",
+        "tokens",
+        "calls"
+      ],
+      "type": "object"
+    }
+  },
+  "required": [
+    "executor",
+    "advisor",
+    "reviewer"
+  ],
+  "type": [
+    "null",
+    "object"
+  ]
+}

changedOutput schema / properties / items / items / required

Previous value: -[
-  "id",
-  "agent_id",
-  "thread_id",
-  "session_id",
-  "status",
-  "origin",
-  "started_at",
-  "credits",
-  "tokens",
-  "tool_progress"
-]New value: +[
+  "id",
+  "agent_id",
+  "thread_id",
+  "session_id",
+  "status",
+  "origin",
+  "started_at",
+  "credits",
+  "tokens",
+  "advisor",
+  "tool_progress"
+]

Changed3 schema fields changedv0.16.0Sep 19, 2026

addedInput schema / properties / cursor

Added value: +{
+  "description": "The next_cursor from a previous list_runs result, to continue where it stopped. Omit for the newest page.",
+  "type": "string"
+}

addedInput schema / properties / limit

Added value: +{
+  "description": "How many runs to return, newest first (default 20, maximum 100).",
+  "maximum": 100,
+  "minimum": 1,
+  "type": "integer"
+}

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "items": {
+      "description": "One page of the agent's runs, most recently started first.",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "agent_id": {
+            "description": "The agent that ran it.",
+            "type": "string"
+          },
+          "cause": {
+            "type": "string"
+          },
+          "command_error": {
+            "type": "string"
+          },
+          "command_state": {
+            "type": "string"
+          },
+          "continuation_run_id": {
+            "type": "string"
+          },
+          "credits": {
+            "type": [
+              "null",
+              "integer"
+            ]
+          },
+          "ended_at": {
+            "type": [
+              "null",
+              "string"
+            ]
+          },
+          "error": {
+            "additionalProperties": false,
+            "description": "Why a terminal error or cancelled run failed, and what to do about it. Absent for a run that is still going or that finished normally.",
+            "properties": {
+              "class": {
+                "description": "The failure class: the run's terminal cause, or \"unknown\" when none was recorded.",
+                "type": "string"
+              },
+              "message": {
+                "description": "What happened, and whether the work was charged.",
+                "type": "string"
+              },
+              "next_step": {
+                "description": "What to do about it.",
+                "type": "string"
+              },
+              "retryable": {
+                "description": "Whether sending the same message again could plausibly succeed.",
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "class",
+              "message",
+              "retryable",
+              "next_step"
+            ],
+            "type": [
+              "null",
+              "object"
+            ]
+          },
+          "id": {
+            "description": "The run's public identifier; pass it to get_run_result as run_id.",
+            "type": "string"
+          },
+          "input_expired": {
+            "description": "True when this run is parked on a question its session has moved past: a later run in the same conversation has completed, so answering it would resume a superseded turn. Do not answer it; start a new run instead.",
+            "type": "boolean"
+          },
+          "input_status": {
+            "type": "string"
+          },
+          "input_updated_at": {
+            "type": [
+              "null",
+              "string"
+            ]
+          },
+          "last_heartbeat_at": {
+            "type": [
+              "null",
+              "string"
+            ]
+          },
+          "origin": {
+            "description": "What started this run: user, schedule, email, background, agent or agent_result.",
+            "type": "string"
+          },
+          "parent_run_id": {
+            "type": "string"
+          },
+          "resume_run_id": {
+            "type": "string"
+          },
+          "resume_status": {
+            "type": "string"
+          },
+          "retryable": {
+            "type": "boolean"
+          },
+          "session_id": {
+            "description": "The conversation this run belongs to; pass it to invoke_agent as session_id to continue it. Identical to thread_id.",
+            "type": "string"
+          },
+          "started_at": {
+            "type": "string"
+          },
+          "status": {
+            "description": "The run's status: queued, running, awaiting_input, completed, error or cancelled.",
+            "type": "string"
+          },
+          "stop_reason": {
+            "type": "string"
+          },
+          "thread_id": {
+            "description": "The conversation this run belongs to. Identical to session_id.",
+            "type": "string"
+          },
+          "tokens": {
+            "type": [
+              "null",
+              "integer"
+            ]
+          },
+          "tool_progress": {
+            "additionalProperties": false,
+            "description": "Durable tool execution progress, from the same telemetry get_run_result reads. Null for a run with no telemetry, and for a terminal run, which has no call in flight to report.",
+            "properties": {
+              "active_tools": {
+                "items": {
+                  "additionalProperties": false,
+                  "properties": {
+                    "id": {
+                      "type": "string"
+                    },
+                    "name": {
+                      "type": "string"
+                    },
+                    "started_at": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "id",
+                    "name",
+                    "started_at"
+                  ],
+                  "type": "object"
+                },
+                "type": [
+                  "null",
+                  "array"
+                ]
+              },
+              "completed_count": {
+                "type": "integer"
+              },
+              "last_completed_at": {
+                "type": [
+                  "null",
+                  "string"
+                ]
+              }
+            },
+            "required": [
+              "active_tools",
+              "completed_count"
+            ],
+            "type": [
+              "null",
+              "object"
+            ]
+          },
+          "upstream_status": {
+            "description": "The model provider's HTTP status when this run died on an upstream fault; absent otherwise.",
+            "type": "integer"
+          }
+        },
+        "required": [
+          "id",
+          "agent_id",
+          "thread_id",
+          "session_id",
+          "status",
+          "origin",
+          "started_at",
+          "credits",
+          "tokens",
+          "tool_progress"
+        ],
+        "type": "object"
+      },
+      "type": [
+        "null",
+        "array"
+      ]
+    },
+    "next_cursor": {
+      "description": "Pass this back as cursor to read the next page. Absent when this page is the end of the history.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "items"
+  ],
+  "type": "object"
+}

Addedv0.7.0Aug 9, 2026
Removedv0.3.0Jul 26, 2026
First observedv0.1.0Jul 4, 2026

TDQS

A4.1/5.0

Behavior5/5

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

Annotations only declare readOnlyHint/openWorldHint/idempotentHint; the description adds real behavioral context beyond them: default page size 20 with a ceiling of 100, cursor round-trip semantics, and the meaning of null tool_progress and input_expired:true. These are exactly the semantics an agent cannot infer and are consistent with idempotentHint=false (a cursor list drifts as new runs appear).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and ordering, then pagination, then the two edge-case field meanings — all in dense, waste-free sentences. The final two sentences explain return-field semantics that the output schema already covers, which is the only slack.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 4-param, zero-required list tool with a full output schema and read-only annotations, the description covers paging, sizing and result interpretation adequately. What it lacks is routing context against get_run_result / list_workspace_workers, which would make selection unambiguous.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 limit, cursor, agent_id and workspace_id, including their defaults and precedence. The description restates limit/default and cursor semantics without adding syntax or format detail beyond the schema, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List the runs of a Workspace or an agent'), plus ordering ('most recently started first') and the fields surfaced per run (status, timing, cost, session_id). An agent knows exactly what this returns without opening the schema. The 'run' concept is distinct from the worker/workspace siblings even though no sibling is named.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains pagination operation (next_cursor / cursor, absence means complete) which is genuine usage guidance, but it never states when to choose this tool over get_run_result or list_workspace_workers, nor when to prefer agent_id vs workspace_id at the description level. Usage is implied rather than declared.

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