Skip to main content
Glama

Sap Session List

sap_session_list

List active SAP sessions with IDs, transaction, screen title, client, user, and system so you can choose the correct session before targeting it.

Instructions

List all active SAP sessions.

Returns session IDs, current transaction, screen title, client, user, and system_name for each. Use this to see what sessions exist before targeting one.

The first sap_login() registers "s1". Additional sessions come from:

  • repeated sap_login() calls (parallel multi-mandant — each new login adds a session alongside the existing ones, not replacing them — see #671)

  • sap_transaction(tcode, new_window=True) (a /o sub-session of an existing connection, sharing its login)

Desktop: when another call has been running on the connection's single COM engine for a while, the result carries a com_engine block saying which connection is busy and since when. That running call is why other tool calls on the same connection hang — wait for it instead of retrying.

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

Input Schema

NameRequiredDescriptionDefault

No arguments

Output Schema

NameRequiredDescriptionDefault
errorNoError message if success=False
popupNoPresent when a popup dialog is active on screen
successNoWhether the operation succeeded
sessionsNoAll active SAP sessions with their current state
com_engineNoDesktop only: state of the connection's single COM scripting engine (issue #905). Present when the engine has been running a call for a while — that call blocks every other tool call on the same connection until it finishes.
active_windowNoWhich window was operated on (e.g., 'wnd[0]', 'wnd[1]'). If 'wnd[1]' or higher, a modal dialog is open.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.9/5.0
Behavior3/5

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

No annotations are provided, so the description must carry the behavior burden, and it does disclose genuinely useful traits: the s1 identifier convention, that parallel logins add rather than replace sessions, that /o sub-sessions share a login, and the desktop `com_engine` busy block explaining why calls hang. However, it never states that the operation is read-only/non-destructive or describes failure modes such as no sessions found, leaving a real gap for an unannotated tool.

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?

Front-loaded with purpose and return shape, then structured bullets for session lifecycle and a separate paragraph for the desktop busy-engine note. The lifecycle bullets arguably describe sibling tools (sap_login, sap_transaction) more than this one, which is some scope creep, but every sentence aids interpretation of the returned IDs.

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

Completeness5/5

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

An output schema exists, so the description need not document return values, and it still covers the identifier model, multi-session scenarios, and the desktop concurrency caveat. For a zero-parameter list tool this is complete.

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?

The tool takes zero parameters, so the baseline is 4; there is no argument semantics to explain and the description correctly does not invent any.

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?

Specific verb+resource ("List all active SAP sessions") plus an enumeration of the returned fields, so an agent knows exactly what it gets. It does not explicitly contrast with close siblings such as sap_session_status or sap_list_connections, which keeps it from a 5.

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?

"Use this to see what sessions exist before targeting one" gives a clear trigger for calling it, and the session-creation notes explain when more than one session will appear. There are no explicit when-not-to-call conditions or named alternatives, so it stops short of a 5.

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