Skip to main content
Glama

job_create

Will work outlive the user request, need retries, or need a status later? job_create queues a durable background job. The platform POSTs the payload to your handler URL and retries on failure (at-least-once, up to 5 attempts with exponential backoff). Handlers are expected to be idempotent.

It suits work that should not block a user request: image processing, report generation, outbound email batches, webhook deliveries. run_at with an ISO-8601 time and explicit time zone schedules a future start. The job reports scheduled while waiting and reserves a slot in the account's job limit; cancel it to free that slot. It starts at or after that time.

Example:

{
  "project_id": "my-saas",
  "handler": "https://my-saas.somewhere.site/api/jobs/process-upload",
  "payload": { "upload_id": "u123", "user_id": "u_alice" },
  "timeout_seconds": 600
}
// Returns: { "job_id": "j_abc", "status": "queued" }

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": {
      "project_id": "<project_id>",
      "handler": "<handler>"
    },
    "name": "job_create"
  }
}

Input Schema

NameRequiredDescriptionDefault
run_atNoOptional earliest start in ISO-8601 with an explicit time zone, for example 2026-10-05T09:00:00Z. Must be future-dated for a new job. Omitted: starts now.
handlerYesFull https:// URL. The platform POSTs the payload here. Usually one of your own /api/... function routes.
payloadNoJSON string or object — becomes the POST body your handler receives.
project_idYesProject ID (UUID), subdomain, or slug — resolved server-side, no UUID lookup needed. 'default' also works when the account has exactly one project; multi-project accounts must name one (the error lists them).
webhook_urlNoOptional https:// URL — platform POSTs {job_id, status, result} here when the job reaches a terminal state.
idempotency_keyNoStable key for one logical creation. The same key with identical arguments is safe after a lost response; independent work takes a new key.
timeout_secondsNoHow long the platform waits for the handler, in seconds. Default 300, max 1800; a deadline of 271-300 s, or any deadline in a preview run, is waited for at most 270 s. When it passes the job fails with JOB_TIMEOUT and is not sent again; the handler may still have been running.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.3/5.0
Behavior5/5

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

Adds substantial behavior beyond the annotations: at-least-once delivery with up to 5 exponential-backoff attempts, handler idempotency expectations, timeout failure producing JOB_TIMEOUT with no resend, and scheduled jobs occupying an account job-limit slot until cancelled. The "handlers are expected to be idempotent" line concerns the caller's endpoint and does not conflict with idempotentHint=false, which the idempotency_key parameter corroborates.

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?

Front-loaded with a bolded decision question, then mechanism, then workload examples, then run_at caveats, then a compact example. The example block is short and doubles as return-value documentation, so every section earns its space.

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 7-parameter mutation with no output schema, the description covers delivery semantics, failure mode, scheduling behavior, and an example return shape. Gaps are modest: no mention of auth/permission prerequisites and no routing to the recurring-job sibling. What an agent needs to invoke it correctly is otherwise present.

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 100%, so the baseline is 3, but the description contributes meaning the schema lacks: run_at jobs report 'scheduled', reserve a slot in the account job limit, and must be cancelled to free it. The example also shows how payload, handler, and timeout_seconds combine in practice. It still omits discussion of webhook_url and idempotency_key, which the schema carries alone.

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

Purpose4/5

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

States a specific verb and resource: "job_create queues a durable background job," and immediately frames the mechanism (platform POSTs payload to handler, retries on failure). An agent can tell this is a one-off durable job tool rather than an immediate/synchronous call. It does not explicitly separate itself from the sibling cron_create (one-off with optional run_at vs. recurring schedule), which keeps it from a 5.

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

Usage Guidelines4/5

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

Opens with a decision test ("Will work outlive the user request, need retries, or need a status later?") and lists concrete qualifying workloads: image processing, report generation, email batches, webhook deliveries. That is clear when-to-use guidance. It offers no explicit exclusion or named alternative, so an agent must infer that recurring work belongs to cron_create.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources