Call Tools Without a Chat Thread

Overview

The tool_call endpoint lets you invoke any tool function from the Genesis global registry as a plain HTTP request. There is no chat thread, no LLM, and no agent decision step — you supply the tool name and arguments, Genesis runs the tool and returns its result. Use this when you already know which tool to run and want deterministic, scriptable execution. Use a chat thread when you want an agent to decide which tools to call based on natural language.

You want…	Use…
The agent to decide what tools to call from natural language	Chat with agents
To run one specific tool with known arguments, headlessly	`POST /api/tool_call`
To list all available tool groups	`GET /api/tool_call/list`
To inspect one visible tool function’s callable schema before invoking it	`POST /api/tool_call/schema`
Topic-specific REST endpoints (with typed schemas)	The relevant API page, e.g. Document Index Endpoints

The tool_call endpoint runs against the same global tool registry that bots use, so most tools the bots can use — Document Index management, scheduler, lineage, Snowflake actions, file operations, MCP tools, etc. — are callable here. Authentication and per-user Permission checks still apply.

Authenticate with a Personal Access Token (PAT). See Personal Access Tokens for how to obtain one.

export GENESIS_URL="https://<your-genesis-host>"
export GENESIS_PAT="gp_replace-me"
AUTH=(-H "Authorization: Bearer $GENESIS_PAT")

For Python scripts, notebooks, or CI jobs, you can wrap the same PAT-backed APIs with genesis_sdk or the product genesis CLI instead of hand-writing every HTTP request.Set GENESIS_API_BASE_URL and GENESIS_API_TOKEN, then use from genesis_sdk import Genesis, Genesis.from_environment(), gx.query.rows(...), gx.tools.list(), or gx.tools.call(name, args). CLI equivalents include genesis query --connection ... --sql ..., genesis tools list, genesis tools schema <name>, and genesis tools call <name> --json-args '{"key":"value"}'.

Endpoints

Method	Path	Description
`GET`	`/api/tool_call/list`	List registered tool groups and counts.
`POST`	`/api/tool_call/descriptors`	Return bounded LLM-facing descriptors for visible tool groups and/or named tools.
`POST`	`/api/tool_call/schema`	Return the LLM-facing schema for one visible tool function.
`POST`	`/api/tool_call`	Invoke one tool function by name.

`GET /api/tool_call/list`

Discovery endpoint. Returns the registered tool groups plus the total number of tool functions visible to the caller. Pass max_groups to return a bounded page: omitted groups are not serialized, while total_groups and total_tools still count every visible group and tool. Use offset with max_groups to request a later page without serializing the groups before it; the response echoes the served offset. A bounded response includes groups_returned and truncated: true when groups were omitted.

curl -sS "${AUTH[@]}" "$GENESIS_URL/api/tool_call/list?max_groups=2&offset=2"

{
  "success": true,
  "response": {
    "total_tools": 186,
    "total_groups": 58,
    "offset": 2,
    "groups_returned": 2,
    "truncated": true,
    "tool_groups": [
      {
        "name": "document_index_tools",
        "description": "Document index management",
        "tool_count": 1
      },
      {
        "name": "scheduler_tools",
        "description": "Scheduler / cron-like jobs",
        "tool_count": 4
      }
    ]
  }
}

This endpoint lists groups, not individual function names. The full tool inventory is documented in the Genesis Data Agent’s Toolkit — each toolkit page lists the tool function names you can pass as func. max_groups is an optional integer query parameter with a minimum of 1. offset is an optional integer query parameter with a minimum of 0; it skips that many visible groups before serializing the page and is echoed in the response when supplied. Use both parameters to page through the registry. Omit max_groups to return the complete visible group listing.

`POST /api/tool_call/descriptors`

Return LLM-facing descriptors for all tools in selected visible groups and/or for individually named tools. This is a discovery-only operation; it does not invoke tools or change which tools a session can use. Group and name requests are bounded at 50 groups and 200 names per request.

curl -sS -X POST "${AUTH[@]}" -H 'Content-Type: application/json' \
  -d '{"groups": ["document_index_tools"], "max_group_descriptors": 3, "exclude_names": ["_document_index"]}' \
  "$GENESIS_URL/api/tool_call/descriptors"

Request body

Field	Type	Required	Description
`groups`	array of strings	No	Visible tool groups whose tools should be described. Maximum `50` entries.
`names`	array of strings	No	Individual visible tool names to describe. Maximum `200` entries.
`max_group_descriptors`	integer or `null`	No	Maximum number of descriptors built from the requested groups. Minimum `0`; omit it to describe every matched group tool. Named tools are always described in full.
`exclude_names`	array of strings	No	Tools to leave out of the groups’ answer entirely: they are not built, named, or counted against `max_group_descriptors`. Maximum `200` entries. Defaults to `[]`.

