Skip to main content
Glama

Sap Session Reset To Primary

sap_session_reset_to_primary

Close every SAP session except the primary s1 to remove orphaned windows and restore a clean state. It reconciles stale registry entries first, then terminates the remaining sessions.

Instructions

Bulk-close every SAP session except the primary one (s1). Use this when parallel agents have left orphaned/extra windows and you want to return to a known-clean state with only s1 open. Reconciles the registry first (drops any sessions that died externally), then closes the rest. WARNING: if you call this from a non-primary session, your own session will be closed and you will appear in killed_agents — your next tool call will fail until you rebind to s1 (or another surviving session) via sap_session_bind. See issue #637 for the parallel-agent drift scenario this addresses.

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_reset_to_primary"
  }
}

Input Schema

NameRequiredDescriptionDefault

No arguments

Output Schema

NameRequiredDescriptionDefault
errorNoError message if success=False
popupNoPresent when a popup dialog is active on screen
errorsNoPer-session error strings, one per failed close attempt
successNoWhether the operation succeeded
active_windowNoWhich window was operated on (e.g., 'wnd[0]', 'wnd[1]'). If 'wnd[1]' or higher, a modal dialog is open.
killed_agentsNoAgent IDs whose bound sessions were closed by this reset. These agents must call sap_session_bind on a different session before continuing.
closed_sessionsNoSession IDs that were closed (e.g. ['s2', 's3', 's4'])
skipped_attachedNoAttached (user-owned) session IDs that were deliberately left open. Drop them from the registry with sap_session_detach if no longer needed.
remaining_sessionsNoSession IDs still active after the reset (typically just ['s1'])

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.9/5.0
Behavior5/5

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

With no annotations supplied, the description carries the full burden and does so well: it explains registry reconciliation before closure, discloses the severe self-kill side effect, mentions the killed_agents result, and warns that subsequent calls fail until rebinding. This is exactly the behavioral context an agent needs before invoking a destructive bulk operation.

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?

The description is front-loaded with purpose and scope, followed by a clear usage condition and an explicit warning. Every sentence contributes operational value; even the issue reference supports the rationale for the tool's existence without derailing the core instruction.

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?

For a destructive, parameterless reset tool with an output schema, the description supplies the missing behavioral context: scope, ordering of registry reconciliation versus closure, self-session risk, and recovery via sap_session_bind. The output schema can carry return-value details, so no further description is required.

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 there is no parameter semantics to explain. The description correctly avoids inventing parameter-level details, and the baseline for a parameterless tool is appropriate here.

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?

The description states a specific verb and resource ('Bulk-close every SAP session except the primary one (s1)') and makes the scope unmistakable by naming the protected session. An agent can distinguish this reset operation from single-session tools such as sap_session_close without further inspection.

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

Usage Guidelines5/5

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

It explicitly names the triggering condition — parallel agents leaving orphaned or extra windows — and describes the desired end state ('known-clean state with only s1 open'). It also names sap_session_bind as the remediation path when rebinding is needed, which is actionable guidance rather than vague context.

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