[Docs index](/docs.md) / [Tool Creation](/docs/tool-creation/overview.md) / Troubleshooting --- # Troubleshooting Common issues and solutions related to tool creation. --- ## The "Create Tool" button is disabled **You have not entered both a name and a description.** Both fields are required. Fill in a descriptive name and a clear description of what the tool does, then try again. --- ## The "Run Test" button is disabled **You have unsaved changes.** Save your code first by clicking **Save**, then the test button becomes active. --- ## My tool fails with a build error **The code could not compile or a dependency could not be resolved.** Check the error message in the test results for details. Common causes: - Syntax errors in your TypeScript code (missing brackets, typos) - An npm package that does not exist or has the wrong name - An import URL that is unreachable Fix the code, save, and run the test again. --- ## My tool fails with "network access denied" or cannot reach the API **The domain is not in the tool's network permissions.** Open the **Permissions** tab in the tool editor, go to **Network Access**, and add the domain your tool is trying to reach (for example, `api.example.com`). If the API uses subdomains, consider using a wildcard like `*.example.com`. --- ## My tool fails with an authentication error from the external API **The API key or token is missing or incorrect.** Check the **Environment Variables** section in the Permissions tab: - Verify the variable name matches what your code expects (for example, `API_KEY` in permissions should match `event.env.API_KEY` in code) - If the variable is linked to a connection, verify the connection is still valid and the credentials have not expired - If the variable is a custom value, re-enter the value to make sure it is correct --- ## My tool times out **The tool took longer than 30 seconds to execute.** Tools have a 30-second execution limit. Common causes: - The external API is slow or unresponsive - The tool is processing too much data in a single call - The tool is waiting for a resource that never responds Consider breaking the work into smaller calls, adding timeouts to your HTTP requests, or paginating large result sets. --- ## My tool returns empty or unexpected results **The API response format may not match what your code expects.** Add logging to your code to inspect the raw response. Check: - Is the API endpoint correct? - Are you reading the right field from the response? - Does the API require specific headers or query parameters you are not sending? Test with a simple case first (a known ID, a small query) to verify the connection works before handling complex inputs. --- ## My published tool is not showing up in tool search **The tool may not have a clear enough description for discovery.** Tool search uses the name and description to find matches. Update the description to be specific about what the tool does, what system it connects to, and what data it returns. Avoid generic descriptions like "Looks up data." --- ## I want to undo a published version **Publish a previous version.** Navigate to the tool's detail page, find the version you want to restore in the **Version History**, click **Duplicate**, then commit and publish the new draft. The tool is now running the restored code. --- ## My environment variable value is not being picked up **Check the variable name for case sensitivity.** Environment variable names are case-sensitive. If your code reads `event.env.API_KEY`, the variable must be named exactly `API_KEY` in the permissions panel, not `api_key` or `Api_Key`. If the variable is linked to a connection, verify the connection is active and the linked field still exists. --- Still need help? Contact your workspace administrator. --- ## Navigation ### In this section: Tool Creation - [Tool Creation](/docs/tool-creation/overview.md) - [Use Cases and Playbooks](/docs/tool-creation/use-cases.md) - [Creating a Tool](/docs/tool-creation/creating-a-tool.md) - [Testing a Tool](/docs/tool-creation/testing-a-tool.md) - [Editing and Versioning](/docs/tool-creation/editing-and-versioning.md) - [Managing Permissions](/docs/tool-creation/managing-permissions.md) - **Troubleshooting** (current) #### Playbooks - [Build Shipment Tracking Tools for Your Logistics Provider](/docs/tool-creation/playbook-logistics-tracking-tools.md) - [Build Tools to Connect Your CRM to AI](/docs/tool-creation/playbook-crm-integration-tools.md) - [Build Tools to Query Your ERP Inventory System](/docs/tool-creation/playbook-erp-inventory-tools.md) - [Build Tools to Query Your Payment Processor](/docs/tool-creation/playbook-payment-processor-tools.md) - [Playbook: Build a Log Anomaly Monitor Across Axiom and Sentry](/docs/tool-creation/playbook-log-anomaly-monitor.md) ### Other sections - [MCP Servers](/docs/mcp-servers/overview.md) - [Agent Filesystem](/docs/agent-filesystem/overview.md) - [Chat Sharing](/docs/chat-sharing/overview.md) - [Scheduled Triggers](/docs/scheduled-triggers/overview.md) - [Agent Skills](/docs/agent-skills/overview.md) - [Sandcastles](/docs/sandcastles/overview.md) - [Subagents](/docs/subagents/overview.md) - [Workspace Permissions](/docs/workspace-permissions/overview.md) [Back to docs index](/docs.md)