Plori

Official

by plori-ai

Overview Schema Source Related Servers Discussions Admin

JavaScript

Remote

Schedule a run

schedule_run

Destructive

Schedule a single future task for a Plori agent by setting delay_seconds or fire_at; it stays awaiting owner confirmation in Plori before it runs.

Instructions

Use this when the user wants one task to start later, such as "run this tonight" or "check again in two hours". Do not use for a repeating schedule such as every day or every week: ask the Workspace's agent with send_workspace_message to set up a scheduled workflow, which the account owner activates. Request one run at a later time, set by delay_seconds or fire_at (RFC 3339). Nothing is scheduled until the account owner confirms the request at confirm_url in the Plori web app: until then its status is awaiting_confirmation and it never fires, and the calling model cannot confirm it. A request whose fire time passes before the owner confirms it is not armed. Returns the request with its prompt, fire_at, status and confirm_url. The run it starts is charged like any run, and its actions outside the agent's own environment pause for the owner's approval one action at a time, as for any run started through this connector.

Input Schema

Name	Required	Description
`prompt`	Yes	The message to send the agent when the schedule fires.
`fire_at`	No	Fire at this RFC3339 timestamp (mutually exclusive with delay_seconds).
`agent_id`	No	The agent's UUID. Give this or workspace_id.
`session_id`	No	A conversation of the agent to deliver the scheduled run into (session_id from an earlier result). Omitted, the conversation the agent is running in when the request is made, or a new conversation when it is idle.
`workspace_id`	No	The Workspace UUID; the Workspace's agent runs the prompt. Give this or agent_id; with both, agent_id is used.
`delay_seconds`	No	Fire this many seconds from now (mutually exclusive with fire_at).

Output Schema

Name	Required	Description
`id`	Yes	The schedule's id.
`kind`	Yes	once: a single run at fire_at.
`prompt`	Yes	The message the agent receives when the schedule fires.
`status`	Yes	awaiting_confirmation until the owner confirms at confirm_url; pending once armed; firing or dispatched while delivery is in progress; done once the run starts; cancelled or failed otherwise.
`fire_at`	No	When it fires, RFC 3339.
`agent_id`	Yes	The agent the run is scheduled for.
`attempts`	Yes	Delivery attempts so far.
`metadata`	No	Extra data recorded with the request; not needed to use it.
`thread_id`	No	The conversation the run is delivered into: the session_id given, else the conversation the agent was running in when the request was made, else a new one.
`created_at`	Yes	When the request was made.
`last_error`	No	Why the last delivery attempt failed, when it did.
`confirm_url`	No	Where the owner confirms, in the Plori web app.
`confirmed_at`	No	When the owner confirmed it.
`last_fired_at`	No	When it last fired.

Schema Changelog

Changes observed during successful MCP inspections.

Changed18 schema fields changedv0.17.1Oct 18, 2026

changedInput schema / properties / agent_id / description

Previous value: -"The agent's UUID."New value: +"The agent's UUID. Give this or workspace_id."

changedInput schema / properties / session_id / description

Previous value: -"Optional thread/session id to deliver the scheduled run into."New value: +"A conversation of the agent to deliver the scheduled run into (session_id from an earlier result). Omitted, the conversation the agent is running in when the request is made, or a new conversation when it is idle."

addedInput schema / properties / workspace_id

Added value: +{
+  "description": "The Workspace UUID; the Workspace's agent runs the prompt. Give this or agent_id; with both, agent_id is used.",
+  "type": "string"
+}

changedInput schema / required

Previous value: -[
-  "agent_id",
-  "prompt"
-]New value: +[
+  "prompt"
+]

addedOutput schema / properties / agent_id / description
```
Added value: +"The agent the run is scheduled for."
```
addedOutput schema / properties / attempts / description
```
Added value: +"Delivery attempts so far."
```

addedOutput schema / properties / confirm_url / description

Added value: +"Where the owner confirms, in the Plori web app."

