Plori

Official

by plori-ai

Overview Schema Source Related Servers Discussions Admin

JavaScript

Remote

Schedule agent run

schedule_run

Destructive

Defer a one-shot agent run by delay_seconds or fire_at, then show the owner the prompt, time, and confirm_url for approval in Plori; recurring runs need create_workflow with a cron trigger.

Instructions

Request a one-shot deferred run of an agent, billed like any run. The schedule is not queued until the account owner confirms it in the Plori web app. Show the owner the prompt, time and confirm_url. The calling model cannot confirm it. Provide either delay_seconds (relative) or fire_at (an RFC3339 timestamp). For a recurring schedule, use create_workflow with a cron trigger instead.

Input Schema

TableJSON 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`	Yes	The agent's UUID.
`session_id`	No	Optional thread/session id to deliver the scheduled run into.
`delay_seconds`	No	Fire this many seconds from now (mutually exclusive with fire_at).

Output Schema

TableJSON Schema

Name	Required	Description
`id`	Yes
`kind`	Yes
`prompt`	Yes
`status`	Yes
`fire_at`	No
`agent_id`	Yes
`attempts`	Yes
`metadata`	No	Arbitrary JSON owned by the producing engine.
`thread_id`	No
`created_at`	Yes
`last_error`	No
`confirm_url`	No
`confirmed_at`	No
`last_fired_at`	No

Schema Changelog

Changes observed during successful MCP inspections.

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.7/5.0

Behavior5/5

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

Annotations declare destructive=false/true semantics and non-idempotency, but the description adds the behavioral facts that matter most: the schedule is not queued until the account owner confirms in the web app, the calling model cannot confirm it, the call is billed like a normal run, and the model should surface prompt/time/confirm_url to the owner. This is exactly the beyond-annotation context the dimension rewards.

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

Conciseness5/5

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

Five tight sentences, front-loaded with the high-stakes fact (deferred, billed, needs owner confirmation) before the parameter mechanics and the sibling routing note. No filler sentences.

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?

With an output schema present, return values need no explanation. For a mutation tool with a human-in-the-loop gate, the description covers billing, the confirmation requirement, who can confirm, what to show the owner, the mutually exclusive time parameters, and the recurring-schedule alternative.

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 all five parameters are already documented in the schema, including the mutual exclusivity of fire_at and delay_seconds. The description restates that exclusivity but adds no format or constraint 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 and resource ('Request a one-shot deferred run of an agent') and immediately scopes it against the recurring alternative (create_workflow with a cron trigger). An agent can distinguish this from invoke_agent, run_workflow, and create_workflow without opening a 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?

Explicitly says when to use this (one-shot deferred) versus the named alternative (recurring via create_workflow), plus the required alternative between delay_seconds and fire_at. It also flags the human confirmation gate as a precondition, which is the kind of routing information most definitions omit.

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