Tools

The Tools page is the central execution capability management interface in Flocks. It centrally manages built-in tools, API tools, local tools, and external services connected through MCP (Model Context Protocol). In the latest WebUI, MCP has been integrated into the Tools page and is no longer a separate top-level menu.

Tools define the actions available to Agents and Workflows. Agents can use tools as callable capabilities, and Workflows can use tools as nodes. Rex can also leverage natural language to assist in integrating, validating, and debugging tools based on API documentation, interface descriptions, or MCP service information.

1. Purpose

1.1 What Tools Solves

Tools unifies scattered execution capabilities for registration, display, configuration, and testing. It mainly solves four problems:

Capability visibility: view which tools exist in the current environment, where they come from, whether they are enabled, and what they can do.
Capability integration: connect API services, MCP Servers, local Python tools, or built-in platform tools.
Credential configuration: configure API Keys, Tokens, Headers, or other secrets for tools that require authentication.
Capability validation: test connections on the page, inspect tool parameters, and run test calls to confirm that tools can be used by Agents and Workflows.

1.2 Relationship with Other Modules

Module	Relationship
Agent	Agents can configure tool allowlists, deciding which tools they can call.
Workflow	Workflow tool nodes can call APIs, MCP, local tools, or built-in tools.
Skills	Skills can describe correct usage, input requirements, and judgment logic for certain tools.
Model List	Tool calling usually depends on the model's tool-calling capability and parameter generation stability.
Workspace	Project-level tools, generated code, and runtime outputs are usually managed with Workspace.

2. Page Structure

The Tools page is organized by tabs. Common entries include:

Tab	Purpose
All Tools	View all registered tools, with search and filters by category, source, and status.
MCP Services	Manage MCP Servers and view tools and resources provided by MCP.
API Integrations	Manage API service tools, configure credentials, and test connectivity.
Local Tools	View local Python tools, such as tools placed under `~/.flocks/plugins/tools/python/`.

Tool lists usually show the tool name, description, source, status, and operation entries. Click a tool to view its parameter schema, security attributes, whether execution confirmation is required, and to run a test call.

3. Tool Types

3.1 Built-In Tools

Built-in tools come with Flocks and are commonly used for basic actions such as file read/write, terminal commands, code search, browser operations, and system information retrieval. They are foundational capabilities for Rex, Agents, and Workflows.

channel_message is a typical channel-type system tool. It receives a target session_id and message content, automatically finds the WeCom, Feishu, or DingTalk conversation bound to that Session, and sends the message. When a user says "send to session_id: session_id: content" in a session, Rex usually uses this tool to push the message to the fixed IM conversation.

Some built-in tools cannot be tested directly on the Tools page. Test them through real tasks in Session conversations.

3.2 API Tools

API tools connect security devices, threat intelligence sources, internal business systems, or external SaaS. Typical examples include ThreatBook, VirusTotal, GreyNoise, vulnerability platforms, alert platforms, asset platforms, and similar systems.

API tools can be added manually, or Rex can generate them automatically from API documentation. Generated tools appear in the API Integrations tab, where credentials can be configured, connectivity tested, and available tools viewed.

3.3 MCP Services

MCP services connect external systems that already provide MCP capabilities. An MCP Server can expose tools and resources. Flocks brings MCP tools into the unified tool system so Agents and Workflows can call them directly.

MCP is suitable when:

The external system already provides an MCP Server.
You want to use a standard protocol to connect multiple tools or resources.
You do not want to write a separate API tool for each interface.
Tool capabilities may change dynamically with the MCP Server.

3.4 Local Tools

Local tools are usually Python scripts or team-internal logic wrappers. They are suitable for private protocol parsing, internal log processing, environment-specific data conversion, and similar scenarios.

Local Python tools can be placed at:

text

~/.flocks/plugins/tools/python/

After placement, refresh Tools to view them in the Local Tools tab. Some local tools are marked "confirmation required," meaning user confirmation is needed before execution. This is appropriate for actions with side effects or higher risk.

4. Connect API Tools

4.1 Add through the Page Form

