Skip to main content
A custom tool is an HTTP request your AI agent can make in the middle of a conversation: check a booking in your reservation system, look up a customer’s loyalty points, get the status of a repair ticket, or register a warranty claim. The Knowledge Base covers facts you can write down; tools cover facts the agent must fetch live. Open Tools in the sidebar to see your tools, create one with New Tool, or browse tools other workspaces have shared with Tools Showcase.

​
What a tool is made of

For the full field-by-field walkthrough, see Create a custom tool.

​
What happens during a conversation

  1. The agent reads the tool’s description and its parameter descriptions alongside everything else it can do, and decides on each message whether the tool fits.
  2. It gathers the parameter values: from what the customer said, from the customer’s stored details, or from the fixed value you configured. If a required value is missing, it asks the customer.
  3. Popcorn sends the request to your URL with the configured method, headers, query string, path values and JSON body.
  4. Your API’s JSON response is handed back to the agent, which uses it to write the reply in its own words.
  5. If the request fails or your API returns an error, the agent receives the error instead of data and replies without the result.
In the Inbox, a reply that used a tool shows the tool name under the message. Click it to open Message Source; Source Tool names the tool. See Working with conversations.

​
What your API must support

​
An example

A repair shop wants the agent to answer “where is my repair?” from its ticketing system. When a customer writes “any news on ticket 482913?”, the agent recognises the request from the description, takes 482913 from the message, calls https://api.example-repairs.com/tickets/482913, and answers from the JSON that comes back.

​
Manage your tools

The Tools page shows one card per tool with its image (or initial), name and description. The pencil opens the tool for editing, the trash icon deletes it after Confirm Deletion, and a checkmark marks tools you have made public. The list shows tools that belong to the workspace; which agents use them is managed from each agent’s page, not here.

​
Tools and agents

A tool in the Tools list belongs to your workspace. To let an agent use it, turn it on in the Tools section of the agent page and publish the agent; Popcorn then gives that agent its own copy of the tool, header values included. The tool does not need to be public. Two consequences follow:
  • To delete a tool, first turn it off in every agent that uses it and publish those agents. Otherwise Popcorn refuses with Failed to delete tool … Make sure it’s not connected to any AI Agents.
  • Editing a tool needs no disconnecting: the copies your agents hold are updated with it. A new URL, method or header value applies to the agents’ next calls. A new name, description or parameter set is part of each agent’s published version, so click Save & review and Publish changes on the agent for those to reach customers.

​
The marketplace

Tools Showcase lists tools that any Popcorn workspace has made public. You can add one to your workspace with a click and then fill in your own header values, or share your own tool with Make Tool Public. See Tools marketplace.

​
Next steps

Create a custom tool

New Tool, the AI-assisted creator, parameters, and connecting to an agent.

Tools marketplace

Share a tool or add a public one.

Agent capabilities

The built-in abilities you turn on in Configuration.

Knowledge Base

For facts you can write down instead of fetching.