Tools
=====

A **tool** is anything an agent can invoke by name. Every tool AIDB
knows about — built-in, custom, or imported from an MCP server — is
listed in one place, ``aidb.tools`` :

.. code:: sql

   SELECT name, tool_type, read_only FROM aidb.tools;

   __OUTPUT__
           name         | tool_type   | read_only
   - --------------------+-------------+-----------
    chunk_text          | native_tool | t
    create_agent        | native_tool | f
    ...

Tools can be invoked in three different ways:

1. natively by the internal agents in AIDB.

2. by external agents via MCP.

3. through SQL for testing and development or other custom use cases.

.. code:: sql

   SELECT aidb.run_tool(catalog_list_objects, {"schema": "public", "object_type": "table"});

   __OUTPUT__
           run_tool
   - --------------------------------------------
    {"comment": null, "truncated": false, "object_name": "my_table", "object_type": "table", "schema_name": "public"},  ...

AIDB has three kinds of tools:

- **``native_tool``** — AIDB’s own built-in catalog. Always available;
  can’t be added, removed, or reconfigured. See :ref:`Native tools <Native tools>`  .

- **``sql_tool``** — a parameterized SQL query you register yourself.
  See :ref:`Custom SQL tools <Custom SQL tools>`  .

- **``mcp_tool``** — a tool imported from an external MCP server. See
  :ref:`MCP tools <MCP tools>`  .

Give an agent access to a tool by listing its name in :ref:`aidb.create_agent <aidb.create_agent>`  ’s
``tools`` array.

Documentation map
-----------------

.. csv-table::
  :header: Page,What it covers
  :widths: 10,30
  :align: left
  :class: longtable

  :ref:`Native tools<Native tools>` ,"AIDB's built-in tool catalog: ad hoc SQL, catalog discovery, semantic knowledge bases, models, volumes, embedding and document processing, agent management, pipelines"
  :ref:`Custom SQL tools<Custom SQL tools>` ,"`aidb.create_sql_tool()`, naming, parameter placeholders, read-only enforcement, removing tools"
  :ref:`MCP tools<MCP tools>` ,"`aidb.import_mcp_tools()`, authentication, filtering, refreshing, removing servers, exposing AIDB's tools over MCP"

For full parameter tables and return types, see :ref:`Tools reference <Tools reference>`  .

.. toctree::
  :maxdepth: 3

  tools--native-tools
  tools--custom-sql-tools
  tools--mcp-tools