Click Add API in Tools and fill in:

API service name: for example threatbook, openweather, or github.
Base URL: root address of the API service.
API Key: optional; you can create the service first and configure credentials later.
Capability description: explain what the API provides. Rex uses this to generate or complete tool code.

If you are not sure how to fill this in, switch to conversational integration mode and let Rex help based on the service name, interface documentation, and requirement description.

4.2 Add through Natural Language

In a session, say to Rex:

text

Help me integrate the VT API service.
The Key is in ~/vt_key.txt.
Documentation URL: https://...

If you do not have documentation ready, you can ask Rex to search first:

text

Search the web for VT API documentation, then integrate the VT API tool.
The Key is in ~/vt_key.txt.

Rex usually:

Reads API documentation or interface descriptions.
Understands authentication, request parameters, and response structure.
Generates API tool code.
Registers the tool in Tools.
Configures or references credentials.
Executes a real request for validation.
Debugs automatically based on failure information.

4.3 Credential Configuration for API Tools

API tools that require authentication show "key required" or a similar status. Click Configure Key to fill in the API Key, Secret, username, password, or other fields required by the service.

Credentials are stored in:

text

~/.flocks/config/.secret.json

The configuration file can reference secrets through {secret:ID}, avoiding sensitive values written directly into tool or MCP configuration.

4.4 Testing API Tools

After configuring credentials, click Test Connection or enter tool details to run a test. Focus on:

Whether the API Key is valid.
Whether the Base URL is correct.
Whether the parameter schema matches the interface.
Whether returned fields can be consumed correctly by Agents or Workflows.
Whether error information is returned clearly by the tool.

A passing test only means basic connectivity works. Real tasks may still be affected by context length, batch size, rate limits, and response format changes.

5. Connect MCP Services

5.1 Connection Methods

When adding an MCP service, choose one of two connection methods:

Connection Method	Suitable For
Stdio local process	Start an MCP Server locally, such as with `npx`, `uvx`, or `python`.
Remote service (SSE / HTTP)	An MCP Server is already provided at a remote address.

Stdio mode requires a startup command and command arguments. Command arguments are usually one per line, for example:

text

npx
@modelcontextprotocol/server-github
--token
{secret:github_token}

Remote service mode requires a service address, for example:

text

http://localhost:3000/sse

The transport protocol can be auto-detected, or you can specify SSE-only or Streamable HTTP-only.

5.2 Authentication Methods

MCP services support multiple authentication methods:

Authentication Method	Description
No authentication	Local services or services in a trusted network.
Bearer Token	Common token authentication.
Custom request headers	Used when the service requires specific Headers.
Query parameters	Used when the service requires authentication information through URL parameters.

Token, Header values, or Query values can be filled in directly or referenced through {secret:secret_id}. Extra request headers must be valid JSON objects.

5.3 MCP Service Management

After adding an MCP service, you can use the MCP Services tab to:

Test connection: verify that the MCP Server is reachable.
Refresh tool list: reread tools exposed by the MCP Server.
View resources: view Resources exposed by the MCP Server.
Disconnect / Connect / Reconnect: manage the service lifecycle.
Configure keys: add required authentication information for services that need credentials.
View details: view service address, protocol version, connection time, tool count, and resource count.

Service states may include connected, error, disconnected, key required, ready, recommended, and similar statuses. When errors occur, first check the startup command, service address, transport protocol, and authentication configuration.

5.4 MCP Tools and Resources

An MCP Server may provide both Tools and Resources:

Tools: executable actions, such as querying, writing, or calling external systems.
Resources: readable context or data sources, such as documents, configuration, or database schema.

Agents and Workflows mainly call MCP Tools. Resources are usually used to enrich context. The tool details page indicates which MCP Server the tool comes from and shows parameters, description, and test entry.

6. Use Local Tools

6.1 Local Tool Directory

Local Python tools are placed by default at:

text

~/.flocks/plugins/tools/python/

This is suitable for team-internal scripts, such as log parsing, internal system queries, data cleaning, format conversion, and offline file processing.

