Skip to main content
Glama

Capture one ABAP run in the debugger

abap_debug

Debug ABAP code on a connected SAP system by setting breakpoints, running code, and capturing call stacks and variables in one call or an interactive session.

Instructions

RULE on an on-premise or private cloud system: trigger "none" needs a human action: relay the steps of the answer (userMessage) to the user and end your turn before calling wait. Pass runFrom "http" for a Fiori app (no SM51 steps). Debug ABAP code on the connected SAP system in ONE call: arm breakpoints (lines or class methods in CLAS, PROG or FUNC objects, optionally with an ABAP condition; or where a message is issued, a statement kind runs, an exception is raised; watchpoints, set at the first stop, then stop wherever a variable changes), run the code (its harmless ABAP Unit tests, an OData GET, or wait while you run it yourself as the same SAP user), and at every stop of that one run record the position, the call stack, the variables and optional steps — then release the program and remove the breakpoints. The program runs once, however many stops you ask for: a breakpoint in a loop with hits 5 shows five iterations of the same run. Nothing stays stopped after the call returns, so name every variable you need up front; to look again, run another capture — or start an interactive session (interactive: true) and decide each move with abap_debug_session. Lines are numbered as abap_source shows the ACTIVE source. Per capture: at most 20 breakpoints and 50 stops, and as many steps as the budgets allow — the run is followed until its result size (maxResultKB, default 40 KB) or inspection time (maxSeconds, default 120 s) runs out, then goes on without stopping. Past 20 steps from one stop, the steps come back as a compact trace; until ends them at a line or once a variable changed. Result: hit; breakpoints (set, with the hits they made, or refused with SAP's reason); debuggee; stops (at, stoppedAt, stack and variables on a breakpoint's first stop — its later stops carry only values, unchanged structures and tables marked so; steps, or a trace of a long run: path = the lines executed per frame, (9-12)×300 = a loop, changes = values where they changed); release; trigger; warnings. Without a stop: reason and hint. A call answers within ABAP_DEBUGGER_CALL_SECONDS (default 50 s). A capture still waiting for its stop or following its run then answers running: true with its session id, and goes on: abap_debug_session action wait picks up its result, action end stops it. trigger "none": on the BTP ABAP Environment or S/4HANA Cloud Public Edition, which have no SAP GUI, never ask about it or mention SM51. On an on-premise or private cloud system, from SAP GUI, only a NEW session opened through SM51 (select the application server, Goto → Remote Logon → Normal) once the breakpoints are armed stops at them — on some systems, a session opened before, or from SAP Logon or SAP Business Client, never does. When the user says they run it from a Fiori app or another HTTP call, pass runFrom "http": no SM51 steps. Otherwise, right after arming, the client shows the user these steps in a dialog where it can (MCP elicitation: accept goes on waiting, decline stops the capture); else the call answers at once with running: true, userMessage (the steps, for the user) and agentInstructions (for you): show userMessage to the user in their language, keeping its numbered steps, END YOUR TURN, and call abap_debug_session action "wait" once they ran the code. runFrom "http" answers at once the same way, telling the user to open the app. It never changes variables or the program flow, never debugs system code, and only debugs the session's own SAP user; it refuses when Eclipse or VS Code already debugs that user.

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

Input Schema