At least one of groups or names is required. The response includes descriptors, count, matched_tool_names, total_matched, groups, unknown_groups, unknown_names, and unavailable_groups. With a group bound, matched_tool_names still names every tool matched by the groups, so a caller can request descriptors omitted from the bounded response by name. exclude_names applies to tools expanded from groups; individually requested names are still described. unavailable_groups identifies groups deliberately not loaded in this build; it is distinct from unknown_groups.

`POST /api/tool_call/schema`

Discovery endpoint for one visible tool function. Use this when your client already knows the tool name and needs the exact callable schema before sending POST /api/tool_call.

curl -sS -X POST "${AUTH[@]}" -H 'Content-Type: application/json' \
  -d '{"name": "_document_index"}' \
  "$GENESIS_URL/api/tool_call/schema"

{
  "success": true,
  "response": {
    "schema": {
      "name": "_document_index"
    },
    "tool_groups": ["document_index_tools"]
  }
}

Request body

Field	Type	Required	Description
`name`	string	Yes	Tool function name. Identifier-like; up to 200 chars; dots are allowed. The tool must be visible to the caller.
`resolve_only`	boolean	No	Default `false`. When `true`, return only whether the tool name resolves and skip building the LLM-facing schema.

The response returns response.schema plus response.tool_groups. When a tool publishes a richer descriptor, Genesis returns that full LLM-facing schema; otherwise the fallback schema includes at least the tool name. Set resolve_only to true when you need to check whether a tool exists before acting on it without requesting its schema. A successful response is:

{
  "success": true,
  "response": {
    "resolved": true
  }
}

POST /api/tool_call/schema applies the same tool-group visibility and permission checks as execution. It returns 403 when the caller lacks the required permission and 404 when the tool name is not registered or visible to the caller. These status codes are unchanged when resolve_only is true.

`POST /api/tool_call`

Invoke a tool function:

POST /api/tool_call
Authorization: Bearer gp_…
Content-Type: application/json

{
  "func": "_document_index",
  "func_args": {
    "action": "LIST_INDICES"
  }
}

{
  "success": true,
  "response": {
    "Success": true,
    "Indices": ["wiki", "support_docs"]
  }
}

Request body

Field	Type	Required	Description
`func`	string	Yes	Tool function name. Identifier-like; up to 200 chars; dots are allowed. The exact same name a bot would emit when calling the tool.
`func_args`	object	No	Keyword arguments for the tool. Keys must be identifier-like (≤100 chars). Ordinary string values are limited to 50 000 chars; file payload arguments are limited to 2 097 152 chars. Most strings are trimmed, except verbatim file-content arguments listed below. Scoped dbt/Jinja templates and raw HTML are rejected unless the target input is on a tool-specific allowlist.
`agent_id`	string or null	No	Optional agent persona for this call. The caller must be allowed to access that agent; authorization is checked for both the caller and agent. Tools that record which agent acted use this persona as the acting-agent identity.
`caller_name`	string or null	No	Optional readable name for the outside calling agent (up to 80 characters). Action Review shows it after `outside agent (sign-in <first 8 characters of the id>)` in Asked by; Genesis reduces it to visible one-line text. If omitted or blank-looking, it shows only that outside-agent sign-in label (`unknown` if the id is unavailable). It changes attribution only: authorization still uses the authenticated caller.

POST /api/tool_call applies scoped input-safety checks before execution. Normal dbt/Jinja template syntax is allowed for dbt_action query and sql_content, and for git_action content fields when you are writing dbt project files under models/, macros/, tests/, snapshots/, or analyses/ with .sql, .yml, or .yaml extensions.When calling apps_action, raw HTML/CSS/JS/SVG content is allowed only for WRITE_FILE or WRITE_FILES destinations under templates/, static/, or assets/ ending in .html, .htm, .css, .js, .mjs, or .svg.For most string arguments, Genesis trims leading and trailing whitespace during sanitization. Arguments whose value is written to a file verbatim, or matched against file content verbatim, are preserved byte-for-byte instead:

file: content, append_content, insert_content, old_string, new_string
git_action: content
apps_action: content

Use these paths when round-tripping file bodies — for example preserving a trailing newline on a write, or indentation in a search-and-replace. Other arguments on the same call (such as action, repo_id, or file_path) are still trimmed.The larger 2 097 152-character limit applies to file content, append_content, insert_content, old_string, and new_string, and to apps_action content. Other string arguments, including git_action content, retain the 50 000-character limit.After the caller is resolved and authorized, Genesis scans string arguments for disallowed HTML and template content before dispatching the tool.

