Skip to main content
Glama
orchestra-hq

Orchestra MCP Server

Official
by orchestra-hq
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

List agent sessions

list_agent_sessions
Read-only

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.

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.

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.
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. Addedv2026.10.12-0

TDQS

A3.9/5.0
Behavior4/5

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

Goes beyond readOnlyHint by explaining the visibility model: user-started sessions are private to the user, API keys never see them, and task-run/incident sessions are workspace-visible. This is valuable behavioral context. Lacks details on pagination, default limits, or response shape, but those are partly covered by schema and output schema.

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?

Two clear sentences that front-load the core action and scope, then explain visibility. Efficient, no wasted words, though the visibility explanation could be slightly more compact.

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?

The description covers the essential visibility constraints, which are crucial for an agent to correctly interpret results. With a rich schema and output schema handling parameters and return values, the description is nearly complete for a list tool. Minor gaps remain around pagination defaults, but those are schema-documented.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema documents all 8 parameters thoroughly. The description adds no param-specific info like syntax or format details, which is fine given the baseline of 3 when schema does the heavy lifting.

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 ('List the agent sessions'), specifies the scope (the workspace the credential resolves to), and the ordering (most recently updated first). It's clearly distinguishable from siblings like get_agent_session or create_agent_session.

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?

The description doesn't explicitly state when to use this tool vs alternatives like get_agent_session (singular) or list_agents. The visibility rules imply usage context, but there is no direct when/when-not guidance or named alternatives.

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