## About tools

Tools are the fundamental building blocks of Agen for SaaS. Each tool represents a single API operation — an endpoint that AI agents can discover, understand, and invoke through your MCP Gateway.

### What is a tool

A tool is a structured definition of an API operation that includes everything an AI agent needs to understand and call it:

| Property | Description | Limit |
|  --- | --- | --- |
| **Tool name** | A unique identifier for the tool (e.g., `Create_a_new_expense`, `Delete_receipt`). | — |
| **Tool description** | A human-readable explanation of what the tool does. AI agents use this to decide when and how to invoke the tool. | 2,000 characters |
| **Tool API** | The HTTP method (GET, POST, PUT, DELETE) and path (e.g., `/api/receipts/{id}`). | — |
| **Source name** | The source this tool was generated from (e.g., `default`, `Frontegg`). | — |


### How tools are created

![extracted-tools](/assets/extracted-tools.64b27475c7bbadd9bcacc10f6b5a0bee2ceb281c081e52a0e012e5d4a932e88e.212f8da4.png)

Tools are automatically generated when you add a **source** to your Agen for SaaS instance:

- **REST sources** — Each endpoint defined in your OpenAPI specification becomes a tool. The tool name, description, method, and path are extracted from the spec.
- **GraphQL sources** — Each query and mutation in your GraphQL schema becomes a tool.
- **MCP server sources** — Tools are discovered dynamically from the remote MCP server.
- **Frontegg source** — Built-in tools that expose Frontegg platform capabilities (e.g., `ApprovalFlowsController_createApp...`, `GeoFencesTenantController_create...`).


After generation, every tool property is fully editable.

### How tools work at runtime

When an AI agent interacts with your MCP Gateway:

1. **Discovery** — The agent calls the MCP `list_tools` endpoint. Agen for SaaS returns all enabled tools that the user has access to (filtered by access control rules and List tools hooks).
2. **Selection** — The AI agent reads tool descriptions and selects the appropriate tool for the user's request.
3. **Invocation** — The agent calls the tool with the required parameters. Agen for SaaS routes the request through the full governance pipeline:
  - **Authentication** — Validates the user's identity token.
  - **Access control** — Checks role/permission mappings.
  - **Policies** — Evaluates conditional rules (deny, step-up, approval).
  - **Hooks** — Executes any active Call tool hooks.
  - **Data protection** — Masks sensitive fields in the response.
4. **Forwarding** — If all checks pass, the request is forwarded to the tool's API endpoint at the source's base URL.
5. **Response** — The API response passes back through the pipeline (data protection masking is applied) and is returned to the AI agent.
6. **Logging** — The entire interaction is recorded in the monitoring system.


### Tool security layers

Every tool call passes through multiple security layers:

| Layer | What it does |
|  --- | --- |
| **Access control** | Ensures the user's JWT contains the required roles or permissions to invoke the tool. |
| **Policies** | Evaluates conditional rules based on request attributes (IP, amount, country) and enforces deny, step-up, or approval actions. |
| **Data protection** | Masks sensitive fields (PII, PHI, PCI) in tool responses based on compliance policies. |
| **Hooks** | Executes custom JavaScript logic that can allow or deny the request. |
| **Monitoring** | Logs the tool call, parameters, response, and all policy decisions for audit. |


### Tool lifecycle

Tools follow this lifecycle:

1. **Generated** — Created automatically from a source (REST, GraphQL, MCP, or Frontegg).
2. **Enabled** — Active and discoverable by AI agents. This is the default state after generation.
3. **Disabled** — Not discoverable by AI agents. The tool definition is preserved but hidden from discovery.
4. **Edited** — Tool properties (name, description, method, path) can be modified at any time.
5. **Deleted** — Permanently removed. This action cannot be undone.


### Best practices

- **Write clear descriptions** — AI agents rely on tool descriptions to understand what each tool does. Include the action performed, expected inputs, and what the response contains.
- **Use consistent naming** — Follow a naming convention that groups related tools (e.g., `Create_expense`, `Get_expense_by_ID`, `Delete_expense`).
- **Disable unused tools** — If a tool is not needed, disable it rather than deleting it. This keeps the definition available for future use.
- **Review generated tools after import** — Auto-generated names and descriptions may need refinement for clarity.
- **Combine with access control** — Restrict sensitive tools to specific roles or permissions rather than leaving them broadly available.


### Related topics

- [Managing tools](/agen-for-saas/tools/managing-tools)
- [Sources](/agen-for-saas/sources/overview)
- [Access control](/agen-for-saas/access-control/overview)
- [Policies](/agen-for-saas/policies/overview)