6.2 Local Tool Recommendations

Local tools should:

Have clear input and output structures.
Use readable parameter names so Agents can generate parameters.
Return clear error messages so Rex can debug.
Mark side-effect actions for confirmation.
Avoid hard-coded sensitive credentials in scripts.

If a local tool is frequently used by multiple Agents, consider writing a Skill that explains when the tool is appropriate, how parameters should be filled, and how results should be interpreted.

7. Tool Details and Testing

7.1 View Tool Details

After clicking a tool, you can view:

Tool description.
Current status.
Source and provider.
Whether it is enabled.
Whether execution confirmation is required.
Parameter names, types, required status, and descriptions.
MCP Server or API service information.

This information affects whether Rex is willing to call the tool and the accuracy of model-generated parameters.

7.2 Run Test Calls

The tool details page usually supports filling JSON parameters to run a test. Before testing, confirm:

JSON syntax is valid.
All required parameters are provided.
Parameter types match the schema.
Credentials are configured and have passed connectivity testing.
The tool is suitable for direct testing on the page.

If the test fails, first classify the error: parameter error, authentication error, network error, server-side error, or tool implementation error.

7.3 Tool Status and Enablement

Tools may be enabled, disabled, unconfigured, abnormal, detecting, and so on. For API services and MCP services, the page usually also shows connection status or credential status.

Disabled tools are not normally called by Agents or Workflows. For critical tools, retest after changing credentials, service addresses, or tool code.

8. `/tools` and `/mcp` Commands in Sessions

In addition to the Tools page, you can use slash commands in WebUI sessions, TUI, or CLI sessions to quickly view tools.

8.1 `/tools` Command

/tools is used to view and manage tools visible to the current runtime. Common forms include:

Command	Purpose
`/tools` or `/tools list`	List current tools by category.
`/tools refresh`	Refresh dynamic tools and return the current tool summary.
`/tools info <name>`	View a tool's category, description, enablement, confirmation requirement, and parameter schema.
`/tools create <requirement>`	Call the `tool-builder` Skill to create a tool from a natural-language requirement.

For example:

text

/tools
/tools info bash
/tools create integrate an API tool for querying IOC reputation

/tools is the lightest troubleshooting entry point. If an Agent does not call the expected tool, first use it to confirm whether the tool is registered, enabled, and clearly parameterized.

8.2 `/mcp` Command

/mcp is used to view MCP services and MCP tools. Common forms include:

Command	Purpose
`/mcp` or `/mcp list`	View the MCP Server list and connection status.
`/mcp status`	View each MCP Server's status, tool count, resource count, and error information.
`/mcp tools`	List tools exposed by all MCP Servers.
`/mcp refresh <server>`	Refresh the tool list for a specified MCP Server.

For example:

text

/mcp status
/mcp tools
/mcp refresh github

If a tool comes from an MCP Server, usually run /mcp status first to confirm that the service is online, then use /mcp tools or /tools info <name> to inspect the specific tool.

8.3 Other Common `/` Commands

In addition to /tools and /mcp, sessions also support other slash commands for quickly viewing capabilities or triggering specific workflows:

Command	Purpose
`/help`	View currently available slash commands.
`/new`	Clear the current conversation history and start a new conversation. `/reset` may also be supported as an alias.
`/skills`	View currently available Skills.
`/agents`	View Agents that can currently be delegated to.
`/workflows`	View currently available Workflows.
`/tasks`	View the Task Center overview.
`/queue`	View task queue status.
`/compact`	Compress and summarize the current session context.
`/clear`	Clear the current UI output without deleting real session data.
`/plan <task>`	Ask Plan Agent to create a plan for the task.
`/ask <question>`	Ask in Q&A-only mode, useful when you do not want to change the environment.
`/init`	Analyze the current project and create or update project-level Agent guidance.
`/bug <description>`	Submit or organize issue feedback.

Channel scenarios also support some session control commands, such as /model, /status, /new, and /reset. Visible commands may vary slightly by entry point. The most accurate method is to enter /help in the current session.

9. CLI and TUI Management Entry Points

