Built-in Tools

PrivateGPT exposes tools in two ways:

Model-driven tool use — pass tools in the tools array of /v1/messages and let the model decide when to call them.
Standalone tool endpoints (/v1/tools/*) — call them directly without going through a chat.

<Note> Built-in tool dependencies are granular. Install the specific extra for the feature you need, or use `private-gpt[tools]` as the bundle fallback. `private-gpt[core]` also includes that bundle. </Note>

Tools in messages

Pass tools in /v1/messages and the model decides when to call them.

Model-driven tool use follows the same per-tool dependency rules. For the broadest support, use private-gpt[tools] or private-gpt[core].

Built-in server tools

Built-in server tools only require name and type. Do not provide inputSchema for built-in tools. Add context only for built-in tools that require it.

Type identifier	Tool	Notes
`semantic_search_v1`	Search ingested documents	Available in `private-gpt[core]` and installs with ingestion support
`tabular_analysis_v1`	Analyze ingested tabular data	Requires `tool-tabular` or `tools`
`database_query_v1`	Query a SQL database	Requires database extras
`web_search_v1`	Search the web	Requires `tool-web-scraping` or `tools`
`web_fetch_v1`	Fetch and extract text from a URL	Requires `tool-web-scraping` or `tools`

Minimal example:

json

{
  "tools": [
    {"name": "search_docs", "type": "semantic_search_v1"},
    {"name": "search_web", "type": "web_search_v1"},
    {"name": "fetch_url", "type": "web_fetch_v1"}
  ]
}

For server-side setup of web tools, see Web Tools.

Example: `semantic_search_v1`

Requires context with an ingested artifact.

json

{
  "model": "qwen3.5:35b",
  "messages": [
    {"role": "user", "content": "What are the payment terms in the contract?"}
  ],
  "tools": [
    {
      "name": "search_docs",
      "type": "semantic_search_v1",
      "context": [
        {
          "type": "ingested_artifact",
          "context_filter": {"collection": "contracts"}
        }
      ]
    }
  ]
}

Example: `tabular_analysis_v1`

Requires private-gpt[tool-tabular], private-gpt[tools], or private-gpt[core]. Also requires context with an ingested artifact.

json

{
  "model": "qwen3.5:35b",
  "messages": [
    {"role": "user", "content": "What is the total revenue by region?"}
  ],
  "tools": [
    {
      "name": "analyze_sales",
      "type": "tabular_analysis_v1",
      "context": [
        {
          "type": "ingested_artifact",
          "context_filter": {"collection": "sales-data"}
        }
      ]
    }
  ]
}

Example: `database_query_v1`

Requires private-gpt[tool-database], private-gpt[database], or a driver-specific extra such as private-gpt[database-postgres]. private-gpt[tools] and private-gpt[core] also work. Also requires context with a sql_database artifact. See Database Tools for install and configuration.

json

{
  "model": "qwen3.5:35b",
  "messages": [
    {"role": "user", "content": "How many orders were placed last month?"}
  ],
  "tools": [
    {
      "name": "query_db",
      "type": "database_query_v1",
      "context": [
        {
          "type": "sql_database",
          "connection_string": "postgresql://user:pass@localhost:5432/mydb",
          "description": "Orders database"
        }
      ]
    }
  ]
}

Connection strings commonly use these schemes:

PostgreSQL: postgresql://...
MySQL: mysql://..., mysql+mysqldb://..., or mysql+pymysql://...
SQL Server: mssql+pyodbc://...
DB2: db2://... or ibm_db_sa://...

Examples:

text

postgresql://user:pass@localhost:5432/mydb
mysql://user:pass@localhost:3306/mydb
mssql+pyodbc://user:pass@localhost:1433/mydb?driver=ODBC+Driver+18+for+SQL+Server
db2://user:pass@localhost:50000/sample

Example: `web_search_v1`

Requires private-gpt[tool-web-scraping], private-gpt[tools], or private-gpt[core]. No context is required.

json

{
  "model": "qwen3.5:35b",
  "messages": [
    {"role": "user", "content": "Find recent news about open source LLMs."}
  ],
  "tools": [
    {
      "name": "search_web",
      "type": "web_search_v1"
    }
  ]
}

Example: `web_fetch_v1`

web_extract_v1 remains accepted as a legacy alias.

Requires private-gpt[tool-web-scraping], private-gpt[tools], or private-gpt[core]. No context is required.

json

{
  "model": "qwen3.5:35b",
  "messages": [
    {"role": "user", "content": "Fetch and summarize https://example.com/article"}
  ],
  "tools": [
    {
      "name": "fetch_url",
      "type": "web_fetch_v1"
    }
  ]
}

Skills in chat

The built-in skill tool is name: "skills" with type: "skills_v1". It expands into load_skill_v1, unload_skill_v1, and list_skills_v1.

These built-in skill tools require a skill filter in tool_context.

Type identifier	Tool
`skills_v1`	Expand into `load_skill_v1`, `unload_skill_v1`, and `list_skills_v1`
`load_skill_v1`	Mark one available skill as loaded
`unload_skill_v1`	Mark one loaded skill as unloaded
`list_skills_v1`	List skills in the current skill filter

Example:

json

{
  "model": "qwen3.5:35b",
  "messages": [
    {"role": "user", "content": "Show me the available skills for this workspace."}
  ],
  "tool_context": [
    {
      "type": "skill",
      "skill_filter": {"collection": "my-org"}
    }
  ],
  "tools": [
    {"name": "skills", "type": "skills_v1"}
  ]
}

Direct load_skill_v1 example:

json

{
  "model": "qwen3.5:35b",
  "messages": [
    {"role": "user", "content": "Load the legal-reviewer skill."}
  ],
  "tool_context": [
    {
      "type": "skill",
      "skill_filter": {"collection": "my-org"}
    }
  ],
  "tools": [
    {"name": "load_skill", "type": "load_skill_v1"}
  ]
}

Code execution in chat

PrivateGPT exposes built-in code-execution tools in two layers:

code_execution_v1 expands into bash_v1 and text_editor_v1.
text_editor_v1 expands into view_v1, str_replace_v1, create_v1, and insert_v1.

These are built-in server tools executed by PrivateGPT.

code_execution_v1 is a server tool. Anthropic code_execution_* tool types translate to this server-side flow in PrivateGPT. That is different from Anthropic bash_* and text_editor_*, which are client tools passed back to the API caller.

Anthropic reference: Code execution tool.

Example: `code_execution_v1`

json

{
  "model": "qwen3.5:35b",
  "messages": [
    {"role": "user", "content": "Inspect the workspace and tell me which files matter."}
  ],
  "tools": [
    {"name": "code_execution", "type": "code_execution_v1"}
  ]
}

Example: `bash_v1`

json

{
  "model": "qwen3.5:35b",
  "messages": [
    {"role": "user", "content": "Run ls in the workspace."}
  ],
  "tools": [
    {"name": "bash", "type": "bash_v1"}
  ]
}

Example: `text_editor_v1`

json

{
  "model": "qwen3.5:35b",
  "messages": [
    {"role": "user", "content": "Open README.md and inspect it."}
  ],
  "tools": [
    {"name": "text_editor", "type": "text_editor_v1"}
  ]
}

Direct text editor subtools

Type identifier	Tool
`view_v1`	View a file or directory
`str_replace_v1`	Replace one exact string in a file
`create_v1`	Create a new file
`insert_v1`	Insert text after a given line

Anthropic-compatible client tools

PrivateGPT also accepts Anthropic-style client tool types. These are passed through to your application with canonical schemas; PrivateGPT does not execute them locally.

Supported client tool families:

Type pattern	Canonical name	Executed by	More info
`bash_*`	`bash`	API caller	Anthropic bash tool
`text_editor_*`	`str_replace_based_edit_tool`	API caller	Anthropic text editor tool
`computer_*`	`computer`	API caller	Anthropic computer use tool
`memory_*`	`memory`	API caller	Anthropic memory tool

Example:

json

{
  "model": "claude-sonnet-4-20250514",
  "messages": [
    {"role": "user", "content": "Open README.md and show me the first 40 lines."}
  ],
  "tools": [
    {"name": "bash", "type": "bash_20250124"},
    {"name": "str_replace_based_edit_tool", "type": "text_editor_20250124"},
    {"name": "computer", "type": "computer_20250124"},
    {"name": "memory", "type": "memory_20250124"}
  ]
}

Custom tools

Define any tool with a JSON Schema. PrivateGPT passes the tool definition to the model; when the model calls it, your application receives a tool_use block and must return a tool_result:

For the broadest tool-calling support, use private-gpt[tools] or private-gpt[core].

json

{
  "tools": [
    {
      "name": "get_order_status",
      "description": "Get the current status of a customer order",
      "inputSchema": {
        "type": "object",
        "properties": {
          "order_id": {"type": "string", "description": "The order ID"}
        },
        "required": ["order_id"]
      }
    }
  ]
}

When the model wants to call the tool, the response contains:

json

{"type": "tool_use", "id": "tu_01abc", "name": "get_order_status", "input": {"order_id": "ORD-123"}}

Send the result back by appending a message with role: "user" containing a tool_result block:

json

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "tu_01abc",
      "content": "Order ORD-123 is shipped and arrives Thursday."
    }
  ]
}

Standalone tool endpoints

Semantic search

Search ingested documents using natural language:

Available in private-gpt[core] and installs with ingestion support.

bash

curl -X POST http://localhost:8080/v1/tools/semantic-search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the payment terms?",
    "context_filter": {"collection": "contracts"}
  }'

Web search

Search the web and get aggregated results:

Requires private-gpt[tool-web-scraping], private-gpt[tools], or private-gpt[core].

bash

curl -X POST http://localhost:8080/v1/tools/web-search \
  -H "Content-Type: application/json" \
  -d '{"query": "latest news about open source LLMs"}'

Web fetch

Fetch and extract text content from a URL:

Requires private-gpt[tool-web-scraping], private-gpt[tools], or private-gpt[core].

bash

curl -X POST http://localhost:8080/v1/tools/web-fetch \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/article"}'

Tabular data analysis

Run a natural language query against CSV or tabular data ingested into a collection:

Requires private-gpt[tool-tabular], private-gpt[tools], or private-gpt[core].

bash

curl -X POST http://localhost:8080/v1/tools/tabular-data-analysis \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is the total revenue by region?",
    "context_filter": {"collection": "sales-data"}
  }'

Database query

Run a natural language query against a connected SQL database:

bash

curl -X POST http://localhost:8080/v1/tools/database-query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How many orders were placed last month?",
    "artifacts": [
      {
        "type": "sql_database",
        "connection_string": "postgresql://user:pass@localhost/mydb"
      }
    ]
  }'

The artifacts entry must contain a sql_database object with a valid SQLAlchemy-style connection string, for example:

text

postgresql://user:pass@localhost:5432/mydb
mysql://user:pass@localhost:3306/mydb
mssql+pyodbc://user:pass@localhost:1433/mydb?driver=ODBC+Driver+18+for+SQL+Server
db2://user:pass@localhost:50000/sample

Tools in messages

Built-in server tools

Example: semantic_search_v1

Example: tabular_analysis_v1

Example: database_query_v1

Example: web_search_v1

Example: web_fetch_v1

Skills in chat

Code execution in chat

Example: code_execution_v1

Example: bash_v1

Example: text_editor_v1

Direct text editor subtools

Anthropic-compatible client tools

Custom tools

Standalone tool endpoints

Semantic search

Web search

Web fetch

Tabular data analysis

Database query

Example: `semantic_search_v1`

Example: `tabular_analysis_v1`

Example: `database_query_v1`

Example: `web_search_v1`

Example: `web_fetch_v1`

Example: `code_execution_v1`

Example: `bash_v1`

Example: `text_editor_v1`