Skip to main content
Glama

Run a block on a schedule

create_schedule

Start firing a schedule block on a cron unattended by pinning a committed workspace version; preview without confirm, then confirm to create and quote the reported firing time.

Instructions

Starts firing a Schedule block on a cron, unattended. THIS is what makes a schedule real — setting schedule on the block only records the cadence in the workspace's content. Requires confirm=true; call without confirm first to preview. It pins the latest COMMITTED version (commit first if there isn't one — the error says so), and the plan decides the fastest allowed cadence: a free workspace is one schedule, hourly. On a free plan the firing time is offset by a fixed number of seconds so every workspace doesn't fire at once — the reply reports it, so quote the real time back to the user.

PINNING IS FROZEN, and that is the opposite of how deploy_endpoint behaves: an endpoint serves the live auto-save and picks up every edit at once, a schedule keeps running its commit. So editing a block the schedule fires changes nothing about tonight's run — that takes a new commit and a schedule pinned to it. Say this to the user when you create one; list_schedules reports canvasAheadOfPin once the two have parted company.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "workspaceId": "<workspaceId>",
      "blockId": "<blockId>",
      "cron": "<cron>"
    },
    "name": "create_schedule"
  }
}

Input Schema

NameRequiredDescriptionDefault
cronYesFive-field cron, e.g. "0 9 * * *" (09:00 daily) or "*/15 * * * *".
blockIdYesThe Schedule block to fire, from get_workspace_content.
confirmNoMust be true to create. Omit/false returns a preview only.
timeZoneNoIANA timezone the cron is read in, e.g. "Europe/Paris". Defaults to UTC.
versionIdNoWorkspace version to pin. Omit for the latest COMMITTED version — never the auto-save, which is where half-finished work lives. A workspace with no commit is rejected, with an explanation.
workspaceIdYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.53.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only declare destructiveHint=false, so the description carries the behavioral load and does so: preview-vs-create semantics, commit prerequisite with a self-explaining error, plan-based cadence ceiling, a fixed firing-time offset, and the fact that the reply reports the real fire time. The frozen-pin behavior and its consequence for later edits is exactly the kind of non-obvious trait an agent must surface to a user.

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 core action and the confirm/preview rule, then the pinning caveat, which is the highest-risk misunderstanding. It is dense and slightly repetitive — the frozen-pin point is made twice (the PINNING IS FROZEN sentence and the 'editing a block the schedule fires changes nothing' sentence) — but nearly every sentence carries decision-relevant 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?

For a 6-parameter mutation with no output schema, the description covers the gaps that matter: the confirmation flow, the commit prerequisite, plan-based limits, the offset firing time, and what the reply reports. Nothing an agent needs to call this correctly or explain the result is missing.

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

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 83%, so the baseline is 3; the description goes beyond it by explaining that versionId pins the latest COMMITTED version and never the auto-save, that a workspace with no commit is rejected, and that the plan constrains allowed cron cadence. It adds little on timeZone beyond the schema, and cron syntax detail lives mostly in the schema.

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+resource+effect: "Starts firing a Schedule block on a cron, unattended," and immediately disambiguates from the near-neighbor action of setting `schedule` on a block, which "only records the cadence." It also distinguishes itself from deploy_endpoint by behavior, so an agent can pick the right tool without opening schemas.

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 explicit operating procedure: requires confirm=true, call without confirm first to preview, commit first if there is no commit. It also names the alternative pattern (deploy_endpoint serves live auto-save; schedule pins a commit) and the follow-up tool (list_schedules reports canvasAheadOfPin), covering when-to-use and when-not.

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