Malformed calls and content-scan refusals are returned as an HTTP 200 refusal rather than a transport error, so MCP clients can read the tool result. Genesis does not dispatch the tool. The outer response has success: false; its nested response has success: false, error_code: "invalid_request", an invalid_arguments array with each failing argument and its problem, and a next_call instruction. Request-validation refusals cover missing, unexpected, or incorrectly typed arguments; missing required parameters are identified as missing rather than as values that failed validation. Use /api/tool_call/schema to check the accepted arguments. Unowned sandbox runs have an additional execution contract. For these runs, POST /api/tool_call returns HTTP 200 with success: false and does not call the requested tool when it would perform ticket mutation, run dispatch, or remote publication and parent-side repository state. The nested response includes the genesis-coding-contract-refusal marker, a refusal.kind of "forbidden", and a next object explaining that the refusal is final. This applies after the tool name is resolved and before any durable thread is created. Read operations remain available, including the permitted read actions for tools such as linear_connector and autodev_run_action.

Response body

{
  "success": true,        // mirrors the tool's own success when present, else true
  "response": { ... }     // raw tool return value
}

The response field is whatever the tool returned. Most Genesis tools return a dict whose first key is Success (capital S — that is the tool-level success flag); the HTTP-level success mirrors it when present. Tool results are operation-specific. For the sign-in-dependent result and approval flow of prover_tools.request_evidence, see its tool reference.

Common status codes

Status	When
`200`	Request was processed. Inspect `success` and `response` for the tool-level outcome or a tool safety rejection.
`400`	Invalid argument key or value (unsafe characters, too long, etc.).
`401`	Missing or invalid PAT / credentials.
`403`	Caller is missing the permission the tool needs. For multiplexed tools such as `lineage_tools_lineage_action`, some individual `action` values (for example `SET_ESTATE_TEMPLATE`) require an additional permission beyond the tool group gate.
`404`	`func` name not in the registry. Use `GET /api/tool_call/list`.
`500`	Tool raised an unhandled exception.
`503`	The requested tool’s MCP service is unavailable. The error body includes `code` and `service`; `code: "service_starting"` means the service is still starting and can be retried in a few seconds, while `code: "service_unavailable"` means the service is not running on this server.

When a dbt safety guard blocks a request or suppresses an unsafe dbt result, the endpoint still returns HTTP 200 with success: false. The nested response includes dbt_safety_rejected: true and either preflight_rejected: true or postflight_rejected: true. Every dbt failure also names its class: error_class: "policy_block" for a guard rejection — with block_reason_code (for example static_output_pattern, judge_denied, judge_unavailable) and a human-readable policy_block_reason — versus error_class: "tool_error" for a genuine dbt or dispatch failure. A parsed judge denial keeps block_reason_code: "judge_denied" and adds judge_reason_code. Recognized values are secret_exposure, environment_access, host_details, file_or_process_access, protected_content, sandbox_bypass, and other_policy; a legacy, missing, unknown, malformed, duplicate, or conflicting category becomes unspecified with the existing generic policy summary. The judge is instructed to return exactly ALLOW or DENY: <reason_code>, without a free-form rationale. Category extraction tolerates letter case, surrounding whitespace, and a sole code fence already accepted by the verdict parser; inline decoration and extra content remain generic. Public reason text is selected by Genesis from fixed summaries: neither the raw judge response nor the rejected input is reflected to the caller.For request-side log(), the judge is instructed to allow only literal message arguments and any supplied info argument must be a literal Boolean; the message content can contain no secret, credential, environment, host, account, or absolute-path data. Dynamic expressions, concatenations, variables, macros, attributes, and sensitive literal content remain deny cases. Projects on the dbt.safety.trusted_projects allowlist (see Advanced Settings — dbt safety settings) skip those static and LLM judges; host-path and secret redaction in dbt_action always still runs. Trusted projects still do not inherit ambient server variables; dbt.safety.trusted_env_vars is the only way to provide explicit non-secret env_var(...) values.

What `tool_call` does not do

tool_call is intentionally a thin wrapper. Compared to a tool call made inside a real bot run, it skips:

Built-in / context tools that depend on a live thread or chat context (tools that need bot_id / thread_id injection). tool_call injects the authenticated user as bot_id and a synthetic api_call_<id> as thread_id. When agent_id is supplied, tools that record the acting agent use that validated persona for attribution.
Streaming — there is no incremental output channel. You get one JSON response.
Recovery and retries that the bot loop normally provides.
Cost accounting in chat budgets.

