Skip to main content
Glama

sitekick_job_start

DestructiveIdempotent

Explicitly start a durable generation job for the sealed project after reviewing project.estimate cost context. Pass its estimate_hash as reviewed_estimate_hash; changed revision or pricing requires renewed review. Actual child requests reserve credits and settle usage. Reuse the exact original command and idempotency key after an uncertain response.

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": {
      "payload": "<payload>",
      "site_ref": "<site_ref>",
      "idempotency_key": "<idempotency_key>"
    },
    "name": "sitekick_job_start"
  }
}

Input Schema

NameRequiredDescriptionDefault
payloadYes
site_refYes
idempotency_keyYes

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4/5.0
Behavior4/5

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

Annotations already declare write, destructive, idempotent, open-world, so the bar is lower, but the description genuinely adds context: the job is durable, child requests reserve credits and settle usage (a real cost side effect), and stale estimates must be re-reviewed. It does not explain what the destructiveHint implies in practice (e.g. what prior state or spend is superseded), which is the main remaining gap.

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?

Four dense sentences, front-loaded with the action and then the prerequisite, cost semantics, and retry rule in logical order. Every sentence carries information; minor density/jargon ('reserve credits and settle usage') costs a point but nothing is filler.

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 destructive, credit-consuming, nested-payload job tool, the description covers prerequisite, cost, idempotency and stale-estimate handling, and an output schema exists so return values need no explanation. Remaining omissions are the concrete destructive effect and failure/rejection behavior.

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 0%, so the description must compensate and largely does: it explains that reviewed_estimate_hash must come from project.estimate and becomes invalid on revision or pricing change, and that idempotency_key must match the original on retry. site_ref and the nested project_id/revision_id are left to naming conventions.

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 ('start') and resource ('durable generation job') plus the qualifying scope ('for the sealed project'), which separates it from sitekick_job_get/cancel/retry. It also names the upstream prerequisite tool (project.estimate), giving an agent a clear sense of where this sits in the workflow, though it does not explicitly contrast itself with sibling start-like tools such as sitekick_release_prepare.

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?

Gives real preconditions: review project.estimate cost context first, pass estimate_hash as reviewed_estimate_hash, and re-review if revision or pricing changed. It also prescribes behavior after an uncertain response (reuse the exact original command and idempotency key). What's missing is explicit negative guidance, e.g. when to use job_retry or job_cancel instead.

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