> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superglue.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# Debugging a Tool
> Use the tool playground to debug your tool
The tool playground is a developer-friendly interface for testing, debugging, and refining your tools. It provides granular control over execution and visibility into every step of your workflow.
## Tool Playground Agent
The tool playground includes an AI agent that helps you debug and modify tools through natural language. Access it via the chat interface in the playground.
## Tool Input
The playground starts with a **Tool Input** card where you define the data your tool will process. We refer to this as the tool payload.
### Manual JSON Input
Enter JSON directly in the payload editor. The playground validates your input against the input schema (if defined) and highlights any validation errors.
```json theme={null}
{
"userId": "12345",
"startDate": "2024-01-01"
}
```
If your tool has an input schema, the playground automatically generates a default payload as a starting point. You can edit this to match your test case.
### File Upload
Upload files to use as input data. The playground:
* Parses files automatically and adds them to your payload
* Shows file status (processing, ready, or error)
* Displays total file size
* Allows you to remove files
When you upload a file named `customers.csv`, it becomes available in your payload and subsequent steps as the `customers` variable.
### Schema Validation
The input card shows an amber-colored warning if your current payload doesn't match the input schema. Click "Run Anyway" to proceed despite validation errors, or fix your payload to match the schema requirements.
## Run All Steps
Click **Run All Steps** to execute your entire tool from start to finish. The playground:
* Executes steps sequentially
* Shows progress with a loading indicator on each step
* Marks completed steps with a green checkmark
* Marks failed steps with a red X
* Pauses before the next **critical** step and waits for your confirmation before continuing (for example, a step that writes data or makes changes in a third-party system)
* Navigates to the first failure or final output when done
Click **Stop Execution** to halt the run after the current step completes.
## Inspect a Step
### Step Input
The **Step Input** section shows exactly what data flows into the step and how it is shaped:
* **currentItem**: This is the evaluated result of the data selector showing as a template chip. See [Using Template Expressions](/guides/using-template-expressions) for more.
* **Aggregated Step Data**: All previous step results, payload objects and other input data.
Some data selectors may reference results from previous steps and may not be evaluated yet. Run all previous steps to inspect the evaluated data selector expression.
### Step Config
The **Step Config** tab shows how this step calls the external system:
* **Step Instruction** – natural‑language description of what the step does and what the response should contain
* **System** – which system is used to make the call
* **Safety badge** – a `Step modifies data on system` pill when the step performs write operations, so you can quickly spot calls that change external state
* **API Config** – HTTP method and URL for the request
* **Headers (JSON)** – JSON object with the request headers sent to the server (for example, the `Authorization` header)
* **Query Parameters** – JSON object with the query parameters appended to the request URL
* **Body** – Request body content, which can be JSON, form data, plain text, or any format
* **Pagination** – controls how the step fetches multiple pages (strategy, page size, cursor/offset paths) or shows *No pagination* when pagination is disabled
* **Stop Condition (JavaScript)** – optional JavaScript function that inspects each `response` and pagination state to decide when to stop fetching more pages
### Template Chips
Dynamic values in the config appear as **template chips** – small badges showing a preview of the evaluated expression. Click a chip to open its **the templating popover**, where you can edit the JavaScript expression and see a live preview of your code expression. Note that previews are only available if the previous step has completed successfully.
To insert a new template, type `@` anywhere in a text field to open the **variable picker**. Browse available variables by category (previous step results, credentials, loop context) and drill into nested properties. Selecting a variable inserts a chip with the correct accessor path.
### Step Result
After execution, the **Output** section shows:
* Successful API responses
* Error messages (with full stack traces for debugging)
* Data structure returned by the step
Click on nested objects to expand and inspect their contents. Use this to verify your step is receiving and returning the expected data structure.
### Run Step
Executes just this one step using the current configuration and previous step results. Use this to:
* Test changes to a single step without re-running the entire tool
* Debug a specific failure in isolation
* Verify your instruction changes work
If the **Step Data Selector** returns an array, the step turns into a loop step, running once for each item in the data selector output array. In this case, you can choose to run a single iteration using the dropdown on the **Run Step** button.
## Final Transform
The **Final Transform** card contains JavaScript code that shapes your raw step outputs into the final result structure.
### Edit Transform Code
The transform receives `sourceData` containing all step results:
```javascript theme={null}
(sourceData) => {
return {
users: sourceData.step_1.map((user) => ({
id: user.id,
name: user.full_name,
email: user.email_address,
})),
total: sourceData.step_1.length,
};
};
```
### Test Transform
Click **Run Transform Code** to execute your transform code against the current step results. This shows:
* The final output structure
* Any JavaScript errors in your transform
* Whether the output matches your response schema (if defined)
The transform runs in a sandboxed environment with access to common utilities. If it fails, the error message shows the exact line and issue.
### Response Schema
Define a JSON schema to validate your final output structure. The playground highlights schema violations and prevents invalid outputs from being returned.
### Manual JSON Input
Enter JSON directly in the payload editor. The playground validates your input against the input schema (if defined) and highlights any validation errors.
```json theme={null}
{
"userId": "12345",
"startDate": "2024-01-01"
}
```
If your tool has an input schema, the playground automatically generates a default payload as a starting point. You can edit this to match your test case.
### File Upload
Upload files to use as input data. The playground:
* Parses files automatically and adds them to your payload
* Shows file status (processing, ready, or error)
* Displays total file size
* Allows you to remove files
When you upload a file named `customers.csv`, it becomes available in your payload and subsequent steps as the `customers` variable.
### Schema Validation
The input card shows an amber-colored warning if your current payload doesn't match the input schema. Click "Run Anyway" to proceed despite validation errors, or fix your payload to match the schema requirements.
## Run All Steps
Click **Run All Steps** to execute your entire tool from start to finish. The playground:
* Executes steps sequentially
* Shows progress with a loading indicator on each step
* Marks completed steps with a green checkmark
* Marks failed steps with a red X
* Pauses before the next **critical** step and waits for your confirmation before continuing (for example, a step that writes data or makes changes in a third-party system)
* Navigates to the first failure or final output when done
Click **Stop Execution** to halt the run after the current step completes.
## Inspect a Step
### Step Input
The **Step Input** section shows exactly what data flows into the step and how it is shaped:
* **currentItem**: This is the evaluated result of the data selector showing as a template chip. See [Using Template Expressions](/guides/using-template-expressions) for more.
* **Aggregated Step Data**: All previous step results, payload objects and other input data.
The **Step Config** tab shows how this step calls the external system:
* **Step Instruction** – natural‑language description of what the step does and what the response should contain
* **System** – which system is used to make the call
* **Safety badge** – a `Step modifies data on system` pill when the step performs write operations, so you can quickly spot calls that change external state
* **API Config** – HTTP method and URL for the request
* **Headers (JSON)** – JSON object with the request headers sent to the server (for example, the `Authorization` header)
* **Query Parameters** – JSON object with the query parameters appended to the request URL
* **Body** – Request body content, which can be JSON, form data, plain text, or any format
* **Pagination** – controls how the step fetches multiple pages (strategy, page size, cursor/offset paths) or shows *No pagination* when pagination is disabled
* **Stop Condition (JavaScript)** – optional JavaScript function that inspects each `response` and pagination state to decide when to stop fetching more pages
### Template Chips
Dynamic values in the config appear as **template chips** – small badges showing a preview of the evaluated expression. Click a chip to open its **the templating popover**, where you can edit the JavaScript expression and see a live preview of your code expression. Note that previews are only available if the previous step has completed successfully.
To insert a new template, type `@` anywhere in a text field to open the **variable picker**. Browse available variables by category (previous step results, credentials, loop context) and drill into nested properties. Selecting a variable inserts a chip with the correct accessor path.
### Step Result
After execution, the **Output** section shows:
* Successful API responses
* Error messages (with full stack traces for debugging)
* Data structure returned by the step
Click on nested objects to expand and inspect their contents. Use this to verify your step is receiving and returning the expected data structure.
### Run Step
Executes just this one step using the current configuration and previous step results. Use this to:
* Test changes to a single step without re-running the entire tool
* Debug a specific failure in isolation
* Verify your instruction changes work
If the **Step Data Selector** returns an array, the step turns into a loop step, running once for each item in the data selector output array. In this case, you can choose to run a single iteration using the dropdown on the **Run Step** button.
## Final Transform
The **Final Transform** card contains JavaScript code that shapes your raw step outputs into the final result structure.
### Edit Transform Code
The transform receives `sourceData` containing all step results:
```javascript theme={null}
(sourceData) => {
return {
users: sourceData.step_1.map((user) => ({
id: user.id,
name: user.full_name,
email: user.email_address,
})),
total: sourceData.step_1.length,
};
};
```
### Test Transform
Click **Run Transform Code** to execute your transform code against the current step results. This shows:
* The final output structure
* Any JavaScript errors in your transform
* Whether the output matches your response schema (if defined)
The transform runs in a sandboxed environment with access to common utilities. If it fails, the error message shows the exact line and issue.
### Response Schema
Define a JSON schema to validate your final output structure. The playground highlights schema violations and prevents invalid outputs from being returned.