If a tool reports it needs thread or bot context, run it through an agent via the chat API instead.

Examples

List document indexes

curl -sS -X POST "${AUTH[@]}" -H 'Content-Type: application/json' \
  -d '{"func": "_document_index", "func_args": {"action": "LIST_INDICES"}}' \
  "$GENESIS_URL/api/tool_call"

Search the `wiki` index

curl -sS -X POST "${AUTH[@]}" -H 'Content-Type: application/json' \
  -d '{
        "func": "_document_index",
        "func_args": {
          "action": "SEARCH",
          "index_name": "wiki",
          "query": "deployment runbook",
          "top_n": 5
        }
      }' \
  "$GENESIS_URL/api/tool_call"

Add a file by `file_id` to an index

curl -sS -X POST "${AUTH[@]}" -H 'Content-Type: application/json' \
  -d '{
        "func": "_document_index",
        "func_args": {
          "action": "ADD_DOCUMENTS",
          "index_name": "docs",
          "file_id": "123e4567-e89b-12d3-a456-426614174000",
          "conflict_policy": "overwrite_on_conflict"
        }
      }' \
  "$GENESIS_URL/api/tool_call"

Ask the document indexes (RAG-style)

curl -sS -X POST "${AUTH[@]}" -H 'Content-Type: application/json' \
  -d '{
        "func": "_document_index",
        "func_args": {
          "action": "ASK",
          "query": "How do we rotate the LiteLLM proxy key?",
          "top_n": 3
        }
      }' \
  "$GENESIS_URL/api/tool_call"

Bulk-delete by metadata

Useful for sweeping out all entries from a single source:

curl -sS -X POST "${AUTH[@]}" -H 'Content-Type: application/json' \
  -d '{
        "func": "_document_index",
        "func_args": {
          "action": "DELETE_BY_METADATA",
          "index_name": "snowflake_metadata",
          "metadata": {"qualified_name": "snowflake://DB/SCHEMA/TABLE"}
        }
      }' \
  "$GENESIS_URL/api/tool_call"

Digital Twin lineage actions

For Digital Twin scan control and estate layout, call lineage_tools_lineage_action through POST /api/tool_call.

Action	Additional args	Notes
`GET_SCAN_PROGRESS`	none	Returns `progress[]` entries with `source_id`, `source_name`, `continuous`, `cycles_completed`, `total_files_discovered`, `total_files_scanned`, `queue_remaining`, `current_cycle_progress_pct`, `is_scanning`, and `is_queued`.
`SET_SCAN_CONTINUOUS`	`source_id` (`string`), `properties.enabled` (`boolean`, default `true`)	Toggles auto-cycle for a source’s active scan.
`SCAN_SOURCE`	`source_id` (`string`), optional `properties.continuous` (`boolean`, default `true`)	Queues a per-source scan and can disable follow-on cycles at enqueue time.
`SET_USAGE_BUDGET`	`properties.token_budget` (`integer` or `null`), optional `properties.budget_window_hours` (`integer`)	Sets or clears the global Context Graph token cap. `null` removes the cap; `0` blocks background work. An omitted window keeps the existing window, or uses the first-ever default of `720` hours. Requires `access_config_panel`.
`SET_ESTATE_TEMPLATE`	`template` (`string[]`)	Validate, persist, and regenerate the shared Data Estate page (`wiki://estate`). Requires `access_config_panel`. `template` must be a non-empty list of unique block type names drawn from `overview`, `areas`, and `systems` (default order: `["overview", "areas", "systems"]`). On success, `response.page` includes the regenerated page plus `template` and `available_block_types`. On validation failure, `response.success` is `false`, `response.error` describes the problem, and `response.available_block_types` lists valid block types.

curl -sS -X POST "${AUTH[@]}" -H 'Content-Type: application/json' \
  -d '{
        "func": "lineage_tools_lineage_action",
        "func_args": {
          "action": "GET_SCAN_PROGRESS"
        }
      }' \
  "$GENESIS_URL/api/tool_call"

{
  "success": true,
  "response": {
    "success": true,
    "progress": [
      {
        "source_id": "repo_customer-onboarding",
        "source_name": "customer-onboarding",
        "continuous": true,
        "cycles_completed": 1,
        "total_files_discovered": 842,
        "total_files_scanned": 520,
        "queue_remaining": 322,
        "current_cycle_progress_pct": 61,
        "is_scanning": true,
        "is_queued": false
      }
    ]
  }
}

