> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genesiscomputing.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Context Tools
> Search capabilities, Genesis product docs, data context, and past SQL query history; manage defaults; and inspect, search, or recover thread memory for Genesis Data Agents.
## Overview
`context_tools` support the customer-facing workflows used to discover capabilities, search Genesis product documentation, search data context, recall past SQL analyses (including unvalidated queries), set agent defaults, control which skills or tool groups are active for a given agent, read curated non-secret deployment identity (such as the Genesis instance name), pause for poll-and-check pacing while background work advances, and inspect, search, or recover thread memory.
## What customers use these tools for
* searching available capabilities,
* searching Genesis product documentation and reading assigned knowledge-base documents,
* searching the Context Graph / Twin index for data assets,
* finding prior SQL queries (validated or not), remembered conventions, and context-specific rejected approaches before rerunning analysis,
* searching other threads for relevant prior conversations and cross-thread context,
* activating or deactivating tool groups,
* setting defaults for an agent,
* controlling the effective context available to an agent,
* checking, compressing, searching hidden thread content, and recovering thread memory,
* resolving which Genesis instance is running (deployment identity) without reading raw environment variables,
* pausing between status checks while a background job, sub-thread, or external process advances.
## Primary tool surfaces
| Tool | Purpose |
| - | - |
| `manage_context` | Search for tools, skills, blueprints, or knowledge-base hits and update the active tool/skill context for the current thread or agent defaults. |
| `search_knowledge_bases` | Search the knowledge bases assigned to the current agent for domain-specific documents, playbooks, or curated references. |
| `read_knowledge_base_doc` | Read the full text of a knowledge-base document returned by `search_knowledge_bases` (supports line/char/chunk pagination). |
| `search_genesis_docs` | Search Genesis product documentation for setup, features, connectors, tool behavior, missions, and troubleshooting guidance. |
| `read_genesis_doc` | Read the full text of a Genesis doc returned by `search_genesis_docs` (supports line/char/chunk pagination). |
| `search_data_context` | Search the Context Graph vector index for tables, views, dashboards, files, notebooks, pipelines, jobs, and related data assets. Use as a first step when users ask about indexed data or before writing SQL or lineage queries. |
| `find_past_queries` | Recall persisted SQL query history across threads so Genesis can reuse prior queries, conventions, and prior concerns before running new SQL. SQL/query history only — does not locate or manage artifacts. |
| `search_threads` | Search other threads for relevant history and cross-thread context without first activating `system_manager_tools`. |
| `get_runtime_values` | Retrieve curated non-secret runtime values for this Genesis instance (currently `genesis_instance_name`). |
| `manage_thread_memory` | Inspect thread-memory usage, run compression, search hidden/compressed messages, list recoverable blocks, and recover compressed content. |
| `wait` | Pause for up to 300 seconds, then resume; call repeatedly for longer poll-and-check loops. |
`manage_context_state` remains available as a legacy alias, but new automations should use `manage_context` for tool and skill context changes.
### `manage_context`
Use `manage_context` to discover capabilities and change the active tool/skill context.
| Parameter | Type | Default | Notes | |
| - | - | - | - | - |
| `action` | string | `SEARCH_CONTEXT` | Allowed values: `SEARCH_CONTEXT`, `SET_CONTEXT`, `ADD_CONTEXT`, `REMOVE_CONTEXT`, `RESET_ACTIVE`, `GET_DEFAULTS`, `SET_DEFAULTS`. | |
| `query` | string | `""` | Search text used with `SEARCH_CONTEXT`. | |
| `search_scope` | string | `all` | Allowed values: `all`, `skills`, `tools`, `blueprints`, `document_indexes`, `knowledge_bases`. | |
| `limit` | integer | `20` | Maximum result count for `SEARCH_CONTEXT`. | |
| `offset` | integer | `0` | Paging offset for `SEARCH_CONTEXT`. | |
| `active_tool_groups` | string | `""` | Comma-separated tool groups for the current thread or agent defaults. | |
| `active_skills` | string | `""` | Comma-separated skill names for the current thread or agent defaults. | |
| `model_tier` | string | `""` | Optional thread tier override: `frontier`, `main`, or `fast`. | |
| `tool_profile_overrides` | object or null | `null` | Optional map of \`tool\_name -> basic | advanced\`. |
| `context_budget_policy` | object or null | `null` | Optional budget hints such as `reserved_headroom_pct`. | |
`never_compress_skills` is set through `set_bot_context_defaults`, not through
`manage_context`; see [Bot Management Tools](/docs/Genbot-Toolkit/Bot-Management-Tools#set_bot_context_defaults).
When an `ADD_CONTEXT` request has no recognized setting, it returns an error and
lists unrecognized caller-supplied argument names. Runtime-injected context
parameters such as `run_id`, `session_id`, and `user_id` are excluded from that
list; nothing is changed.
**Example**
```python theme={null}
manage_context(
action="SEARCH_CONTEXT",
query="Snowflake dashboard access",
search_scope="all",
)
manage_context(
action="ADD_CONTEXT",
active_tool_groups="data_connector_tools,snowflake_tools",
)
```
`SEARCH_CONTEXT` returns bucketed matches under `tool_groups`, `skills`, `blueprints`, `document_indexes`, and `knowledge_bases`. Matching ignores common stopwords, so words such as `the`, `a`, and `is` are not reported as evidence in `matched_terms`. Use `ADD_CONTEXT` for likely capability matches, follow up with `search_knowledge_bases(...)` for relevant knowledge-base hits, then `read_knowledge_base_doc(index_name=..., doc_path=...)` to read the full document (do not use `read_genesis_doc` for user knowledge-base documents), and use the Team Wiki tools directly for graph-backed wiki content: `wiki_search(query="...")`, `wiki_list(prefix="...")`, then `wiki_read(qualified_name="...")`.
For paging, `capabilities_has_more` and `knowledge_bases_has_more` independently indicate whether their respective result sources have another page. `next_offset` is the shared continuation offset when either source has more results; pass it as `offset` on the next `SEARCH_CONTEXT` call.
A registered channel-bound tool group can remain in `tool_groups` discovery even when
its runtime adapter cannot dispatch. Currently this applies to `slack_tools`. Such a
result is marked `available: false` and includes `unavailable_reason`; the group is
kept visible so the agent can explain the operational issue instead of treating the
name as misspelled. Capability policy still controls visibility, so policy-denied
groups are not re-admitted by this availability marker.
**Private tool groups** are reserved for trusted internal workflows and are
omitted from `SEARCH_CONTEXT` discovery. They cannot be activated through
`ADD_CONTEXT` or `SET_CONTEXT` — Genesis rejects the name as an unknown tool
group rather than surfacing it as registered-but-not-allowed. A privileged job
runner may pin a private group (and any required skills) onto a dedicated
thread through the Context Control API; per-tool runtime guards enforce the
actual access boundary. The current private group is
`upgrade_advisor_tools`, used only on Eve's active post-upgrade-advisor
threads (`upgrade_advisor_*` thread ids with both the `post-upgrade-advisor`
skill and `upgrade_advisor_tools` already active). Calls outside that context
return a generic refusal without indicating which admission check failed.
### Private upgrade advisor tools (`upgrade_advisor_tools`)
Genesis pins this private group (and the `post-upgrade-advisor` skill) onto Eve's
dedicated `upgrade_advisor_*` threads when the post-upgrade advisor job runs.
The four tools below are not customer-callable through normal chat discovery;
they are documented here for operators and internal automation authors.
| Tool | Purpose |
| - | - |
| `get_release_notes` | Read the running release's detailed advisor notes, with same-version concise fallback and whole-line pagination. |
| `get_install_inventory` | Return the pre-built install inventory snapshot (bots, Apps, flows, blueprints, connections). |
| `get_open_enhancement_requests` | List open enhancement requests for cross-referencing against release items. |
| `save_upgrade_summary` | Validate and persist Eve's finished personalized upgrade report to disk. |
#### `get_release_notes`
Call at the start of an advisor run, then continue until `next_start_line` is
`null`. The tool reads the detailed advisor document at
`config/release-notes/v.md`; if that document is missing or
unreadable, it falls back to the same-version concise Mintlify changelog page
shown in the upgrade modal's **Release notes** tab:
`config/genesis-docs-source/docs/Getting-Started/changelog/v.mdx`.
It does not substitute another release. A dev build without an exact published
release returns empty notes.
| Parameter | Type | Default | Notes |
| - | - | - | - |
| `version` | string | omitted | Optional request label echoed as `requested_version`. Omit to use the live runtime label; selection uses the live runtime's GA or RC version. |
| `start_line` | integer | `1` | First source line to return. Pass the preceding response's `next_start_line` unchanged for each continuation. |
Returns `success`, `runtime_version`, `requested_version`, `matched_version_label`
(exact clean release label or `null`), `source_kind` (`detailed`, `concise`, or
`none`), `release_notes_markdown` for the current page, `start_line`,
`total_lines`, `returned_lines`, and `next_start_line`. Read every page before
drafting the advisor report. If a page fails or cannot fit the inline output
budget, stop and report incomplete release input; do not synthesize from a
partial document. Empty notes mean there is no usable published input.
When `search_scope="document_indexes"` (or `all`), matching index names appear under `document_indexes`. Those hits can include a ready-to-run `search_action`, an optional `list_action`, and an `activate_action` that turns on `document_index_tools` for the current thread. Index create, rename, and delete operations refresh this discovery path automatically, so updated index names show up without a Genesis restart.
`SET_DEFAULTS` updates the bot's thread-start defaults only. Bot-wide access
policy is enforced separately through `tool_access_mode`,
`tool_access_list`, `skill_access_mode`, and `skill_access_list` in Agent
Center and the Context Control API.
When a bot uses `allowlist` or `denylist` policy, requests to activate
blocked tool groups or skills are rejected instead of being silently ignored.
Bot default auto-loads are also capped by default at `12` tool groups;
operators can override that cap with `CONTEXT_DEFAULTS_MAX_TOOL_GROUPS`.
The number of tool functions those groups contain is not capped by default —
the provider function cap is the only ceiling.
For persistent bot-wide defaults and access policy (not just the current
thread), use `set_bot_context_defaults` or `set_bot_capability_policy` in
[Data Agent Creation Tools](/docs/Genbot-Toolkit/Bot-Management-Tools). Policy,
preflight, and cap rejections return structured `details` on that tool envelope.
Provider-function-cap details use the same fields as the Context Control API's
`409` preflight response, documented in
[Genesis API](/docs/Genesis-API/API-Reference#context-control-endpoints).
When `ADD_CONTEXT` or `SET_CONTEXT` requests a policy-authorized channel-bound group
whose adapter cannot dispatch, the request is rejected with structured
`unavailable_tool_groups` details. The detail names the group and explains what an
administrator must configure or re-enable; it is not reported as a policy denial.
### Assigned skill reading from `context_tools`
Whenever `manage_context` activates a skill via `ADD_CONTEXT` or `SET_CONTEXT` — either explicitly via `active_skills` or as an auto-activated prerequisite — Genesis tries to return that skill's primary `SKILL.md` inline in the same tool response. The activation hint carries the same truncation, supplementary-file manifest, and continuation metadata used elsewhere, and when the primary file is inlined Genesis also marks the skill as read for the current thread immediately.
Skill discovery and inline activation reads also refresh from the current registered package state on the next call. Registering, syncing, or removing an AgentSkill source marks the capability registry for background reconcile, so `SEARCH_CONTEXT` with `search_scope="skills"` and `SET_DEFAULTS` policy checks see new or removed packages within seconds without restarting Genesis.
Updates to `SKILL.md`, source registration metadata, or Genesis bindings do not require a Genesis restart before `manage_context` or the related skill viewers pick them up.
If Genesis cannot inline a given skill package, the activation still succeeds. In that fallback case `skill_activation_hints[].primary_file_inlined` is `false` and `skill_activation_hints[].next_step` points at the exact `read_assigned_skill_file(...)` call needed to open `SKILL.md`.
These always-on tools remain useful for inspecting supplementary files, paging through a truncated `SKILL.md`, or reading the primary file on demand when inline delivery is unavailable:
| Tool | Purpose |
| - | - |
| `list_assigned_skills` | List skill summaries assigned to the current bot. |
| `list_assigned_skill_files` | Browse bundled files for an assigned skill package. |
| `read_assigned_skill_file` | Read `SKILL.md` or another bundled text file, with paging metadata such as `next_start_char` and `continuation_hint`. When the skill has no on-disk AgentSkills package but its catalog spec includes a non-empty `description`, reading the primary `SKILL.md` serves that description instead of erroring (`source: "description_fallback"`). |
**Typical flow**
```python theme={null}
result = manage_context(action="ADD_CONTEXT", active_skills="run-genesis-tests")
hint = result["skill_activation_hints"][0]
if hint["primary_file_inlined"]:
skill_text = hint["primary_file_content"]
if hint["primary_file_truncated"]:
read_assigned_skill_file(
skill_name="run-genesis-tests",
relative_path="SKILL.md",
start_char=hint["primary_file_next_start_char"],
)
else:
read_assigned_skill_file(
skill_name="run-genesis-tests",
relative_path="SKILL.md",
)
list_assigned_skill_files(skill_name="run-genesis-tests")
```
Use the returned file manifest to find a skill's supplementary paths. For example,
`prove-data-work` points to `the-path.md` for its step-by-step procedure; read that path
separately when needed rather than assuming it was included with `SKILL.md`:
```python theme={null}
read_assigned_skill_file(
skill_name="prove-data-work",
relative_path="the-path.md",
)
```
The `ADD_CONTEXT` response includes:
* `new_skills_added` — list of newly activated skills.
* `auto_activated_skills` — prerequisite skills Genesis activated automatically.
* `inlined_skills` — skills whose primary `SKILL.md` is included directly in this response.
* `skill_activation_hints[].primary_file_inlined` — `true` when `primary_file_content` is present on the hint.
* `skill_activation_hints[].primary_file_content` — primary `SKILL.md` text when inline delivery succeeds.
* `skill_activation_hints[].primary_file_truncated` and `skill_activation_hints[].primary_file_next_start_char` — pagination metadata when the inline `SKILL.md` body was cut off and needs continuation via `read_assigned_skill_file(...)`.
* `skill_activation_hints[].next_step` — either confirms the inline primary-file path or gives the exact `read_assigned_skill_file(...)` follow-up when the primary file is truncated or unavailable.
Only skills that transition from inactive to active in a given call receive new inline activation hints. Re-running `manage_context(action="ADD_CONTEXT", active_skills="...")` for a skill that is already in the active set is a no-op for inline delivery and read-marking purposes; adding a *different* skill in the same call still returns hints only for the newly activated one.
`read_assigned_skill_file` is a pure read operation. By default it returns up to 50,000 characters, includes paging metadata, and when truncated adds a `truncation_note` that says how much remains and shows the exact continuation call. For registry-only skills (catalog description without bundled package files), a successful primary-file read returns the description text with `source: "description_fallback"` and `message: "Served skill description (no package file present)."` — supplementary paths still require a real package. Skills activated via `ADD_CONTEXT`/`SET_CONTEXT` count as read as soon as Genesis successfully inlines the primary file in the activation response; if activation falls back to a pointer-only hint, opening `SKILL.md` with `read_assigned_skill_file` marks it read explicitly (including description-fallback reads). Default thread-start skills already count as read because their `SKILL.md` is auto-injected into the thread.
For skill behavior after compression, including the reread hint, see [Agents Center and Skills](/docs/User-Guide/Agents-Center-And-Skills).
### `search_knowledge_bases`
Use `search_knowledge_bases` when `SEARCH_CONTEXT` surfaces a promising knowledge-base hit or when you already know you want to search the curated KBs assigned to the current bot. This is the correct tool (not `search_genesis_docs`) for finding documents the user created, uploaded, or stored.
| Parameter | Type | Default | Notes |
| - | - | - | - |
| `query` | string | none | Required search text. |
| `knowledge_base_id` | string or null | `null` | Optional assigned KB ID to narrow the search to one knowledge base. |
| `top_k` | integer | `10` | Maximum KB matches returned. Max `50`. |
**Example**
```python theme={null}
search_knowledge_bases(
query="renewal path",
knowledge_base_id="customer-success",
)
```
`search_knowledge_bases` returns preview snippets only. To read the full text
of a knowledge-base document, follow up with
`read_knowledge_base_doc(index_name=..., doc_path=...)` (described below) — do
NOT use `read_genesis_doc` for user knowledge-base documents. Both KB tools
live in the always-on `context_tools` group when the bot has at least one
knowledge base assigned.
### `read_knowledge_base_doc`
Use `read_knowledge_base_doc` to pull the full text of a document that `search_knowledge_bases` surfaced. Pass the `index_name` plus the `doc_path` (or `file_name` / `file_id`) exactly as returned by the search hit. The reader only lets the current bot read from indexes bundled into knowledge bases assigned to it, and returns paginated content just like `read_genesis_doc`.
| Parameter | Type | Default | Notes |
| - | - | - | - |
| `index_name` | string | none | Required. The `index_name` from a `search_knowledge_bases` hit. |
| `doc_path` | string | `""` | Document handle (`doc_path` or `source`) from a hit. One of `doc_path`, `file_name`, or `file_id` is required. |
| `file_name` | string | `""` | File name from a hit. Fallback handle. |
| `file_id` | string | `""` | File ID for the document, if known. |
| `knowledge_base_id` | string or null | `null` | Optional assigned KB ID to scope the read. |
| `pagination_mode` | string | `lines` | `lines`, `chars`, or `chunks`. |
| `start` | integer | `0` | Starting line, char, or chunk offset. |
| `count` | integer or null | `null` | Maximum lines/chars/chunks to return. Defaults to `400` for `lines`, `20000` for `chars`, and `20` for `chunks`. |
**Example**
```python theme={null}
hits = search_knowledge_bases(query="renewal path", top_k=1)
top = hits["results"][0]
doc = read_knowledge_base_doc(index_name=top["index_name"], doc_path=top["doc_path"])
if doc["has_more"]:
more = read_knowledge_base_doc(
index_name=top["index_name"],
doc_path=top["doc_path"],
start=doc["next_start"],
)
```
### `search_genesis_docs`
Use `search_genesis_docs` for Genesis product questions about setup, features, connectors, missions, tool behavior, or troubleshooting. This tool only covers Genesis's own product documentation — for documents the user created, uploaded, or stored, use `search_knowledge_bases` instead.
| Parameter | Type | Default | Notes |
| - | - | - | - |
| `query` | string | none | Required search text. |
| `top_k` | integer | `10` | Maximum documentation matches returned. Max `50`. |
**Example**
```python theme={null}
search_genesis_docs(
query="How do I configure Snowflake OAuth in Genesis?",
top_k=5,
)
```
`search_genesis_docs` returns preview snippets only. When you need the full
doc content (for deeper answers, troubleshooting, or citations), follow up
with `read_genesis_doc(doc_path=...)` described below — both tools live in
the always-on `context_tools` group, so no extra activation is required.
Use `search_genesis_docs` for Genesis product guidance, `search_data_context` for customer data assets in the Context Graph, and [Document Index Tools](/docs/Genbot-Toolkit/Document-Index-Tools) for uploaded or mission-specific document collections.
### `read_genesis_doc`
Use `read_genesis_doc` to pull the full text of a doc that `search_genesis_docs` surfaced. It accepts the `doc_path` or `file_name` from a search result directly — no need to know the absolute on-disk path — and returns paginated content.
| Parameter | Type | Default | Notes |
| - | - | - | - |
| `doc_path` | string | `""` | Display path from `search_genesis_docs` (for example `docs/User-Guide/Flows.mdx`). Either `doc_path` or `file_name` is required. |
| `file_name` | string | `""` | File name from `search_genesis_docs` (for example `Flows.mdx`). Used as a fallback handle. |
| `pagination_mode` | string | `lines` | `lines`, `chars`, or `chunks`. |
| `start` | integer | `0` | Starting line, char, or chunk offset. |
| `count` | integer or null | `null` | Maximum lines/chars/chunks to return. Defaults to `400` for `lines`, `20000` for `chars`, and `20` for `chunks`. |
**Example**
```python theme={null}
hits = search_genesis_docs(query="workspace definitions Flows SQL Python steps", top_k=1)
top = hits["results"][0]
doc = read_genesis_doc(doc_path=top["doc_path"])
if doc["has_more"]:
more = read_genesis_doc(doc_path=top["doc_path"], start=doc["next_start"])
```
The response includes `content`, `has_more`, and `next_start` so follow-up
calls can page through longer docs without re-running search. Use
`pagination_mode="chars"` for prose-heavy reads and `pagination_mode="chunks"`
when you want to match the exact ChromaDB chunk view.
`read_genesis_doc` only reads Genesis product documentation. If the user asked
for a document they created, uploaded, or stored, use `read_knowledge_base_doc`
(after `search_knowledge_bases`) instead. A "Genesis doc not found" error is
almost always a sign the requested document is a user knowledge-base document.
### `search_data_context`
Call `search_data_context` when the user asks about data, tables, pipelines, jobs, or other objects that may be indexed in the Context Graph — for example "what tables do we have for billing?", "where does the ETL pipeline write?", or "find anything related to customer orders". Also use it as a first step before writing SQL or building lineage queries, to discover what's available.
It returns semantic search hits from the Context Graph vector index. Only nodes with indexed content (passed via the `content` field during `ADD_NODE` or `BULK_ADD_NODES`) are searchable here. Genesis can also fall back to graph-only matches when the semantic index does not return a strong candidate. Graph-only hits have no semantic similarity: they omit `score`, report `score_basis: "not_measured"`, and may include `graph_lexical_score` to order those fallback hits against each other. When semantic search is unavailable, a graph-only hit whose asset still has indexed content includes `has_indexed_document: true` and its indexed text. A graph-only hit without an indexed document can still include column names and count from its context-graph node, with `column_names_source: "context_graph"`; `column_names_partial: true` means the node lists fewer usable names than its column count. `ddl_available: false` in this case means the index has no definition, not that the asset's structure is unknown. `last_scanned_at`, when present, gives the context graph's last scan time for the asset. If results are empty but you expect data to exist, try `lineage_action` with `action="SEARCH_NODES"` for graph-based lookup, or verify that the source has been scanned with content indexing.
For how Jira source removal affects indexed issue search, see
[Jira Context Graph Scans](/docs/Integrations/Jira/Jira).
The response includes `success` (bool), `results` (hits with `qualified_name`, `source_system`, `node_type`, `score`, and optional `top_learnings`), `results_basis` (what the returned ranking represents), `pagination` (`returned` rows on this page, `candidate_total` in the retrieved candidate pool, and `next_offset` when another page exists), `candidates_by_section` (the candidate pool grouped by section, including candidates not represented in this page), `returned_by_section` (the rows in `results[]` grouped by section), and `warnings` (non-fatal issues). When `success` is `false`, the `error` field explains the failure and `error_code` may carry the machine-readable reason returned by the underlying `SEARCH_INDEX` operation. Use `error_code` rather than matching the English error text when it is present. Empty `results` with `success: true` means no matches, not a backend error.
The response also includes `semantic_index`, which explains whether semantic search ran. An available index reports `status: "available"`, `embedding_provider`, and `embedding_model`. An unavailable index reports `status: "unavailable"`, `missing` (`vector_store` or `embedding_client`), a diagnostic `reason`, and `enable_with`. If the missing component is the embedding client, Genesis also adds `genesis_enable_with` and `genesis_note`: configure the active provider and model with `embedding.active_provider` and `embedding.active_model` (or their `EMBEDDING_PROVIDER` and `EMBEDDING_MODEL` environment settings). The provider's `models.embedding_model` names a model but does not select it. A graph-only response is therefore distinguishable from a query with no matches.
For a user-scoped search, `warnings` includes an RBAC availability warning if
the RBAC subsystem failed during server startup. In that case, Genesis still
filters connections using each connection's allowed-user list, but does not
apply the admin-wide access bypass. Processes that do not initialize RBAC,
such as standalone utilities, do not emit this warning.
For data-asset hits, `column_names` is a preview rather than a complete schema, but every name in it is a whole identifier: a preview cut in the middle of a name omits that name instead of returning a fragment. `column_names_listed` reports how many names the row carries, while `column_count` reports how many columns the asset declares when the full indexed definition provides a reliable width. For example, `column_names_listed: 8` with `column_count: 19` means the row shows 8 of 19 columns; if the preview cuts inside the first identifier, it can show `column_names_listed: 0` while the asset still has columns. For a graph-only hit without an indexed document, those names and the count come from the context-graph node instead of indexed text; the returned list is limited to 50 names. If `column_names_partial` is `true`, the row omits one or more columns; call `describe_asset` before deciding that a column does not exist. A preview can also stop inside a trailing table clause after the final column name; when it still lists every declared column, `column_names_partial` is not set. When the asset's definition does not state a measurable width, `column_count` is omitted and `column_count_basis: "not_measured"` explains why. `ddl_available` describes the asset's indexed text, not just the preview: it is `true` when that text carries a `CREATE` statement or a declared column list that `describe_asset` can return, including a view whose DDL has no explicit column list. A shortened preview can therefore have `ddl_available: true` even when the definition is not visible in the preview. For Databricks assets, Unity Catalog table and column comments are included in the indexed content, so queries can match the descriptions recorded in those comments. When `describe_asset` returns a bound connection, its `canonical_connection_id` uses the same `.` form as the database-connection listing; pass either that value or `connection_id` to `run_query`.
For lineage traversal use `lineage_action` with `GET_UPSTREAM` or `GET_DOWNSTREAM`. Use `GET_INDEX_DOCUMENT` for an asset's indexed text, including DDL. When the index has no document but the context graph holds the asset, `GET_INDEX_DOCUMENT` remains unsuccessful (`success: false`) and reports `index_document: "absent"`, with available schema and scan facts in `graph_node`. Use `GET_NODE` for that node's summary and lineage neighbours.
| Parameter | Type | Default | Notes |
| - | - | - | - |
| `query` | string | none | Required search text. |
| `top_k` | integer | `15` | Maximum semantic matches returned. Max `100`. |
| `offset` | integer | `0` | 0-based result offset within the retrieved asset candidates. Retrieval uses `top_k` or `40`, whichever is larger; raise `top_k` above `40` to reach further. Wiki learnings are not paged. |
| `source_system` | string | `""` | Optional filter such as `snowflake`, `databricks`, `genesis`, or `git`. |
| `node_type` | string | `""` | Optional filter such as `table`, `view`, `dashboard`, `notebook`, or `file`. |
| `connection_id` | string | `""` | Optional filter matching `metadata.connection_id` or `metadata.source_name`. |
| `min_score` | float | `0` | Minimum similarity for indexed matches. The default applies no score floor; ranking still orders the page and `top_k` bounds its size. Graph-only, connection-inventory, and wiki-learning hits are not filtered by this threshold, and an asset named by its own name is never removed by it. When a non-zero threshold suppresses candidates, the response carries `score_filter` with the suppressed count and the highest suppressed score; a matching `warnings[]` entry is added when the page is short. |
| `include_raw` | boolean | `false` | Include raw Twin hit payloads in `raw_results`. |
`bot_id`, `thread_id`, and `user_id` are injected implicitly by Genesis at runtime, so you normally provide only the search and filter parameters above.
**Example**
```python theme={null}
search_data_context(
query="orders fact table",
top_k=10,
offset=0,
min_score=0,
source_system="snowflake",
)
```
Responses include `pagination` with `offset`, `top_k`, `candidate_total`, `returned`, `has_more`, and `next_offset`. `candidate_total` counts candidates retrieved for the query; `returned` counts rows on the current page. Pages of one query are slices of one ranking and do not repeat or drop rows. Pass `offset=pagination["next_offset"]` to fetch the next page when `has_more` is `true`. Retrieval uses `top_k` or `40`, whichever is larger, so a `top_k` below `40` retrieves the same candidate pool and only narrows the page. `results_basis` explains that these are ranked matches, not an enumeration of everything a connection contains. Wiki learnings are counted in `candidate_total` but are not paged; when `wiki_learnings.candidate_total_is_lower_bound` is `true`, the count is a lower bound because the wiki-learning fetch cap was reached, so call `wiki_search(query=...)` to retrieve the full set of matches.
`candidates_by_section` splits `pagination.candidate_total` by section, so it can
name a section that has no row on the current page. `returned_by_section` splits
`pagination.returned`, the rows in `results[]`. Use these fields instead of the
removed `section_counts`, `section_counts_returned`, and `total` response keys.
To resolve `bound_inaccessible`, a Genesis administrator can grant the person a
role listed under the connection's **Roles with Access**, or give an agent access
through its connection profile. See [Connections](/docs/Setup/Connections) and
[Users and Roles](/docs/Setup/Users-And-Roles).
Response items can include `connection_id`, `connection_name`, `search_source`, `connection_bound`, and `connection_binding_status`. `connection_name` identifies the registered connection that owns the asset; use it with `connection_id` when distinguishing assets from multiple database connections. When a hit carries a `connection_id`, Genesis cross-checks the live connection registry once per search so stale index metadata is not advertised as bound. When the registry is available, `connection_binding_status` reflects the live state and may override an indexed `bound` value. Possible values are `bound_unmeasured` (registered; nothing probed it, so reachability is not measured — the ordinary case because listing a connection does not open it), `bound` (registered and measured reachable), `bound_unreachable` (registered and measured unreachable), `bound_inaccessible` (registered, but the person or agent asking has not been granted access to it; a Genesis administrator can grant it), `bound_removed` (the index still names the connection but it is no longer registered), or `unbound`. Unbound candidates are not aggregated into `warnings`; inspect each result's `connection_binding_status` when binding matters. Hits may also include `connection_status` (the same vocabulary when the live registry was consulted), and searches that return it include `connection_status_vocabulary`, a mapping for every status value used on that page. `connection_reachable` is present only when reachability was actually measured: `true` for `bound`, `false` for `bound_unreachable` / `bound_inaccessible` / `bound_removed`, and omitted for `bound_unmeasured` — an absent `connection_reachable` means nothing was measured, never `false`. `connection_bound` is `false` when `connection_status` is `bound_inaccessible` or `bound_removed`. When the registry cannot be read, Genesis falls back to indexed metadata and omits `connection_status` / `connection_reachable`. `search_source` identifies the scoring lane: `indexed` hits use semantic similarity in `score`; `graph_only` hits are unscored and omit `score`, with `score_basis: "not_measured"`, and may expose `graph_lexical_score` for ordering within that fallback tier. A query that names an asset by its own name keeps that result even when its semantic score is below `min_score`; such a result is marked `name_match: "exact"`. Graph-only hits can also include `graph_lexical_match`, naming the matching tier (`name_is_query`, `name_starts_with_query`, `name_contains_query`, `qualified_name_ends_with_query`, `qualified_name_contains_query_at_segment_boundary`, `qualified_name_contains_query`, `every_query_word`, or `some_query_words`), and `graph_lexical_matched_words`, listing the query words found for the word-match tiers. These fields explain why an unscored row appears; they are not semantic similarity. `connection_inventory` hits use a connection-registry text match and are also not comparable with indexed similarity. `min_score` filters only `indexed` hits. Each result also carries a stable `result_id`, and `result_groups.sections[].result_ids` point back to those top-level `results[]` entries instead of duplicating item payloads. The `result_groups.database_connections[]` list contains at most one entry per connection, even when an asset hit ranks ahead of its connection node. Its `qualified_name` uses the single typed form `genesis:///connection/` (for example, `genesis://snowflake/connection/analytics`) for both an asset-derived entry and the connection node, so the same connection is not represented by two qualified names. Entries use `result_ids` to reference their matching asset results; use the top-level `results[]` for the full payloads. Regular entity hits with saved Team Wiki learnings also include `learnings_count`, `learnings_preview`, `top_learnings`, and `learnings_ref`; some hits additionally include `match_source` and `matched_qn` when the learning is anchored on a related entity. When `learnings_count` is greater than `0`, `top_learnings` carries up to 3 one-line headline teasers (each with `statement_id`, `headline`, and `category`). `search_data_context(...)` can also return dedicated `kind="wiki_learning"` results with `anchor_qn`, `learning_text`, `statement_id`, `score`, `match_source="text"`, and, when `anchor_qn` is present, `available_actions=["wiki_read"]`, `recommended_next_action="wiki_read"`, and `recommended_next_action_basis` explaining that `wiki_read` on the anchor returns the learning with the other learnings there. (`search_knowledge_bases` searches an agent's document indexes and does not return wiki learnings.) Read `learning_text` directly for those results, and call `wiki_read(qualified_name=result["anchor_qn"])` if you need more learnings on that anchor. Over MCP the same recommendation is a `call_tool` call object running `wiki_read` on `anchor_qn`. If a regular entity hit has `learnings_count` greater than `0`, review the returned `top_learnings` headlines and call `wiki_read(qualified_name=result["learnings_ref"])` before answering when any headline is relevant — the headlines are teasers only; read the full page so caveats, conventions, data quality warnings, and historical context can inform the response. When Twin needs to fall back or cannot complete the full preferred path cleanly, the response can also include top-level `warnings` plus `index_status_reason`. Short `summary` text is prose-first and strips raw DDL from the summary when the preview does not provide an explicit summary tag.
The response also reports index coverage. `index_status="partial"` means one or more
registered connections that a Context Graph scanner can read have no harvested tables
or views; `unharvested_connections` names them, and `unharvested_matching_query`
identifies the ones whose connection name or description matches the query. Lowering
`min_score` cannot reach data that was never harvested. `harvest_calls` provides the
exact Genesis registry call for each entry in `unharvested_connections`; each item has
`connection_id`, `tool_name`, `arguments`, and a `note` explaining the route. Use the
`tool_name` and `arguments` from that item rather than assuming every connection needs
registration first. An already registered source is harvested with
`action="SCAN_SOURCE"` and its `source_id`; a non-Genesis scanner with no registered
source is harvested with `action="REGISTER_SOURCE"`, its `source_type`, the
`connection_id`, and `scan_now=true`; and a `sqlite` connection is harvested by
scanning the deployment-wide Genesis source (`source_id="genesis"`), not by registering
a `sqlite` source. If the source registry cannot be read, the call is still provided,
but its note says whether the connection's existing source is unknown instead of
claiming that no source is registered. A connection with no scanner for its type, or a demo database whose
tables are not loaded into the index, is not `partial`: `unindexable_connections`
lists its `connection_id`, `canonical_connection_id`, `connection_type`, reason, and
whether its name or description matches the query. Search never sees those tables, but
`run_query` can still query the connections. When a scannable connection has no indexed
assets, Genesis checks the source registry and the 50 most recent scans for its own
source; a completed scan means the scan ran and found no tables or views, rather than
being unharvested. For a `sqlite` connection read by the deployment-wide Genesis source,
an active `database` container node named
`genesis://sqlite/connection/` with a `last_scanned_at` value proves that
the scan read the connection, even when it found no tables or views, so an empty SQLite
read does not remain `partial` forever. `index_status="coverage_unmeasured"` means Genesis could not
determine which registered connections have indexed assets, or a connection has no
listed type. `ready_with_warnings` means `warnings[]` is non-empty; `ready` means
coverage was measured for the scope and no warnings were returned. When
`connection_id` filters the search, `index_status_reason` identifies that connection
scope and says that registered connections outside the filter were not checked; the
status is not an instance-wide all-clear.
For `source_system="genesis"` hits, `text_preview` can be enriched from the
live Genesis object record instead of raw indexed text. Dataset previews can
summarize the description plus source hints, microapp previews can summarize
the app type plus bound datasets or connections, and dashboard previews can
summarize the description plus connection or source context.
### `find_past_queries`
Use `find_past_queries` for SQL/query history only when a user references prior SQL work such as "that report" or "the analysis we did yesterday", or asks about a table or view they may have queried before. It cannot locate, inspect, or manage artifacts such as blueprints, apps, files, or dashboards — do not call it merely because the request names one of those, or as background context for an artifact upload, replace, or install operation. Use the artifact's own tool group instead (activate via `manage_context` if needed). Genesis resolves the request to Twin-qualified anchors (from explicit `anchor_qns`, qualified names embedded in `topic`, token overlap with table/view names from visible past queries, or Team Wiki text search), looks up persisted SQL results across accessible threads, and returns reusable query matches plus related conventions and concerns. Recall is not gated on L0 wiki validation — unvalidated past queries can match when their extracted anchors align with the topic.
Use `search_data_context(...)` when the task is to inspect catalog metadata for a table or view, use `search_threads(...)` for broader cross-thread text recall that is not anchored to persisted SQL history, and use artifact-specific tools (blueprint, app, file manager, etc.) when the task is to find or manage a named artifact.
`find_past_queries(...)` works in both SQLAlchemy metadata deployments and
legacy SQLite-backed metadata deployments. In legacy mode, Genesis writes
query-anchor sidecar rows alongside stored query results and can lazily
backfill older stored results the next time this tool runs.
| Parameter | Type | Default | Notes |
| - | - | - | - |
| `topic` | string | none | Required natural-language topic, table/view name, or prior-report description from past SQL work. A plain topic can match extracted table/view names from visible past queries without an exact qualified name or wiki entry. |
| `anchor_qns` | `string[]` or `null` | `null` | Optional explicit Twin qualified names such as `snowflake://DB/SCHEMA/TABLE`. |
| `connection_id` | string or null | `null` | Optional `connection_id` filter. Defaults to all visible connections. |
| `since` | string or null | `null` | Optional ISO timestamp lower bound for `query_results.created_at`. |
| `until` | string or null | `null` | Optional ISO timestamp upper bound for `query_results.created_at`. |
| `scope` | string | `self` | Search scope: `self` or `all`. Use `all` only when the caller has `view_all_threads`. |
| `limit` | integer | `10` | Maximum matched queries returned. Max `50`. |
| `include_categories` | `string[]` or `null` | `null` | Optional L0 learning categories that count as `validated` in `matched_queries`; does not gate recall. Accepted values: `final`, `exploratory`, `rejected_approach`, `superseded`, `open_question`. When omitted, Genesis defaults to `["final"]`. |
`bot_id` and `user_id` are injected implicitly by Genesis at runtime, so you normally provide only the topic and optional filters above.
**Example**
```python theme={null}
find_past_queries(
topic="that churn report we built yesterday",
connection_id="snowflake-prod",
limit=5,
)
find_past_queries(
topic="customer orders mart",
anchor_qns=["snowflake://ANALYTICS/MART/CUSTOMER_ORDERS"],
include_categories=["final", "exploratory"],
)
```
The response includes `matched_queries`, `relevant_conventions`, `prior_concerns`, and `why_matched`. Each `matched_queries[]` item can include `query_id`, `thread_id`, `sql`, `columns`, `first_page_preview`, `first_page_redacted`, `created_at`, `category`, `validation_status`, and `matched_anchors`. `validation_status` is `validated` when a matched query has an L0 learning in one of the `include_categories` values (excluding `rejected_approach`), `rejected` when only `rejected_approach` learnings apply, or `unvalidated` when no qualifying L0 learning exists. `category` reflects the worst L0 learning category when present, or is `null` for unvalidated matches. `why_matched.resolution_method` reports how anchors were resolved: `explicit`, `topic_explicit_qn`, `query_text`, `wiki_text`, or `none`. If the caller cannot view a matched thread's row preview, `first_page_preview` is `null` and `first_page_redacted` is `true`.
For SQLite tables, a graph-qualified anchor also checks the historical
`sqlite://main/` anchor used by older query records. Genesis keeps
those records readable without migrating them; new anchors use the
connection-qualified graph identity.
Treat `prior_concerns` as context-specific rejected approaches, not blanket bans. A rejection from one prior report may not apply to a different question about the same table or view.
If `matched_queries` is empty, or a broader `scope="all"` search is not available to the caller, fall back to `search_threads(...)` for wider recall. When the user needs the actual prior SQL, tool outputs, artifact links, or report details rather than a recall summary, inspect the best candidate with `read_thread(thread_id="...", include_tool_calls=True)` (activate [System Manager Tools](/docs/Genbot-Toolkit/System-Manager-Tools) if needed). When the hit belongs to another bot, also pass `thread_bot_id` from the search result's `bot_id`.
When the user asks where data comes from, how a table is populated, or what feeds a dashboard or report, start with [Lineage Tools](/docs/Genbot-Toolkit/Lineage-Tools) and `lineage_action(action="GET_UPSTREAM", qualified_name="...")`. Fall back to thread or query recall only if upstream lineage has no relevant edges or does not explain the answer.
### Team Wiki tools
These calls live in `wiki_tools`, not `context_tools`, but they now complement `manage_context` because `SEARCH_CONTEXT` no longer returns Team Wiki hits. Use them when you need a read-only page for a scanned asset, an authored learning anchor that is not yet in the graph, or when you want to browse the Team Wiki hierarchy directly.
| Tool | Purpose |
| - | - |
| `wiki_search` | Semantic search across Team Wiki pages for relevant data assets and other graph-backed nodes. |
| `wiki_list` | List the immediate child nodes under an optional qualified-name prefix, including branches created by active authored learnings whose anchors are not in the graph. |
| `wiki_read` | Read one dynamically rendered Team Wiki page by `qualified_name`, including a learnings-only page when the anchor is not in the graph. |
| `wiki_write` | Save a learning or domain fact to the Team Wiki for a scanned data entity (requires `wiki.write_enabled` in AppConfig). |
#### `wiki_search`
Matching authored learnings are returned under `learning_hits`. Each learning
hit's `score` is a text-match strength on a 0–1 higher-is-better scale.
| Parameter | Type | Default | Notes |
| - | - | - | - |
| `query` | string | none | Required non-empty semantic search text. |
| `max_results` | integer | `20` | Maximum number of matching nodes returned. Max `200`. |
| `offset` | integer | `0` | Number of matches to skip for paging. |
| `wiki_id` | string | `default` | Wiki identifier; defaults to the shared graph-backed wiki. |
**Example**
```python theme={null}
wiki_search(
query="revenue dashboard",
max_results=10,
)
```
#### `wiki_list`
| Parameter | Type | Default | Notes |
| - | - | - | - |
| `prefix` | string | `""` | Optional qualified-name parent to list under. Leave empty to list top-level source systems. |
| `wiki_id` | string | `default` | Wiki identifier; defaults to the shared graph-backed wiki. |
**Example**
```python theme={null}
wiki_list(prefix="snowflake://ANALYTICS")
```
#### `wiki_read`
| Parameter | Type | Default | Notes |
| - | - | - | - |
| `qualified_name` | string | none | Required fully qualified graph node name to read, such as `snowflake://ANALYTICS/FINANCE/REVENUE`. |
| `wiki_id` | string | `default` | Wiki identifier; defaults to the shared graph-backed wiki. |
**Example**
```python theme={null}
wiki_read(qualified_name="snowflake://ANALYTICS/FINANCE/REVENUE")
```
If the requested qualified name has active authored learnings but no matching
Context Graph node, `wiki_read` returns a synthesized learnings-only page. Use
`wiki_list` to browse these learning-anchor branches under their qualified-name
prefix.
`wiki_read` also pairs with `search_data_context(...)`: when a regular entity hit includes `learnings_count` greater than `0`, review the returned `top_learnings` headlines (up to 3; each has `statement_id`, `headline`, and `category`) and use `learnings_ref` as the `qualified_name` to retrieve the full Team Wiki learnings for that entity when any headline is relevant. The headlines are teasers only — do not treat them as the full learning content. When `search_data_context(...)` returns `kind="wiki_learning"` results, read `learning_text` directly and use `wiki_read(qualified_name=result["anchor_qn"])` if you need the full Team Wiki page for that anchor.
When the H2 correction classifier is enabled, statement-tagged `wiki_read`
events from a threaded agent conversation are also treated as reliance signals
for the next-user-turn correction scan. See [Team Wiki Learnings and Memory](/docs/User-Guide/Team-Wiki-Learnings#h2-correction-classifier-model)
for the scan behavior and deduplication details.
For SQLite tables, `wiki_read` also resolves the historical
`sqlite://main/` learning anchor when you request the table's
connection-qualified graph name. Existing learnings remain available without
data migration.
#### `wiki_write`
Available only when `wiki.write_enabled` is `true` in AppConfig (the `wiki_tools` group is hidden otherwise). Interactive chat turns tag writes with `source_channel="chat"` by default. Flow and sandbox-runtime calls go through the flow tool bridge, which stamps non-spoofable provenance: `flow:` for flow steps, or `runtime:` when the bridge serves `execute_python_code` (sandbox runtime reuses the flow bridge with `flow_id` equal to the execution id). Agents do not set `source_channel`; it is omitted from the tool schema.
| Parameter | Type | Default | Notes |
| - | - | - | - |
| `qualified_name` | string | none | Required graph node the learning is about (for example `snowflake://ANALYTICS/FINANCE/REVENUE`). |
| `content` | string | none | Required learning text — state it clearly and concisely. |
| `commit_message` | string | `""` | Brief description of why the learning is being saved. |
| `supersedes_key` | string or null | `null` | When replacing a prior learning, pass its `statement_id` from `wiki_read` results or a `wiki_write` response to hide the older version from overlays and search. |
| `category` | string | `final` | Validation state (`final` for explicit saves). |
| `privacy_class` | string | `metadata` | `metadata` by default; use `contains_values` only when the learning includes specific data values. For `wiki_edit`, an explicitly provided value is applied exactly, including a `contains_values` to `metadata` downgrade after specific values are removed. |
| `wiki_id` | string | `default` | Wiki identifier; defaults to the shared graph-backed wiki. |
**Example**
```python theme={null}
wiki_write(
qualified_name="snowflake://ANALYTICS/FINANCE/REVENUE",
content="Revenue is recognized on shipment date, not invoice date.",
commit_message="Domain convention from finance review",
)
```
To replace a stale learning, call `wiki_read` first and pass the learning's
`statement_id` as `supersedes_key`. To refine an active learning with
`wiki_edit`, pass that same `statement_id` as its key. If the key is ambiguous
or does not identify an active learning, re-run `wiki_read` and use the current
`statement_id` shown there.
When using `wiki_edit`, an explicitly provided `category` is applied exactly to
the active learning. Use `rejected_approach` to retire a learning from the
default `final`-filtered overlays; valid categories are `final`, `exploratory`,
`rejected_approach`, `superseded`, and `open_question`.
When using `wiki_edit`, an explicitly provided `privacy_class` is also applied
exactly in either direction. Pass `metadata` after removing specific data
values from the text to downgrade a learning from `contains_values`; otherwise,
automated merges preserve the more restrictive class.
If a same-text `wiki_edit` retry encounters an earlier edit event, Genesis
deduplicates it when the requested category and privacy class are already
present. If the earlier event recorded the text but not the requested category
or privacy class, the retry re-applies the missing state and returns
`reason="reapplied_after_noop_event"`. A retry with different current text is
treated as stale and remains suppressed, so it cannot overwrite a later edit.
Background Librarian extraction is separate: it runs only when both `wiki.write_enabled` and `wiki.librarian_enabled` are `true`, and uses `wiki.extractor_model`. See [Advanced Settings → Team Wiki / Librarian settings](/docs/Setup/Advanced-Settings#team-wiki--librarian-settings).
### `search_threads`
Use `search_threads` for cross-thread discovery from the always-on `context_tools` surface. For current-thread-only recall, use `manage_thread_memory(action="SEARCH_MESSAGES", ...)` instead.
| Parameter | Type | Default | Notes |
| - | - | - | - |
| `query` | string | none | Required search text. |
| `limit` | integer | `20` | Maximum threads to return. Max `50`. |
| `include_summary` | boolean | `false` | Generate brief summaries for top hits. |
| `include_hidden` | boolean | `false` | Include hidden or background-job threads in results. |
| `bot_ids` | `string[]` or `null` | `null` | Optional list of bot IDs to search. Defaults to the current bot from context when omitted. |
| `response_format` | string | `formatted` | Response shape: `formatted` or `structured`. |
**Example**
```python theme={null}
search_threads(query="database migration")
search_threads(
query="ETL pipeline",
limit=10,
include_summary=True,
response_format="structured",
)
```
If `search_threads(...)` returns a plausible candidate, inspect that top hit before launching narrower searches. When you need staged search or structured tool/result filters, activate [System Manager Tools](/docs/Genbot-Toolkit/System-Manager-Tools) and use `find_threads(...)` directly. For one-hit inspection, use `read_thread(thread_id="...")`, and switch to `read_thread(thread_id="...", include_tool_calls=True)` for prior SQL, tool outputs, artifact links, reports, or other execution details. When the hit's owning bot differs from the current bot, pass `thread_bot_id` from the result's `bot_id`.
### `get_runtime_values`
Use `get_runtime_values` when the user, an agent-authored Flow, or integration code asks which Genesis instance is running, needs the instance name, or needs deployment identity without reading raw process environment variables.
This tool takes no parameters. It is part of the always-on `context_tools` group.
**Return shape**
| Field | Type | Notes |
| - | - | - |
| `success` | boolean | Whether runtime values were resolved. |
| `values` | object | Present when `success` is `true`. Currently includes `genesis_instance_name` (string): the resolved Genesis instance name used for deployment identity and routing. |
| `error` | string | Present when `success` is `false`. Resolution failure message for diagnosis. |
**Example (agent tool call)**
```python theme={null}
get_runtime_values()
```
**Example (Flow Python step)**
```python theme={null}
from genesis_flow import tools
result = tools.call("get_runtime_values")
if result.get("success"):
instance = result["values"]["genesis_instance_name"]
```
For user-facing Genesis settings use [config\_manager](/docs/Genbot-Toolkit/Config-Manager-Tools). For credentials or external service endpoints modeled as Connections use [connections\_action\_tools](/docs/Genbot-Toolkit/Additional-Tool-Groups#connections-action-tools).
If `success` is `false` or `genesis_instance_name` is missing or unexpected, use the `error` message for diagnosis and ask an administrator to configure `server.instance_name` through APP\_CONFIG, Helm `genesisConfig`, or `GENESIS__SERVER__INSTANCE_NAME`. See also [Metrics](/docs/Setup/Metrics) for how instance name is used in observability.
### `wait`
Use `wait` for a short, bounded pause when nothing will notify or wake the thread as work finishes, then check the work's status. Genesis clamps each call to 1–300 seconds. Do not use it to wait for an asynchronous run or job, or another agent, that wakes the thread when it is done. Instead, declare the matching stance with [`declare_goal_turn_status`](/docs/Genbot-Toolkit/Additional-Tool-Groups#declare_goal_turn_status) (`awaiting_run` or `awaiting_agent`) and end your turn; the wake returns you with the result. For running something at a future clock time, use a scheduled task or process instead.
| Parameter | Type | Default | Notes |
| - | - | - | - |
| `seconds` | integer | none | Required. Seconds to wait. Min `1`. Max `300`. |
| `reason` | string or null | `null` | Optional description of what you are waiting for; echoed in the result and server log. |
`bot_id` and `thread_id` are injected implicitly by Genesis at runtime.
**Return shape**
| Field | Type | Notes |
| - | - | - |
| `success` | boolean | `true` when the pause completed. |
| `waited_seconds` | number | Actual elapsed seconds (rounded to one decimal). |
| `reason` | string or null | Echo of the optional `reason` parameter. |
| `resumed_at` | string | UTC ISO-8601 timestamp when the pause ended. |
| `hint` | string | Suggests the next step, such as checking status or reading a completion notice. |
| `reminder` | string | Repeats that work which wakes the thread should use `declare_goal_turn_status` and end the turn instead of waiting again. |
**Example**
```python theme={null}
wait(seconds=30, reason="Databricks job run")
# After wait returns, check whether the background work progressed:
# read_thread(...), manage_thread_memory(...), or a domain status tool.
```
`wait` does not emit interim progress updates while it is paused. Its result includes a
reminder on every call, including a short poll: if the awaited work wakes the thread
itself, declare the matching stance and end the turn instead of waiting again.
### `manage_thread_memory`
Use `manage_thread_memory` for panel-aligned memory status, compression, thread-history search, and recovery.
| Parameter | Type | Default | Notes |
| - | - | - | - |
| `action` | string | `GET_STATUS` | Allowed values: `GET_STATUS`, `COMPRESS`, `RECOVER`, `SEARCH_MESSAGES`, `LIST_RECOVERABLE_BLOCKS`, `GET_HIDDEN_MESSAGES`, `GET_COMPRESSED_TOOL_RESULT`, `GET_COMPRESSED_PARAM_ARCHIVE`. |
| `target_percentage` | integer | `50` | Desired post-compression usage percentage for `COMPRESS`. |
| `compression_version` | string or null | `null` | Optional compressor override for `COMPRESS`: `V3` (legacy adaptive compressor) or `V6` (flat prose-first summary compressor). Defaults to the configured thread trimmer version, currently `V6`; other requested values fall back to `V6`. |
| `detailed_breakdown` | boolean | `false` | Include projected next-call bucket details for `GET_STATUS`. |
| `recover_handle` | string | `""` | Legacy recovery handle for `RECOVER`. Genesis auto-detects `recovery_id`, `tool_call_id`, or `archive_ref`. |
| `include_nested` | boolean | `false` | Include nested matryoshka layers for `LIST_RECOVERABLE_BLOCKS`. |
| `archive_ref` | string | `""` | Archive reference for `GET_COMPRESSED_PARAM_ARCHIVE`. |
| `archive_offset` | integer | `0` | Starting character offset for archived-parameter recovery. |
| `archive_max_chars` | integer | `4000` | Max characters returned by archived-parameter recovery. |
| `result_tool_call_id` | string | `""` | Tool-call ID for `GET_COMPRESSED_TOOL_RESULT`. |
| `result_message_index` | integer or null | `null` | Optional fallback message index for older compressed tool results. |
| `result_offset` | integer | `0` | Starting character offset for tool-result recovery, compressed or still visible in the thread. |
| `result_max_chars` | integer or null | `null` | Optional character cap for tool-result recovery. For an uncompressed result, omission returns up to 4,000 characters; `0` requests up to 50,000, and a positive value is capped at 12,000. |
| `recovery_id` | string | `""` | Legacy fallback handle for `GET_HIDDEN_MESSAGES`. For V6 summaries, prefer `start_message_num` plus `end_message_num`. |
| `hidden_offset` | integer | `0` | Number of hidden messages to skip. |
| `hidden_max_messages` | integer | `10` | Max hidden messages returned. |
| `hidden_content_offset` | integer | `0` | Character offset for chunked `GET_HIDDEN_MESSAGES` retrieval of one large message. |
| `hidden_content_max_chars` | integer or null | `null` | Optional character cap for one hidden-message chunk. When omitted, Genesis uses a 3000-character default. |
| `hidden_message_index` | integer or null | `null` | Legacy/debug direct retrieval index for `GET_HIDDEN_MESSAGES`. Prefer numeric V6 recovery by message number. |
| `hidden_node_id` | string | `""` | Legacy/debug node handle for a hidden message. Normal V6 recovery should use message numbers instead. |
| `start_message_num` | integer or null | `null` | Optional lower bound for `GET_HIDDEN_MESSAGES` or `SEARCH_MESSAGES`. For V6, combine with `end_message_num` to recover one exact message or a numeric range. |
| `end_message_num` | integer or null | `null` | Optional upper bound for `GET_HIDDEN_MESSAGES` or `SEARCH_MESSAGES`. |
| `query` | string | `""` | Search text for `SEARCH_MESSAGES`. |
| `search_scope` | string | `all` | For `SEARCH_MESSAGES`: `all`, `visible`, `hidden`, `summary`, `raw`, or `artifact`. |
**Example**
```python theme={null}
manage_thread_memory(action="GET_STATUS", detailed_breakdown=True)
manage_thread_memory(action="COMPRESS", target_percentage=50)
manage_thread_memory(
action="SEARCH_MESSAGES",
query="quarterly revenue",
search_scope="hidden",
)
manage_thread_memory(action="RECOVER", recover_handle="call_abc123")
manage_thread_memory(
action="GET_HIDDEN_MESSAGES",
start_message_num=42,
end_message_num=42,
message_offset=0,
)
```
For `GET_STATUS`, Genesis returns panel-aligned compression reporting. When the last-call snapshot includes `compression_history`, the response includes that object and derives `total_compressions`, `has_thread_compression_passes`, and `has_been_compressed` from `compression_history.total_event_count` when present, otherwise `compression_history.count`. `count` and `visible_event_count` reflect returned rows; `total_event_count` is the lifetime pass total. The separate `compression_artifacts` object still comes from the internal `GET_STATS` recovery summary.
`LIST_RECOVERABLE_BLOCKS` returns discovery entries for compressed tool results with fields such as `tool_name`, `tool_call_id`, `message_index`, and `handle`. For older compressed tool results that predate stored `tool_name` metadata, Genesis backfills `tool_name` from the original assistant tool call when that mapping is still available, and `result_message_index` remains the compatibility fallback for retrieval.
`GET_COMPRESSED_TOOL_RESULT` also recovers a result that is not compressed. In that case,
the response has `status: "not_compressed"`, `nothing_lost: true`, and quotes the stored
result in `value_chunk`; it is the tool's answer, so repeat the call only if that answer
was itself an error. Use `result_offset` with `has_more` and `next_offset` to read the
remaining text.
For V6 threads, `SEARCH_MESSAGES` and summary hints prefer durable `start_message_num` / `end_message_num` handles. `hidden_node_id` and `hidden_message_index` remain legacy/debug-only escape hatches.
On Databricks Apps, archived tool-call argument recovery can survive a restart for arguments within the durable-storage limits. See [Durable SQLite stores on Databricks](/docs/deployments/Databricks/Genesis-On-Databricks#durable-sqlite-stores).
### `local_files`
On Genesis Desktop, lists, reads and searches files anywhere on the person's
computer: Documents, Desktop, Downloads and project folders. It is available
only in laptop mode; on hosted and self-hosted Genesis the `file` tool stays
confined to Genesis's own repositories and uploads.
| Parameter | Type | Default | Description |
| - | - | - | - |
| `action` | string | none | Required: `list`, `read`, `search`, `find`, `write`, `delete` or `move`. |
| `path` | string | `""` | The file or folder: `~/Documents`, an absolute path, or a path relative to the home folder. Empty is the home folder. |
| `pattern` | string | `""` | `search`: the text to look for (case-insensitive). `find`: part of a name or a glob such as `*.pdf`. |
| `regex` | boolean | `false` | `search`: treat `pattern` as a regular expression. |
| `file_glob` | string | `""` | `search`: only files whose name matches this glob. |
| `include_hidden` | boolean | `false` | `list`, `search`, `find`: include names that start with `.`. |
| `start_line`, `max_lines` | integer | `1`, `400` | `read`: the window of lines to return (at most 2,000). |
| `max_results` | integer | `100` | `search`, `find`: most results to return (at most 1,000). |
| `content` | string | none | `write`: the full text of the file (at most 1 MB). |
| `overwrite` | boolean | `false` | `write`: replace a file that already exists. |
| `destination` | string | `""` | `move`: the new path, which must not exist yet. |
**Examples**
```python theme={null}
local_files(action="list", path="~/Documents")
local_files(action="search", path="~/projects/app", pattern="TODO", file_glob="*.py")
local_files(action="write", path="~/Desktop/summary.md", content="# Summary\n...")
```
`list`, `read`, `search` and `find` run at once. On a Mac, the first look into
Documents, Desktop or Downloads makes macOS ask the person whether Genesis may
open that folder; if they decline, the tool returns `refused` and says where to
allow it (System Settings → Privacy & Security → Files and Folders).
`write`, `delete` and `move` inside Genesis's own folders run at once. Anywhere
else they create an Action Review approval card in the thread, and nothing
changes until a person approves. `delete` removes a file or an empty folder.
Credential stores stay closed by default: `~/.ssh`, `~/.aws`, `~/.azure`,
`~/.gnupg`, `~/.config/gcloud`, `~/.config/gh`, `~/.kube`, `~/.docker`,
`~/.netrc`, `~/.git-credentials`, the macOS keychain, browser profiles and
cookies, other CLI sign-ins (Databricks, Snowflake, dbt, npm, PyPI, Terraform, Cargo, Maven, Gradle, RubyGems, Vault, Oracle Cloud, 1Password, Claude Code, Codex), `.env` and `.envrc` files, and Genesis's own database, logs and keys. An administrator can open them
with `desktop.file_access_block_credentials`; see [Genesis Desktop file
access](/docs/Setup/Advanced-Settings#genesis-desktop-file-access).
The result includes a `status` (`ok`, `needs_approval`, `refused`, `not_found`
or `unavailable`) and, by action, `entries`, `content`, `matches` or `paths`.
### `run_local_command`
On Genesis Desktop, runs a bash command on the person's computer in an OS
sandbox. It is available only in laptop mode. Command mode is always on in
Genesis Desktop; in other laptop-mode deployments, an administrator controls
it. See [Genesis Desktop command
mode](/docs/Setup/Advanced-Settings#genesis-desktop-command-mode).
| Parameter | Type | Default | Description |
| - | - | - | - |
| `command` | string | none | Required bash command. It runs as `bash -c`, so pipes, `&&`, redirects, globs and scripts work. |
| `reason` | string | none | Required. One short sentence saying why the command is needed. The approval card shows its redacted text under the command, with whitespace collapsed and a maximum of 300 characters. |
| `working_directory` | string | `""` | Absolute path of the folder to run in, such as a project or Git repository. Empty runs in a fresh empty folder. The home folder itself, `~/Library` and hidden folders are refused. |
| `timeout_seconds` | integer | `60` | Command timeout in seconds, bounded to `1`–`300`. |
**Examples**
```python theme={null}
run_local_command(
command="df -h",
reason="To see how much disk space is free.",
)
run_local_command(
command="git push",
reason="To publish the fix to the shared branch.",
working_directory="/path/to/repository",
)
```
Local reads run immediately. Programs that only read include `ls`, `cat`, `head`,
`tail`, `pwd`, `grep`, `wc`, `echo`, `printf`, `df`, `du`, `uname`, `uptime`,
`whoami`, `id`, `stat`, `which`, `type`, `vm_stat`, `sw_vers`, `system_profiler`,
`lsof`, `cut`, `tr` and `column`. Some programs are read-only only with safe
arguments: `printf` without `-v`; `find` without `-exec`, `-execdir`, `-ok`,
`-okdir`, `-delete` or output-file options; `rg` without `--pre`; `sort` without
output or compression-program options; `uniq` without a second file; `file` without
compile options; `date` without a date-to-set argument; `hostname` without a new
name; `sysctl` without a value; `top` with a positive sample count such as
`top -l 1`; `diskutil list` or `diskutil info`; `ps` without options that print
process environments; and `jq` unless its filter reads the environment or loads
filters/modules from files. An unquoted file-name pattern that could expand into
a writing or program-running option also asks for approval. Version checks run immediately for
`python` and `python3` with `--version`
or `-V`; `java` with `-version` or `--version`; `go` with `version`; and `node`,
`npm`, `yarn`, `pnpm`, `deno`, `bun`, `ruby`, `uv`, `pip`, `pip3`, `cargo`,
`rustc`, `docker`, `brew`, `terraform`, `claude` and `codex` with `--version`.
Read-only AWS, GitHub, Azure and Git CLI commands run immediately on their own.
Local reads can also be joined only by `|`, `&&`, `||` or `;`, such as
`ps aux | grep python`; a CLI command in a chain needs approval. Every other
command, including one with a redirect, `&`, a substitution, a variable, `env`,
a network tool or a program that writes, creates an Action Review approval card in the thread that
shows the exact command and the agent's reason; nothing runs until a person
approves. Destructive commands such as `rm -rf`, `git push --force` and AWS delete
operations are marked on the card. Sign-in commands are handed to the person to
run in their terminal. After an expired sign-in, use the returned `login_command`
and retry.
In the sandbox a command can read the person's files (Documents, other
projects, anything in the home folder) and system programs and files, except the
credential stores that [`local_files`](#local_files) keeps closed (`~/.ssh`,
other CLIs' sign-ins, browser profiles, `.env` files, Genesis's own data) while
`desktop.file_access_block_credentials` is on. The working folder is writable
only after approval. Its temporary folder and the sign-in/cache files needed by
any AWS, GitHub, Azure or Git CLI it runs are writable for the command; nothing
else can be written. When a command reports "Operation not permitted", the
result's `refused_paths` says whether Genesis's sandbox refused the path or
macOS privacy may have (a read in Documents, Desktop or Downloads that the person
has not allowed for Genesis). Approved commands
can reach any internet host, while a read that runs at once can reach only its
CLI's servers. Loopback, link-local, cloud-metadata and this computer's own
addresses are blocked. A CLI's settings and sign-in are available only when the
command invokes that CLI; mentioning its name as an argument does not open its
settings.
The result includes a `status` (`ok`, `failed`, `timed_out`, `needs_approval`,
`needs_person`, `needs_sign_in`, `refused`, or `unavailable`). Completed runs
also return `exit_code`, `output`, `truncated`, and `duration_seconds`. Immediate
command output is redacted and limited to 20,000 characters. Commands whose
output may contain credentials require approval, and that output is withheld.
Approved commands return an exit code and up to 1,500 characters of output to
the thread after the person approves them. The approval card then shows the run's
result: Running, Done, Failed with its exit code, or Timed out, with the output.
## Related pages
* [Agents Center and Skills](/docs/User-Guide/Agents-Center-And-Skills)
* [Skill Runtime Tools](/docs/Genbot-Toolkit/Skill-Runtime-Tools)