Tools

Tools

Every tool needs a role, and each role can do everything the roles below it can (see Roles and Audit).

flowchart LR
    viewer["viewer<br/>ask, search, verify, feedback, receipts"] --> operator["operator<br/>+ read-only SQL"] --> admin["admin<br/>+ layers, archived patterns, users, audit, reset"]

Loading

Asking and checking

Tool	Role	What it does
strata_ask(question, layers=None, include_sources=True, top_k=10, response_format="concise", mode=None)	viewer	Rewrites a question, searches in parallel, reranks, and returns found, partly found or not found with the best passages, each with its file, page, lines, headings and date (what it returns). A note says when a named clause is cut or left out, when more sections match than were read or the question names more than 10 references, or when a name the question asks about is in no passage. When a passage returned comes from an extractive layer, or with mode: "extractive", it answers with the document's own sentences and a receipt
strata_verify(draft, passages)	viewer	Checks a drafted answer against the passages it cites: every quote, and every number, date, amount, code and clause reference in a sentence, must be in the passages cited there. A fact in a sentence with no citation is checked against all the passages given; a draft with no citation at all is flagged. A verified draft gets a receipt; a draft with citations but nothing to check returns nothing_checked and none. Sentences with no quote or fact are listed in unchecked_sentences, outside the verdict (checking a drafted answer)
strata_search(query, layers=None, top_k=5, metadata_filter=None)	viewer	Hybrid search for exact terms and identifiers, with optional layer and metadata filters, and a confidence level; a clause or section the query names (clause 7.2) comes first, verbatim, marked "cut": true when only its start fits; a top-level note counts the matching sections past the first 10 and names the references past the first 10, which were not looked up
strata_get_receipt(receipt_id)	viewer	Opens a receipt (rcpt_…, also the resource strata://receipts/{receipt_id}): the stored quotes of an answer, each in its surrounding document text, marked current, changed (with the newer version) or gone (its file was removed from its folder or its layer was deleted). Open to whoever asked, to admins, and to anyone who may read every cited layer, for RECEIPT_RETENTION_DAYS (90 by default). From the command line: stratakb receipt <id>. Receipts are issued by strata_verify and by extractive answers
strata_feedback(interaction_id, helpful, correct_layer=None, better_query=None, chunk_feedback=None)	viewer	Rates a result as helpful or not, per answer or per passage (S1) or chunk (useful, wrong or outdated); see Feedback
strata_learning_stats(layer=None)	viewer	What the learning system has recorded and learned, the top synonyms with their layer and usage_count

Layers

Tool	Role	What it does
strata_list_knowledge_layers()	viewer	Lists layers with document and chunk counts and their answer mode. Admins also see each layer's owner, root folder and archived patterns
strata_get_layer_status(name)	viewer	One layer's configuration and ingestion history, with the same admin-only fields
strata_create_knowledge_layer(name, display_name, description="", metadata_schema=None, chunk_config=None, routing_patterns=None, answer_mode="grounded")	admin	Creates a layer
strata_ingest_documents(layer_name, source_path, replace_all=False)	admin	Syncs a file or folder into a layer: adds, replaces and removes files; reports added, updated, unchanged, removed, skipped and flagged (what it reports)
strata_apply_preset(preset_path, docs_root=None, dry_run=False)	admin	Creates or updates a layer from a preset and ingests its sources
strata_set_archived_patterns(layer_name, patterns)	admin	Replaces the layer's list of archived file patterns, in .gitignore style, at most three wildcards each; an empty list clears them. Citations are labelled from the next ask on, with no new ingest
strata_delete_knowledge_layer(name)	admin	Deletes a layer and its chunks
strata_reset_learning(layer=None, confirm=False)	admin	Clears learned rewrites, synonyms and affinities, for one layer or all

Server, users and audit

Tool	Role	What it does
strata_whoami()	viewer	Your identity and role
strata_admin_health()	viewer	Database, pgvector and schema status, the local-only switch, the providers that receive data, whether the SQL tools are on, and the embedding model and vector column checks
strata_admin_audit_log(user_id, action, tool_name, from_date, to_date, limit=50)	admin	Queries the audit log; every filter is optional
strata_admin_list_users()	admin	Lists users and roles
strata_admin_update_role(user_external_id, new_role)	admin	Changes a user's stored role

Database

Tool	Role	What it does
strata_db_schema(table_name=None)	viewer	Lists tables, or a table's columns and keys
strata_db_vector_stats()	viewer	Chunk counts per layer, vector dimensions and index sizes
strata_db_sample_chunks(layer_name, limit=5)	viewer	Sample chunks from a layer
strata_db_query(sql, params=None)	operator	Read-only SQL (only with READONLY_DATABASE_URL)
strata_db_explain(sql)	operator	Query plan for a SQL statement (only with READONLY_DATABASE_URL)

Resource and prompt

• strata://receipts/{receipt_id}: the same receipt strata_get_receipt opens, with the same access rules.
• answer_from_documents: an MCP prompt with a question and optional comma-separated layers, walking the answer contract. It reads no data and needs no role; the tools it names make their usual role checks.

Notes

The SQL tools never run as the owner role. They are only registered when READONLY_DATABASE_URL is set, and at startup the server removes them again when that role is a superuser, a member of a superuser role, a member of pg_read_server_files, pg_write_server_files, pg_execute_server_program or pg_signal_backend, or cannot be checked within 5 seconds (for example, the database is unreachable or does not answer; restart the server once it is up). strata_admin_health says which applies under sql_tools. What the strata_readonly role can read is in Read-only SQL.

Identity. On the stdio transport, STRATA_USER and STRATA_ROLE set who you are. The server reads them once, when it starts; changing either takes a restart. Whoever starts the server picks the role, so on stdio roles separate duties rather than enforce security; see SECURITY.md.

stratakb add has no role check: whoever can reach the database with DATABASE_URL can add a folder. Each run writes one audit entry with the tool name cli:add, the folder, the run id and the counts per outcome (no file names). Its user is STRATA_USER when you set it, otherwise os: plus your login name, a name nobody verified.

Search and ask each write one audit entry with the first 200 characters of the query or question, with IBANs, BICs and account numbers replaced by placeholders ([IBAN_REDACTED], [BIC_REDACTED], [ACCT_REDACTED]), plus the layers searched and whether routing fell back; for strata_ask also the answer mode used. AUDIT_STORE_RAW_QUERIES=true keeps the question as written; LEARNING_STORE_RAW_QUERIES has no effect on the audit log.

Feedback and reset each write one audit entry. A feedback entry holds the interaction id and the rating, not the suggested query or layer, and names only the extras (layer correction, better query, chunk ratings) that were stored; a reset entry names the layer, or says it reset everything. A reset runs as one transaction: if it fails in the database, nothing is deleted, and the tool returns an error and writes no audit entry. An empty layer is refused; omit it for a global reset. A layer is trimmed of surrounding spaces, and the result gives the number of rows deleted, with a message when that is 0 because the layer has no learning data or does not exist. A layer reset keeps the interaction history and does not reach synonyms stored with no layer, so a pair with enough evidence is learned again on the next promoter run; use the global reset to remove a bad synonym for good.

Chunk ratings. A rating other than useful, wrong or outdated refuses the whole strata_feedback call: it stores nothing, and the error lists the allowed values. When the rating is stored but an extra is not, the status stays ok, and not_stored and warning name each extra that failed (correct_layer, better_query, chunk rating S2). A failed learning read or write logs a warning with the error type only, never the error text.

Presets and archived patterns. Each strata_apply_preset run writes one audit entry with the layer, whether it was created, updated or already up to date, the names of the settings that changed (never their values) and the number of documents and chunks ingested. A refused run writes none. strata_set_archived_patterns writes a set_archived_patterns entry with the layer and the patterns, and so does strata_apply_preset when it changes a layer's archived patterns or creates a layer with some.