NameRequiredDescriptionDefault
urlNotrigger=http: a host-relative OData path on the connected system, e.g. /sap/opu/odata4/sap/zui_travel/srvd/sap/ztravel/0001/Travel?$top=1. GET only: saves and actions need a unit test or trigger=none.
lineNoShorthand for one breakpoint at this 1-based line of type + name.
nameNoObject name of `line`, and the default of every breakpoint and of the unit-test trigger.
typeNoObject type of `line`, and the default of every breakpoint: CLAS, PROG or FUNC.
stepsNoSteps after each stop (default 0; with until and no steps: step until it holds). Up to 20 come back one entry each (position and variables); more come back as a compact trace — the lines executed, loops folded as (9-12)×300, the variables only where they changed. Only maxSeconds and maxResultKB bound how far it goes.
untilNoEnd the steps early: once the run stands on a line of the source the steps started in, and/or once a variable changed.
watchNoWatchpoints (max 5), set in the run at its first stop, after that stop's steps: the run then also stops wherever a variable changes — where does LV_STATUS change, or become 'E' with a condition? Each stop says from and to. The variable must be visible at that first stop (a local of its method, an attribute ME->…, a global); SAP refuses it otherwise.
runFromNotrigger=none: where the user runs the code, when their request says so. http: a Fiori app, a browser, Postman or any HTTP call — no SM51 steps; the call answers once the breakpoints are armed so the user opens the app. sapgui: a report, a transaction, a screen — the SM51 steps. Leave it out when unsure: the steps cover both.
triggerNoWhat runs the code. unittest (default): the harmless ABAP Unit tests of triggerName, else of type + name, else of the first breakpoint object (FUNC: its function group). http: a GET of url. none: the capture only waits timeoutSeconds while you run the code yourself (Fiori app, a report, Postman) as the SAME SAP user — the tool description says what to tell the user first.
stepModeNoover (default): stay in the method; into: follow calls into the called method; out: return to the caller.
variablesNoRead at every stop and after every step: LV_TOTAL, LS_HEAD-VBELN, LT_ITEMS, LT_ITEMS[3], ME->MV_STATE, SY-SUBRC (max 20). Structures expand one level, tables show their first 5 rows. Default: every variable of the stopped frame (up to 60). The run is released when the call returns, so ask for everything up front.
maxSecondsNoTime budget of the inspection once the run stopped (default 120): long step runs need more — each step costs two or three requests to SAP. The server's ceiling applies (ABAP_DEBUGGER_MAX_SECONDS, default 600). The program waits in a work process meanwhile.
breakpointsNoThe stops of the run (max 20): each a line, a CLAS method, a message, a statement kind or an exception class. One run can stop in several objects.
interactiveNotrue: an interactive session — return at the first stop and keep the program waiting there, then drive it call by call with abap_debug_session (step, continue, inspect, end), deciding each move from what you see. steps, if given, run before this call returns. The program holds a work process until the session ends; it is released after a while without a call. Default false: the whole capture in this one call.
maxResultKBNoSize budget of the result in KB of JSON (default 40, about 10k tokens); the server's ceiling applies (ABAP_DEBUGGER_MAX_RESULT_KB, default 200).
triggerNameNotrigger=unittest: the class, program or function group whose unit tests run the code, when it is not the breakpoint object.
exceptionClassNoAlso (or only) stop where this exception class is raised, e.g. CX_SY_ZERODIVIDE.
timeoutSecondsNoHow long to wait for the first stop (1-900; default 60, 300 with trigger=none: the user reads the steps and opens their session first). The capture stops listening then.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.0.3
    • addedInput schema / properties / runFrom
      Added value: +{
      +  "description": "trigger=none: where the user runs the code, when their request says so. http: a Fiori app, a browser, Postman or any HTTP call — no SM51 steps; the call answers once the breakpoints are armed so the user opens the app. sapgui: a report, a transaction, a screen — the SM51 steps. Leave it out when unsure: the steps cover both.",
      +  "enum": [
      +    "sapgui",
      +    "http"
      +  ],
      +  "type": "string"
      +}
    • changedInput schema / properties / timeoutSeconds / description
      Previous value: -"How long to wait for the first stop (1-900, default 60)."New value: +"How long to wait for the first stop (1-900; default 60, 300 with trigger=none: the user reads the steps and opens their session first). The capture stops listening then."
    • changedInput schema / properties / trigger / description
      Previous value: -"What runs the code. unittest (default): the harmless ABAP Unit tests of triggerName, else of type + name, else of the first breakpoint object (FUNC: its function group). http: a GET of url. none: the capture only waits timeoutSeconds while you run the code yourself (Fiori app, SE38, Postman) as the SAME SAP user."New value: +"What runs the code. unittest (default): the harmless ABAP Unit tests of triggerName, else of type + name, else of the first breakpoint object (FUNC: its function group). http: a GET of url. none: the capture only waits timeoutSeconds while you run the code yourself (Fiori app, a report, Postman) as the SAME SAP user — the tool description says what to tell the user first."
  2. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

Beyond the annotations, it discloses hard budgets (20 breakpoints, 50 stops, maxResultKB 40 KB default, maxSeconds 120 s default), what happens when the call times out (running: true plus a session id picked up by abap_debug_session), that nothing stays stopped after return, and the SM51/new-session prerequisite for on-premise systems. It also states the non-mutation contract ('never changes variables or the program flow, never debugs system code') and the refusal case when Eclipse or VS Code already debugs the user.

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?

For an 18-parameter tool the length is largely earned, and key constraints (one run, nothing stays stopped, name variables up front) are stated early. However, the opening 'RULE' block about trigger 'none' and runFrom 'http' is duplicated almost verbatim later in the text, and the purpose statement is pushed behind that rule, costing some front-loading.

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?

There is no output schema, but the description fully enumerates the return shape: hit, breakpoints (with SAP's refusal reasons), debuggee, stops with at/stoppedAt/stack/variables and trace format, release, trigger, warnings, plus the reason/hint shape when no stop occurs. Given the tool's complexity, an agent has enough to call it correctly and interpret results.

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 per-parameter baseline is 3; the description still adds cross-parameter meaning the schema cannot express, such as the trigger='none' + runFrom interaction, the steps/until relationship ('with until and no steps: step until it holds'), and the 20-step threshold that switches output to a compact trace. Some prose largely restates schema wording (budget defaults, breakpoint kinds), which keeps it from a 5.

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 names a concrete verb chain and resource: arm breakpoints, run the code, record position/stack/variables, then release the program and remove the breakpoints — all in ONE call. It also explicitly separates itself from abap_debug_session (interactive sessions) and from abap_source (line numbering), so an agent can route between siblings without opening schemas.

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 states when to use the one-shot capture versus the interactive alternative ('interactive: true ... decide each move with abap_debug_session') and when each trigger mode applies (unittest default, http for a Fiori/OData GET, none for a user-run session). It even covers the ambiguous case with 'Leave it out when unsure: the steps cover both.'

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