Create a custom tool

Learn how to create custom tools with Retool Agents.

Version: Cloud and 3.227 Edge

Retool Agents is currently in public beta on Retool Cloud.

Create a custom tool to provide your agent with reusable, complex logic with strongly-typed parameters. Custom tools are especially useful if you have a specific need not covered by one of the core tools or other types of tools you can create or import. Custom tools use a canvas of pre-built query blocks that you connect together to interact with resources, transform data, and run additional logic.

Custom tools are very similar to the multi-step functions that are available in Retool Workflows.

Features

Key features of custom tools for agents include:

• Strongly-typed parameters.
• A Function Generator chat interface that can automatically create a custom function.
• The flexibility and power of workflows without the cost associated with workflow runs.
• An independent control flow.
• Support for all available block types.

Custom tools run on behalf of the currently authenticated user, which is reflected in the current_user object.

Add a custom tool

The instructions in this section explain how to create a custom tool using an example that gets Retool changelog entries between a start and end date. This example is also used as part of the Retool Agents tutorial.

1. Create a new agent or navigate to an existing agent. Open the Configuration tab.
2. In the Tools section, click the + Add Tool button.
3. Click Create new custom tool. A tool configuration page opens.
4. In the Name setting, enter fetchFromChangelog
5. In the Description setting, enter Searches for and filters changelog entries by user-provided date range.
6. Click Add parameter twice. Click to update each parameter, and configure them with the following settings:

   Name	Type	Description	Required
   startDate	String	The start date (inclusive) for filtering entries, in YYYY-MM-DD format.	Yes
   endDate	String	The end date (inclusive) for filtering entries, in YYYY-MM-DD format.	Yes

7. Select Edit function in the Function Logic section.

Edit function

You have two options for creating function logic: you can manually assemble blocks to create your desired control flow, or you can use the Function Generator, to create a function automatically using your choice of LLM.

Manually assemble blocks

To manually assemble blocks that retrieve changelog entries and filter them by date, complete the following steps:

1. Delete the code1 block. Click and drag from the Parameters block. Create a Resource query block with the REST API resource type to GET the JSON feed for the Changelog: https://docs.retool.com/changelog/feed.json. Name it getChangelogEntries.
2. From getChangelogEntries, click and drag to add a Code block. Replace the default code with the following JavaScript:

   return getChangelogEntries.data.items
3. From the Code block, click and drag to add a Filter block with the following Expression to use the moment() date library to match any posts within the specified range:

   moment(value.date_modified).isBetween(moment(params.startDate), moment(params.endDate))
4. All functions must have a Response block. From the Filter block, click and drag to add a Response block with a Status code of 200 and the following Return body:

   filter1.data
5. Click Done.
6. On the Edit Tool page, click Save.

Use Function Generator

Provide the Function Generator instructions about what actions you want your function to perform:

1. Paste the following command into the Function Generator:

   Write a function that retrieves the changelog entries from https://docs.retool.com/changelog/feed.json. Return only the items with a date_modified between or on the startDate and endDate.
2. The Function Generator provides a plan that outlines the function it will create. Review the plan, and click Accept.
3. Once the canvas updates with your new function, provide example start and end dates in the params block and click Test Function.

   Depending on the model and prompt you use, you may have varying results and need to troubleshoot the code that's generated.

4. Click Done.
5. On the Edit Tool page, click Save.

You can also optionally @ tag any previously-created resources to indicate that you want to include a Resource query block that accesses that resource.

Billing for custom tools

While the functions used by custom tools are functionally similar to workflows, they are billed differently. The time that your custom tool takes to run contributes to the overall billable time for your agent. Refer to the Billing and usage guide for more information.