Skip to main content
Glama

Create OpenCode session

opencode_session_create

Creates a new OpenCode session in a specified directory, defaulting to the client's workspace. Set an agent, model, title, or permissions, and pass a parent session ID to spawn a child subagent session.

Instructions

Create a new OpenCode session in a directory. Defaults to the client's current workspace. Use agent='build' for implementation work, 'plan' for planning, and 'general'/'explore' for subagents. Pass parentSessionID to create a child (subagent) session.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "opencode_session_create"
  }
}

Input Schema

NameRequiredDescriptionDefault
agentNoAgent id, e.g. build, plan, general, explore
modelNoExplicit model, e.g. { providerID: 'opencode', id: 'iceman-free' }
titleNo
directoryNoAbsolute working directory for the session
permissionsNoPer-session permission ruleset
parentSessionIDNoMakes this a subagent session

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.7/5.0
Behavior3/5

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

Annotations only declare readOnlyHint=false, so the description must carry the rest. It adds useful behavior beyond the annotations: the directory defaults to the client's current workspace, and parentSessionID turns the call into a subagent session. It does not disclose what is returned, whether session creation has side effects like spawning a process, or how title/permissions interact with defaults.

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?

Three tight sentences with the core action front-loaded, followed by argument guidance and the child-session note. Each sentence carries information; there is no filler or repetition of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a six-parameter creation tool with nested objects and no output schema, the description covers agent, directory, and parentSessionID but is silent on model and permissions, and never tells the agent what comes back (e.g. a session ID needed for opencode_session_prompt). Adequate but with clear gaps.

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 83%, so the baseline is 3, and the description earns an increment by attaching real meaning to agent values and to parentSessionID ('makes this a subagent session' is clarified semantically). The nested model and permissions parameters still receive no explanation in the description.

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?

The description opens with a specific verb and resource ('Create a new OpenCode session in a directory'), which clearly separates it from sibling read/management tools like session_list or session_delete. It stops short of explicitly naming a sibling it must not be confused with, so it lands just under the top mark.

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?

It gives actionable guidance on argument choice: 'build' for implementation work, 'plan' for planning, 'general'/'explore' for subagents, and parentSessionID to create a child session. What is missing is tool-selection guidance, such as when to create a fresh session versus reusing an existing one via opencode_session_get or list.

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