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
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.
never_compress_skills is set through set_bot_context_defaults, not through
manage_context; see Bot Management Tools.
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
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.
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<clean-version>.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<clean-version>.mdx.
It does not substitute another release. A dev build without an exact published
release returns empty notes.
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. 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.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:
Typical flow
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:
ADD_CONTEXT response includes:
new_skills_added— list of newly activated skills.auto_activated_skills— prerequisite skills Genesis activated automatically.inlined_skills— skills whose primarySKILL.mdis included directly in this response.skill_activation_hints[].primary_file_inlined—truewhenprimary_file_contentis present on the hint.skill_activation_hints[].primary_file_content— primarySKILL.mdtext when inline delivery succeeds.skill_activation_hints[].primary_file_truncatedandskill_activation_hints[].primary_file_next_start_char— pagination metadata when the inlineSKILL.mdbody was cut off and needs continuation viaread_assigned_skill_file(...).skill_activation_hints[].next_step— either confirms the inline primary-file path or gives the exactread_assigned_skill_file(...)follow-up when the primary file is truncated or unavailable.
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.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.
Example
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.
Example
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.
Example
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 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.
Example
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.
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 <type>.<name> 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.
Example
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 and
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://<type>/connection/<name> (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/<connection_id> 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.
Example
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/<table> 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 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 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 inwiki_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.
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.
Example
wiki_list
Example
wiki_read
Example
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
for the scan behavior and deduplication details.
For SQLite tables, wiki_read also resolves the historical
sqlite://main/<table> 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:<flow_id> for flow steps, or runtime:<execution_id> 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.
Example
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.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.
Example
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 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
Example (agent tool call)
For user-facing Genesis settings use config_manager. For credentials or external service endpoints modeled as Connections use 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 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 (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.
Return shape
Example
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.
Example
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.
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.
Examples
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 its working folder and system programs and
files. 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; the rest of the home folder (other
projects, ~/.ssh and unrelated credentials) is unreadable. 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.