chore: import upstream snapshot with attribution

docs/content/Tools/_meta.js

@@ -0,0 +1,22 @@
+export default {
+  "basics": {
+    "title": "🔧 Tools Basics",
+    "href": "/Tools/basics"
+  },
+  "api-tool": {
+    "title": "🗝️ API Tool",
+    "href": "/Tools/api-tool"
+  },
+  "remote-device": {
+    "title": "🖥️ Remote Device",
+    "href": "/Tools/remote-device"
+  },
+  "artifacts-and-code-execution": {
+    "title": "📦 Artifacts and Code Execution",
+    "href": "/Tools/artifacts-and-code-execution"
+  },
+  "creating-a-tool": {
+    "title": "🛠️ Creating a Custom Tool",
+    "href": "/Tools/creating-a-tool"
+  }
+}

docs/content/Tools/api-tool.mdx

@@ -0,0 +1,153 @@
+---
+title: 🗝️ Generic API Tool
+description: Learn how to configure and use the API Tool in DocsGPT to connect with any RESTful API without writing custom code.
+---
+
+import { Callout } from 'nextra/components';
+import Image from 'next/image';
+
+# Using the Generic API Tool
+
+The API Tool provides a no-code/low-code solution to make DocsGPT interact with third-party or internal RESTful APIs. It acts as a bridge, allowing the Large Language Model (LLM) to leverage external services based on your chat interactions.
+ This guide will walk you through its capabilities, configuration, and best practices.
+
+## Introduction to the Generic API Tool
+
+**When to Use It:**
+    * Ideal for quickly integrating existing APIs where the interaction involves standard HTTP requests (GET, POST, PUT, DELETE).
+    * Suitable for fetching data to enrich answers (e.g., current weather, stock prices, product details).
+    * Useful for triggering simple actions in other systems (e.g., sending a notification, creating a basic task).
+
+**Contrast with Custom Python Tools:**
+    * **API Tool:** Best for straightforward API calls. Configuration is done through the DocsGPT UI.
+    * **Custom Python Tools:** Preferable when you need complex logic before or after the API call, handle non-standard authentication (like complex OAuth flows), manage multi-step API interactions, or require intricate data processing not easily managed by the LLM alone. See [Creating a Custom Tool](/Tools/creating-a-tool) for more.
+
+## Capabilities of the API Tool
+
+**Supported HTTP Methods:** You can configure actions using standard HTTP methods such as:
+    * `GET`: To retrieve data.
+    * `POST`: To submit data to create a new resource.
+    * `PUT`: To update an existing resource.
+    * `DELETE`: To remove a resource.
+
+**Request Configuration:**
+    * **Headers:** Define static or dynamic HTTP headers for authentication (e.g., API keys), content type specification, etc.
+    * **Query Parameters:** Specify URL query parameters, which can be static or dynamically filled by the LLM based on user input.
+    * **Request Body:** Define the structure of the request body (e.g., JSON), with fields that can be static or dynamically populated by the LLM.
+
+**Response Handling:**
+    * The API Tool executes the request and receives the raw response from the API (typically JSON or plain text).
+    * This raw response is then passed back to the LLM.
+    * The LLM uses this response, along with the context of your query and the description of the API tool action, to formulate an answer or decide on follow-up actions. The API tool itself doesn't deeply parse or transform the response beyond basic content type detection (e.g., loading JSON into a parsable object).
+
+## Configuring an API as a Tool
+
+You can configure the API Tool through the DocsGPT user interface, found in **Settings -> Tools**. When you add or modify an API Tool, you'll define specific actions that DocsGPT can perform.
+
+<Callout type="info">
+  The configuration involves defining how DocsGPT should call an API endpoint. Each configured API call essentially becomes a distinct "action" the LLM can choose to use.
+</Callout>
+
+Below is an example of how you might configure an API action, inspired by setting up a phone number validation service:
+
+<Image
+  src="/toolIcons/api-tool-example.png"
+  alt="API Tool configuration example for phone validation"
+  width={800}
+  height={450}
+  style={{ margin: '1em auto', display: 'block', borderRadius: '8px' }}
+/>
+_Figure 1: Example configuration for an API Tool action to validate phone numbers._
+
+**Defining an API Endpoint/Action:**
+
+When you configure a new API action, you'll fill in the following fields:
+
+-   **`Name`:** A user-friendly name for this specific API action (e.g., "Phone-check" as in the image, or more specific like "ValidateUSPhoneNumber"). This helps in managing your tools.
+-   **`Description`:** This is a **critical field**. Provide a clear and concise description of what the API action does, what kind of input it expects (implicitly), and what kind of output it provides. The LLM uses this description to understand when and how to use this action.
+-   **`URL`:** The full endpoint URL for the API request.
+-   **`HTTP Method`:** Select the appropriate HTTP method (e.g., GET, POST) from a dropdown.
+-   **`Headers`:** You can add custom HTTP headers as key-value pairs (Name, Value). Indicate if the value should be `Filled by LLM` or is static. If filled by LLM, provide a `Description` for the LLM.
+
+-   **`Query Parameters`:** For `GET` requests or when parameters are sent in the URL.
+    * **`Name`:** The name of the query parameter (e.g., `api_key`, `phone`).
+    * **`Type`:** The data type of the parameter (e.g., `string`).
+    * **`Filled by LLM` (Checkbox):**
+        - **Unchecked (Static):** The `Value` you provide will be used for every call (e.g., for an `api_key` that doesn't change).
+        - **Checked (Dynamic):** The LLM will extract the appropriate value from the user's chat query based on the `Description` you provide for this parameter. The `Value` field is typically left empty or contains a placeholder if `Filled by LLM` is checked.
+    * `Description`: Context for the LLM if the parameter is to be filled dynamically, or for your own reference if static.
+    * `Value`: The static value if not filled by LLM.
+
+-   **`Request Body`:** Used to send data (commonly JSON) to the API. Similar to Query Parameters, you define fields with `Name`, `Type`, whether it's `Filled by LLM`, a `Description` for dynamic fields, and a static `Value` if applicable.
+
+**Response Handling Guidance for the LLM:**
+
+While the API Tool configuration UI doesn't have explicit fields for defining response parsing rules (like JSONPath extractors), you significantly influence how the LLM handles the response through:
+    * **Tool Action `Description`:** Clearly state what kind of information the API returns (e.g., "This API returns a JSON object with 'status' and 'location' fields for the phone number."). This helps the LLM know what to look for in the API's output.
+    * **Prompt Engineering:** For more complex scenarios, you might need to adjust your global or agent-specific prompts to guide DocsGPT on how to interpret and present information from API tool responses. See [Customising Prompts](/Guides/Customising-prompts).
+
+## Using the Configured API Tool in Chat
+
+Once an API action is configured and enabled, DocsGPT's LLM can decide to use it based on your natural language queries.
+
+**Example (based on the phone validation tool in Figure 1):**
+
+1.  **User Query:** "Hey DocsGPT, can you check if +14155555555 is a valid phone number?"
+
+2.  **DocsGPT (LLM Orchestration):**
+    * The LLM analyzes the query.
+    * It matches the intent ("check if ... is a valid phone number") with the description of the "Phone-check" API action.
+    * It identifies `+14155555555` as the value for the `phone` parameter (which was marked as `Filled by LLM` with the description "Phone number to check").
+    * DocsGPT constructs the GET API request.
+3.  **API Tool Execution:**
+    * The API Tool makes the HTTP GET request.
+    * The external API (AbstractAPI) processes the request and returns a JSON response, e.g.:
+        ```json
+        {
+          "phone": "+14155555555",
+          "valid": true,
+          "format": {
+            "international": "+1 415-555-5555",
+            "national": "(415) 555-5555"
+          },
+          "country": {
+            "code": "US",
+            "name": "United States",
+            "prefix": "+1"
+          },
+          "location": "California",
+          "type": "Landline"
+        }
+        ```
+
+4.  **DocsGPT Response Formulation:**
+    * The API Tool passes this JSON response back to the LLM.
+    * The LLM, guided by the tool's description and the user's original query, extracts relevant information and formulates a user-friendly answer.
+    * **DocsGPT Chat Response:** "Yes, +14155555555 appears to be a valid landline phone number in California, United States."
+
+## Advanced Tips and Best Practices
+
+**Clear Description is the Key:** The LLM relies heavily on the `Description` field of the API action and its parameters. Make them unambiguous and action-oriented. Clearly state what the tool does and what kind of input it expects (even if implicitly through parameter descriptions). 
+
+**Iterative Testing:** After configuring an API tool, test it with various phrasings of user queries to ensure the LLM triggers it correctly and interprets the response as expected.
+  
+**Error Handling:**
+    * If an API call fails, the API Tool will return an error message and status code from the `requests` library or the API itself. The LLM may relay this error or try to explain it.
+    * Check DocsGPT's backend logs for more detailed error information if you encounter issues.
+  
+**Security Considerations:**
+    * **API Keys:** Be mindful of API keys and other sensitive credentials. The example image shows an API key directly in the configuration. For production or shared environments avoid exposing configurations with sensitive keys.
+    * **Rate Limits:** Be aware of the rate limits of the APIs you are integrating. Frequent calls from DocsGPT could exceed these limits.
+    * **Data Privacy:** Consider the data privacy implications of sending user query data to third-party APIs.
+-   **Idempotency:** For tools that modify data (POST, PUT, DELETE), be aware of whether the API operations are idempotent to avoid unintended consequences from repeated calls if the LLM retries an action.
+
+## Limitations
+
+While powerful, the Generic API Tool has some limitations:
+
+-   **Complex Authentication:** Advanced authentication flows like OAuth 2.0 (especially 3-legged OAuth requiring user redirection) or custom signature-based authentication often require custom Python tools.
+-   **Multi-Step API Interactions:** If a task requires multiple API calls that depend on each other (e.g., fetch a list, then for each item, fetch details), this kind of complex chaining and logic is better handled by a custom Python tool.
+-   **Complex Data Transformations:** If the API response needs significant transformation or processing before being useful to the LLM, a custom Python tool offers more flexibility.
+-   **Real-time Streaming (SSE, WebSockets):** The tool is designed for request-response interactions, not for maintaining persistent streaming connections.
+
+For scenarios that exceed these limitations, developing a [Custom Python Tool](/Tools/creating-a-tool) is the recommended approach.

docs/content/Tools/artifacts-and-code-execution.mdx

@@ -0,0 +1,101 @@
+---
+title: 📦 Artifacts and Code Execution
+description: Generate editable documents, run sandboxed code, and read files with the DocsGPT artifact, code executor, and read document tools.
+---
+
+import { Callout } from 'nextra/components';
+
+# Artifacts and Code Execution
+
+DocsGPT can generate documents, run code, and read files for you during a chat or inside an agent workflow. Three built-in tools work together for this:
+
+- **Artifact** builds and edits documents such as slide decks, Word documents, spreadsheets, PDFs, and HTML.
+- **Code Executor** runs code in a sandboxed session and turns any files the code writes into downloadable artifacts.
+- **Read Document** parses an uploaded or produced file (PDF, Word, PowerPoint, and more) into text, markdown, or structured data.
+
+All three are opt-in: enable Artifact and Code Executor per agent in the tool picker (they need a running [sandbox runner](https://github.com/arc53/DocsGPT/tree/main/deployment/sandbox)), and Read Document is available inside workflows. A new agent starts with no tools enabled.
+
+## Artifacts
+
+An **artifact** is a file the assistant produces that you can open, download, and edit later. Artifacts are versioned: every edit appends a new version at the same artifact, so you can review or restore an earlier one. Bytes are stored on the server and are never passed through the model, so large files stay fast and cheap to work with.
+
+In a normal chat, a produced artifact appears as a chip under the assistant's reply (for example, "Artifact"). Open it to:
+
+- preview the content in a side panel (HTML and similar kinds render inline),
+- download the file,
+- ask for changes, which create a new version.
+
+### The Artifact tool
+
+The Artifact tool keeps a structured spec as the source of truth and renders the file from it. Editing means changing the spec and re-rendering, which keeps a clean and diffable version history. It exposes three actions:
+
+- **create** a new artifact from a kind and a spec,
+- **edit** an existing artifact with a targeted change (preferred for small edits),
+- **rewrite** an artifact with a full replacement spec.
+
+Supported kinds are presentation (.pptx), document (.docx), spreadsheet (.xlsx), pdf, and html.
+
+## Code Executor
+
+The Code Executor runs Python in a sandboxed, stateful session bound to your conversation (or to a workflow run). Files the code writes into the workspace are captured as artifacts automatically, so a script that produces `report.csv` gives you a downloadable artifact with no extra steps.
+
+Key points:
+
+- The session is stateful, so variables, imports, and files persist between calls in the same conversation while it is kept alive.
+- Only a compact summary is returned to the model (an output tail plus artifact references), never raw file bytes.
+- Each run has a fixed wall-clock limit of about 60 seconds. For longer work, start it in the background and check back with more calls.
+- Install packages from inside the code itself when you need them.
+
+<Callout type="warning">
+  By default the Code Executor runs model-authored code without an approval
+  prompt. Turn on per-action approval on the agent if you want a human to
+  confirm each run.
+</Callout>
+
+### Run inputs
+
+You can pass files into a run. Each input accepts a short reference returned by a previous artifact action, a full artifact id, or the name or id of a file you attached to the conversation. The referenced files are placed in the workspace before the code runs.
+
+## Read Document
+
+Read Document parses a file into text, markdown, structured JSON (with tables), or chunks. It is meant for workflows where a node needs the contents of an uploaded or produced document, for example a compliance flow that extracts fields and validates them against a JSON schema.
+
+Parsing runs in the DocsGPT parsing worker rather than the sandbox, so it uses the same document engine as the rest of the product and works with every sandbox backend.
+
+## Using these tools in workflows
+
+Inside an agent workflow the same building blocks are available:
+
+- A **Code node** runs a script bound to the run, with the workflow state available to it as data.
+- Agent and code nodes can receive selected documents as inputs and hand files to each other by reference.
+- Produced artifacts are visible from the workflow run view.
+
+See [Workflow Nodes](/Agents/nodes) for the node-level details.
+
+## Configuration
+
+Code execution and rendering run inside a sandbox. DocsGPT ships two backends, selected with `SANDBOX_BACKEND`:
+
+- **`jupyter`** (default): a self-hosted runner that you operate. See the runner setup notes under `deployment/sandbox`.
+- **`daytona`**: Daytona Cloud, a managed per-session sandbox. Set `DAYTONA_API_KEY` and choose a region with `DAYTONA_TARGET`.
+
+### Render libraries on Daytona
+
+Artifact rendering imports `python-pptx`, `python-docx`, `openpyxl`, and `reportlab` inside the sandbox. The self-hosted runner already has them. Daytona's default image does not, so presentation, document, spreadsheet, and pdf rendering fail there until you point Daytona at an image that includes them. HTML and markdown artifacts need no extra libraries and work on any image.
+
+Build a snapshot with the libraries once, then set `DAYTONA_SNAPSHOT` to it:
+
+```bash
+# Reads DAYTONA_API_KEY / DAYTONA_API_URL / DAYTONA_TARGET from your environment:
+python scripts/build_daytona_snapshot.py
+# then set in your environment:
+#   DAYTONA_SNAPSHOT=docsgpt-artifacts-py312
+```
+
+### Useful settings
+
+- `SANDBOX_BACKEND`: `jupyter` or `daytona`.
+- `SANDBOX_EXEC_TIMEOUT`: per-run wall-clock cap in seconds.
+- `SANDBOX_MAX_TTL`: upper bound on how long a kept-alive session lives.
+- `DAYTONA_API_KEY`, `DAYTONA_TARGET`, `DAYTONA_SNAPSHOT`: Daytona Cloud settings.
+- Per-user artifact quotas bound how many artifacts and how much storage each user can hold.

docs/content/Tools/basics.mdx

@@ -0,0 +1,136 @@
+---
+title: Tools Basics - Enhancing DocsGPT Capabilities
+description: Understand what DocsGPT Tools are, how they work, and explore the built-in tools available to extend DocsGPT's functionality.
+---
+
+import { Callout } from 'nextra/components';
+import Image from 'next/image';
+import { ToolCards } from '../../components/ToolCards';
+
+# Understanding DocsGPT Tools
+
+DocsGPT Tools are powerful extensions that significantly enhance the capabilities of your DocsGPT application. 
+They allow DocsGPT to move beyond its core function of retrieving information from your documents and enable it to perform actions, 
+interact with external data sources, and integrate with other services. You can find and configure available tools within 
+the "Tools" section of the DocsGPT application settings in the user interface.
+
+## What are Tools?
+
+-   **Purpose:** The primary purpose of Tools is to bridge the gap between understanding a user's request (natural language processing by the LLM) and executing a tangible action. This could involve fetching live data from the web, sending notifications, running code snippets, querying databases, or interacting with third-party APIs.
+
+-   **LLM as an Orchestrator:** The Large Language Model (LLM) at the heart of DocsGPT is designed to act as an intelligent orchestrator. Based on your query and the declared capabilities of the available tools (defined in their metadata), the LLM decides if a tool is needed, which tool to use, and what parameters to pass to it.
+
+-   **Action-Oriented Interactions:** Tools enable more dynamic and action-oriented interactions. For example:
+    * *"What's the latest news on renewable energy?"* - This might trigger a web search tool to fetch current articles.
+    * *"Fetch the order status for customer ID 12345 from our database."* - This could use a database tool.
+    * *"Summarize the content of this webpage and send the summary to the #general channel on Telegram."* - This might involve a web scraping tool followed by a Telegram notification tool.
+
+## Overview of Built-in Tools
+
+DocsGPT includes a suite of pre-built tools designed to expand its capabilities out-of-the-box. Below is an overview of the currently available tools. 
+
+<ToolCards
+  items={[
+    {
+      title: 'API Tool',
+      link: '/Tools/api-tool',
+      description: 'A highly flexible tool that allows DocsGPT to interact with virtually any API without needing to write custom Python code.'
+    },
+    {
+      title: 'Brave Search',
+      link: 'https://github.com/arc53/DocsGPT/blob/main/application/agents/tools/brave.py',
+      description: 'Enables DocsGPT to perform real-time web and image searches using the Brave Search API. Requires an API key.'
+    },
+    {
+      title: 'DuckDuckGo Search',
+      link: 'https://github.com/arc53/DocsGPT/blob/main/application/agents/tools/duckduckgo.py',
+      description: 'Performs web and image searches using DuckDuckGo. No API key required.'
+    },
+    {
+      title: 'CryptoPrice',
+      link: 'https://github.com/arc53/DocsGPT/blob/main/application/agents/tools/cryptoprice.py',
+      description: 'Fetches the current price of specified cryptocurrencies using the CryptoCompare public API.'
+    },
+    {
+      title: 'Ntfy',
+      link: 'https://github.com/arc53/DocsGPT/blob/main/application/agents/tools/ntfy.py',
+      description: 'Allows DocsGPT to send push notifications to ntfy topics on a specified server, ideal for alerts and updates.'
+    },
+    {
+      title: 'Telegram Bot',
+      link: 'https://github.com/arc53/DocsGPT/blob/main/application/agents/tools/telegram.py',
+      description: 'Allows DocsGPT to send messages or images to Telegram chats via a Telegram Bot. Requires a bot token and chat ID.'
+    },
+    {
+      title: 'PostgreSQL Database',
+      link: 'https://github.com/arc53/DocsGPT/blob/main/application/agents/tools/postgres.py',
+      description: 'Connects to a PostgreSQL database to execute SQL queries and retrieve schema information.'
+    },
+    {
+      title: 'Read Webpage (browser)',
+      link: 'https://github.com/arc53/DocsGPT/blob/main/application/agents/tools/read_webpage.py',
+      description: 'Fetches the HTML content of a URL and converts it to Markdown for the agent to read.'
+    },
+    {
+      title: 'Remote Device',
+      link: '/Tools/remote-device',
+      description: 'Runs shell commands on a paired remote machine through the docsgpt-cli host. See the Remote Device guide.'
+    },
+    {
+      title: 'MCP Tool',
+      link: '/Guides/Integrations/mcp-tool-integration',
+      description: 'Connects to remote Model Context Protocol (MCP) servers to access their dynamic tools and resources.'
+    },
+    {
+      title: 'Memory',
+      link: 'https://github.com/arc53/DocsGPT/blob/main/application/agents/tools/memory.py',
+      description: 'Stores and retrieves information across conversations through a per-user memory file directory.'
+    },
+    {
+      title: 'Notepad',
+      link: 'https://github.com/arc53/DocsGPT/blob/main/application/agents/tools/notes.py',
+      description: 'A single editable note. Supports viewing, overwriting, and string replacement.'
+    },
+    {
+      title: 'Todo List',
+      link: 'https://github.com/arc53/DocsGPT/blob/main/application/agents/tools/todo_list.py',
+      description: 'Manages todo items — creating, viewing, updating, and deleting todos.'
+    }
+  ]}
+/>
+
+## Default Chat Tools
+
+In a regular chat (no custom agent), DocsGPT can enable a small set of tools automatically so the assistant is useful out of the box. These are the **default chat tools**, controlled by the `DEFAULT_CHAT_TOOLS` setting:
+
+```env
+DEFAULT_CHAT_TOOLS=memory,read_webpage,scheduler
+```
+
+- Default tools are config-free and run with synthetic, deterministic tool IDs (no manual setup needed).
+- Each user can opt out of individual default tools from their settings; the disabled list is stored per user.
+- Some default tools are excluded from **headless runs** (scheduled tasks and webhook triggers). For example, `scheduler` is skipped in those runs to prevent a scheduled task from chaining new schedules on every fire.
+
+To change the defaults for the whole instance, set `DEFAULT_CHAT_TOOLS` to a comma-separated list of tool names. See [App Configuration](/Deploying/DocsGPT-Settings) for the full settings reference.
+
+## Using Tools in DocsGPT (User Perspective)
+
+Interacting with tools in DocsGPT is designed to be intuitive:
+
+1.  **Natural Language Interaction:** As a user, you typically interact with DocsGPT using natural language queries or commands. The LLM within DocsGPT analyzes your input to determine if a specific task can or should be handled by one of the available and configured tools.
+
+2.  **Configuration in UI:**
+    * Tools are generally managed and configured within the DocsGPT application's settings, found under a "Tools" section in the GUI.
+    * For tools that interact with external services (like Brave Search, Telegram, or any service via the API Tool), you might need to provide authentication credentials (e.g., API keys, tokens) or specific endpoint information during the tool's setup in the UI.
+
+3.  **Prompt Engineering for Tools:** While the LLM aims to intelligently use tools, for more complex or reliable agent-like behaviors, you might need to customize the system prompts. Modifying the prompt can guide the LLM on when and how to prioritize or chain tools to achieve specific outcomes, especially if you're building an agent designed to perform a certain sequence of actions every time. For more on this, see [Customising Prompts](/Guides/Customising-prompts).
+
+## Advancing with Tools
+
+Understanding the basics of DocsGPT Tools opens up many possibilities:
+
+* **Leverage the API Tool:** For quick integrations with numerous external services, explore the [API Tool Detailed Guide](/Tools/api-tool).
+* **Develop Custom Tools:** If you have specific needs not covered by built-in tools or the generic API tool, you can develop your own. See our guide on `[Developing Custom Tools](/Tools/creating-a-tool)` (placeholder for now).
+* **Build AI Agents:** Tools are the fundamental building blocks for creating sophisticated AI agents within DocsGPT. Explore how these can be combined by looking into the `[Agents section/tab concept - link to be added once available]`.
+
+By harnessing the power of Tools, you can transform DocsGPT into a more versatile and proactive assistant tailored to your unique workflows.

docs/content/Tools/creating-a-tool.mdx

@@ -0,0 +1,186 @@
+---
+title: 🛠️ Creating a Custom Tool
+description: Learn how to create custom Python tools to extend DocsGPT's functionality and integrate with various services or perform specific actions.
+---
+
+import { Callout } from 'nextra/components';
+import { Steps } from 'nextra/components';
+
+# 🛠️ Creating a Custom Python Tool
+
+This guide provides developers with a comprehensive, step-by-step approach to creating their own custom tools for DocsGPT. By developing custom tools, you can significantly extend DocsGPT's capabilities, enabling it to interact with new data sources, services, and perform specialized actions tailored to your unique needs.
+
+## Introduction to Custom Tool Development
+
+### Why Create Custom Tools?
+
+While DocsGPT offers a range of built-in tools and a versatile API Tool, there are many scenarios where a custom Python tool is the best solution:
+
+* **Integrating with Proprietary Systems:** Connect to internal APIs, databases, or services that are not publicly accessible or require complex authentication.
+* **Adding Domain-Specific Functionalities:** Implement logic specific to your industry or use case that isn't covered by general-purpose tools.
+* **Automating Unique Workflows:** Create tools that orchestrate multiple steps or interact with systems in a way unique to your operational needs.
+* **Connecting to Any System with an Accessible Interface:** If you can interact with a system programmatically using Python (e.g., through libraries, SDKs, or direct HTTP requests), you can likely build a DocsGPT tool for it.
+* **Complex Logic or Data Transformation:** When API interactions require intricate logic before sending a request or after receiving a response, or when data needs significant transformation that is difficult for an LLM to handle directly.
+
+### Prerequisites
+
+Before you begin, ensure you have:
+
+* A solid understanding of Python programming.
+* Familiarity with the DocsGPT project structure, particularly the `application/agents/tools/` directory where custom tools reside.
+* Basic knowledge of how APIs work, as many tools involve interacting with external or internal APIs.
+* Your DocsGPT development environment set up. If not, please refer to the [Setting Up a Development Environment](/Deploying/Development-Environment) guide.
+
+## The Anatomy of a DocsGPT Tool
+
+Custom tools in DocsGPT are Python classes that inherit from a base `Tool` class and implement specific methods to define their behavior, capabilities, and configuration needs.
+
+The **foundation** for all custom tools is the abstract base class, located in `application/agents/tools/base.py`. Your custom tool class **must** inherit from this class.
+
+### Essential Methods to Implement
+
+Your custom tool class needs to implement the following methods:
+
+1. **`__init__(self, config: dict)`**
+    
+    - **Purpose:** The constructor for your tool. It's called when DocsGPT initializes the tool.
+    - **Usage:** This method is typically used to receive and store tool-specific configurations passed via the `config` dictionary. This dictionary is populated based on the tool's settings, often configured through the DocsGPT UI or environment variables. For example, you would store API keys, base URLs, or database connection strings here.
+    - **Example** (`brave.py`)**:**
+        ``` python
+        class BraveSearchTool(Tool):
+            def __init__(self, config):
+                self.config = config
+                self.token = config.get("token", "") # API Key for Brave Search
+                self.base_url = "https://api.search.brave.com/res/v1"
+        ```
+
+2. **`execute_action(self, action_name: str, **kwargs) -> dict`**
+    
+    - **Purpose:** This is the workhorse of your tool. The LLM, acting as an agent, calls this method when it decides to use one of the actions your tool provides.
+    - **Parameters:**
+        - `action_name` (str): A string specifying which of the tool's actions to run (e.g., "brave_web_search").
+        - `**kwargs` (dict): A dictionary containing the parameters for that specific action. These parameters are defined in the tool's metadata (`get_actions_metadata()`) and are extracted or inferred by the LLM from the user's query.
+    - **Return Value:** A dictionary containing the result of the action. It's good practice to include keys like:
+        - `status_code` (int): An HTTP-like status code (e.g., 200 for success, 500 for error).
+        - `message` (str): A human-readable message describing the outcome.
+        - `data` (any): The actual data payload returned by the action (if applicable).
+        - `error` (str): An error message if the action failed.
+    - **Example (`read_webpage.py`):**
+        
+        ``` python
+        def execute_action(self, action_name: str, **kwargs) -> str:
+            if action_name != "read_webpage":
+                return f"Error: Unknown action '{action_name}'. This tool only supports 'read_webpage'."
+        
+            url = kwargs.get("url")
+            if not url:
+                return "Error: URL parameter is missing."
+            # ... (logic to fetch and parse webpage) ...
+            try:
+                # ...
+                return markdown_content 
+            except Exception as e:
+                return f"Error processing URL {url}: {e}"
+        ```
+        
+        A more structured return:
+        
+        ``` python
+        # ... inside execute_action
+        try:
+            # ... logic ...
+            return {"status_code": 200, "message": "Webpage read successfully", "data": markdown_content}
+        except Exception as e:
+            return {"status_code": 500, "message": f"Error processing URL {url}", "error": str(e)}
+        ```
+        
+3. **`get_actions_metadata(self) -> list`**
+    
+    - **Purpose:** This method is **critical** for the LLM to understand what your tool can do, when to use it, and what parameters it needs. It effectively advertises your tool's capabilities.
+    - **Return Value:** A list of dictionaries. Each dictionary describes one distinct action the tool can perform and must follow a specific JSON schema structure.
+        - `name` (str): A unique and descriptive name for the action (e.g., `mytool_get_user_details`). It's a common convention to prefix with the tool name to avoid collisions.
+        - `description` (str): A clear, concise, and unambiguous description of what the action does. **Write this for the LLM.** The LLM uses this description to decide if this action is appropriate for a given user query.
+        - `parameters` (dict): A JSON Schema object defining the parameters that the action expects. This schema tells the LLM what arguments are needed, their types, and which are required.
+            - `type`: Should always be `"object"`.
+            - `properties`: A dictionary where each key is a parameter name, and the value is an object defining its `type` (e.g., "string", "integer", "boolean") and `description`.
+            - `required`: A list of strings, where each string is the name of a parameter that is mandatory for the action.
+    - **Example (`postgres.py` - partial):**
+        
+        ``` python
+        def get_actions_metadata(self):
+            return [
+                {
+                    "name": "postgres_execute_sql",
+                    "description": "Execute an SQL query against the PostgreSQL database...",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "sql_query": {
+                                "type": "string",
+                                "description": "The SQL query to execute.",
+                            },
+                        },
+                        "required": ["sql_query"],
+                        "additionalProperties": False, # Good practice to prevent unexpected params
+                    },
+                },
+                # ... other actions like postgres_get_schema
+            ]
+        ```
+        
+4. **`get_config_requirements(self) -> dict`**
+    
+    - **Purpose:** Defines the configuration parameters that your tool needs to function (e.g., API keys, specific base URLs, connection strings, default settings). This information can be used by the DocsGPT UI to dynamically render configuration fields for your tool or for validation.
+    - **Return Value:** A dictionary where keys are the configuration item names (which will be keys in the `config` dict passed to `__init__`) and values are dictionaries describing each requirement:
+        - `type` (str): The expected data type of the config value (e.g., "string", "boolean", "integer").
+        - `description` (str): A human-readable description of what this configuration item is for.
+        - `secret` (bool, optional): Set to `True` if the value is sensitive (e.g., an API key) and should be masked or handled specially in UIs. Defaults to `False`.
+    - **Example (`brave.py`):**
+        
+        ``` python
+        def get_config_requirements(self):
+            return {
+                "token": { # This 'token' will be a key in the config dict for __init__
+                    "type": "string",
+                    "description": "Brave Search API key for authentication",
+                    "secret": True
+                },
+            }
+        ```    
+
+## Tool Registration and Discovery
+
+DocsGPT's ToolManager (located in application/agents/tools/tool_manager.py) automatically discovers and loads tools.
+
+As long as your custom tool:
+
+1. Is placed in a Python file within the `application/agents/tools/` directory (and the filename is not `base.py` or starts with `__`).
+2. Correctly inherits from the `Tool` base class.
+3. Implements all the abstract methods (`execute_action`, `get_actions_metadata`, `get_config_requirements`).
+
+The `ToolManager` should be able to load it when DocsGPT starts. 
+
+## Configuration & Secrets Management
+
+- **Configuration Source:** The `config` dictionary passed to your tool's `__init__` method is typically populated from settings defined in the DocsGPT UI (if available for the tool) or from environment variables/configuration files that DocsGPT loads (see [⚙️ App Configuration](/Deploying/DocsGPT-Settings)). The keys in this dictionary should match the names you define in `get_config_requirements()`.
+- **Secrets:** Never hardcode secrets (like API keys or passwords) directly into your tool's Python code. Instead, define them as configuration requirements (using `secret: True` in `get_config_requirements()`) and let DocsGPT's configuration system inject them via the `config` dictionary at runtime. This ensures that secrets are managed securely and are not exposed in your codebase.
+
+## Best Practices for Tool Development
+
+- **Atomicity:** Design tool actions to be as atomic (single, well-defined purpose) as possible. This makes them easier for the LLM to understand and combine.
+- **Clarity in Metadata:** Ensure action names and descriptions in `get_actions_metadata()` are extremely clear, specific, and unambiguous. This is the primary way the LLM understands your tool.
+- **Robust Error Handling:** Implement comprehensive error handling within your `execute_action` logic (and the private methods it calls). Return informative error messages in the result dictionary so the LLM or user can understand what went wrong.
+- **Security:**
+    - Be mindful of the security implications of your tool, especially if it interacts with sensitive systems or can execute arbitrary code/queries.
+    - Validate and sanitize any inputs, especially if they are used to construct database queries or shell commands, to prevent injection attacks.
+- **Performance:** Consider the performance implications of your tool's actions. If an action is slow, it will impact the user experience. Optimize where possible.
+
+## (Optional) Contributing Your Tool
+
+If you develop a custom tool that you believe could be valuable to the broader DocsGPT community and is general-purpose:
+
+1. Ensure it's well-documented (both in code and with clear metadata).
+2. Make sure it adheres to the best practices outlined above.
+3. Consider opening a Pull Request to the [DocsGPT GitHub repository](https://github.com/arc53/DocsGPT) with your new tool, including any necessary documentation updates.
+
+By following this guide, you can create powerful custom tools that extend DocsGPT's capabilities to your specific operational environment.

docs/content/Tools/remote-device.mdx

@@ -0,0 +1,111 @@
+---
+title: 🖥️ Remote Device
+description: Run shell commands on a paired remote machine from a DocsGPT agent using docsgpt-cli host.
+---
+
+import { Callout } from 'nextra/components';
+
+# Remote Device Tool
+
+The Remote Device tool lets a DocsGPT agent run shell commands on a machine you control, such as a server, a Raspberry Pi, or your own laptop. You install `docsgpt-cli` on that machine, run it in `host` mode, and pair it with your DocsGPT account. The paired device then shows up as a tool you can attach to any agent.
+
+The machine connects outward to DocsGPT, so it works behind NAT or a firewall without opening any inbound ports.
+
+## How it works
+
+1. You run `docsgpt-cli host` on the target machine. It pairs to your account and keeps a lightweight connection open: it polls while idle and streams while a command is running.
+2. When an agent calls the device's `run_command` action, DocsGPT sends the command down to the daemon.
+3. The daemon runs the command locally, streams stdout and stderr back, and the agent uses the output to continue.
+4. Every invocation is recorded in the device's activity log.
+
+## Prerequisites
+
+- `docsgpt-cli` installed on the machine you want to control. See the [installation instructions](https://github.com/arc53/DocsGPT-cli#installation): download a binary from the [releases page](https://github.com/arc53/DocsGPT-cli/releases), use Homebrew (`brew tap arc53/docsgpt-cli && brew install docsgpt-cli`), or build from source.
+- Outbound internet access from that machine to your DocsGPT instance.
+
+<Callout type="info">
+  The `host` commands require a docsgpt-cli build with remote-device support. If `docsgpt-cli host` is not recognized, update to the latest release or build from source.
+</Callout>
+
+## Pair a device
+
+Pairing uses a short one-time code (a device-code style flow).
+
+1. In DocsGPT, go to **Settings -> Tools**, click **Add tool**, and choose **Remote Device**.
+2. Give it a name, an optional description (the agent sees this, so describe what the machine is for), and pick an approval mode. DocsGPT then shows a pairing code such as `ABCD-WXYZ` and the command to run.
+3. On the target machine, run:
+   ```bash
+   docsgpt-cli host pair --url https://your-docsgpt-instance
+   ```
+   Enter the code when prompted. (Omit `--url` to use the default cloud instance.)
+4. The UI switches to "Paired" once the code is redeemed. If you ran the command at a terminal, the CLI then offers to start the daemon or install it as a service.
+
+## Run the daemon
+
+Start it in the foreground:
+
+```bash
+docsgpt-cli host
+```
+
+You will see a startup banner, then periodic "idle" heartbeats. Press Ctrl-C to stop.
+
+To keep it running across reboots, install it as a service:
+
+```bash
+# Linux (systemd). As root this installs a system service; otherwise a user service.
+docsgpt-cli host install-service
+
+# macOS (launchd). The default is a per-user LaunchAgent that starts on login.
+docsgpt-cli host install-service
+
+# Always-on machine that starts at boot (Linux example):
+sudo docsgpt-cli host install-service --system --user $USER
+```
+
+Remove the service with `docsgpt-cli host uninstall-service`.
+
+## Approval modes
+
+The approval mode is set per device, either in the pairing form or later on the device's page under **Settings -> Tools**. There are two modes:
+
+- **Ask** (default): every command pauses for your approval before it runs. You approve it from the chat. You can also choose "approve and don't ask again" to auto-approve that command pattern in the future.
+- **Full access**: commands run without asking.
+
+<Callout type="warning">
+  A built-in safety denylist always applies, even in Full access mode. Catastrophic commands (for example `rm -rf /`, fork bombs, writing directly to a disk device, or `git push --force`) still pause for explicit approval and cannot be bypassed.
+</Callout>
+
+Compound commands are split on operators such as `&&`, `||`, `;`, and `|`, and each part is checked on its own, so a dangerous part cannot be hidden behind a safe one.
+
+## Attach to an agent
+
+A paired device behaves like any other tool. Open or create an agent, add the device from the tool picker, and the agent can call its `run_command` action. The picker shows whether the device is currently online.
+
+If you attach more than one device to an agent, give each a clear description so the agent can pick the right one.
+
+## Manage a device
+
+Open the device from **Settings -> Tools** to:
+
+- See its status (online or offline, with last-seen time), host, OS, and CLI version.
+- Change its name, description, or approval mode.
+- View recent activity (the command audit log).
+- Revoke it.
+
+From the CLI:
+
+```bash
+docsgpt-cli host status   # live status from the server
+docsgpt-cli host revoke   # revoke on the server and clear local state
+docsgpt-cli host reset    # clear local pairing only (leaves the server-side device)
+```
+
+Revoking a device stops its daemon: the next time it checks in it sees the revocation, prints a message, and exits. Under a service manager it will not be restarted.
+
+## Security notes
+
+- The machine connects outward only. No inbound ports are opened.
+- Each device has its own token, stored hashed on the server and revocable at any time.
+- Prefer **Ask** mode for any machine with sensitive data on it. Use **Full access** only on machines you are comfortable letting an agent drive unattended, and remember that the denylist is the only automatic guard in that mode.
+- Every command is logged on the server and visible in the device's activity log.