> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jelou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# What is it

> Tools are reusable functions that execute specific tasks within Jelou and return a result, without interacting with the user.

They are used within flows (Workflows) to connect with external services, perform quick calculations, or automate actions, helping to build simpler and more maintainable flows.

## Features

### Execution mode

The mode depends on who invokes the Tool:

* **From a workflow** (Tool node): execution is **asynchronous**. The workflow suspends, the Tool runs separately, and the workflow resumes when it finishes, with the result already available in the output variable you configured. Output mapping and the success and error paths work exactly as before.
* **From an AI Agent**: execution is **synchronous**. The agent waits for the result to fold it into its reply.

In both cases the Tool does not interact with the user: it asks no questions and waits for no replies while it runs.

### Block the user while the Tool runs

Because execution from a workflow is asynchronous, the user stays free while the Tool works: if they write, their message leaves the workflow and the project router handles it. If you would rather have them wait, enable **Block flow** on the Tool node and configure a **Waiting message**.

| Field               | Description                                                                                                                                                                   |
| :------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Block flow**      | Holds the user inside this execution while the Tool runs. Disabled by default, so the Tool nodes you already have behave exactly as before.                                   |
| **Waiting message** | Text the user receives each time they write while the Tool works. It accepts variables. If you leave it empty, blocking still applies and their messages simply get no reply. |

Messages sent during the block are always discarded: they do not enter the workflow, so later nodes — including an AI Agent — never see them. They get a reply only if you configured a waiting message.

The block is released on its own as soon as the Tool finishes, through either its success or its error path, and the flow continues. As a backstop it is capped at **5 minutes**: if the Tool takes longer, the user goes back to talking to the router, and the workflow still continues when the Tool answers.

