Native tools ============ AIDB ships with a large built-in catalog of native tools — mostly thin wrappers around existing AIDB functionality, so an agent can operate on pipelines, knowledge bases, models, and volumes the same way you would from SQL directly. This is one of three tool types AIDB supports — see :ref:`Tools reference ` for the full catalog, including :ref:`Custom SQL tools ` and :ref:`MCP tools ` . ``sleep`` is always available to every agent regardless of its configured ``tools`` list — unless the backing model caps how many tools a request can carry and the agent’s other configured tools already fill that cap — since it backs the reasoning loop’s own ability to pause and resume. Every other native tool must be explicitly listed in ``tools`` to be usable. A tool’s exact parameters are always visible with ``SELECT params FROM aidb.tools WHERE name = ''`` ; the tables below give the one-line description and read-only status for each. Ad hoc SQL ---------- .. csv-table:: :header: Tool,Read-only,Description :widths: 12,15,25 :align: left :class: longtable `run_sql_query`,Yes,Run a read-only SQL query against the database and return its rows as JSON. Catalog discovery ----------------- Introspection of the database catalog: these tools let an agent discover what schemas, tables, views, and functions exist, without having to construct ``information_schema`` /``pg_catalog`` queries itself. They’re related to the :ref:`Semantic knowledge bases ` below, but the two are complementary rather than interchangeable: - **Catalog discovery tools** do live, exact lookups against the Postgres catalog. They need no setup, always reflect the current state of the database, and match by exact name or SQL ``LIKE`` pattern. - **Semantic knowledge base tools** run semantic (vector) search over a crawled snapshot of the schema. They require a pre-built, opt-in knowledge base (and a re-crawl to pick up structural changes), but can answer natural-language questions like “which table holds customer contact info?” that exact catalog lookups can’t. A typical agent uses both: semantic search to find the right table from a vague description, then catalog discovery to get its exact, current columns and foreign keys. All four tools are privilege-aware — they only return objects the calling user can actually see. Listings hide Postgres and AIDB internal schemas as well as installed extensions’ schemas and objects by default (``catalog_get_object_details`` deliberately doesn’t hide extension objects: explicitly naming one is asking for it). Listings are capped at 200 rows; every row carries a ``truncated`` flag that’s ``true`` when more rows exist, signaling the caller to narrow the search with ``schema`` or ``name_pattern`` . Optional text parameters treat an empty string the same as an omitted argument. .. csv-table:: :header: Tool,Read-only,Description :widths: 12,15,25 :align: left :class: longtable `catalog_list_schemas`,Yes,List schemas in the current database. Hides Postgres/AIDB internal schemas and installed extensions' schemas unless `include_system` is set. `catalog_list_objects`,Yes,"List tables, views, materialized views, foreign tables, and/or functions. Narrow with `schema`, `object_type`, and/or `name_pattern`." `catalog_get_object_details`,Yes,"Get full detail on one object by name: columns, primary/unique/foreign keys for relations; arguments and return type for functions." `catalog_list_relations`,Yes,"List foreign-key relationships — every FK in a schema, or only edges touching one specific table, in either direction." Semantic knowledge bases ------------------------ Schema-search knowledge bases to allow semantic search based discovery of tables, columns, and other DB objects. Distinct from the knowledge bases for user data that pipelines can create. .. csv-table:: :header: Tool,Read-only,Description :widths: 12,15,25 :align: left :class: longtable `create_semantic_kb`,No,Create a semantic knowledge base over one or more schemas for natural-language schema search. `delete_semantic_kb`,No,Delete a semantic knowledge base by name. `list_semantic_kbs`,Yes,List all registered semantic knowledge bases. `get_semantic_kb`,Yes,Get a registered semantic knowledge base's configuration by name. `refresh_semantic_kb`,No,Re-crawl a semantic knowledge base's schemas to pick up structural changes. `update_semantic_kb_auto_processing`,No,Change a semantic knowledge base's auto-processing mode. `get_column_definitions`,Yes,Search a semantic knowledge base for matching column/table definitions. `get_metadata`,Yes,"Search a semantic knowledge base's full schema metadata (columns, tables, comments)." `get_entity_definitions`,Yes,Search a semantic knowledge base for matching table/view definitions. `semantic_kb_search`,Yes,"Run a composite semantic search over a knowledge base, returning one ranked list of matching tables, views, columns, and aliases with a source-type discriminator." `search_by_comment`,Yes,Search a semantic knowledge base's schema/table/column comments by similarity. `semantic_kb_stats`,Yes,Get row/entity counts for a semantic knowledge base. Models ------ See :ref:`Integrating models ` . .. csv-table:: :header: Tool,Read-only,Description :widths: 12,15,25 :align: left :class: longtable `list_models`,Yes,List all registered models. `get_model`,Yes,Get a registered model's configuration by name. `create_model`,No,Register a new model with a provider and configuration. `delete_model`,No,Delete a registered model by name. `sync_hcp_models`,No,Sync models available from the configured Hybrid Manager (HM) into the model registry. `list_hcp_models`,Yes,List models already synced from HM. `get_hcp_models`,Yes,"List models available from HM, synced or not." `create_hcp_model`,No,Register a model from HM under a local name. Volumes ------- See :ref:`Configuring external storage ` . .. csv-table:: :header: Tool,Read-only,Description :widths: 12,15,25 :align: left :class: longtable `list_volumes`,Yes,List all registered volumes. `create_volume`,No,Register a new volume backed by an object store. `delete_volume`,No,Delete a volume by name. `list_volume_content`,Yes,List the files stored in a volume. `read_volume_file`,Yes,Read a file's contents from a volume. `write_volume_data`,No,Write data to a file in a volume. `delete_volume_file`,No,Delete a file from a volume. Embedding and document processing --------------------------------- See :ref:`SQL functions ` . .. csv-table:: :header: Tool,Read-only,Description :widths: 12,15,25 :align: left :class: longtable `encode_text`,Yes,Compute a text embedding vector for document/search-index storage. `encode_text_query`,Yes,Compute a text embedding vector tuned for querying (vs. indexing). `encode_image`,Yes,Compute an image embedding vector. `generate_text`,Yes,Generate text from a language model. `get_model_description`,Yes,Get a human-readable description of a model. `list_model_providers`,Yes,List the foreign-server-backed model providers available for registering models against. `rerank_text`,Yes,Rerank a list of candidate texts against a query using a reranker model. `get_adapter_embedding_dimensions`,Yes,Get a model's output embedding dimensionality for text or image input. `chunk_text`,Yes,Split text into chunks suitable for embedding. `parse_html`,Yes,Parse HTML into plaintext or markdown. `parse_pdf`,Yes,"Extract text from a PDF, one row per page." `pdf_to_image`,Yes,"Render a PDF's pages to images, one row per page." `perform_ocr`,Yes,Run OCR over an image or scanned document. `summarize_text`,Yes,Summarize text using a language model. Agent management ---------------- See :ref:`Managing agents ` . Letting an agent create or reconfigure *other* agents (including itself) is a powerful, self-modifying capability — grant these tools deliberately. .. csv-table:: :header: Tool,Read-only,Description :widths: 12,15,25 :align: left :class: longtable `list_agents`,Yes,List all registered agents. `create_agent`,No,Create a new agent. Returns a single row with an `error` column (`NULL` on success). `update_agent`,No,Update an existing agent's configuration. Only fields explicitly passed are changed. `delete_agent`,No,Delete an agent by name. Returns a single row with an `error` column (`NULL` on success). `sleep`,Yes,"Pause reasoning for a number of seconds, then automatically resume. Always available to every agent, regardless of its configured tool list, unless the model's own tool-count cap is already filled by the agent's other configured tools." Pipelines --------- See :ref:`AI pipelines ` . .. csv-table:: :header: Tool,Read-only,Description :widths: 12,15,25 :align: left :class: longtable `search_pipelines`,Yes,List all registered data pipelines. `get_pipeline`,Yes,Get a registered data pipeline's configuration by name. `delete_pipeline`,No,Delete a registered data pipeline by name. `run_pipeline`,No,"Manually run a pipeline once, processing any pending source rows." `get_pipeline_metrics`,Yes,Get a pipeline's processing status and row counts. `get_error_logs`,Yes,"List a pipeline's record-level processing errors, optionally filtered." `clear_error_logs`,No,Delete specific pipeline error log entries by id. `requeue_pipeline_errors`,No,Mark specific pipeline errors' source rows dirty so the next run retries them. `get_error_log_summary`,Yes,"Get error counts for a pipeline, grouped by step, operation, and category." `get_all_error_summaries`,Yes,"Get error counts across every pipeline, grouped by step, operation, and category." !!!note Pipeline authoring (``aidb.create_pipeline`` /``aidb.update_pipeline`` ) has no native tool. Those functions take up to 30 parameters across step/step-options pairs — impractical for a single generic tool call — so multi-step pipeline authoring isn’t currently something an agent can do on its own.