curl -sS -X POST "${AUTH[@]}" -H 'Content-Type: application/json' \
  -d '{
        "func": "lineage_tools_lineage_action",
        "func_args": {
          "action": "SET_SCAN_CONTINUOUS",
          "source_id": "repo_customer-onboarding",
          "properties": {
            "enabled": false
          }
        }
      }' \
  "$GENESIS_URL/api/tool_call"

Update the Data Estate section template

curl -sS -X POST "${AUTH[@]}" -H 'Content-Type: application/json' \
  -d '{
        "func": "lineage_tools_lineage_action",
        "func_args": {
          "action": "SET_ESTATE_TEMPLATE",
          "template": ["areas", "systems", "overview"]
        }
      }' \
  "$GENESIS_URL/api/tool_call"

{
  "success": true,
  "response": {
    "success": true,
    "page": {
      "qualified_name": "wiki://estate",
      "title": "Data Estate",
      "body_markdown": "...",
      "template": ["areas", "systems", "overview"],
      "available_block_types": ["overview", "areas", "systems"]
    }
  }
}

Python wrapper

import os, requests

def call_tool(func: str, **kwargs) -> dict:
    resp = requests.post(
        f"{os.environ['GENESIS_URL'].rstrip('/')}/api/tool_call",
        headers={"Authorization": f"Bearer {os.environ['GENESIS_PAT']}"},
        json={"func": func, "func_args": kwargs},
        timeout=120,
    )
    resp.raise_for_status()
    body = resp.json()
    if not body.get("success", True):
        raise RuntimeError(body)
    return body["response"]


hits = call_tool(
    "_document_index",
    action="SEARCH",
    index_name="wiki",
    query="kubernetes deployment",
    top_n=5,
)
for hit in hits.get("results", []):
    print(hit.get("source"), hit.get("score"))

Discovering tool names and arguments

Most Genesis tools are documented in the Genesis Data Agent’s Toolkit section. Each toolkit page lists the tool function names along with the arguments the agents use, which are the same names and arguments you pass in func and func_args. If you already know the tool name and need a machine-readable argument schema, call POST /api/tool_call/schema. That endpoint returns the same LLM-facing schema Genesis exposes internally, along with the tool groups the function belongs to. A few popular starting points:

For the all-purpose Document Index tool covered above, the action names are upper-snake-case strings:

ADD_DOCUMENTS, ADD_TEXT, CREATE_INDEX, LIST_INDICES, DELETE_INDEX,
LIST_DOCUMENTS, SEARCH, RENAME_INDEX, ASK, DELETE_DOCUMENT,
DELETE_BY_METADATA, GET_DOCUMENT, RENAME_DOCUMENT, GET_INDICES_STATS

The Document Index Endpoints page covers the same actions through typed REST endpoints, which can be more convenient for typed clients.

Getting Started

Getting to Know Genesis

Creating A Mission

User Guide

Blueprint

Genesis Data Agents

Genesis Prover

Genesis Apps

Genesis REST API

Genesis Agent Security Controls

Genesis Data Agent's Toolkit

Setup

Slack and Teams

Data Connections

Deployment Options

Call Tools Without a Chat Thread

Overview

Endpoints

`GET /api/tool_call/list`

`POST /api/tool_call/descriptors`

Request body

`POST /api/tool_call/schema`

Request body

`POST /api/tool_call`

Request body

Response body

Common status codes

What `tool_call` does not do

Examples

List document indexes

Search the `wiki` index

Add a file by `file_id` to an index

Ask the document indexes (RAG-style)

Bulk-delete by metadata

Digital Twin lineage actions

Update the Data Estate section template

Python wrapper

Discovering tool names and arguments

​Overview

​Endpoints

​GET /api/tool_call/list

​POST /api/tool_call/descriptors

​Request body

​POST /api/tool_call/schema

​Request body

​POST /api/tool_call

​Request body

​Response body

​Common status codes

​What tool_call does not do

​Examples

​List document indexes

​Search the wiki index

​Add a file by file_id to an index

​Ask the document indexes (RAG-style)

​Bulk-delete by metadata

​Digital Twin lineage actions

​Update the Data Estate section template

​Python wrapper

​Discovering tool names and arguments

​Related pages

Overview

Endpoints

`GET /api/tool_call/list`

`POST /api/tool_call/descriptors`

Request body

`POST /api/tool_call/schema`

Request body

`POST /api/tool_call`

Request body

Response body

Common status codes

What `tool_call` does not do

Examples

List document indexes

Search the `wiki` index

Add a file by `file_id` to an index

Ask the document indexes (RAG-style)

Bulk-delete by metadata

Digital Twin lineage actions

Update the Data Estate section template

Python wrapper

Discovering tool names and arguments

Related pages