<Note>
  It does not apply to Tools invoked by an **AI Agent** — that execution is synchronous and suspends nothing — nor to a Tool node running inside another Tool: only the workflow that talks to the user can hold them. It also does not apply in tests from the canvas, or once an operator takes over the conversation. The **Pause** node has the same option; see [Pause](/en/guides/nodos/pausa#block-the-flow-during-the-pause).
</Note>

### Reusable across flows and projects

A single Tool can be used in multiple Workflows and in any project within the company.

### Publishing and internal use

They can be published to the Marketplace (private by default) and consumed from any active project.

### Controlled versioning

Each change generates a new version (v1, v2, v3), and you can decide which version to use in each Workflow.

### Optional external consumption

They include API documentation for external use and support for MCP integration, when you need to expose them outside of Jelou.

### Native Tools ready to use

In addition to creating your own Tools, Jelou offers predefined Tools that you can use directly from the AI Agent node.

### Tool composition

You can use the **Tool** node inside others: nest reusable logic with anti-recursion safeguards and full traceability. See the [Tool composition](/en/guides/tools/composition) guide.

## Native Tools vs Custom Tools

**Native Tools** are predefined tools available within the AI Agent node. They are configured in the **TOOLS** section of the node and allow the AI Agent to perform actions such as searching for products in the catalog, transferring conversations to advisors, sending interactive messages, getting the current date and time, or calculating the day of the week. They are ready to use without needing to create them.

**Custom Tools** are functions you create for specific business needs. You can build them using nodes like API, Code, or Datum, and then publish them to reuse in other projects. They are ideal when you need to connect with external services, perform specific calculations, or automate actions not covered by native Tools.

## Use cases

Tools are ideal for:

### Integrating APIs and external services

Connecting with third-party systems, databases, or web services.

**Example:** Creating a Tool that queries the Stripe API to validate card numbers without storing them in your database.

### Performing calculations or transformations

Processing data, validating information, or executing mathematical operations.

**Example:** A Tool that calculates credit eligibility based on a customer's score and income.

### Querying and updating data

Accessing stored information or modifying records.

### Executing specific actions

Sending notifications, generating reports, or performing system operations.

**Example:** Send a notification when a process completes. A Tool runs at the end of a flow and sends a notification via email or WhatsApp to the customer confirming their request was received or approved (for example, a credit application or a purchase order).

## Tool vs HTTPS Tool

In Jelou there are two types of Tools. Both execute automatic functions, but are used in different contexts. The main difference is where they run and who consumes them.

| Aspect                | Tool                                     | HTTPS Tool                                       |
| --------------------- | ---------------------------------------- | ------------------------------------------------ |
| **Where it's used**   | Inside Jelou, within flows (Workflows)   | From any external service via HTTP               |
| **How it's consumed** | Directly within a Workflow               | Via API calls                                    |
| **Security**          | Internal platform handling               | Requires an access token                         |
| **Speed**             | Faster (internal execution)              | May have latency due to the HTTP layer           |
| **Typical cases**     | Internal data, integrations within Jelou | Exposing functions to other systems or using MCP |

### Practical rule

✅ **Use Tool** if the function lives and runs within a flow in Jelou

🌐 **Use HTTPS Tool** if you need something external to consume it

## Best practices

* **Descriptive names**: Use clear names that indicate what the Tool does
* **Descriptions**: Add descriptions to inputs and outputs to make them easier to use
* **Conscious versioning**: Publish new versions only when you make significant changes
* **Secret variables**: Always mark any sensitive information (API keys, tokens, credentials) as "secret"
* **Error handling**: Include validations and error handling in your Tool
* **Thorough testing**: Test your Tool with different scenarios before publishing it
* **Reusability**: Design generic Tools that can be used in multiple contexts

## Common mistakes

* **Not configuring environment variables**: Forgetting to create or configure variables needed for authentication
* **Using hardcoded values**: Including API keys or credentials directly in the code instead of using secret variables
* **Not validating inputs**: Not verifying that inputs have the correct format or type
* **Forgetting to select the version**: Not explicitly choosing the Tool version when using it in a Workflow
* **Not testing before publishing**: Publishing a Tool without verifying it works correctly
* **Making up IDs**: Using team, operator, or resource IDs that don't exist in the platform
* **Not documenting changes**: Publishing new versions without documenting what changed and why

## Validation checklist

Before publishing a Tool, verify:

* The Tool has a descriptive and clear name
* All inputs are configured with types and descriptions
* Outputs are correctly mapped
* Required environment variables are created (and marked as secret if applicable)
* The Tool has been tested with different input values
* Error cases are handled correctly
* Input and output documentation is clear
* There are no hardcoded values that should be variables
* The Tool works correctly when consumed from a Workflow
* If it is an HTTPS Tool, the API documentation is available and correct

## FAQ

<Accordion title="Can I use a Tool in multiple Workflows?">
  Yes. Once published, a Tool can be used in any Workflow in any project within your company. Tools are reusable throughout the entire company.

  **Example:** If you create a Tool 'calculate\_tax', you can use it in 3 different Workflows without duplicating code.
</Accordion>

<Accordion title="What happens if I update a Tool after publishing it?">
  When you publish an updated Tool, a new version is generated (v1, v2, v3, etc.). Workflows that already use previous versions will continue working with that version. You can choose which version to use in each Workflow.
</Accordion>

<Accordion title="How do I consume a Tool from an external service?">
  If your Tool is published as an HTTPS Tool, you can access the API documentation from the Tool section. There you will find the URL, the security token, and examples of how to consume it via HTTP. You can also use the MCP integration so that external AI agents can discover and use your Tool automatically.
</Accordion>

<Accordion title="Are secret variables secure?">
  Yes. Variables marked as "secret" are encrypted and not visible to other users. Even when consuming an HTTPS Tool externally, secret variables remain protected.
</Accordion>

<Accordion title="What nodes can I use in a Tool?">
  Currently supported nodes include API, Code, Datum, and the **Tool** node (to [compose Tools](/en/guides/tools/composition)), among others. Check the nodes section in the documentation for the full list and their specific features.
</Accordion>

<Accordion title="Can I view the version history of a Tool?">
  Yes. In the Tool's API documentation, you can see all published versions and the change history. This helps you understand what changed in each version and why.
</Accordion>

<Accordion title="What is MCP and how does it relate to Tools?">
  MCP (Model Context Protocol) is a protocol for external AI agents (not Jelou) that want to discover and use your Tools.

  By enabling MCP, a unique URL is generated that allows these agents to access your published Tools and use them autonomously.
</Accordion>