9.1 Manage MCP Tools in CLI

In the current CLI, tool management is mainly done through MCP commands and the WebUI page. Common MCP commands include:

Command	Purpose
`flocks mcp list`	View configured MCP Servers and their status.
`flocks mcp add`	Add an MCP Server interactively.
`flocks mcp add --name <name> --type remote --url <url>`	Add a remote MCP Server.
`flocks mcp add --name <name> --type local --command "<cmd>"`	Add a local stdio MCP Server.
`flocks mcp auth <name>`	Authenticate a remote MCP Server that supports OAuth.
`flocks mcp logout <name>`	Clear authentication for a specified MCP Server.
`flocks mcp connect <name>`	Connect to a specified MCP Server.
`flocks mcp disconnect <name>`	Disconnect from a specified MCP Server.
`flocks mcp tools [server]`	View MCP tools exposed by all or a specified Server.
`flocks mcp refresh [server]`	Refresh MCP tools for all or a specified Server.
`flocks mcp debug <name>`	Debug MCP Server configuration and connection.

API tools and local Python tools in Tools are usually managed through WebUI, Rex's /tools create, local directories, or project plugin directories. MCP tools are better maintained with flocks mcp commands.

9.2 View and Switch Tool Context in TUI

TUI syncs the current Agent, MCP Server, and available tool status. Common operations include:

Use /tools and /mcp in the input box to view tool and MCP status.
Use the MCP dialog to view and connect MCP Servers.
View MCP Server connection count and error status in the sidebar.
Use flocks debug agent <agent> --tool <tool> --params '<json>' to debug whether an Agent can execute a specified tool.

Example:

bash

flocks debug agent rex --tool bash --params '{"cmd":"pwd"}'

To verify whether an Agent is allowed to call a tool, TUI's debug agent command is more direct than trial and error in a session.

10. How Agents and Workflows Use Tools

10.1 Agent Tool Allowlist

Tools are registered at the platform level, but Agents can configure their own tool allowlists. This lets each Agent see only tools relevant to its responsibilities, reducing the chance of wrong calls.

For example:

Intelligence analysis Agents only configure IOC query, threat intelligence API, and report-writing tools.
Device inspection Agents only configure browser, device API, and file-writing tools.
Vulnerability triage Agents only configure vulnerability databases, asset query, and impact assessment tools.

10.2 Workflow Tool Nodes

Workflows can call APIs, MCP, local Python, or other tools through tool nodes. Tool nodes are suitable for clear, repeatable, stable input/output actions, such as:

Query IOCs.
Pull asset information.
Call alert platform interfaces.
Parse logs.
Write files.
Send notifications.

If complex judgment is needed before or after a tool call, place the judgment logic in an Agent node or Skill. Let the tool node handle only the stable action.

11. Real Example: Connect the VT API Tool

11.1 User Input

text

Search the web for VT API documentation, then help me integrate the VT API service.
The Key is in a file.

11.2 Generation Process

Rex:

Searches or reads VT API documentation.
Understands interface structure, authentication, and query parameters.
Generates API tool code.
Sends a real request with the Key provided by the user.
Adjusts field parsing and error handling based on the response.
After validation, adds the tool to Tools.

11.3 Acceptance

After completion, do three things:

Confirm normal service status in the API Integrations tab.
Run a test with a sample IOC in tool details.
Trigger a real task in a session or Workflow to confirm that the Agent consumes returned results correctly.

12. FAQ

12.1 Is a Tool Loaded Automatically After Integration, or Must It Be Enabled Manually?

It usually appears automatically in Tools and can be used by Rex in later tasks. If it does not appear, refresh the page and confirm whether the tool is installed in the current Workspace or the user-level directory.

12.2 If Pasted JSON Fails in MCP Testing, Is It a Format Problem or a Calling Problem?

Troubleshoot by layers:

Validate JSON syntax first.
Check whether the parameter structure matches the tool schema.
Check whether the MCP Server is connected.
Finally decide whether the tool is suitable for direct invocation in the page test box.

12.3 Why Does a Tool Pass Testing but Fail in Real Tasks?

