Tools overview
Tools give your agents the ability to do things — call an API, run a calculation, query a database, search a knowledge base, or send an email. An agent’s reasoning decides what to do; a tool is how it gets done.
You manage tools in the Agent Tools area of a project. It lives in the project sidebar under Agentic Workspace → Tools, and its heading reads Agent Tools with the subtitle “Manage tools available to agents in this project.”
Three tool scopes
Every tool belongs to one of three scopes:
| Scope | What it is | Who creates it |
|---|---|---|
| System | Built-in capabilities provided by qRaptor — calculator, datetime, web search, database access, RAG, and more. | qRaptor (read-only) |
| Project | Custom tools you build for your specific use case — an HTTP call to your API, or a Python handler. | You |
| MCP | Tools discovered from an external Model Context Protocol server you connect (GitHub, Stripe, Notion, and others). | You (connect a server) |
This section covers System and Project tools. Connecting MCP servers is documented in MCP servers.
Tool categories
Every tool declares a category that describes its behavior and how the platform caches its results:
| Category | Meaning | Caching |
|---|---|---|
| Function | Pure computation — idempotent, no side effects. | Cacheable |
| Data Pull | Read-only data fetch. | TTL cached |
| Action | Side-effect operation (writes, sends, mutates). | Never cached |
Choosing the right category matters: an Action must never be cached, because running it twice has real consequences.
Data classification
Each tool also declares a data classification and one or more data types, so the platform can govern how sensitive data flows through your agents:
| Classification | Meaning |
|---|---|
| Public | No sensitive data. |
| Internal | Internal business data. |
| Confidential | Sensitive business data. |
| Restricted | Highly sensitive (PII/PHI). |
Data types are tags: General, PII (Personal Info), PHI (Health Info), Financial, and Credentials.
Human-in-the-Loop (HIL)
A tool can require Human-in-the-Loop approval before it runs. When HIL is enabled, execution pauses and a person must approve (or reject) the call — useful for irreversible or high-risk actions. Tools that require approval show a HIL badge in the registry.
You configure HIL when you create a tool. See Create a tool.
Configuration status
System tools often need a configuration value to work — an API key for web search, for example. The registry shows each tool’s configuration status as a badge:
| Badge | Meaning |
|---|---|
| Ready | The tool has everything it needs and can be used. |
| Config Required | The tool needs a configuration value that hasn’t been set yet. |
| Config Missing | A referenced configuration value can’t be found in project settings. |
See Configuration & secrets for how tools reference project configuration with {{config.xxx}}.
Lifecycle
Project tools move through a lifecycle. Only Published tools are available for agents to use.
| Status | Meaning |
|---|---|
| Draft | Not yet published, only visible in Studio. |
| Ready for Review | Submitted for review before publishing. |
| Published | Active and available for agents to use. |
| Deprecated | Will be removed soon; agents should migrate. |
| Archived | No longer available for use. |
See Publish & lifecycle for the full workflow.
How agents use tools
Once a tool is published, agents invoke it in two ways:
- Deterministically — a Task Agent calls a specific tool from a Tools Call node in its workflow graph. You wire the inputs; the tool runs exactly where you placed it.
- LLM-driven — an AI Agent is given a set of tools as skills, and the model decides which to call and when.
What’s next
- The Tools registry → — Browse, search, and filter tools
- Built-in tools → — Reference of every System tool
- Create a tool → — Build a custom tool step by step
- Use tools in a Task Agent → — Add a Tools Call node
- Configuration & secrets → — Reference project config safely