lmstudio

LM Studio: start a background task

task_start

Run a prompt on a local model in the background and get a task_id immediately. Include files, images, or a session_id, then check progress with task_status.

Instructions

Run a prompt, with optional text files and images, on a local model in the background and return a task_id at once. Pass session_id to continue a session, or model (plus optional session settings) to start a new session for the task. Follow it with task_status; stop it with task_cancel.

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": "task_start"
  }
}

Input Schema

Name	Required	Description
`files`	No	Absolute paths to text files (code, logs, documents) to add to the message, up to 2 MB each. Use this instead of pasting file contents.
`model`	No	Model for a new session, when session_id is not given.
`title`	No	Name for the new session. Default: the start of the prompt.
`images`	No	Absolute paths to PNG, JPEG, WebP or GIF files, for vision models.
`prompt`	Yes	What the local model should do.
`reload`	No	If the model is loaded with a smaller context than needed, unload it and load it again.
`reasoning`	No	Reasoning effort, for models that support it.
`session_id`	No	Run the task inside this session.
`temperature`	No	0 is deterministic.
`integrations`	No	LM Studio plugins or MCP servers the local model may use, as configured in LM Studio, e.g. "mcp/github".
`system_prompt`	No	System instructions.
`context_length`	No	Context the new session needs. Default: the model's saved default. Leave it out unless the user asks for a specific context: a saved default is the user's choice for this model.
`max_output_tokens`	No	Upper limit for generated tokens per answer.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.3.2Nov 13, 2026

changedInput schema / properties / context_length / description

Previous value: -"Context the new session needs. Default: the model's saved default."New value: +"Context the new session needs. Default: the model's saved default. Leave it out unless the user asks for a specific context: a saved default is the user's choice for this model."

addedInput schema / properties / files

Added value: +{
+  "description": "Absolute paths to text files (code, logs, documents) to add to the message, up to 2 MB each. Use this instead of pasting file contents.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

First observedv0.1.0Nov 11, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered; the description adds the important non-obvious behavior that this is non-blocking and returns a task_id at once, which drives the whole calling pattern. It does not say what happens when neither session_id nor model is supplied (which model gets used).

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?

Three sentences, front-loaded with the async behavior and return value, then the session-mode branching, then lifecycle tools. No sentence is filler and nothing is buried after low-value detail.

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 13-parameter tool with no output schema, the description covers the essentials: what it returns (task_id), how to continue work (task_status) and how to stop it (task_cancel). The one gap is the default-model fallback when neither session_id nor model is provided, which an agent may need before calling.

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 already 100%, so the baseline is 3, and the description earns a bump by synthesizing the otherwise scattered session_id/model/title/context_length parameters into a single branching rule: continue an existing session versus start a new one with model plus optional session settings. It adds no meaning for the remaining parameters, which the schema already documents well.

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 ('Run a prompt ... on a local model') plus the key distinguishing trait: it executes in the background and returns a task_id immediately rather than blocking. That async contract distinguishes it from the synchronous 'chat' sibling without needing to name it.

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 explicit routing for the two session modes ('Pass session_id to continue a session, or model ... to start a new session') and names the follow-up and stop tools ('Follow it with task_status; stop it with task_cancel'). It stops short of saying when not to use this tool, e.g. that interactive/blocking use should go to chat.

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