Skip to main content
Glama
Vitalini

ebb-ai

by Vitalini
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

schedule_task

Queue an LLM task to run during a low-carbon, off-peak grid window before a deadline, cutting cost through batch APIs.

Instructions

Queue an AI task to run during off-peak hours inside the given deadline. Four parallel wins: (1) lighter on the electricity grid — deferring non-urgent tasks smooths projected AI compute demand; (2) up to 50% cheaper — auto-routes through Anthropic/OpenAI Batch APIs when the deadline allows; (3) faster sync calls — off-peak queues are shorter; (4) lower carbon — dispatch at the cleanest electricity-grid hour. Invoke this tool whenever the user phrases a request with deferral language: "do this later", "by tomorrow", "tonight", "overnight", "by EOD", "sometime this week", "when you have a moment", "remind me to", "queue this up", "schedule this", "no rush", "not urgent". Convert the user's wording to an ISO-8601 deadline and pass the task as the prompt. Returns a task_id you can later check with check_queue_status. Good fits: nightly digests, batch summaries, research sweeps, evaluator runs, multi-step report generation — anything the user is fine waiting on. Do NOT use for live chat, interactive code edits, or any task the user is actively waiting to see complete.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
modelNoModel to dispatch with (e.g. 'claude-sonnet-5' for Anthropic, 'gpt-6-sol' for OpenAI). Defaults per provider: anthropic 'claude-sonnet-5' (EBB_DEFAULT_MODEL overrides it), openai 'gpt-6-sol', gemini 'gemini-3.8-flash', ollama 'llama3.1'. When >= 2 'candidates' are supplied, routing may overwrite this with the winning candidate.
promptYesThe prompt or task description to dispatch when the chosen window arrives.
regionNoGrid-region override (Electricity Maps zone code such as 'US-CAL-CISO'). Defaults to the host's configured region, else a host-timezone guess, else GB.
dry_runNoIf true, return the planned dispatch (recommended window + carbon estimate) WITHOUT persisting anything. Useful for confirmation flows.
deadlineYesISO-8601 timestamp (e.g. '2026-05-13T08:00:00-04:00') by which the task must have completed. Must be in the future. Required.
dispatchNoIf true (default), persist a provider_call task body that `ebb tick` (CLI) or scheduler.tick (library) can dispatch. Set to false only to enqueue a placeholder prompt without a dispatchable body (legacy in-memory mode).
providerNoWhich provider to dispatch this task through: 'anthropic', 'openai', 'gemini', or 'ollama' (local). Defaults to 'anthropic'. 'anthropic' and 'openai' can auto-route through a 50%-cheaper Batch API when the deadline allows; 'gemini' and 'ollama' always dispatch synchronously.
candidatesNoOptional cross-provider routing candidates: 'provider:model' strings (e.g. ['anthropic:claude-haiku-4-5','openai:gpt-6-luna','ollama:llama-3-1-8b']) the caller EXPLICITLY allows. With >= 2 entries the scheduler scores them at the chosen dispatch window on a weighted blend of carbon, cost and latency and dispatches the winner (recording the full scored list on the signed receipt). No silent model swaps — routing only ever picks from this list. Absent or a single entry leaves the provider/model behavior unchanged. Every candidate model must exist in the price table or the task is rejected loudly.
output_pathNoOptional absolute file path. When the task completes, ebb-ai writes { taskId, result, receipt } as JSON to this path.
route_weightsNoOptional routing weights {carbon, cost, latency}, non-negative and normalized internally. Default {carbon:0.6, cost:0.3, latency:0.1}. Only used when 'candidates' has >= 2 entries.
carbon_budget_gNoOptional hard cap on estimated grams CO2-equivalent for this task. Windows above the cap are dropped before the cleanest is chosen; if none inside the deadline meets the cap the task fails rather than dispatching to a dirty window.
redact_in_receiptNoOptional regex patterns to strip from the prompt before storing it on the receipt. Omit to use the default redaction of API-key-looking strings.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.16.0

TDQS

A4.6/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and mostly does: it discloses off-peak dispatch, Batch API auto-routing with up to 50% cost reduction, grid-region/carbon-aware window selection, deadline conversion, and that a task_id is returned for later status checks. It stops short of stating failure semantics (e.g. what happens when no window meets a carbon cap or the deadline passes) and leans on promotional framing for what are really behavioral claims.

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?

The purpose is front-loaded in sentence one and the routing/return facts follow in a logical order. The four-item 'parallel wins' block is longer than necessary and partly promotional, but the trigger-phrase enumeration and exclusions carry real selection value, so the length is mostly earned.

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 12-parameter, deeply nested tool with no annotations and no output schema, the description supplies everything an agent needs to decide to call it and how to shape the core call: purpose, triggers, exclusions, deadline/prompt mapping, provider/batch behavior, and the downstream status-check path. Remaining specifics (weights, output_path, redaction) are thoroughly covered by the 100%-covered schema.

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 description coverage is 100%, so the baseline is 3, but the description adds genuine mapping guidance beyond the schema: convert the user's deferral wording into an ISO-8601 deadline and pass the underlying request as the prompt. It does not, however, explain the relationship between candidate routing, weights, or the carbon budget beyond what the schema already says.

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?

The first sentence states a specific verb and resource with scope: 'Queue an AI task to run during off-peak hours inside the given deadline.' It also names the follow-up sibling (check_queue_status) and scopes itself apart from live/interactive work, so an agent can distinguish it from recommend_window or get_grid_forecast.

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?

It gives explicit invocation triggers ('do this later', 'by tomorrow', 'overnight', 'no rush', etc.), concrete good-fit workloads (nightly digests, batch summaries, research sweeps), and explicit exclusions (live chat, interactive code edits, tasks the user is actively waiting on). This is about as complete a when/when-not statement as a description can carry.

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

Deploy Server

Other Tools