Superglue MCP

--- title: "Debugging a Tool" description: "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 Input The playground starts with a **Tool Input** card where you define the data your tool will process. <video autoPlay className="w-full rounded-lg"> <source src="/resources/tool-input-demo.mp4" type="video/mp4" /> </video> ### 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 { "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 a red border if your 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 <img src="../resources/step-input.png" alt="Step input" className="w-full rounded-lg mb-4" /> The **Step Input** section shows exactly what data flows into the step and how it is shaped: - **Aggregated Step Input**: A merged JSON containing previous step results, original payload fields, and processed file data - **Step Data Selector (JavaScript)**: a selector function that receives the aggregated input as `sourceData` and returns the slice of data this step should operate on. - **Step Data**: the result of the selector and the exact data passed into the step (also available in config as `sourceData.currentItem`) ### Step Config <img src="../resources/step-config.png" alt="Step output" className="w-full rounded-lg" /> 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 - **Integration** – which integration 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 ### Step Result <img src="../resources/step-output.png" alt="Step output" className="w-full rounded-lg" /> 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 or Fix a Step ### 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 becomes iterational—it runs once for each item in the array. In this case, you can choose to run a single iteration using the dropdown on the **Run Step** button. ### Fix Step Opens a modal where you can refine the **step-specific instruction** and trigger an LLM-powered repair for this step. The modal provides two actions: - **Fix Step & Execute** – uses the LLM to update the step configuration and immediately runs the step with the fixed version - **Fix Step** – uses the LLM to update the step configuration but does not run it yet (you can execute it later with **Run Step**) <video autoPlay className="w-full rounded-lg"> <source src="/resources/fix-step.mp4" type="video/mp4" /> </video> Use this when: - A step is failing and you want the LLM to find and apply a fix - You've made manual changes but they're not working as expected <Note> A fixed step will update the step configuration in the view but will not save it. You need to publish the tool to persist changes. </Note> ## 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 (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. ## Debugging Workflow When a tool fails, follow this workflow: 1. **Check the failed step** - Look at the step marked with a red X 2. **Inspect the error** - Read the error message in the Output section 3. **Review the input** - Verify the step received the expected data 4. **Try Fix Step** - Let auto-repair suggest a configuration change 5. **Edit instruction** - Manually refine the step instruction if needed 6. **Run Step** - Test your changes on just this step 7. **Run All Steps** - Verify the entire tool works end-to-end