Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

[Metabot] Improved streamed reasoning metadata (#78416)

Sloan Sparger207a7bdb066f
diff --git a/src/metabase/metabot/agent/streaming.clj b/src/metabase/metabot/agent/streaming.clj
index 1f83c244d83..3772d726b6c 100644
--- a/src/metabase/metabot/agent/streaming.clj
+++ b/src/metabase/metabot/agent/streaming.clj
@@ -21,6 +21,15 @@
(def entity-saved-type "AI-SDK data type for saved-entity annotations." "entity_saved")
(def adhoc-viz-type "AI-SDK data type for ad-hoc visualizations." "adhoc_viz")
(def static-viz-type "AI-SDK data type for static visualizations." "static_viz")
+(def search-results-type "AI-SDK data type for a search tool's result list." "search_results")
+(def tool-title-type "AI-SDK data type for a tool call's settled display title." "tool_title")
+
+(def ^:private ephemeral-data-types
+ "Data types not written to MetabotMessage.data."
+ ;; state is diffed separately into the row's state column
+ ;; search_results and tool_title render under the client-only chain of
+ ;; thought, never rehydrated
+ #{state-type search-results-type tool-title-type})
(defn persistable-data-part?
"True if `part` should be written to MetabotMessage.data. `state` parts are
@@ -31,7 +40,7 @@
(`:start`, `:usage`, `:finish`) separately."
[part]
(not (and (= :data (:type part))
- (= state-type (:data-type part)))))
+ (contains? ephemeral-data-types (:data-type part)))))
;;; Query URL Encoding
@@ -141,6 +150,23 @@
:data-type entity-saved-type
:data value})
+(defn search-results-part
+ "Data part carrying a search tool's hit list (`:total_count` + `:results`),
+ rendered under the search step in the chain of thought."
+ [value]
+ {:type :data
+ :data-type search-results-type
+ :data value})
+
+(defn tool-title-part
+ "Data part carrying a tool call's display title, derived from what the tool
+ actually read/did; [[expand-data-parts-xf]] stamps on the tool-call id it
+ labels."
+ [title]
+ {:type :data
+ :data-type tool-title-type
+ :data {:title title}})
+
(defn viz-part
"Return the `generated_entity` card data part that surfaces a query/chart result
to the frontend. Embeds the (legacy) `query` so the FE runs and renders the card
@@ -167,11 +193,16 @@
;;; Stream Processing Transducers
(def expand-data-parts-xf
- "Stateless transducer that expands :data-parts from tool-output results.
- Passes through all parts unchanged, then appends any data parts after tool-output parts."
+ "Stateless transducer that appends a tool-output's :data-parts after it, passing
+ everything else through. Every object-shaped payload is stamped with its originating
+ tool-call id, so the client can render it under the matching chain-of-thought step
+ and the source stays traceable when debugging. Array payloads (e.g. todo_list) carry
+ no keyed slot, so they're left as-is."
(mapcat (fn [part]
(if (= (:type part) :tool-output)
- (cons part (get-in part [:result :data-parts]))
+ (cons part (for [dp (get-in part [:result :data-parts])]
+ (cond-> dp
+ (map? (:data dp)) (assoc-in [:data :tool_call_id] (:id part)))))
[part]))))
(defn post-process-xf
diff --git a/src/metabase/metabot/self.clj b/src/metabase/metabot/self.clj
index a35a76bf200..0568e44e9c4 100644
--- a/src/metabase/metabot/self.clj
+++ b/src/metabase/metabot/self.clj
@@ -316,6 +316,7 @@
make-source (fn []
(eduction (comp (core/tool-executor-xf tools)
(core/lite-aisdk-xf)
+ (core/stamp-tool-titles-xf tools)
(report-aisdk-errors-xf tracking-opts)
(report-token-usage-xf tracking-opts)
(report-tool-usage-xf tracking-opts))
diff --git a/src/metabase/metabot/self/core.clj b/src/metabase/metabot/self/core.clj
index 0a555b881aa..63e70c873fd 100644
--- a/src/metabase/metabot/self/core.clj
+++ b/src/metabase/metabot/self/core.clj
@@ -236,6 +236,22 @@
[]
(aisdk-xf {:stream-text? true}))
+(defn stamp-tool-titles-xf
+ "Stamp a client-facing `:title` onto `:tool-input` parts via each tool's
+ optional `:title-fn`. A throwing title-fn leaves the part untitled."
+ [tools]
+ (map (fn [part]
+ (if-let [title-fn (and (= :tool-input (:type part))
+ (:title-fn (get tools (:function part))))]
+ (let [title (try
+ (title-fn (:arguments part))
+ (catch Throwable e
+ (log/debug e "tool title-fn failed" {:tool (:function part)})
+ nil))]
+ (cond-> part
+ (string? title) (assoc :title title)))
+ part))))
+
;;; AI SDK SSE Output
;;
;; Converts internal parts to the AI SDK v5+ SSE protocol: typed `UIMessageChunk`
@@ -446,10 +462,11 @@
:toolName (:function part)}))
:tool-input
- (rf result (format-sse-event {:type "tool-input-available"
- :toolCallId (:id part)
- :toolName (:function part)
- :input (:arguments part)}))
+ (rf result (format-sse-event (cond-> {:type "tool-input-available"
+ :toolCallId (:id part)
+ :toolName (:function part)
+ :input (:arguments part)}
+ (:title part) (assoc :title (:title part)))))
:tool-output
(rf result
diff --git a/src/metabase/metabot/tmpl.clj b/src/metabase/metabot/tmpl.clj
index 57623091eaa..2668da8e6d9 100644
--- a/src/metabase/metabot/tmpl.clj
+++ b/src/metabase/metabot/tmpl.clj
@@ -27,9 +27,10 @@
:else (str label ": " value "\n")))
(defn link
- "[{label}]({(join link)})"
+ "[{label}]({(join link)}); square brackets are stripped from the label — they
+ break markdown link parsing (the label can't contain `]`)"
[label & bits]
- (format "[%s](%s)" label (apply str bits)))
+ (format "[%s](%s)" (str/replace (str label) #"[\[\]]" "") (apply str bits)))
(defn markdown-table
"Render a sequence of maps as a markdown table.
diff --git a/src/metabase/metabot/tools.clj b/src/metabase/metabot/tools.clj
index 9c17585fa3d..4f3b6114138 100644
--- a/src/metabase/metabot/tools.clj
+++ b/src/metabase/metabot/tools.clj
@@ -161,6 +161,7 @@
:schema (:schema m)
:prompt (:prompt m)
:decode (:decode m)
+ :title-fn (:title-fn m)
:system-instructions (:system-instructions m)
:capabilities (:capabilities m)
:scope (:scope m)
diff --git a/src/metabase/metabot/tools/resources.clj b/src/metabase/metabot/tools/resources.clj
index 2f4123a1014..da7cf03ed34 100644
--- a/src/metabase/metabot/tools/resources.clj
+++ b/src/metabase/metabot/tools/resources.clj
@@ -68,7 +68,9 @@
[metabase.api.common :as api]
[metabase.documents.core :as documents]
[metabase.documents.prose-mirror :as prose-mirror]
+ [metabase.metabot.agent.streaming :as streaming]
[metabase.metabot.scope :as scope]
+ [metabase.metabot.tmpl :as te]
[metabase.metabot.tools.entity-details :as entity-details]
[metabase.metabot.tools.field-stats :as field-stats]
[metabase.metabot.tools.shared :as shared]
@@ -77,6 +79,7 @@
[metabase.models.interface :as mi]
[metabase.transforms.core :as transforms]
[metabase.util :as u]
+ [metabase.util.i18n :refer [tru]]
[metabase.util.log :as log]
[metabase.util.malli :as mu]
[metabase.util.match :as match]
@@ -873,6 +876,82 @@
_ (throw (ex-info (str "Unsupported URI: " uri)
{:uri uri :segments segments})))))
+;; ----- Display titles -----
+
+(def ^:private link-models
+ "URI leading segment -> model, for entities rendered as `metabase://` links. Mirrors
+ `METABASE_PROTOCOL_ENTITY_MODELS` in metabot/utils/links.ts — keep the two in sync."
+ {"dashboard" :model/Dashboard
+ "database" :model/Database
+ "collection" :model/Collection
+ "table" :model/Table
+ "question" :model/Card
+ "model" :model/Card
+ "document" :model/Document
+ "transform" :model/Transform})
+
+(def ^:private plain-models
+ "URI leading segment -> model for entities that aren't `metabase://`-linkable; their
+ name still shows as plain text instead of the bare \"Reading resource\" fallback."
+ {"metric" :model/Card
+ "measure" :model/Measure
+ "segment" :model/Segment})
+
+(defn- nav-noun
+ "Localized noun for a top-level navigation URI, so browsing reads as e.g.
+ \"Read databases\" rather than the bare fallback."
+ [segments]
+ (case segments
+ ["databases"] (tru "databases")
+ ["collections"] (tru "collections")
+ ["user" "recent-items"] (tru "recent items")
+ nil))
+
+(defn- aspect-noun
+ "Localized noun for the sub-resource an `entity/{id}/…` URI drills into; words match
+ existing site copy. nil for the bare entity."
+ [segment aspect]
+ (if (and (= segment "dashboard") (= aspect "items"))
+ (tru "cards")
+ (case aspect
+ "fields" (tru "fields")
+ "derived" (tru "dependents")
+ "sources" (tru "sources")
+ "dimensions" (tru "dimensions")
+ "items" (tru "items")
+ "tables" (tru "tables")
+ "models" (tru "models")
+ "schemas" (tru "schemas")
+ "subcollections" (tru "subcollections")
+ "target" (tru "target")
+ nil)))
+
+(defn- uri-label
+ "Label for one successfully read resource, built from what the read returned — no
+ extra queries. The entity plus any drilled-into aspect (`[Orders](…) columns`), an
+ aspect noun alone when the result carries no entity name (`tables`), or a
+ navigation noun (`databases`). nil when nothing fits."
+ [{:keys [uri content]}]
+ (let [{segments :segments} (parse-uri uri)
+ [segment id-str & rst] segments
+ id (some-> id-str parse-long)
+ ;; tables carry a raw :name (ORDERS) and a friendly :display_name (Orders);
+ ;; prefer the latter so the label matches the search results
+ entity-name (when (and id (or (link-models segment) (plain-models segment)))
+ (let [so (:structured-output content)]
+ (or (:display_name so) (:name so))))
+ title (when (string? entity-name)
+ (if (link-models segment)
+ (te/link entity-name "metabase://" segment "/" id)
+ entity-name))
+ ;; drop the trailing field/dimension id so `.../fields/10` still reads as "fields"
+ noun (when id (aspect-noun segment (last (remove parse-long rst))))]
+ (cond
+ (and title noun) (str title " " noun)
+ title title
+ noun noun
+ :else (nav-noun segments))))
+
;; ----- Tool entry points -----
(defn- fetch-single-uri
@@ -949,15 +1028,24 @@
;; Fetch all URIs (sequentially for now, could parallelize with pmap)
(let [resources (mapv fetch-single-uri uris)
- formatted (format-resources resources)]
+ formatted (format-resources resources)
+ labels (into []
+ (comp (filter :content)
+ (keep #(try (uri-label %) (catch Throwable _ nil)))
+ (distinct))
+ resources)]
(log/info "Fetched resources" {:total (count resources)
:successful (count (filter :content resources))
:errors (count (filter :error resources))})
- {:resources resources
- :output formatted}))
-
-(mu/defn ^{:tool-name "read_resource"
- :scope scope/agent-resource-read}
+ (cond-> {:resources resources
+ :output formatted}
+ (seq labels)
+ ;; just the object (the entities/aspects) — the client wraps it in the verb
+ ;; + tense ("Reading …" while active, "Read …" once settled)
+ (assoc :data-parts [(streaming/tool-title-part (str/join ", " labels))]))))
+
+(mu/defn ^{:tool-name "read_resource"
+ :scope scope/agent-resource-read}
read-resource-tool
"Read detailed information about Metabase resources via URI patterns. Use this to navigate
the instance and drill into specific entities. URIs returned by `search` can be fed directly
diff --git a/src/metabase/metabot/tools/save_entity.clj b/src/metabase/metabot/tools/save_entity.clj
index 3ec0ddffad7..cea26f09af1 100644
--- a/src/metabase/metabot/tools/save_entity.clj
+++ b/src/metabase/metabot/tools/save_entity.clj
@@ -231,7 +231,10 @@
:data-parts [(streaming/entity-saved-part
{:chart_id chart_id
:card_id (:id card)
- :destination saved-destination})]})
+ :destination saved-destination
+ ;; markdown entity link the chain-of-thought renders
+ ;; as the settled "Saved …" step label
+ :title (te/link question-name link)})]})
(catch Exception e
(log/errorf "Error saving entity: %s" (ex-message e))
(if (:agent-error? (ex-data e))
diff --git a/src/metabase/metabot/tools/search.clj b/src/metabase/metabot/tools/search.clj
index e197ce679ef..e214e266b04 100644
--- a/src/metabase/metabot/tools/search.clj
+++ b/src/metabase/metabot/tools/search.clj
@@ -4,6 +4,7 @@
[clojure.string :as str]
[medley.core :as m]
[metabase.api.common :as api]
+ [metabase.metabot.agent.streaming :as streaming]
[metabase.metabot.config :as metabot.config]
[metabase.metabot.scope :as scope]
[metabase.metabot.search-models :as metabot.search-models]
@@ -87,7 +88,9 @@
:verified verified?
:official official?
:collection collection-info})
- (m/assoc-some :curated curated)))))
+ (m/assoc-some :curated curated
+ :display (:display result)
+ :moderated_status moderated_status)))))
(defn- enrich-with-collection-descriptions
"Fetch and merge collection descriptions for all search results that have collection IDs."
@@ -533,6 +536,16 @@
(str "Maximum number of results (default " default-search-limit ", max " max-search-limit "). "
"Use a larger value (20–50) for broad or generic queries; keep the default for narrow, specific ones."))
+(defn- search-result->item
+ "Trim a search result to the fields the chain-of-thought results card renders.
+ `:display` (a question's viz type) and `:moderated_status` let the client pick the
+ exact entity icon, matching the app's search/command-palette icons."
+ [r]
+ (-> (select-keys r [:id :type :name :display_name :database_id :database_schema :database_name])
+ (m/assoc-some :display (some-> (:display r) name)
+ :moderated_status (:moderated_status r)
+ :collection (some-> (:collection r) (select-keys [:id :name])))))
+
(defn- do-search
[label allowed-types search-opts {:keys [semantic_queries keyword_queries entity_types limit] :as _args}]
(if-let [invalid (invalid-entity-types entity_types allowed-types)]
@@ -549,7 +562,10 @@
{:output (format-search-output results)
:structured-output {:result-type :search
:data results
- :total_count (count results)}})
+ :total_count (count results)}
+ :data-parts [(streaming/search-results-part
+ {:total_count (count results)
+ :results (mapv search-result->item results)})]})
(catch Exception e
(log/error (str "Error in " label ": " (ex-message e)))
{:output (str "Search failed: " (or (ex-message e) "Unknown error"))}))))
@@ -562,8 +578,17 @@
[:maybe [:sequential [:enum {:description entity-types-desc} "table" "model" "metric" "dashboard" "document" "question"]]]]
[:limit {:optional true} [:maybe [:int {:min 1 :max max-search-limit :description limit-desc}]]]])
-(mu/defn ^{:tool-name "search"
- :scope scope/agent-search}
+(defn- search-display
+ [{:keys [keyword_queries semantic_queries]}]
+ (let [queries (distinct (concat keyword_queries semantic_queries))]
+ (when (seq queries)
+ ;; just the object (the queries) — the client wraps it in the verb + tense
+ ;; ("Searching for …" while active, "Searched for …" once finished)
+ (str/join ", " queries))))
+
+(mu/defn ^{:tool-name "search"
+ :scope scope/agent-search
+ :title-fn search-display}
search-tool
"Find tables, models, metrics, dashboards, documents, and saved questions by topic across the instance. Use it when you don't know where something lives; once you have a hit, drill into it with read_resource rather than searching the same concept again."
[args :- search-schema]
@@ -578,8 +603,9 @@
[:maybe [:sequential [:enum {:description entity-types-desc} "table" "model"]]]]
[:limit {:optional true} [:maybe [:int {:min 1 :max max-search-limit :description limit-desc}]]]])
-(mu/defn ^{:tool-name "search"
- :scope scope/agent-search}
+(mu/defn ^{:tool-name "search"
+ :scope scope/agent-search
+ :title-fn search-display}
sql-search-tool
"Find SQL-queryable data sources (tables and models) within a specific database by topic."
[{:keys [database_id] :as args} :- sql-search-schema]
@@ -594,8 +620,9 @@
"table" "model" "metric" "question" "dashboard" "document"]]]]
[:limit {:optional true} [:maybe [:int {:min 1 :max max-search-limit :description limit-desc}]]]])
-(mu/defn ^{:tool-name "search"
- :scope scope/agent-search}
+(mu/defn ^{:tool-name "search"
+ :scope scope/agent-search
+ :title-fn search-display}
nlq-search-tool
"Find NLQ-queryable data sources by topic, or find dashboards and documents as save destinations."
[{:keys [entity_types] :as args} :- nlq-search-schema]
@@ -614,8 +641,9 @@
[:maybe [:sequential [:enum {:description entity-types-desc} "table" "model" "transform"]]]]
[:limit {:optional true} [:maybe [:int {:min 1 :max max-search-limit :description limit-desc}]]]])
-(mu/defn ^{:tool-name "search"
- :scope scope/agent-search}
+(mu/defn ^{:tool-name "search"
+ :scope scope/agent-search
+ :title-fn search-display}
transform-search-tool
"Find transforms, plus the tables and models around them, by topic."
[{:keys [search_native_query] :as args} :- transform-search-schema]
diff --git a/test/metabase/metabot/agent/core_test.clj b/test/metabase/metabot/agent/core_test.clj
index 065d1aecfec..fb002b85803 100644
--- a/test/metabase/metabot/agent/core_test.clj
+++ b/test/metabase/metabot/agent/core_test.clj
@@ -354,6 +354,7 @@
{:type :tool-output
:function "search"
:result {:structured-output {:total_count 1}}}
+ {:type :data :data-type "search_results"}
{:type :start}
{:type :tool-input :function "construct_notebook_query"}
;; Cumulative usage after iteration 2: 100+200=300 prompt, 20+30=50 completion
diff --git a/test/metabase/metabot/agent/streaming_test.clj b/test/metabase/metabot/agent/streaming_test.clj
index 14779234f25..a426a0111e9 100644
--- a/test/metabase/metabot/agent/streaming_test.clj
+++ b/test/metabase/metabot/agent/streaming_test.clj
@@ -157,6 +157,10 @@
(deftest persistable-data-part?-test
(testing "state parts are not persisted (value lives on MetabotConversation.state)"
(is (false? (streaming/persistable-data-part? (streaming/state-part {:queries {}})))))
+ (testing "search-results parts are not persisted (they render under the ephemeral chain of thought)"
+ (is (false? (streaming/persistable-data-part? (streaming/search-results-part {:total_count 0 :results []})))))
+ (testing "tool-title parts are not persisted (they render under the ephemeral chain of thought)"
+ (is (false? (streaming/persistable-data-part? (streaming/tool-title-part "[Orders](metabase://table/1)")))))
(testing "other parts are persisted"
(is (true? (streaming/persistable-data-part? (streaming/todo-list-part []))))
(is (true? (streaming/persistable-data-part? {:type :text :text "hi"})))))
@@ -190,7 +194,18 @@
result (into [] streaming/expand-data-parts-xf parts)]
(is (= 3 (count result)))
(is (= "a" (:data-type (second result))))
- (is (= "b" (:data-type (nth result 2)))))))
+ (is (= "b" (:data-type (nth result 2))))))
+ (testing "stamps the originating tool-call id into every object-shaped data payload"
+ (let [parts [{:type :tool-output
+ :id "call-7"
+ :result {:data-parts [(streaming/search-results-part {:total_count 1 :results []})
+ (streaming/entity-saved-part {:card_id 5})
+ {:type :data :data-type "todo_list" :data []}]}}]
+ [_ search-part entity-part todo-part] (into [] streaming/expand-data-parts-xf parts)]
+ (is (= "call-7" (get-in search-part [:data :tool_call_id])))
+ (is (= "call-7" (get-in entity-part [:data :tool_call_id])))
+ ;; array payloads have no keyed slot, so they're passed through untouched
+ (is (= [] (:data todo-part))))))
(deftest resolve-links-xf-test
(testing "resolves metabase:// links in text parts"
diff --git a/test/metabase/metabot/self_test.clj b/test/metabase/metabot/self_test.clj
index 4bf3308fe46..b426811c66f 100644
--- a/test/metabase/metabot/self_test.clj
+++ b/test/metabase/metabot/self_test.clj
@@ -546,7 +546,35 @@
(first (sse-events [{:type :tool-output :id "call-2" :error {:message "Tool failed"}}])))))
(testing ":tool-input-start maps to tool-input-start"
(is (= {:type "tool-input-start" :toolCallId "call-3" :toolName "search"}
- (first (sse-events [{:type :tool-input-start :id "call-3" :function "search"}]))))))
+ (first (sse-events [{:type :tool-input-start :id "call-3" :function "search"}])))))
+ (testing "a :title on a :tool-input part rides along on tool-input-available"
+ (is (= {:type "tool-input-available" :toolCallId "call-4" :toolName "read_resource"
+ :input {} :title "Inspecting [Orders](metabase://dashboard/5)"}
+ (first (sse-events [{:type :tool-input :id "call-4" :function "read_resource"
+ :arguments {} :title "Inspecting [Orders](metabase://dashboard/5)"}]))))))
+
+(deftest ^:parallel stamp-tool-titles-xf-test
+ (let [tools {"greet" {:tool-name "greet" :title-fn (fn [{:keys [who]}] (str "Greeting " who))}
+ "boom" {:tool-name "boom" :title-fn (fn [_] (throw (ex-info "nope" {})))}
+ "num" {:tool-name "num" :title-fn (fn [_] 42)}
+ "plain" {:tool-name "plain"}}
+ stamp #(into [] (self.core/stamp-tool-titles-xf tools) [%])]
+ (testing "title-fn result becomes :title"
+ (is (= [{:type :tool-input :id "c1" :function "greet" :arguments {:who "Sam"}
+ :title "Greeting Sam"}]
+ (stamp {:type :tool-input :id "c1" :function "greet" :arguments {:who "Sam"}}))))
+ (testing "a throwing title-fn leaves the part untitled"
+ (is (= [{:type :tool-input :id "c2" :function "boom" :arguments {}}]
+ (stamp {:type :tool-input :id "c2" :function "boom" :arguments {}}))))
+ (testing "a non-string result leaves the part untitled"
+ (is (= [{:type :tool-input :id "c3" :function "num" :arguments {}}]
+ (stamp {:type :tool-input :id "c3" :function "num" :arguments {}}))))
+ (testing "a tool without a title-fn is untouched"
+ (is (= [{:type :tool-input :id "c4" :function "plain" :arguments {}}]
+ (stamp {:type :tool-input :id "c4" :function "plain" :arguments {}}))))
+ (testing "non-tool-input parts pass through"
+ (is (= [{:type :text :id "t1" :text "hi"}]
+ (stamp {:type :text :id "t1" :text "hi"}))))))
(deftest parts->aisdk-sse-xf-data-test
(testing "data parts become typed data events with a generated id"
diff --git a/test/metabase/metabot/tools/resources_test.clj b/test/metabase/metabot/tools/resources_test.clj
index 1c6c5341bc6..107bb44ecf7 100644
--- a/test/metabase/metabot/tools/resources_test.clj
+++ b/test/metabase/metabot/tools/resources_test.clj
@@ -343,6 +343,65 @@
(is (=? {:resources [{:error string?}]}
(read-resource/read-resource {:uris ["metabase://transform/99999"]}))))))))
+(defn- read-title
+ "The chain-of-thought title `read-resource` derives from what it read."
+ [& uris]
+ (-> (read-resource/read-resource {:uris (vec uris)})
+ :data-parts first :data :title))
+
+(deftest read-resource-title-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Dashboard {dash-id :id} {:name "Sales Overview"}
+ :model/Table {table-id :id} {:name "orders" :display_name "Orders" :active true}]
+ (testing "a single entity becomes a markdown link"
+ (is (= (str "[Sales Overview](metabase://dashboard/" dash-id ")")
+ (read-title (str "metabase://dashboard/" dash-id)))))
+ (testing "square brackets in a name are stripped — they'd break the client's link parsing"
+ (mt/with-temp [:model/Dashboard {bracket-id :id} {:name "Sales [2024]"}]
+ (is (= (str "[Sales 2024](metabase://dashboard/" bracket-id ")")
+ (read-title (str "metabase://dashboard/" bracket-id))))))
+ (testing "a table uses its friendly display_name"
+ (is (= (str "[Orders](metabase://table/" table-id ")")
+ (read-title (str "metabase://table/" table-id)))))
+ (testing "a sub-resource appends its aspect, so fields reads differently than the entity"
+ (is (= (str "[Orders](metabase://table/" table-id ") fields")
+ (read-title (str "metabase://table/" table-id "/fields")))))
+ (testing "a list read that carries no entity name falls back to the aspect noun"
+ (is (= "cards"
+ (read-title (str "metabase://dashboard/" dash-id "/items")))))
+ (testing "multiple URIs join as a comma-delimited list; failed reads are skipped"
+ (is (= (str "[Sales Overview](metabase://dashboard/" dash-id "), "
+ "[Orders](metabase://table/" table-id "), databases")
+ (read-title (str "metabase://dashboard/" dash-id)
+ (str "metabase://table/" table-id)
+ "metabase://dashboard/99999"
+ "metabase://databases"))))
+ (testing "no URIs -> no title data part"
+ (is (nil? (read-title))))
+ (testing "a named but non-linkable entity surfaces as plain text, not a link"
+ (mt/with-temp [:model/Card {metric-id :id} {:name "Revenue"
+ :type :metric
+ :database_id (mt/id)
+ :table_id (mt/id :orders)
+ :dataset_query {:database (mt/id)
+ :type :query
+ :query {:source-table (mt/id :orders)
+ :aggregation [[:count]]}}}]
+ (is (= "Revenue"
+ (read-title (str "metabase://metric/" metric-id))))))
+ (testing "a document becomes a markdown link"
+ (mt/with-temp [:model/Document {doc-id :id} {:name "Campaign plan"}]
+ (is (= (str "[Campaign plan](metabase://document/" doc-id ")")
+ (read-title (str "metabase://document/" doc-id))))))
+ (testing "a navigation list names what's being browsed"
+ (is (= "databases" (read-title "metabase://databases")))
+ (is (= "recent items" (read-title "metabase://user/recent-items"))))
+ (testing "a missing entity -> no title"
+ (is (nil? (read-title "metabase://dashboard/99999"))))
+ (testing "an unreadable entity never leaks its name"
+ (with-redefs [mi/can-read? (constantly false)]
+ (is (nil? (read-title (str "metabase://dashboard/" dash-id)))))))))
+
;; ===== Permission coverage — every branch =====
;;
;; Two patterns:
diff --git a/test/metabase/metabot/tools/save_entity_test.clj b/test/metabase/metabot/tools/save_entity_test.clj
index 3eb54b1a688..079ba019f9a 100644
--- a/test/metabase/metabot/tools/save_entity_test.clj
+++ b/test/metabase/metabot/tools/save_entity_test.clj
@@ -63,7 +63,10 @@
(is (= "c-1" (get-in part [:data :chart_id])))
(is (= (:id card) (get-in part [:data :card_id])))
(is (= {:type "collection" :id (:id coll)}
- (get-in part [:data :destination])))))))))
+ (get-in part [:data :destination]))))
+ (testing "carries a markdown entity link the chain of thought shows as the Saved label"
+ (is (= (str "[Venues by price](metabase://question/" (:id card) ")")
+ (get-in part [:data :title])))))))))
(deftest save-rehydrated-chart-test
(mt/with-current-user (mt/user->id :crowberto)
diff --git a/test/metabase/metabot/tools/search_test.clj b/test/metabase/metabot/tools/search_test.clj
index d8268543c5c..0762763ff32 100644
--- a/test/metabase/metabot/tools/search_test.clj
+++ b/test/metabase/metabot/tools/search_test.clj
@@ -15,6 +15,37 @@
[metabase.util :as u]
[toucan2.core :as t2]))
+(deftest ^:parallel search-display-test
+ (testing "joins keyword and semantic queries into the search object (client owns the verb/tense)"
+ (is (= "revenue, orders"
+ (#'search/search-display {:keyword_queries ["revenue"] :semantic_queries ["orders"]}))))
+ (testing "dedupes overlapping queries"
+ (is (= "revenue"
+ (#'search/search-display {:keyword_queries ["revenue"] :semantic_queries ["revenue"]}))))
+ (testing "no queries -> nil"
+ (is (nil? (#'search/search-display {})))))
+
+(deftest ^:parallel search-result->item-test
+ (testing "trims a result to the fields the results card renders, nesting collection id+name"
+ (is (= {:id 1 :type "table" :name "orders" :display_name "Orders"
+ :database_id 2 :database_schema "PUBLIC" :database_name "Sample"
+ :collection {:id 3 :name "Finance"}}
+ (#'search/search-result->item
+ {:id 1 :type "table" :name "orders" :display_name "Orders"
+ :database_id 2 :database_schema "PUBLIC" :database_name "Sample"
+ :collection {:id 3 :name "Finance" :authority_level nil}
+ :score 0.99 :description "wide table"}))))
+ (testing "no collection -> no collection key"
+ (is (= {:id 5 :type "dashboard" :name "Revenue"}
+ (#'search/search-result->item
+ {:id 5 :type "dashboard" :name "Revenue" :collection nil}))))
+ (testing "carries a question's display (as a string) + moderated_status for the exact icon"
+ (is (= {:id 7 :type "question" :name "Revenue" :display "line"
+ :moderated_status "verified"}
+ (#'search/search-result->item
+ {:id 7 :type "question" :name "Revenue" :display :line
+ :moderated_status "verified"})))))
+
(deftest ^:parallel reciprocal-rank-fusion-test
(testing "Basic RRF with single list"
(let [single-list [[{:id 1 :model "card" :name "Card 1"}
@@ -283,6 +314,7 @@
:database_id nil
:verified true
:official false
+ :moderated_status "verified"
:collection {:id 11 :name "Analytics" :authority_level nil}
:updated_at "2024-01-04"
:created_at "2024-01-04"}]
diff --git a/test/metabase/metabot/tools_test.clj b/test/metabase/metabot/tools_test.clj
index adfd48b87e2..2e7a001d5ea 100644
--- a/test/metabase/metabot/tools_test.clj
+++ b/test/metabase/metabot/tools_test.clj
@@ -21,6 +21,13 @@
(is (string? (:tool-name m)))
(is (some? (:schema m))))))))
+(deftest wrap-tools-with-state-carries-title-fn-test
+ (testing "a tool var's :title-fn metadata reaches the tool-def map"
+ (let [wrapped (agent-tools/wrap-tools-with-state
+ {"search" #'agent-tools/search-tool}
+ (atom {}) nil nil)]
+ (is (fn? (get-in wrapped ["search" :title-fn]))))))
+
(deftest filter-by-capabilities-test
(testing "returns tools with no capability requirements when capabilities empty"
(let [tool-vars [#'agent-tools/search-tool #'agent-tools/read-resource-tool]]