Testing only verifies basic connectivity. Real tasks add longer context, larger outputs, batch requests, rate limits, and tool combinations. First distinguish whether all tools fail or only one tool fails, then narrow it down to model parameter generation, tool implementation, credentials, or the external service.

12.4 Do Tools Work Normally in Docker?

It depends on the tool type:

API tools: work if network access and credentials are correct.
MCP Stdio tools: require the corresponding commands, dependencies, and environment variables inside the container.
Browser tools: interactive browser mode is usually not suitable in Docker and must be confirmed for the deployment mode.
Local file / Bash tools: pay attention to mounted directories and permissions.

12.5 A Tool Call Succeeds, but the Result Is Not Saved Automatically. What Should I Do?

Many tools only return results by default and do not write to disk. When file output is needed:

Explicitly require "write the result to a file" in the task Prompt.
Add an output path parameter to the tool definition.
Add a write-file node in the Workflow.
Write the final output to outputs/ in Workspace.

12.6 Can an API Tool Be Used Only by Specific Agents?

Yes. After registration, a tool is a platform capability, but each Agent can configure its own tool allowlist. This prevents Agents from using irrelevant tools by mistake.

12.7 What If an MCP Service Fails to Connect?

Verify the following:

Whether the stdio startup command can execute in the current environment.
Whether command arguments are one per line and in the correct order.
Whether the remote service address is reachable.
Whether the transport protocol is correct.
Whether Token, Header, or Query parameters are valid.
Whether {secret:ID} has already been configured in the credential file.

Agent: Main caller of tools.
Workflow: Execution source for tool nodes.
Skills: Preserve tool usage methods and judgment standards.
Model Configuration: Tool calling depends on stable model-generated parameters.
Workspace: Manage project-level tools, outputs, and context.
Scenario Practice - Internal Security Product Integration: Priorities for different tool integration methods.
Scenario Practice - Browser Automation: Path from browser operations to fixed API tools.

Operation demo videos will be added to this page after release materials are stable.

Tools

1. Purpose

1.1 What Tools Solves

1.2 Relationship with Other Modules

2. Page Structure

3. Tool Types

3.1 Built-In Tools

3.2 API Tools

3.3 MCP Services

3.4 Local Tools

4. Connect API Tools

4.1 Add through the Page Form

4.2 Add through Natural Language

4.3 Credential Configuration for API Tools

4.4 Testing API Tools

5. Connect MCP Services

5.1 Connection Methods

5.2 Authentication Methods

5.3 MCP Service Management

5.4 MCP Tools and Resources

6. Use Local Tools

6.1 Local Tool Directory

6.2 Local Tool Recommendations

7. Tool Details and Testing

7.1 View Tool Details

7.2 Run Test Calls

7.3 Tool Status and Enablement

8. /tools and /mcp Commands in Sessions

8.1 /tools Command

8.2 /mcp Command

8.3 Other Common / Commands

9. CLI and TUI Management Entry Points

9.1 Manage MCP Tools in CLI

9.2 View and Switch Tool Context in TUI

10. How Agents and Workflows Use Tools

10.1 Agent Tool Allowlist

10.2 Workflow Tool Nodes

11. Real Example: Connect the VT API Tool

11.1 User Input

11.2 Generation Process

11.3 Acceptance

12. FAQ

12.1 Is a Tool Loaded Automatically After Integration, or Must It Be Enabled Manually?

12.2 If Pasted JSON Fails in MCP Testing, Is It a Format Problem or a Calling Problem?

12.3 Why Does a Tool Pass Testing but Fail in Real Tasks?

12.4 Do Tools Work Normally in Docker?

12.5 A Tool Call Succeeds, but the Result Is Not Saved Automatically. What Should I Do?

12.6 Can an API Tool Be Used Only by Specific Agents?

12.7 What If an MCP Service Fails to Connect?

13. Related Modules

8. `/tools` and `/mcp` Commands in Sessions

8.1 `/tools` Command

8.2 `/mcp` Command

8.3 Other Common `/` Commands