addedOutput schema / properties / confirmed_at / description
```
Added value: +"When the owner confirmed it."
```
addedOutput schema / properties / created_at / description
```
Added value: +"When the request was made."
```
addedOutput schema / properties / fire_at / description
```
Added value: +"When it fires, RFC 3339."
```
addedOutput schema / properties / id / description
```
Added value: +"The schedule's id."
```
addedOutput schema / properties / kind / description
```
Added value: +"once: a single run at fire_at."
```

addedOutput schema / properties / last_error / description

Added value: +"Why the last delivery attempt failed, when it did."

addedOutput schema / properties / last_fired_at / description
```
Added value: +"When it last fired."
```

changedOutput schema / properties / metadata / description

Previous value: -"Arbitrary JSON owned by the producing engine."New value: +"Extra data recorded with the request; not needed to use it."

addedOutput schema / properties / prompt / description

Added value: +"The message the agent receives when the schedule fires."

addedOutput schema / properties / status / description

Added value: +"awaiting_confirmation until the owner confirms at confirm_url; pending once armed; firing or dispatched while delivery is in progress; done once the run starts; cancelled or failed otherwise."

addedOutput schema / properties / thread_id / description

Added value: +"The conversation the run is delivered into: the session_id given, else the conversation the agent was running in when the request was made, else a new one."

Changed2 schema fields changedv0.17.0Oct 1, 2026
- addedOutput schema / properties / confirm_url
```
Added value: +{
+  "type": "string"
+}
```
- addedOutput schema / properties / confirmed_at
```
Added value: +{
+  "type": [
+    "null",
+    "string"
+  ]
+}
```

Changed1 schema field changedv0.16.0Sep 19, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "agent_id": {
+      "type": "string"
+    },
+    "attempts": {
+      "maximum": 2147483647,
+      "minimum": -2147483648,
+      "type": "integer"
+    },
+    "created_at": {
+      "type": "string"
+    },
+    "fire_at": {
+      "type": [
+        "null",
+        "string"
+      ]
+    },
+    "id": {
+      "type": "string"
+    },
+    "kind": {
+      "type": "string"
+    },
+    "last_error": {
+      "type": "string"
+    },
+    "last_fired_at": {
+      "type": [
+        "null",
+        "string"
+      ]
+    },
+    "metadata": {
+      "description": "Arbitrary JSON owned by the producing engine."
+    },
+    "prompt": {
+      "type": "string"
+    },
+    "status": {
+      "type": "string"
+    },
+    "thread_id": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "id",
+    "agent_id",
+    "kind",
+    "status",
+    "prompt",
+    "attempts",
+    "created_at"
+  ],
+  "type": "object"
+}

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

TDQS

A4.6/5.0

Behavior5/5

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

Annotations only flag destructive/openWorld/non-idempotent; the description goes well beyond by disclosing the entire confirmation lifecycle: nothing is armed until the owner confirms at confirm_url, status is awaiting_confirmation until then, the calling model cannot confirm, and a fire time that passes before confirmation never arms. It also discloses billing treatment and per-action approval outside the agent environment.

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 the selection rule, then the mechanics, then the return shape, with no filler sentences. It is a single dense paragraph rather than parsed sections, and the closing sentence on charging/per-action approval is marginal, but nearly every clause carries new behavioral information.

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

Completeness5/5

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

Covers selection, parameterization, the asynchronous confirmation gate, failure mode (fire time passing), and a brief return summary; an output schema exists so return details need not be expanded. Nothing an agent needs to invoke this correctly is missing.

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 coverage is 100%, so the schema already documents all six parameters including the fire_at/delay_seconds mutual exclusivity and RFC 3339 format that the description restates. The description adds no syntax or format detail beyond the schema, so the baseline 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 (schedule) and resource (one run) with explicit scope: 'Request one run at a later time, set by delay_seconds or fire_at'. It distinguishes itself from the closest sibling by name and by the one-off vs repeating distinction, so an agent can route correctly without opening either schema.

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

Usage Guidelines5/5

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

Gives an explicit when-to-use with example utterances ('run this tonight', 'check again in two hours') and an explicit when-not ('Do not use for a repeating schedule such as every day or every week') with the named alternative, send_workspace_message. Nothing 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.