@littlebigbrain/mcp 0.8.0 → 0.9.0

package/README.md

@@ -104,6 +104,22 @@ The result contains one row on a fresh graph:
 The query follows a stored relationship to its database label. Strong consistency
 lets it read the import without waiting for a background index job.
 
+An agent without a SPARQL query can pass the question in plain words:
+
+```json
+{
+  "mode": "question",
+  "graph": "quickstart",
+  "question": "Which database does Auth Service write to?"
+}
+```
+
+The server selects the kind of query, writes the SPARQL query from a
+description of the graph, checks it, and runs it. The result holds the route,
+the rationale, the query, and its rows. `next` continues the same query with
+`mode: "sparql"`. Each question uses model tokens and counts toward a daily
+limit of the stack, so the tool does not retry a failed call.
+
 For your own data, start with `lbb_inspect` using `action: "guide"` or
 `action: "ontology"`. Imported Resource Description Framework (RDF) data keeps
 its original identifiers; inspect it with SPARQL when choosing query predicates.
@@ -113,15 +129,15 @@ its original identifiers; inspect it with SPARQL when choosing query predicates.
 | Tool | Purpose |
 | --- | --- |
 | `lbb_inspect` | Read the schema, graph status, and entities. |
-| `lbb_query` | Run SPARQL queries, search by meaning, or request summary statistics. |
+| `lbb_query` | Ask a question in plain words, run SPARQL queries, search by meaning (also inside a SPARQL query with `search:similarTo`), or request summary statistics. |
 | `lbb_rdf` | Import RDF documents or add facts with SPARQL `INSERT DATA`. |
 | `lbb_embeddings` | Inspect search setup and preview the text to embed. |
 | `lbb_embeddings_manage` | Set up or refresh embeddings, or change the embedding model. |
 | `lbb_embeddings_delete` | Delete an embedding and its stored vectors. |
 | `lbb_commit` | Write or retract JSON facts, or record search feedback. |
 | `lbb_configure` | Define record types and relationships, list and apply ontology starters (CRM, documents, work), or publish validation rules. |
-| `lbb_evals` | Label query results and check whether later queries return the expected answers. |
-| `lbb_models` | Compare retrieval settings and read model training datasets. |
+| `lbb_evals` | Label query results and check whether later queries return the expected answers. Read the model checks of a graph, and agree with or correct a check that the user confirmed. |
+| `lbb_models` | Compare retrieval settings, read model training datasets, or read a month of managed-model activity. |
 
 See [search by meaning](https://docs.littlebigbrain.com/guides/search-by-meaning/)
 for embedding setup. To define constraints with the Shapes Constraint Language

package/dist/question.d.ts

@@ -0,0 +1,24 @@
+import type { LbbClient } from "@littlebigbrain/client";
+type QuestionRoute = "lookup" | "aggregate" | "search" | "history" | "schema" | "unanswerable";
+export interface QuestionArgs {
+    question: string;
+    context?: string;
+    route?: QuestionRoute;
+    limit?: number;
+    run?: boolean;
+    detail?: string;
+    graph?: string;
+}
+/**
+ * `lbb_query mode=question`: the server turns the question into a SPARQL
+ * query and, by default, runs it. The rows are bounded as `mode=sparql`
+ * bounds them, and `next` continues the same query with `mode=sparql`.
+ */
+export declare function answerQuestion(client: LbbClient, args: QuestionArgs, textFormat?: "compact" | "pretty"): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: Record<string, unknown>;
+}>;
+export {};

package/dist/question.js

