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

# Add and configure agent tools

> Add and configure built-in and custom tools for a Weles AI agent stage so agents can access external data and perform actions.

Tools give an agent access to external data or actions. They are configured per **AI Agent** stage. The available fields come from the tool type's configuration schema; fields marked with an asterisk are required. The model decides whether to call a tool, so verify behavior with a real test rather than assuming it will always call one.

## Add a built-in tool to a stage

1. Open **Workflows**, select a workflow and an **AI Agent** stage, and open the stage's **Tools** tab.
2. Select **Add Tool**, expand the new tool card, and choose a **Tool type**. Give it a distinct **Name (label)** and fill in the displayed configuration fields. Array fields accept comma-separated entries; object fields require valid JSON.
3. Configure the endpoint and any required credentials using values approved for your deployment. Addresses must be reachable from the service executing the agent, not merely from your browser. Review the network, data access, and effect of every tool.
4. Select **Save** on the stage. Ask a non-sensitive test question that requires the tool. Inspect the response and tool-call activity; diagnose connectivity, credentials, permissions, and model tool-calling support if it fails.

### Example: web search

Start the optional `search` Compose profile, if approved for your deployment. Add **Web Search**, set `base_url` to `http://searxng:8080`, `num_results` to `5`, and `search_type` to `web`. Save the stage and ask a question requiring current public information. Search queries are sent to the configured search service and its upstream providers. Use **Web Scraper** separately when page-content retrieval is needed.

### Example: vector search

Start and configure Qdrant and a compatible embedding provider. Add **Vector Database**, set `url` to `http://qdrant:6333`, enter an existing `collection_name`, set `top_k` to `5`, and choose the same compatible embedding model used to populate the collection. Populate the collection before testing. An empty collection, incompatible vector dimensions, or a provider/model mismatch will prevent useful results.

## MCP tools

Choose **MCP Server (Streamable HTTP)**, **MCP Server (SSE)**, **MCP Server (HTTP)**, or **MCP Server (stdio)** according to the server's transport. Enter the endpoint or command and relevant arguments, authentication and timeout, then select **Discover Tools**.

For Streamable HTTP, select the discovered tools the agent may use and save the stage; discovery alone does not select them. For the other transports, select a discovered tool to fill its name and schema, or configure the tool name and discovery options as appropriate. Re-discover and save when server tools change. The stdio command runs in the Weles execution environment; only use trusted servers and commands. Protect credentials and restrict access to approved services.

## Available built-in tool types

This catalogue reflects the application build; the tool picker is authoritative for the deployed version. Defaults below are application defaults, not a guarantee that a service is running.

| Tool type | Purpose and key settings |
| - | - |
| `web_search` | Search using SearXNG-compatible service. `base_url`, `num_results`, `search_type` (`web`, `images`, or `web+images`). |
| `web_scraper` | Retrieve readable page content using the scraper service. `service_url`, `timeout`. |
| `vector_db` | Search Qdrant. Required `collection_name`; configure `url`, `top_k`, `embedding_model`. |
| `knowledge_graph` | Query Neo4j. Required `bolt_uri`, `password`; optional `user`, `database`. |
| `sql_table` | Run SELECT queries. Required `connection_string`; optional `table`, `columns`, `max_rows`. Use a database account with read-only permissions. |
| `http_request` | Make HTTP requests. Optional fixed `url` and `method`, plus `headers`, `param_schema`, `query_mapping`, `static_query`, `static_body`, and `timeout`. Without a fixed URL, the agent can choose one. |
| `redis_cache` | Read or write Redis values. Configure `host`, `port`, and `ttl`. |
| `file_reader` | Read text files using a configured `base_path` in the executing environment. Do not rely on this setting alone as a filesystem security boundary. |
| `python_eval` | Execute Python with a restricted set of built-ins and `allowed_modules`. Do not treat this as a secure isolation boundary. |
| `email_sender` | Send SMTP messages. Required `smtp_host` and `from_addr`; configure `smtp_port`, `username`, and `password` as needed. |
| `mcp_server` | Legacy HTTP JSON-RPC MCP integration. Required `endpoint`; configure `tool_name`, `auto_discover`, `timeout`, `headers`, `auth_type`, and `auth_value` as appropriate. |
| `mcp_sse` | MCP over SSE. Required `endpoint`; similar selection, timeout and authentication settings. |
| `mcp_stdio` | MCP subprocess over standard input/output. Required `command`; configure `args`, `env`, `tool_name`, `auto_discover`, `timeout`, and `startup_timeout`. |
| `mcp_streamable_http` | MCP Streamable HTTP. Required `endpoint`; configure `timeout`, `headers`, authentication, discover and select allowed tools. |

> [!WARNING]
>
> Tools can disclose data, access internal services, execute code, or perform external actions such as sending email or HTTP requests. Use least-privilege credentials, restrict network egress and filesystem access, and review tool configurations. SQL table restrictions and Python's restricted execution are not substitutes for database permissions and OS/container isolation. Avoid enabling dangerous tools for untrusted workloads.

## Install a custom tool package

For an AI-oriented package schema and complete HTTP, MCP, and agent workflow examples, see [Create Tool Manager packages](https://docs.welesai.com/ai-agents/tool-packages.md).

In **Tool Manager**, select **Install Tool**. Browse the available packages or import a trusted package from JSON, a file, or a URL; review its type, endpoint, permissions, required secrets, and schema before installing. The JSON import requires `name`, `slug`, and `type`; supported types include `http`, `mcp_server`, `mcp_sse`, `mcp_stdio`, and `mcp_streamable_http`. The slug uses lowercase letters, digits, and underscores. Enable the installed package, then select it from the agent stage's tool picker, where it is marked **Custom**. Installing a package does not automatically add it to an agent.

For installed packages that declare secrets, configure the named entries under **Secrets**. Names must start with an uppercase letter and contain only uppercase letters, digits, and underscores. The package can refer to a vault secret with a double-braced name, for example `{{SERVICE_TOKEN}}`; verify that the package's required secrets are configured before testing. Secrets Vault values are encrypted using `SECRET_ENCRYPTION_KEY`; preserve this key securely. This substitution applies to installed tool package configuration; do not assume it applies to provider keys or every built-in tool field. Test with non-sensitive data, and do not expose credentials in examples or logs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.