Skip to main content
Glama
Orchestra MCP Server

Orchestra MCP Server

Official
by orchestra-hq

List agent sessions

list_agent_sessions
Read-only

List agent sessions visible to the caller in a workspace, most recently updated first, with filters for status, agent, incident, mode, and search text.

Instructions

List the agent sessions in the workspace the credential resolves to that the caller can see, most recently updated first. A session started by a user in the Orchestra UI is visible to that user alone, so an API key never sees one. Sessions started for a task run or an incident are visible to everyone in the workspace who can view the agent.

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

Input Schema

NameRequiredDescriptionDefault
qNoOnly return sessions whose name, or whose agent's name, contains this text. Case-insensitive.
pageNoPage number. Must be greater than or equal to 1.
statusNoOnly return sessions in these statuses. Repeat the parameter to match any of several, e.g. `?status=BUSY&status=IDLE`. One of `BUSY`, `EXPIRED`, `FAILED`, `IDLE`, `INITIALISING`, `PENDING`, `STARTUP_ERROR`.
archivedNoReturn only archived sessions instead of only unarchived ones. Defaults to false.
agent_idsNoOnly return sessions of these agents. Repeat the parameter to match any of several, e.g. `?agent_ids=<id>&agent_ids=<id>`.
page_sizeNoNumber of items per page. Defaults to 50; maximum 100.
incident_idNoOnly return sessions about this incident.
session_modeNoOnly return sessions started in these modes. Repeat the parameter to match any of several. One of `USER`, `TASK_RUN`, `INCIDENT`.
X-Orchestra-Account-IdNoAct on this account rather than the one the credential resolves to. Omit it to use the credential's own account. An API key is issued to a single account, so it may only name that account; an OAuth token may name any account its grant covers.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv2026.10.29-0
    • addedInput schema / properties / incident_id
      Added value: +{
      +  "anyOf": [
      +    {
      +      "format": "uuid4",
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "Only return sessions about this incident."
      +}
  2. Addedv2026.10.12-0

TDQS

A3.9/5.0
Behavior4/5

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

readOnlyHint=true already declares safety, and the description goes further by disclosing the visibility model: user-started sessions are private to that user, API keys never see them, and task-run/incident sessions are workspace-wide. It also discloses result ordering. Pagination mechanics are left to the schema.

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 tight sentences: scope and ordering first, then the two visibility cases. No filler, no repetition of schema 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?

With an output schema present and full parameter documentation, the description only needs to carry the authorization/visibility model, which it does clearly. Return shape and pagination are appropriately left to structured fields.

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 real meaning by tying the USER / TASK_RUN / INCIDENT modes to their differing visibility rules, which helps an agent reason about what session_mode filtering will actually return.

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?

States a specific verb and resource ("List the agent sessions") plus the scope of the workspace the credential resolves to and the ordering (most recently updated first). An agent can tell it is a listing tool, though it never names a sibling to contrast with get_agent_session or list_agents.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by "list" rather than stated: there is no explicit "use this when… / use get_agent_session instead when…" guidance. The visibility note helps the agent predict results but does not route between this and other session-related siblings.

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

Deploy Server

Other Tools