@@ -0,0 +1,87 @@
+import { QUESTION_MAX_ROWS } from "./tool-contracts.js";
+import { defaultRowLimit, normalizeDetail, queryEnvelope, queryToolResult, rowPageFrom, rowPageNext, scoped, } from "./tool-runtime.js";
+/**
+ * `lbb_query mode=question`: the server turns the question into a SPARQL
+ * query and, by default, runs it. The rows are bounded as `mode=sparql`
+ * bounds them, and `next` continues the same query with `mode=sparql`.
+ */
+export async function answerQuestion(client, args, textFormat) {
+    const detail = normalizeDetail(args.detail);
+    const run = args.run ?? true;
+    const rowLimit = Math.min(args.limit ?? defaultRowLimit(detail), QUESTION_MAX_ROWS);
+    const target = scoped(client, args.graph);
+    const body = {
+        question: args.question,
+        ...(args.context !== undefined ? { context: args.context } : {}),
+        ...(args.route !== undefined ? { route: args.route } : {}),
+        run,
+        ...(run ? { limit: rowLimit } : {}),
+    };
+    // Each call uses model tokens, and the server corrects a failing query
+    // once, so a failed call is not retried.
+    const response = await target.request("POST", "/v1/query/rewrite", {
+        body,
+        retry: false,
+        query: { consistency: target.defaultConsistency },
+    });
+    const { route, query, result } = response;
+    const traceId = result?.trace_id ?? null;
+    const answer = {
+        route: { kind: route.kind, confidence: route.confidence, by: route.by },
+        rationale: response.rationale,
+        sparql: query?.sparql ?? null,
+        entailment: query?.entailment ?? null,
+        ...(typeof query?.as_of_commit_seq === "number"
+            ? { as_of_commit_seq: query.as_of_commit_seq }
+            : {}),
+        ...(response.history ? { history: response.history } : {}),
+        error: response.error ?? null,
+        trace_id: traceId,
+        attempts: response.attempts,
+    };
+    const notes = [];
+    if (traceId) {
+        notes.push(`eval trace ${traceId}: to label rows, read their item ids with lbb_evals action=trace trace_id=${traceId}, then call lbb_evals action=label trace_id=${traceId} item=<id> valid=true|false (or items=[…]).`);
+    }
+    if (response.history?.as_of_date) {
+        notes.push(`The question names the date ${response.history.as_of_date}. Find the commit of that date, then run the query with lbb_query mode=sparql as_of_commit_seq=<commit>.`);
+    }
+    if (response.error && query) {
+        notes.push("The last query failed (see error). Correct it and run it with lbb_query mode=sparql, or ask again with more context.");
+    }
+    const label = `lbb_query.question: route ${route.kind} (${route.by}, confidence ${route.confidence.toFixed(2)})`;
+    const data = result
+        ? JSON.parse(result.results)
+        : undefined;
+    const rowPage = result ? rowPageFrom(result) : undefined;
+    const bindings = data?.results
+        ?.bindings;
+    if (data && rowPage && query && Array.isArray(bindings)) {
+        // The same query continues with mode=sparql at the commit the run read.
+        const pin = query.as_of_commit_seq ?? result?.snapshot?.served_at_seq;
+        const cursorBase = {
+            v: 1,
+            mode: "sparql",
+            graph: args.graph,
+            detail,
+            row_limit: rowLimit,
+            query: query.sparql,
+            entailment: query.entailment,
+            ...(typeof pin === "number" ? { as_of_commit_seq: pin } : {}),
+        };
+        return queryToolResult(queryEnvelope(label, { ...answer, ...data }, detail, rowPage, rowPageNext(cursorBase, rowPage), cursorBase, { textFormat, notes }), textFormat);
+    }
+    // No rows to page: the query only, an ASK answer, or no query at all. The
+    // query text is returned whole.
+    const summary = data
+        ? `${label}: ran the query`
+        : query
+            ? `${label}: ${response.error ? "the query failed" : "the query, not run"}`
+            : `${label}: no query`;
+    return queryToolResult({
+        summary,
+        data: { ...answer, ...(data ?? {}) },
+        ...(rowPage ? { row_page: rowPage } : {}),
+        ...(notes.length ? { notes } : {}),
+    }, textFormat);
+}

package/dist/tool-contracts.js

@@ -2,6 +2,8 @@ import { z } from "zod";
 export const DEFAULT_DETAIL = "compact";
 export const HARD_OUTPUT_CHARS = 80_000;
 export const MAX_QUERY_ROW_LIMIT = 5_000;
