Built-in Tools

PrivateGPT exposes tools in two ways:

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

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.

Minimal example:

1
{
2
  "tools": [
3
    {"name": "search_docs", "type": "semantic_search_v1"},
4
    {"name": "search_web", "type": "web_search_v1"},
5
    {"name": "fetch_url", "type": "web_fetch_v1"}
6
  ]
7
}

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

Example: semantic_search_v1

Requires context with an ingested artifact.

1
{
2
  "model": "qwen3.5:35b",
3
  "messages": [
4
    {"role": "user", "content": "What are the payment terms in the contract?"}
5
  ],
6
  "tools": [
7
    {
8
      "name": "search_docs",
9
      "type": "semantic_search_v1",
10
      "context": [
11
        {
12
          "type": "ingested_artifact",
13
          "context_filter": {"collection": "contracts"}
14
        }
15
      ]
16
    }
17
  ]
18
}

Example: tabular_analysis_v1

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

1
{
2
  "model": "qwen3.5:35b",
3
  "messages": [
4
    {"role": "user", "content": "What is the total revenue by region?"}
5
  ],
6
  "tools": [
7
    {
8
      "name": "analyze_sales",
9
      "type": "tabular_analysis_v1",
10
      "context": [
11
        {
12
          "type": "ingested_artifact",
13
          "context_filter": {"collection": "sales-data"}
14
        }
15
      ]
16
    }
17
  ]
18
}

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.

1
{
2
  "model": "qwen3.5:35b",
3
  "messages": [
4
    {"role": "user", "content": "How many orders were placed last month?"}
5
  ],
6
  "tools": [
7
    {
8
      "name": "query_db",
9
      "type": "database_query_v1",
10
      "context": [
11
        {
12
          "type": "sql_database",
13
          "connection_string": "postgresql://user:pass@localhost:5432/mydb",
14
          "description": "Orders database"
15
        }
16
      ]
17
    }
18
  ]
19
}

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:

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.

1
{
2
  "model": "qwen3.5:35b",
3
  "messages": [
4
    {"role": "user", "content": "Find recent news about open source LLMs."}
5
  ],
6
  "tools": [
7
    {
8
      "name": "search_web",
9
      "type": "web_search_v1"
10
    }
11
  ]
12
}

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.

1
{
2
  "model": "qwen3.5:35b",
3
  "messages": [
4
    {"role": "user", "content": "Fetch and summarize https://example.com/article"}
5
  ],
6
  "tools": [
7
    {
8
      "name": "fetch_url",
9
      "type": "web_fetch_v1"
10
    }
11
  ]
12
}

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.

Example:

1
{
2
  "model": "qwen3.5:35b",
3
  "messages": [
4
    {"role": "user", "content": "Show me the available skills for this workspace."}
5
  ],
6
  "tool_context": [
7
    {
8
      "type": "skill",
9
      "skill_filter": {"collection": "my-org"}
10
    }
11
  ],
12
  "tools": [
13
    {"name": "skills", "type": "skills_v1"}
14
  ]
15
}

Direct load_skill_v1 example:

1
{
2
  "model": "qwen3.5:35b",
3
  "messages": [
4
    {"role": "user", "content": "Load the legal-reviewer skill."}
5
  ],
6
  "tool_context": [
7
    {
8
      "type": "skill",
9
      "skill_filter": {"collection": "my-org"}
10
    }
11
  ],
12
  "tools": [
13
    {"name": "load_skill", "type": "load_skill_v1"}
14
  ]
15
}

Code execution in chat

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

1. code_execution_v1 expands into bash_v1 and text_editor_v1.
2. 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

1
{
2
  "model": "qwen3.5:35b",
3
  "messages": [
4
    {"role": "user", "content": "Inspect the workspace and tell me which files matter."}
5
  ],
6
  "tools": [
7
    {"name": "code_execution", "type": "code_execution_v1"}
8
  ]
9
}

Example: bash_v1

1
{
2
  "model": "qwen3.5:35b",
3
  "messages": [
4
    {"role": "user", "content": "Run ls in the workspace."}
5
  ],
6
  "tools": [
7
    {"name": "bash", "type": "bash_v1"}
8
  ]
9
}

Example: text_editor_v1

1
{
2
  "model": "qwen3.5:35b",
3
  "messages": [
4
    {"role": "user", "content": "Open README.md and inspect it."}
5
  ],
6
  "tools": [
7
    {"name": "text_editor", "type": "text_editor_v1"}
8
  ]
9
}

Direct text editor subtools

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:

Example:

1
{
2
  "model": "claude-sonnet-4-20250514",
3
  "messages": [
4
    {"role": "user", "content": "Open README.md and show me the first 40 lines."}
5
  ],
6
  "tools": [
7
    {"name": "bash", "type": "bash_20250124"},
8
    {"name": "str_replace_based_edit_tool", "type": "text_editor_20250124"},
9
    {"name": "computer", "type": "computer_20250124"},
10
    {"name": "memory", "type": "memory_20250124"}
11
  ]
12
}

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].

1
{
2
  "tools": [
3
    {
4
      "name": "get_order_status",
5
      "description": "Get the current status of a customer order",
6
      "inputSchema": {
7
        "type": "object",
8
        "properties": {
9
          "order_id": {"type": "string", "description": "The order ID"}
10
        },
11
        "required": ["order_id"]
12
      }
13
    }
14
  ]
15
}

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

1
{"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:

1
{
2
  "role": "user",
3
  "content": [
4
    {
5
      "type": "tool_result",
6
      "tool_use_id": "tu_01abc",
7
      "content": "Order ORD-123 is shipped and arrives Thursday."
8
    }
9
  ]
10
}

Standalone tool endpoints

Semantic search

Search ingested documents using natural language:

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

$
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].

$
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].

$
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].

$
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:

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. See Database Tools for install and configuration.

$
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:

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