Skip to main content
Glama

Run a research agent

run_agent

Hand a research question to an agent that searches the web, maps sites and reads pages on its own, then answers with the sources it used. Use it for questions that need several pages or sites to answer. When you know what to fetch, search_web and scrape_urls are quicker and cheaper. Inputs: prompt says what to find, e.g. 'the monthly price of each plan on example.com'. urls gives pages to start from, e.g. ['https://example.com/pricing']. schema shapes the answer, e.g. {"type": "object", "properties": {"plans": {"type": "array"}}}; without one the answer is {"text": ...}. allowed_domains=['example.com'] keeps it to those sites; with urls and no allowed_domains it stays on the sites of urls, as a page could tell it to go elsewhere, and allowed_domains=[] lets it read any site. Cost: pages are charged as they are read, and a page the site refuses is free; the model's tokens at the model provider's price plus 20%. A question answered from one page typically costs 40-130 credits, most of it the model's tokens, against 1-4 for scrape_urls of that page. max_credits caps the whole run, 500 by default here; a run that reaches it stops with what it found, and continue_agent carries it on. Timing: it returns at once with a job, as an agent works for minutes. Call get_job(kind='agent', id=...) every 30 to 60 seconds; cancel_job stops it. Calling run_agent again with the same inputs in the same ten-minute window returns that run, not a new one. Needs write access; a read-only connection is refused with code 'read_only'.

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": {
      "prompt": "<prompt>"
    },
    "name": "run_agent"
  }
}

Input Schema

NameRequiredDescriptionDefault
urlsNoUp to 20 absolute http(s) URLs for the agent to start from; omit to let it search.
promptYesWhat the agent should find out, 1 to 10,000 characters, as a question or a task.
schemaNoA JSON Schema object whose type is object or array; the answer then matches it. Omit for a text answer, {"text": ...}.
max_stepsNoThe most steps the agent may take, 1 to 100; omit for 40.
max_creditsNoThe most the run may spend, 1 to 100,000 credits; omit for 500.
allowed_domainsNoUp to 20 sites the agent stays within, e.g. ['example.com']. Omitted, it stays on the sites of urls (or reads any site when there are none); [] lets it read any site.

Output Schema

NameRequiredDescriptionDefault
idNoThe run's id: for get_job and cancel_job with kind 'agent'.
jobNoWhile it works: {kind: 'agent', 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.
dataNoThe answer: JSON matching the schema, or {text} without one; {partial} at credit_limit. When the answer is too long for 60,000 characters, a string of its JSON text, cut, and the note says where the whole answer is.
noteNoWhat to do next, and what was cut and where to get it whole.
errorNoWhen the call failed, or the run ended in error: what went wrong, in words an assistant can act on.
stepsNoThe steps the agent has taken.
budgetNoThe most the run may spend: max_credits, or less when the workspace had less left (budgetLimited).
detailNoOnly on a failure: the API's own wording, when the error was rephrased.
promptNoThe question as it was asked.
statusNoqueued/running with a `job` while it works; done, credit_limit (stopped at its budget, data.partial holds what it found, continue_agent carries it on), cancelled or error once finished; 'expired' past its keep date. On an error, the HTTP status code.
sourcesNoThe pages the answer rests on, each {url, title, pageId}; the first 50 when the answer had to be cut.
stopReasonNoWhy it stopped early, e.g. credit_limit, step_limit or cancelled; empty when it finished on its own.
creditsUsedNoCredits spent so far: pages read plus the model's tokens.
fieldSourcesNoWhere each value of data came from: its path (e.g. 'plans[0].price', or '[2].name' for a list answer) to {url, pageId}, a page the run read. The first thing left out when the answer is too long for 60,000 characters, and the note says so.
budgetLimitedNotrue when the budget was lowered to what the workspace had left when the run started.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / max_credits / description
      Previous value: -"The most the run may spend, 1 to 100,000 credits; omit for 2,000."New value: +"The most the run may spend, 1 to 100,000 credits; omit for 500."
  2. Added

TDQS

A4.8/5.0
Behavior5/5

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

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false) by disclosing the credit pricing model, that refused pages are free, the default 500-credit cap and how a capped run terminates, the async job return, the ten-minute deduplication window, and the write-access prerequisite with error code 'read_only'. These are exactly the operational facts an agent needs and none are in the structured fields.

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 purpose and the alternative, then cleanly sectioned into Inputs, Cost and Timing labels. It is dense but nearly every sentence carries decision-relevant information; the cost comparison to scrape_urls (40-130 vs 1-4 credits) is a slight elaboration beyond what routing needs.

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 high-complexity, expensive, open-world async tool, the description covers cost, timing, polling, deduplication, cancellation, authorization and answer shaping; return values are covered by the output schema. Nothing an agent needs before calling it 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 100%, so the schema already documents defaults and ranges for all six parameters. The description still adds value with a concrete prompt example, the rationale that a page could redirect the agent off-site when urls are given without allowed_domains, and the explicit effect of allowed_domains=[]. It stops short of covering max_steps, which the schema handles alone.

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 and resource with scope: an agent that searches the web, maps sites and reads pages, then answers with sources. It explicitly contrasts with search_web and scrape_urls, so an agent can distinguish it from siblings without opening a 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 both sides of the routing decision: use for questions needing several pages or sites, and use search_web/scrape_urls when you know what to fetch because they are quicker and cheaper. It also states the follow-up protocol (poll get_job every 30-60s, cancel_job to stop, continue_agent after a credit cap).

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.