Tools reference =============== Reference for tool-related functions, views, and types. For guide-style documentation, see :ref:`Tools reference ` . For the full native tool catalog, see :ref:`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. .. csv-table:: :header: Column,Type,Description :widths: 12,15,25 :align: left :class: longtable `name`,text,The tool's name. `description`,text,Shown to the model as part of the tool's definition. `tool_type`,text,"`'native_tool'`, `'sql_tool'`, or `'mcp_tool'`." `params`,jsonb,"For `native_tool`/`sql_tool`: an array of `{name, type, description}` objects. For `mcp_tool`: the server's raw JSON Schema `inputSchema`." `read_only`,boolean,Whether the tool is known to never write. Always `false` for `mcp_tool` rows — see :ref:`Read-only mode` . 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. .. csv-table:: :header: Column,Type,Description :widths: 12,15,25 :align: left :class: longtable `name`,text,Unique tool name (primary key). `description`,text,Shown to the model. `query_text`,text,"The stored SQL statement, with `${name}` placeholders." `read_only`,boolean,Whether the tool is enforced as read-only. `return_type_hint`,`aidb.ToolParam[]`,Documented return shape. Not currently surfaced to the model. `params`,`aidb.ToolParam[]`,The tool's declared parameters. `created_at`,timestamp,Creation time. `updated_at`,timestamp,Last update time. aidb.mcp_registry ^^^^^^^^^^^^^^^^^ Registered external MCP servers. .. csv-table:: :header: Column,Type,Description :widths: 12,15,25 :align: left :class: longtable `name`,text,Unique server name (primary key). `url`,text,The server's MCP endpoint. `transport`,text,`'streamable_http'` or `'sse'`. `headers`,jsonb,Stored request headers. Not readable by `aidb_users` (may hold secrets). `headers_env`,text,Environment variable name to read headers from instead. Mutually exclusive with `headers`. `tool_filter`,text[],"Tool names imported from this server, if filtered." `created_at`,timestamp,Registration time. `updated_at`,timestamp,Last update time. -------------- Tool management functions ------------------------- aidb.create_sql_tool ^^^^^^^^^^^^^^^^^^^^ Registers a parameterized SQL query as a tool. Parameters ^^^^^^^^^^ .. csv-table:: :header: Parameter,Type,Default,Description :widths: 15,12,12,20 :align: left :class: longtable `name`,TEXT,Required,Unique name for the tool. `description`,TEXT,Required,Shown to the model as part of the tool's definition. `sql_statement`,TEXT,Required,"The query to run, with `${name}` placeholders for each declared parameter." `params`,JSONB,Required,"The tool's parameters, built with `aidb.tool_params()`." `read_only`,BOOLEAN,`true`,"If `true`, reject the statement at registration time unless it's provably read-only." `return_type_hint`,JSONB,NULL,Documents the query's return shape. Not currently surfaced to the model. 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 ^^^^^^^ .. code:: sql 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 customers 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-1: Parameters ^^^^^^^^^^ .. csv-table:: :header: Parameter,Type,Description :widths: 12,15,25 :align: left :class: longtable `name`,TEXT,The tool or server name. .. _returns-1: 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-2: Parameters ^^^^^^^^^^ .. csv-table:: :header: Parameter,Type,Default,Description :widths: 15,12,12,20 :align: left :class: longtable `name`,TEXT,Required,Unique name for the server registration. `url`,TEXT,Required,The server's MCP endpoint URL. `transport`,TEXT,`'streamable_http'`,`'streamable_http'` or `'sse'` — only `'streamable_http'` is fully supported today. `headers`,JSONB,NULL,Request headers to send. Mutually exclusive with `headers_env`. `tool_filter`,TEXT[],NULL,Import only these tool names. Omit to import everything the server advertises. `headers_env`,TEXT,NULL,"Environment variable holding the headers JSON, read fresh on each use instead of storing it. Mutually exclusive with `headers`. Name must start with the :ref:`AI pipelines ` prefix." .. _returns-2: 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-1: Example ^^^^^^^ .. code:: sql 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. 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. Default: NULL ); -------------- aidb.refresh_mcp_tools ^^^^^^^^^^^^^^^^^^^^^^ Re-fetches an already-registered MCP server’s advertised tools and refreshes the cache. .. _parameters-3: Parameters ^^^^^^^^^^ .. csv-table:: :header: Parameter,Type,Description :widths: 12,15,25 :align: left :class: longtable `name`,TEXT,The registered server's name. .. _returns-3: 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-4: Returns ^^^^^^^ ``TABLE(name TEXT, description TEXT, input_schema JSONB)`` — one row per tool in ``aidb.tools`` . -------------- Parameter helpers ----------------- aidb.tool_param ^^^^^^^^^^^^^^^ Builds one SQL tool parameter. .. _parameters-4: Parameters ^^^^^^^^^^ .. csv-table:: :header: Parameter,Type,Default,Description :widths: 15,12,12,20 :align: left :class: longtable `name`,TEXT,Required,The parameter's name. `type`,TEXT,Required,The parameter's SQL type. `description`,TEXT,Required,Description shown to the model. .. _returns-5: 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-5: Parameters ^^^^^^^^^^ .. csv-table:: :header: Parameter,Type,Description :widths: 12,15,25 :align: left :class: longtable `params`,VARIADIC JSONB[],Zero or more `aidb.tool_param()` results. .. _returns-6: 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()`` .