Tools reference v7

Reference for tool-related functions, views, and types. For guide-style documentation, see Tools. For the full native tool catalog, see Native tools.

Catalog views

aidb.tools

The unified, read-only catalog of every tool AIDB knows about — the union of native tools, registered SQL tools, and cached MCP tools.

aidb.sql_tool_registry

Backs registered SQL tools. aidb.tools is the union view most queries should use instead; query this directly to see a SQL tool's stored query text.

aidb.mcp_registry

Registered external MCP servers.

Tool management functions

aidb.create_sql_tool

Registers a parameterized SQL query as a tool.

Parameters

Returns

TEXT — the tool's name, on success. Raises if the name is already taken (by any tool type) or the statement isn't a single, invocable, read-only-compliant (if read_only => true) statement.

Example

SELECT aidb.create_sql_tool(
    name             => 'orders_by_customer',
    description      => 'Look up recent orders for a customer by id.',
    sql_statement    => 'SELECT id, status, total FROM orders WHERE customer_id = ${customer_id} ORDER BY created_at DESC LIMIT ${limit}',
    params           => aidb.tool_params(
        aidb.tool_param('customer_id', 'INT', 'The customer''s id.'),
        aidb.tool_param('limit', 'INT', 'Maximum number of orders to return.')
    ),
    read_only        => true,  -- optional; enforced, not just descriptive. Default: true
    return_type_hint => NULL   -- optional; documents the returned row shape, same aidb.tool_params() shape as `params`. Default: NULL
);

aidb.delete_tool

Deletes a SQL tool or an MCP server registration by name (removing every tool the server advertised along with it). Built-in native tools can't be deleted.

Parameters

Returns

TEXT — the deleted name, on success. Raises if no such tool or server exists, or if name is a native tool.

aidb.import_mcp_tools

Registers an external MCP server and imports the tools it advertises.

Parameters

Returns

TEXT — the server's name, on success. Raises if the name is taken, the URL is unreachable, or no advertised tool matches tool_filter.

Example

SELECT aidb.import_mcp_tools(
    name        => 'weather',
    url         => 'https://weather.example.com/mcp',
    transport   => 'streamable_http',  -- optional; 'streamable_http' or 'sse'. Default: 'streamable_http'
    headers     => NULL,               -- optional; request headers to send, for example, an auth token. Mutually exclusive with headers_env and headers_k8s_secret. Default: NULL
    tool_filter => NULL,               -- optional; import only these tool names. Default: NULL (import everything the server advertises)
    headers_env => NULL,               -- optional; env var holding the headers JSON instead of storing it. Mutually exclusive with headers and headers_k8s_secret. Default: NULL
    headers_k8s_secret => NULL         -- optional; file path to a mounted Kubernetes Secret holding the headers JSON. Mutually exclusive with headers and headers_env. Default: NULL
);

aidb.refresh_mcp_tools

Re-fetches an already-registered MCP server's advertised tools and refreshes the cache.

Parameters

Returns

INTEGER — the number of tools now cached (after tool_filter applies).

aidb.get_mcp_tools

Converts every currently registered tool (native, SQL, and MCP alike) into an MCP tools/list-shaped descriptor.

Returns

TABLE(name TEXT, description TEXT, input_schema JSONB) — one row per tool in aidb.tools.

aidb.run_tool

Runs any tool in aidb.tools by name, whether native, SQL, or MCP, and returns its result. The tool runs as the caller's own session role. A read_only SQL tool runs read only. That doesn't change the caller's transaction, which can still write afterward. The MCP server dispatches catalog tools through this function.

Parameters

Returns

JSONB, the tool's result. The function raises an error if:

• The tool doesn't exist.
• arguments isn't a JSON object.
• arguments has a key the tool doesn't declare.
• arguments leaves out a required argument.
• An MCP tool returns an isError result.

Example

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

Parameter helpers

aidb.tool_param

Builds one SQL tool parameter.

Parameters

Returns

JSONB — pass one or more of these to aidb.tool_params().

aidb.tool_params

Combines one or more aidb.tool_param() results, or (called with no arguments) declares an empty parameter list.

Parameters

Returns

JSONB — pass to aidb.create_sql_tool()'s params or return_type_hint.

aidb.param / aidb.params

Generic parameter-spec constructors, used by native tools that accept an enum-constrained argument. aidb.param() additionally accepts enum_values TEXT[]. Not typically needed directly — aidb.tool_param()/aidb.tool_params() are the constructors for create_sql_tool().