+/** The most rows `POST /v1/query/rewrite` returns from a run. */
+export const QUESTION_MAX_ROWS = 1_000;
 export const READ_ONLY = { readOnlyHint: true };
 export const IDEMPOTENT_WRITE = {
     readOnlyHint: false,
@@ -43,6 +45,8 @@ export const graphScope = {
 };
 export const jsonObjectSchema = z.record(z.string(), z.unknown());
 export const jsonObjectArraySchema = z.array(jsonObjectSchema);
+/** A month, `yyyy-mm` (UTC), as the model activity and model checks read it. */
+export const yearMonthSchema = z.string().regex(/^\d{4}-(0[1-9]|1[0-2])$/);
 export const readScope = { detail: detailSchema, ...graphScope };
 export const metadataPageSchema = {
     page_size: z
@@ -373,10 +377,11 @@ export const inspectInputSchema = z.discriminatedUnion("action", [
             .describe("Entity id (hex); alternative to entity_type+name"),
         entity_type: z.string().optional(),
         name: z.string().optional(),
+        // Kept for an actionable error when an older connector sends this field.
         as_of: z
             .string()
             .optional()
-            .describe("Valid-time snapshot pin (RFC3339): reproduce the node as of this instant."),
+            .describe("Unsupported for entity; use as_of_commit_seq for a retained commit snapshot."),
         as_of_commit_seq: z
             .number()
             .int()
@@ -391,6 +396,9 @@ export const inspectInputSchema = z.discriminatedUnion("action", [
 // agent write a valid query on the first attempt instead of round-tripping
 // through the ontology to reverse-engineer term IRIs.
 export const SPARQL_IRI_GUIDE = 'IRI scheme: relations are <https://littlebigbrain.com/r/NAME> (NAME lowercased, e.g. writes_to; reverse a relation with the ^ path operator, no stored inverse triple). Types are <https://littlebigbrain.com/class/NAME> (lowercased), matched as `?x a <…/class/NAME>` with explicit entailment=subclass, rdfs, or owl for inference (default none). Property fields are <https://littlebigbrain.com/p/NAME> (lowercased). The local name is ALWAYS lowercase — an uppercase one (e.g. <…/r/FOR_CLIENT>) is a different, non-existent IRI that silently matches nothing; this tool auto-lowercases the local name of /r/, /class/, and /p/ IRIs for you and adds a `notes` entry when it does, so a stray uppercase still resolves. (Structured mode\'s `predicate` is case-insensitive on its own.) Entities are content-addressed <https://littlebigbrain.com/e/HASH> — never build an entity IRI from a name; anchor a named entity by its label instead: `?e <http://www.w3.org/2000/01/rdf-schema#label> "Acme"`. Discover the exact relation and type names with lbb_inspect action=ontology. SELECT and ASK only (CONSTRUCT/DESCRIBE are rejected).';
+// Search by meaning runs inside SPARQL text as a pattern, so an agent can
+// filter and join the hits in one query instead of a search then a lookup.
+export const SPARQL_SEARCH_GUIDE = 'Search by meaning inside the query (the graph needs an embedding; see lbb_embeddings action=list): PREFIX search: <https://littlebigbrain.com/search#> SELECT ?x ?score WHERE { ?x search:similarTo "card payments" ; search:score ?score . ?x <https://littlebigbrain.com/r/calls> ?y } ORDER BY DESC(?score) LIMIT 5. The other patterns filter and join the hits. One search:similarTo per query, with a variable subject, in the main group (not inside OPTIONAL, UNION, MINUS or a subquery). The object is text, an entity IRI (records like that one) or a vector literal. search:top N sets the hits (1 to 1000; default the query LIMIT, then 10) and search:embedding "name" searches one embedding. FILTER(?score > 0.8) keeps close hits. The result\'s search field reports the plan (nearest, filter_first or search_first), the hits and complete.';
 export const queryInputSchema = z.discriminatedUnion("mode", [
     z
         .object({
@@ -433,7 +441,7 @@ export const queryInputSchema = z.discriminatedUnion("mode", [
         query: z
             .string()
             .optional()
-            .describe(`SPARQL 1.1 query text (SELECT or ASK). Valid-time as_of is unsupported; use as_of_commit_seq for a retained commit snapshot. ${SPARQL_IRI_GUIDE} Example: SELECT ?service ?db WHERE { ?service <https://littlebigbrain.com/r/writes_to> ?db } LIMIT 10`),
+            .describe(`SPARQL 1.1 query text (SELECT or ASK). Valid-time as_of is unsupported; use as_of_commit_seq for a retained commit snapshot. ${SPARQL_IRI_GUIDE} Example: SELECT ?service ?db WHERE { ?service <https://littlebigbrain.com/r/writes_to> ?db } LIMIT 10. ${SPARQL_SEARCH_GUIDE}`),
         // Kept for an actionable error when an older connector sends this field.
         as_of: z
             .string()
@@ -454,6 +462,42 @@ export const queryInputSchema = z.discriminatedUnion("mode", [
         ...readScope,
     })
         .strict(),
+    z
+        .object({
+        mode: z.literal("question"),
+        question: z
+            .string()
+            .min(1)
+            .describe("question: the question in plain words (required), 1 to 4,000 characters. The server writes the SPARQL query from a description of this graph, checks it, and runs it."),
+        context: z
+            .string()
+            .optional()
+            .describe("question: notes for the model, at most 8,000 characters: what the data means, units, names to prefer."),
+        route: z
+            .enum([
+            "lookup",
+            "aggregate",
+            "search",
+            "history",
+            "schema",
+            "unanswerable",
+        ])
+            .optional()
+            .describe("question: the kind of query, when you know it. Omit it and the router model selects it."),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(QUESTION_MAX_ROWS)
+            .optional()
+            .describe("question: rows the run returns, 1 to 1,000. Defaults by detail: compact=20, standard=100, full=1000."),
+        run: z
+            .boolean()
+            .optional()
+            .describe("question: run the query and return its rows. Defaults to true; false returns the query only."),
+        ...readScope,
+    })
+        .strict(),
     z
         .object({
         mode: z.literal("search"),
@@ -503,6 +547,10 @@ export const queryInputSchema = z.discriminatedUnion("mode", [
             .boolean()
             .optional()
             .describe("Plan without running: the scope, the resolved filter, and the allowed count. No model call."),
+        rerank: z
+            .boolean()
+            .optional()
+            .describe("true: the managed rerank model (Jev) orders the best hits by how well each answers the text, and each hit gets its relevance (0 to 1); adds about 0.3 s. false: the similarity order. Omit it to follow the graph's search setting."),
         request: z
             .string()
             .optional()
@@ -610,7 +658,7 @@ export const configureInputSchema = z.discriminatedUnion("action", [
         change: z
             .array(ontologyEvolveOpSchema)
             .min(1)
-            .max(64)
+            .max(128)
             .describe("The ontology operations a person applies by accepting, in order (same shapes as evolve_ontology ops)"),
         rationale: z
             .string()

package/dist/tool-runtime.js

@@ -324,6 +324,7 @@ export function queryEnvelope(label, value, detailArg, rowPage, next, repage, op
         return {
             ...envelope(label, value, detailArg, next),
             row_page: rowPage,
+            ...(options.extra ?? {}),
             ...(options.notes?.length ? { notes: options.notes } : {}),
         };
     }
@@ -353,6 +354,7 @@ export function queryEnvelope(label, value, detailArg, rowPage, next, repage, op
             next: hasMore
                 ? continuationNext(repage, page.offset + count, repage.row_limit)
                 : undefined,
+            ...(options.extra ?? {}),
             ...(options.notes?.length ? { notes: options.notes } : {}),
         };
     };
@@ -658,8 +660,8 @@ export async function guide(scopedClient) {
             search_feedback: "When a result set is useful or clearly wrong, write relevance labels with lbb_commit mode=search_feedback. Use grade 3 for ideal/good results, grade 1 for partially relevant results, and grade 0 for bad results. Include the original query, search_id when present, target identity, rank, score, and an optional split train/eval/unspecified. These labels are stored in __lbb_feedback/main and later exported as qrels-style training/eval data; they are not customer facts.",
             inspect: "Use lbb_inspect for ontology, schema metadata, the published conformance report, metadata, entities, and this guide. Use lbb_query with SPARQL property paths for exact path queries.",
             ontology_decorations: "lbb_inspect action=ontology returns a decoration_status catalog: each ontology decoration is enforced (the engine acts on it — state_reducer, value_type, super_types, properties, supernode_policy; cardinality, which GET /v1/ontology/conformance audits as sh:maxCount; and inverse_name/symmetric, which SPARQL resolves as relation aliases — an inverse name is queryable directly (lowered to ^forward, no stored inverse triple) and a symmetric relation matches both directions), advisory (transitive, temporal_semantics, required), or reserved (stored but unwired — default_weight, resolvable, alias/embedding_fields). You can also always reverse any relation in SPARQL by flipping the triple pattern or using ^forward. Each relation_def also carries edge_count — the number of current edges of that relation in this graph's snapshot — so you can tell at a glance which declared relations are actually populated (edge_count 0 = declared but unused) without a separate summary call.",
-            search: "Use lbb_query mode=search to find instances by meaning. It covers every searchable class; filter narrows it by class and by relationship, and the graph checks every hit. To plan a search: (1) lbb_embeddings action=list gives the searchable classes, the facts each text is made from, and the graph's model. (2) lbb_query mode=sparql shows the relationships of a class on a sample: PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#> SELECT ?p (COUNT(DISTINCT ?s) AS ?n) (SAMPLE(?l) AS ?example) WHERE { { SELECT ?s WHERE { ?s a <CLASS> } LIMIT 500 } ?s ?p ?o . FILTER(isIRI(?o) && ?p != rdf:type) OPTIONAL { ?o rdfs:label ?l } } GROUP BY ?p ORDER BY DESC(?n); write ?o ?p ?s for the links into the class, and SELECT ?c WHERE { ?c rdfs:subClassOf* <CLASS> } (same prefixes) for its subclasses. (3) lbb_query mode=search with filter [{class}, {via, to}] and explain=true returns the plan: the resolved relationship and entities, the allowed count, and the mode, with no model call. Check it, then run the search without explain. A name in to resolves against labels (a small typo too); an unknown relationship or name answers with the options.",
-            query: "Use lbb_query for structured SPARQL-subset bodies, SPARQL text, and canned analysis. SPARQL is the only query surface. A mode=structured body is { patterns: [{ subject, predicate, object }], filters?, group_by?, group_keys?, aggregates?, having? }; a pattern `predicate` is a relation name and is case-insensitive. mode=structured GROUP BY is not limited to entity identity: group_keys can key on a typed scalar property or calendar bucket. In SPARQL text, relations are <https://littlebigbrain.com/r/NAME> and types <https://littlebigbrain.com/class/NAME>. Each query pins one published watermark.",
+            search: "Use lbb_query mode=search to find instances by meaning. It covers every searchable class; filter narrows it by class and by relationship, and the graph checks every hit. To plan a search: (1) lbb_embeddings action=list gives the searchable classes, the facts each text is made from, and the graph's model. (2) lbb_query mode=sparql shows the relationships of a class on a sample: PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#> SELECT ?p (COUNT(DISTINCT ?s) AS ?n) (SAMPLE(?l) AS ?example) WHERE { { SELECT ?s WHERE { ?s a <CLASS> } LIMIT 500 } ?s ?p ?o . FILTER(isIRI(?o) && ?p != rdf:type) OPTIONAL { ?o rdfs:label ?l } } GROUP BY ?p ORDER BY DESC(?n); write ?o ?p ?s for the links into the class, and SELECT ?c WHERE { ?c rdfs:subClassOf* <CLASS> } (same prefixes) for its subclasses. (3) lbb_query mode=search with filter [{class}, {via, to}] and explain=true returns the plan: the resolved relationship and entities, the allowed count, and the mode, with no model call. Check it, then run the search without explain. A name in to resolves against labels (a small typo too); an unknown relationship or name answers with the options. To search and filter in one query, use SPARQL text: PREFIX search: <https://littlebigbrain.com/search#> SELECT ?x ?score WHERE { ?x search:similarTo \"words\" ; search:score ?score . ?x a <CLASS> } ORDER BY DESC(?score) LIMIT 10. Any other pattern on ?x filters the hits; the result's search field reports the plan and complete. (4) For a question in words, rerank=true lets the rerank model (Jev) put first the hits that answer it; each hit then carries relevance (0 to 1), and the search takes about 0.3 s more. Without rerank the graph's search setting decides.",
+            query: "Use lbb_query for questions in plain words (mode=question), structured SPARQL-subset bodies, SPARQL text, and canned analysis. SPARQL is the only query surface; mode=question also returns the SPARQL query the server wrote for the question. A mode=structured body is { patterns: [{ subject, predicate, object }], filters?, group_by?, group_keys?, aggregates?, having? }; a pattern `predicate` is a relation name and is case-insensitive. mode=structured GROUP BY is not limited to entity identity: group_keys can key on a typed scalar property or calendar bucket. In SPARQL text, relations are <https://littlebigbrain.com/r/NAME> and types <https://littlebigbrain.com/class/NAME>. Each query pins one published watermark.",
             write: "Use lbb_commit for fact writes and relevance feedback; omitted idempotency keys are content-derived so retries dedupe. Set typed scalar attributes via entity_properties once the field is registered (add it on a live graph with lbb_configure evolve_ontology add_property). For feedback, use mode=search_feedback rather than fact triplets.",
             configure: "Use lbb_configure dry_run=true to preview definitions, ordered evolution (including add_super_types), or SHACL publication. Definition extracts native metadata; use lbb_rdf import to store full RDF/OWL and lbb_rdf update for additive INSERT DATA; RDF deletion/replacement is unsupported. Follow every lbb_inspect ontology/schema next cursor; fields are complete and metadata changes invalidate the cursor. Publication is asynchronous: inspect action=publication, then verify asserted axioms AND expected answers with lbb_query entailment=owl. SHACL conformance alone does not prove ontology completeness. First identify the questions the model must answer, reusable vocabularies, dates, evidence, and distinctions such as hypothesis versus confirmed fact.",
         },

package/dist/tools.js

@@ -1,8 +1,9 @@
 import { z } from "zod";
 import { metadataPage } from "./metadata-pages.js";
+import { answerQuestion } from "./question.js";
 import { registerRdfTool } from "./rdf-tool.js";
 import { queryTiming } from "./query-observer.js";
-import { DESTRUCTIVE, IDEMPOTENT_WRITE, MUTATING, READ_ONLY, configureInputSchema, configureWireSchema, detailSchema, graphScope, inspectInputSchema, inspectWireSchema, jsonObjectSchema, queryInputSchema, queryWireSchema, searchFeedbackSchema, } from "./tool-contracts.js";
+import { DESTRUCTIVE, IDEMPOTENT_WRITE, MUTATING, READ_ONLY, configureInputSchema, configureWireSchema, detailSchema, graphScope, inspectInputSchema, inspectWireSchema, jsonObjectSchema, queryInputSchema, queryWireSchema, searchFeedbackSchema, yearMonthSchema, } from "./tool-contracts.js";
 import { analyze, assertCursorScope, contentHashKey, decodeQueryCursor, effectiveRowLimit, enrichError, errorResult, guide, normalizeDetail, normalizeLbbIris, ontologyDefineBody, queryCommitPin, queryEnvelope, queryToolResult, requireString, rowPageFrom, rowPageNext, run, scoped, stableJson, toolResult, } from "./tool-runtime.js";
 export function registerLbbTools(server, client, options = {}) {
     registerRdfTool(server, client);
@@ -46,6 +47,9 @@ export function registerLbbTools(server, client, options = {}) {
                         limit: args.limit ?? 50,
                     });
                 case "entity":
+                    if (args.as_of !== undefined) {
+                        throw new Error("entity valid-time as_of is not supported; use as_of_commit_seq for a retained commit snapshot");
+                    }
                     return target.entityDetail({
                         ...(args.entity_id
                             ? { id: args.entity_id }
@@ -53,14 +57,13 @@ export function registerLbbTools(server, client, options = {}) {
                                 type: requireString(args.entity_type, "entity_type"),
                                 name: requireString(args.name, "name"),
                             }),
-                        asOf: args.as_of,
                         asOfCommitSeq: args.as_of_commit_seq,
                     });
             }
         });
     });
     server.registerTool("lbb_query", {
-        description: "Analytical and expert reads. Modes: structured (SPARQL-subset JSON body), sparql (SPARQL text), search (instances by meaning over every searchable class; filter narrows by class and relationship; every hit checked against the graph), analyze. SPARQL is the query language; search finds what the words describe. To plan a search: lbb_embeddings action=list, then SPARQL for a class's relationships on a sample, then mode=search with explain=true to check the resolved filter before the real search (lbb_inspect action=guide has the queries). Relations are <https://littlebigbrain.com/r/NAME> and types <https://littlebigbrain.com/class/NAME> (both lowercased); entities are content-addressed, so anchor a named one by its rdfs:label rather than building its IRI. Structured and text queries pin one published watermark for the request.",
+        description: "Analytical and expert reads. Modes: question (a question in plain words), structured (SPARQL-subset JSON body), sparql (SPARQL text), search (instances by meaning over every searchable class; filter narrows by class and relationship; every hit checked against the graph), analyze. Use mode=question when you have a question in plain words and no SPARQL query: the server selects the kind of query (route), writes the SPARQL query from a description of the graph, checks it, runs it, and returns the route, the rationale, the query and its rows. Continue or correct that query with mode=sparql. Each question uses model tokens and counts toward a daily limit of the stack. SPARQL is the query language; search finds what the words describe. SPARQL text can also search by meaning inside the query with ?x <https://littlebigbrain.com/search#similarTo> \"words\", so the other patterns filter and join the hits in one query; the result's search field reports the plan. To plan a search: lbb_embeddings action=list, then SPARQL for a class's relationships on a sample, then mode=search with explain=true to check the resolved filter before the real search (lbb_inspect action=guide has the queries). Relations are <https://littlebigbrain.com/r/NAME> and types <https://littlebigbrain.com/class/NAME> (both lowercased); entities are content-addressed, so anchor a named one by its rdfs:label rather than building its IRI. Structured and text queries pin one published watermark for the request.",
         inputSchema: queryWireSchema,
         annotations: READ_ONLY,
     }, (rawArgs) => {
@@ -95,9 +98,9 @@ export function registerLbbTools(server, client, options = {}) {
                     const pin = (requested) => !cursor && requested === undefined
                         ? timing.measureAsync("query_pin_metadata", () => queryCommitPin(target, requested, cursor))
                         : queryCommitPin(target, requested, cursor);
-                    const buildEnvelope = (value, rowPage, next, cursorBase, notes) => timing.measure("query_envelope", () => {
+                    const buildEnvelope = (value, rowPage, next, cursorBase, notes, extra) => timing.measure("query_envelope", () => {
                         timing.counts({ received_rows: rowPage?.returned });
-                        const result = queryEnvelope(`lbb_query.${args.mode}`, value, detail, rowPage, next, cursorBase, { textFormat: options.queryTextFormat, notes });
+                        const result = queryEnvelope(`lbb_query.${args.mode}`, value, detail, rowPage, next, cursorBase, { textFormat: options.queryTextFormat, notes, extra });
                         if (options.timing) {
                             const nextCursor = result.next?.cursor;
                             timing.counts({
@@ -241,6 +244,12 @@ export function registerLbbTools(server, client, options = {}) {
                     if (response.trace_id) {
                         notes.push(`eval trace ${response.trace_id}: to label rows, read their item ids with lbb_evals action=trace trace_id=${response.trace_id}, then call lbb_evals action=label trace_id=${response.trace_id} item=<id> valid=true|false (or items=[…]).`);
                     }
+                    // A query with a search:similarTo pattern reports how the search
+                    // ran; keep that report whole next to the rows.
+                    const search = response.search ?? undefined;
+                    if (search && !search.complete) {
+                        notes.push(`search bound ${search.hits} of the ${search.top} hits asked for (complete: false): fewer entities satisfy the rest of the query among the candidates the search may score. When at most 20,000 entities match the other patterns, the search scores every match.`);
+                    }
                     const data = timing.measure("query_results_parse", () => JSON.parse(response.results));
                     const rowPage = rowPageFrom(response);
                     const cursorBase = {
@@ -256,7 +265,7 @@ export function registerLbbTools(server, client, options = {}) {
                         as_of_commit_seq: asOfCommitSeq,
                     };
                     const next = rowPageNext(cursorBase, rowPage);
-                    const sparqlEnvelope = buildEnvelope(data, rowPage, next, cursorBase, notes);
+                    const sparqlEnvelope = buildEnvelope(data, rowPage, next, cursorBase, notes, search ? { search } : undefined);
                     return render(sparqlEnvelope);
                 }
                 catch (error) {
@@ -264,6 +273,17 @@ export function registerLbbTools(server, client, options = {}) {
                 }
             })();
         }
+        if (args.mode === "question") {
+            const questionArgs = args;
+            return (async () => {
+                try {
+                    return await answerQuestion(client, questionArgs, options.queryTextFormat);
+                }
+                catch (error) {
+                    return errorResult(await enrichError(client, error));
+                }
+            })();
+        }
         if (args.mode === "search") {
             const searchArgs = args;
             // The caller's detail shapes the hits like every other mode: compact
@@ -279,6 +299,7 @@ export function registerLbbTools(server, client, options = {}) {
                     request: searchArgs.request,
                     filter: searchArgs.filter,
                     explain: searchArgs.explain,
+                    rerank: searchArgs.rerank,
                 });
             });
         }
@@ -295,17 +316,25 @@ export function registerLbbTools(server, client, options = {}) {
         });
     });
     server.registerTool("lbb_models", {
-        description: "Read model-training inputs or compare retrieval configurations over one pinned published snapshot. shadow_eval takes the API ShadowEvalRequest body; dataset actions return bounded training examples at an optional signal split.",
+        description: "Read model-training inputs or compare retrieval configurations over one pinned published snapshot, or read what the managed models did. shadow_eval takes the API ShadowEvalRequest body; dataset actions return bounded training examples at an optional signal split. activity reads one month of the stack's model use (all graphs): calls, items, estimated tokens and cost per feature (index, search, fit, judge, training) and model, by day and by graph, the months with activity, and the model each feature uses now.",
         inputSchema: {
-            action: z.enum(["shadow_eval", "suggest_dataset", "extractor_dataset"]),
+            action: z.enum([
+                "shadow_eval",
+                "suggest_dataset",
+                "extractor_dataset",
+                "activity",
+            ]),
             body: jsonObjectSchema.optional(),
             limit: z.number().int().positive().optional(),
             split_seq: z.number().int().nonnegative().optional(),
+            month: yearMonthSchema
+                .optional()
+                .describe("activity: the month, yyyy-mm (UTC). Defaults to the current month."),
             detail: detailSchema,
             ...graphScope,
         },
         annotations: READ_ONLY,
-    }, ({ action, body, limit, split_seq, detail, graph }) => run(client, `lbb_models.${action}`, detail, () => {
+    }, ({ action, body, limit, split_seq, month, detail, graph }) => run(client, `lbb_models.${action}`, detail, () => {
         const target = scoped(client, graph);
         switch (action) {
             case "shadow_eval":
@@ -316,6 +345,8 @@ export function registerLbbTools(server, client, options = {}) {
                 return target.suggestDataset({ limit, splitSeq: split_seq });
             case "extractor_dataset":
                 return target.extractorDataset({ limit, splitSeq: split_seq });
+            case "activity":
+                return target.modelActivity({ month });
         }
     }));
     const embeddingSetup = {
@@ -430,7 +461,7 @@ export function registerLbbTools(server, client, options = {}) {
         return scoped(client, graph).embeddings.delete(name);
     }));
     server.registerTool("lbb_evals", {
-        description: "Managed evals: the thumbs up / thumbs down of the graph, per result. A query run with `request` (lbb_query) records a trace with one item per result (hit or row); trace reads it back with the item ids. label marks one result (item + valid) or several (items) relevant or not; the labels become the golden's ground truth. golden freezes a query (every result it returns now is relevant). run replays every golden at the current commit: pass when every relevant result is back and no wrong one is; new results open a review trace. judge lets the platform's judge model (the hosted frontier model) label unlabeled results. summary, traces, goldens, results, and settings read state.",
+        description: "Managed evals: the thumbs up / thumbs down of the graph, per result. A query run with `request` (lbb_query) records a trace with one item per result (hit or row); trace reads it back with the item ids. label marks one result (item + valid) or several (items) relevant or not; the labels become the golden's ground truth. golden freezes a query (every result it returns now is relevant). run replays every golden at the current commit: pass when every relevant result is back and no wrong one is; new results open a review trace. judge lets the platform's judge model (the hosted frontier model) label unlabeled results. summary, traces, goldens, results, and settings read state. Model checks: a judge model checks a sample of the model calls LBB makes for the graph (rerank, route, rewrite, fit, propose, label). checks_summary reads a month per job and model (checks, score, right, partly, wrong, reviews) and the judge's agreement with people; checks lists the month's checks, newest first, with the judge's verdict, score and reason and the ground truth (`truth`). review_check records a person's review of one check (call_id): agree=true keeps the judge's verdict; agree=false with verdict (and an optional score, reference and note) corrects it. The review becomes the call's ground truth, so show the check to the user and review only what the user confirmed.",
         inputSchema: {
             action: z.enum([
                 "summary",
@@ -445,6 +476,9 @@ export function registerLbbTools(server, client, options = {}) {
                 "run",
                 "results",
                 "settings",
+                "checks_summary",
+                "checks",
+                "review_check",
             ]),
             trace_id: z
                 .string()
@@ -472,7 +506,10 @@ export function registerLbbTools(server, client, options = {}) {
                 .string()
                 .optional()
                 .describe("label: who labels (an agent name)."),
-            note: z.string().optional(),
+            note: z
+                .string()
+                .optional()
+                .describe("label / review_check: why. review_check: at most 2,000 characters."),
             sparql: z
                 .string()
                 .optional()
@@ -509,11 +546,47 @@ export function registerLbbTools(server, client, options = {}) {
                 .enum(["strong", "eventual"])
                 .optional()
                 .describe("run / accept: strong reads the head, eventual the last published commit."),
+            month: yearMonthSchema
+                .optional()
+                .describe("checks_summary / checks: the month, yyyy-mm (UTC). Defaults to the current month."),
+            job: z
+                .enum(["rerank", "route", "rewrite", "fit", "propose", "label"])
+                .optional()
+                .describe("checks: only the checks of one job."),
+            verdict: z
+                .enum(["right", "partly", "wrong"])
+                .optional()
+                .describe("checks: only the checks whose ground truth has this verdict. review_check with agree=false: the right verdict."),
+            reviewed: z
+                .boolean()
+                .optional()
+                .describe("checks: true = only the checks a person reviewed, false = only the others."),
+            after: z
+                .string()
+                .optional()
+                .describe("checks: the next_after of the previous page."),
+            call_id: z
+                .string()
+                .optional()
+                .describe("review_check: the check's `call` id, from checks."),
+            agree: z
+                .boolean()
+                .optional()
+                .describe("review_check: true = the judge is right, false = correct it with verdict."),
+            score: z
+                .number()
+                .min(0)
+                .max(1)
+                .optional()
+                .describe("review_check with agree=false: the right score, 0 to 1. Omit for the judge's score of that verdict."),
+            reference: jsonObjectSchema
+                .optional()
+                .describe('review_check with agree=false: the right answer. A rerank or label check: {"grades": {"<hit id>": 0..3}}; a route or fit check: {"picks": {"<question id>": "<option>"}}.'),
             detail: detailSchema,
             ...graphScope,
         },
         annotations: MUTATING,
-    }, ({ action, trace_id, item, valid, items, by, note, sparql, surface, embedding, top_k, request, golden_id, limit, unlabeled, consistency, detail, graph, }) => run(client, `lbb_evals.${action}`, detail, () => {
+    }, ({ action, trace_id, item, valid, items, by, note, sparql, surface, embedding, top_k, request, golden_id, limit, unlabeled, consistency, month, job, verdict, reviewed, after, call_id, agree, score, reference, detail, graph, }) => run(client, `lbb_evals.${action}`, detail, () => {
         const target = scoped(client, graph);
         switch (action) {
             case "summary":
@@ -567,6 +640,36 @@ export function registerLbbTools(server, client, options = {}) {
                 return target.evals.results({ limit });
             case "settings":
                 return target.evals.settings();
+            case "checks_summary":
+                return target.checks.summary({ month });
+            case "checks":
+                return target.checks.list({
+                    job,
+                    month,
+                    verdict,
+                    reviewed,
+                    after,
+                    limit,
+                });
+            case "review_check":
+                if (!call_id)
+                    throw new Error("review_check requires call_id");
+                if (agree === undefined)
+                    throw new Error("review_check requires agree");
+                if (agree &&
+                    (verdict !== undefined ||
+                        score !== undefined ||
+                        reference !== undefined))
+                    throw new Error("review_check with agree=true takes no verdict, score or reference");
+                if (!agree && !verdict)
+                    throw new Error("review_check with agree=false requires verdict");
+                return target.checks.review(call_id, {
+                    agree,
+                    ...(verdict ? { verdict } : {}),
+                    ...(score !== undefined ? { score } : {}),
+                    ...(reference ? { reference } : {}),
+                    ...(note ? { note } : {}),
+                });
         }
     }));
     server.registerTool("lbb_commit", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebigbrain/mcp",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "MCP server for little big brain: search, graph queries, and data import",
   "license": "Apache-2.0",
   "repository": {
@@ -52,7 +52,7 @@
     "test:coverage": "npm run clean:test && tsc -p tsconfig.test.json && node --test --experimental-test-coverage --test-coverage-include=test-dist/*.js --test-coverage-exclude=test-dist/*.test.js --test-coverage-exclude=test-dist/stdio.js --test-coverage-exclude=test-dist/test-support.js --test-coverage-lines=90 --test-coverage-branches=70 --test-coverage-functions=85 \"test-dist/**/*.test.js\""
   },
   "dependencies": {
-    "@littlebigbrain/client": "^0.17.0",
+    "@littlebigbrain/client": "^0.19.0",
     "@modelcontextprotocol/sdk": "^1",
     "zod": "^3"
   },