Skip to main content
Glama

Write a research report

start_research
Destructive

Fits when the user wants a written report that answers a question from the live web, with the page behind each cited sentence, and has approved its price. Not for one fact or a quick answer, which the fast web search gives, or for a table of results. Starts a run that splits the question into parts, searches the live web, reads pages and writes a markdown report with numbered citations, or JSON that matches a given JSON Schema. A quick report takes about a minute, a deep one up to about fifteen. Returns the run's id, its status and its price at once. The report is charged once, at delivery, at its depth's price ($0.10 quick, $0.30 standard, $1.00 deep) from the account's balance; a failed or cancelled run is not charged. A depth priced above confirm_max_cents is refused, and the same idempotency_key returns the same run.

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": {
      "question": "<question>",
      "confirm_max_cents": "<confirm_max_cents>",
      "idempotency_key": "<idempotency_key>"
    },
    "name": "start_research"
  }
}

Input Schema

NameRequiredDescriptionDefault
depthNoquick, standard or deep: how far the run searches and reads, and its price.standard
lengthNoshort, standard or long: the target length of the text, not of the research.standard
languageNoThe report's language. Without it, the language of the question.
questionYesThe question in plain words, in any language.
output_schemaNoA JSON Schema for the answer. Without it, the report is markdown text.
exclude_domainsNoSites the run never reads.
idempotency_keyYesA key that stays the same if this call is retried, so the run starts once.
include_domainsNoSites the run reads from, and no others.
confirm_max_centsYesThe most the user approved for this report, in cents. A depth priced above it is refused and nothing runs.

Output Schema

NameRequiredDescriptionDefault
idNo
depthNo
linksNo
statusNo
price_usdNo
created_atNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "properties": {
      +    "created_at": {
      +      "type": "string"
      +    },
      +    "depth": {
      +      "type": "string"
      +    },
      +    "id": {
      +      "type": "string"
      +    },
      +    "links": {
      +      "type": "object"
      +    },
      +    "price_usd": {
      +      "type": "number"
      +    },
      +    "status": {
      +      "type": "string"
      +    }
      +  },
      +  "type": "object"
      +}
  2. Added

TDQS

A4.7/5.0
Behavior5/5

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

Beyond the annotations, the description discloses latency (about a minute for quick, up to about fifteen for deep), the immediate return shape (run id, status, price), the billing model (charged once at delivery, $0.10/$0.30/$1.00 by depth, no charge on failure or cancellation), the refusal rule above confirm_max_cents, and conditional idempotency via the key. These are precisely the behavioral facts an agent needs before spending a user's balance, and none are derivable from the annotations alone.

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?

Every sentence carries a distinct fact — fit, exclusions, mechanics, latency, return shape, billing — and the fit criterion is front-loaded. The single dense paragraph packs price, idempotency and refusal rules together at the end, which is slightly harder to scan than the rest, but there is no redundant 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 nine-parameter, mutating, spend-incurring tool with an output schema, the description covers cost, timing, gating and return values thoroughly. The one thing left implicit is the follow-up path after a run starts (polling with get_research or stopping with cancel_research), which the agent would need for a fifteen-minute deep run.

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 adds meaning the schema does not: depth maps to concrete prices and to the confirm_max_cents refusal rule, output_schema is framed by what happens without it (markdown vs JSON), and idempotency_key is explained as the retry-safety mechanism. Remaining parameters (language, include/exclude domains, length) are left to their schema text.

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 description uses a specific verb and resource ('starts a run' that 'splits the question into parts, searches the live web, reads pages and writes a markdown report') and explicitly separates this tool from the fast web search and from table-producing tools. An agent can identify what the tool produces (a cited markdown report or schema-shaped JSON) without opening the 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?

It states the exact triggering conditions ('user wants a written report ... and has approved its price') and the exclusions ('not for one fact or a quick answer ... or for a table of results'), each paired with the alternative that fits. Prerequisites such as price approval and the confirm_max_cents gate are named rather than implied.

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.