Skip to main content
Glama

Start a project run now

start_run

Crawl a project's site now with its saved settings, or re-read only the pages you list. The run is compared with the one before it. Use it after create_project or update_project, or whenever fresh results are wanted. For a site with no project use crawl_site. Inputs: project_id from list_projects. urls=['/pricing'] re-reads just those pages, resolved against the project's site, and compares them with the last full run; a URL on another site is refused before anything runs. wait=true returns the finished run instead of the queued one. Cost: 1 to 4 credits per page. A run that uses up the credit budget stops and keeps what it read. Refusals: 409 while another run is queued or running (stop it with cancel_job), and 402 with no credits left. Timing: with wait=true, a run that outlasts the connection's time limit comes back as a job for get_job. Read the results with list_pages and get_changes. Needs write access; a read-only connection is refused with code 'read_only'.

Input Schema

NameRequiredDescriptionDefault
urlsNoUp to 500 pages of the project's site to re-read, as full URLs or paths; omit to crawl the whole site.
waitNotrue waits for the run to finish (minutes for a large site); false (default) returns as soon as it is queued.
project_idYesThe project's 32-character hex id, from list_projects.

Output Schema

NameRequiredDescriptionDefault
idNoThe run's id: for get_job, cancel_job and the run_id of list_pages and get_changes.
jobNoWhen the wait ran out first: {kind: 'run', id, project_id} for get_job and cancel_job.
codeNoOnly on a failure: a machine-readable reason, e.g. read_only, validation, plan_limit or not_found.
noteNoWhat to do next when it is still going.
stopNoWhy it ended, e.g. the credit budget; empty while running.
errorNoOnly when the call failed: what went wrong, in words an assistant can act on.
scopeNoHow many URLs a start_run with urls listed; 0 for a full run.
countsNoPages by outcome, e.g. {ok, blocked, error}.
detailNoOnly on a failure: the API's own wording, when the error was rephrased.
pagesNNoPages read so far.
queuedNotrue while it waits for a worker.
statusNorunning, complete, partial (some pages refused), failed or cancelled. On an error, the HTTP status code.
triggerNomanual, scheduled, api or recrawl.
changedNNoPages added, modified or removed against the run before; null until compared.
coverageNoPercent of the known site this run reached.
startedAtNoWhen it started (ISO 8601).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / properties / id / description
      Previous value: -"The run's id: for get_job, cancel_job and the run_id of list_pages, get_page and get_changes."New value: +"The run's id: for get_job, cancel_job and the run_id of list_pages and get_changes."
  2. Changed3 schema fields changed
    • changedInput schema / properties / project_id / description
      Previous value: -"The project's id, as list_projects or create_project returns it."New value: +"The project's 32-character hex id, from list_projects."
    • addedInput schema / properties / urls
      Added value: +{
      +  "anyOf": [
      +    {
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Up to 500 pages of the project's site to re-read, as full URLs or paths; omit to crawl the whole site.",
      +  "title": "Urls"
      +}
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "additionalProperties": true,
      +  "description": "A run of a project, or a job when a wait ran out first.",
      +  "properties": {
      +    "changedN": {
      +      "description": "Pages added, modified or removed against the run before; null until compared.",
      +      "title": "Changedn"
      +    },
      +    "code": {
      +      "description": "Only on a failure: a machine-readable reason, e.g. read_only, validation, plan_limit or not_found.",
      +      "title": "Code"
      +    },
      +    "counts": {
      +      "description": "Pages by outcome, e.g. {ok, blocked, error}.",
      +      "title": "Counts"
      +    },
      +    "coverage": {
      +      "description": "Percent of the known site this run reached.",
      +      "title": "Coverage"
      +    },
      +    "detail": {
      +      "description": "Only on a failure: the API's own wording, when the error was rephrased.",
      +      "title": "Detail"
      +    },
      +    "error": {
      +      "description": "Only when the call failed: what went wrong, in words an assistant can act on.",
      +      "title": "Error"
      +    },
      +    "id": {
      +      "description": "The run's id: for get_job, cancel_job and the run_id of list_pages, get_page and get_changes.",
      +      "title": "Id"
      +    },
      +    "job": {
      +      "description": "When the wait ran out first: {kind: 'run', id, project_id} for get_job and cancel_job.",
      +      "title": "Job"
      +    },
      +    "note": {
      +      "description": "What to do next when it is still going.",
      +      "title": "Note"
      +    },
      +    "pagesN": {
      +      "description": "Pages read so far.",
      +      "title": "Pagesn"
      +    },
      +    "queued": {
      +      "description": "true while it waits for a worker.",
      +      "title": "Queued"
      +    },
      +    "scope": {
      +      "description": "How many URLs a start_run with urls listed; 0 for a full run.",
      +      "title": "Scope"
      +    },
      +    "startedAt": {
      +      "description": "When it started (ISO 8601).",
      +      "title": "Startedat"
      +    },
      +    "status": {
      +      "description": "running, complete, partial (some pages refused), failed or cancelled. On an error, the HTTP status code.",
      +      "title": "Status"
      +    },
      +    "stop": {
      +      "description": "Why it ended, e.g. the credit budget; empty while running.",
      +      "title": "Stop"
      +    },
      +    "trigger": {
      +      "description": "manual, scheduled, api or recrawl.",
      +      "title": "Trigger"
      +    }
      +  },
      +  "title": "RunOut",
      +  "type": "object"
      +}
  3. Changed2 schema fields changed
    • addedInput schema / properties / project_id / description
      Added value: +"The project's id, as list_projects or create_project returns it."
    • addedInput schema / properties / wait / description
      Added value: +"true waits for the run to finish (minutes for a large site); false (default) returns as soon as it is queued."
  4. First observed

TDQS

A4.9/5.0
Behavior5/5

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

Goes well beyond annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false) by disclosing cost (1-4 credits/page), budget-exhaustion behavior, specific refusal codes (409 for concurrent runs, 402 for no credits), the read_only rejection, and timing/timeout behavior with wait=true. This is exactly the operational context annotations cannot carry.

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-loads purpose, then organizes the rest under labeled sections (Inputs, Cost, Refusals, Timing) so an agent can scan to the relevant behavior. Despite its length, each sentence carries distinct, decision-relevant information with no filler.

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 non-idempotent, credit-consuming crawl trigger, it covers cost, failure modes, auth requirements, and result retrieval (list_pages/get_changes). An output schema exists, so return-value detail is correctly left out.

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 baseline is 3; the description adds real meaning on top — urls are resolved against the project's site, compared with the last full run, and a foreign-site URL is refused pre-run, while wait=true returns the finished run instead of the queued one. This enriches the schema's terse field docs.

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+scope: 'Crawl a project's site now with its saved settings, or re-read only the pages you list.' It explicitly names the sibling it is not ('For a site with no project use crawl_site'), so an agent can route without opening either 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?

Gives explicit when-to-use triggers ('after create_project or update_project, or whenever fresh results are wanted') and names the alternative (crawl_site) with its selecting condition. Preconditions like needing write access are also stated.

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.