The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
Add titles to tools in API to match Claude Connector requirements (#73725)
Timofey Kachalov5b37c9c6deda
diff --git a/src/metabase/agent_api/api.clj b/src/metabase/agent_api/api.cljindex 768140419bf..9302efb23f9 100644--- a/src/metabase/agent_api/api.clj+++ b/src/metabase/agent_api/api.clj@@ -328,6 +328,7 @@Reciprocal Rank Fusion when both query types are provided."{:scope metabot/agent-search:tool {:name "search"+ :title "Search Tables and Metrics":description (str "Search for tables and metrics in Metabase. ""Use term_queries for keyword search or semantic_queries for natural language search. ""Both arguments are arrays of strings, for example term_queries: [\"orders\", \"revenue\"].")@@ -642,12 +643,14 @@metadata and an optional `continuation_token` for fetching the next page."{:scope "agent:query":tool {:name "query"+ :title "Query Tables and Metrics":description (str "Execute a Metabase query from a structured program and return ""results with column metadata. If more rows are available, the ""response includes a continuation_token — pass it back to get the ""next page.\n\n""The body is either a structured program (see construct_query) or "- "{\"continuation_token\": \"...\"} from a previous response.")}}+ "{\"continuation_token\": \"...\"} from a previous response.")+ :annotations {:read-only? true}}}[_route-params_query-paramsbody :- ::query-request]@@ -713,7 +716,8 @@Standard userspace query limits are enforced (2000 rows for simple queries, 10000 for aggregated)."{:scope metabot/agent-query-execute:tool {:name "execute_query"- :description "Execute a previously constructed query and return the results with column metadata, row count, and execution time."}}+ :description "Execute a previously constructed query and return the results with column metadata, row count, and execution time."+ :annotations {:read-only? true :idempotent? true}}}[_route-params_query-params{encoded-query :query} :- ::execute-query-request]diff --git a/src/metabase/api/macros/defendpoint/tools_manifest.clj b/src/metabase/api/macros/defendpoint/tools_manifest.cljindex 30dfa71f31a..fe2ba267737 100644--- a/src/metabase/api/macros/defendpoint/tools_manifest.clj+++ b/src/metabase/api/macros/defendpoint/tools_manifest.clj@@ -160,11 +160,13 @@:open-world? :openWorldHint})(defn- method-default-annotations- "Infer default MCP ToolAnnotations from HTTP method."+ "Infer default MCP ToolAnnotations from HTTP method. POST defaults to non-destructive — opt+ in with `:destructive? true` for endpoints that actually destroy data."[method](case method- (:get :head) {:readOnlyHint true- :idempotentHint true}+ (:get :head) {:readOnlyHint true+ :idempotentHint true}+ :post {:destructiveHint false}:put {:destructiveHint false:idempotentHint true}:delete {:destructiveHint true@@ -172,15 +174,36 @@{}))(defn infer-annotations- "Build MCP ToolAnnotations from HTTP method defaults merged with explicit `:annotations` from `:tool` metadata."+ "Compute MCP ToolAnnotations from HTTP method defaults merged with explicit `:annotations`.+ Returns `{:annotations <merged> :redundant <pairs> :contradictory? <bool>}`. Callers should+ reject `:redundant` entries (explicit declarations must add information beyond the+ HTTP-method default) and `:contradictory?` (a tool can't be both read-only and destructive).++ `destructiveHint` is dropped from `:annotations` when `readOnlyHint` is true since per the+ MCP spec it's only meaningful for non-read-only tools — but if both were `true` before the+ drop, the result is flagged `:contradictory?` rather than silently coalesced."[method explicit-annotations]- (let [defaults (method-default-annotations method)- explicit (into {}- (keep (fn [[k v]]- (when-let [mcp-key (annotation-key-mapping k)]- [mcp-key v])))- explicit-annotations)]- (merge defaults explicit)))+ (let [method-defaults (method-default-annotations method)+ explicit (into {}+ (keep (fn [[k v]]+ (when-let [mcp-key (annotation-key-mapping k)]+ [mcp-key v])))+ explicit-annotations)+ merged (merge method-defaults explicit)+ read-only? (true? (:readOnlyHint merged))+ ;; Report redundancies with the developer's original key (e.g. :read-only?), not the+ ;; translated MCP key, so the error points at what they actually wrote.+ redundant (into {}+ (keep (fn [[k v]]+ (when-let [mcp-key (annotation-key-mapping k)]+ (when (= v (get method-defaults mcp-key))+ [k v]))))+ explicit-annotations)]+ (cond-> {:annotations (cond-> merged+ read-only? (dissoc :destructiveHint))+ :redundant redundant}+ (and read-only? (true? (:destructiveHint merged)))+ (assoc :contradictory? true))))(defn- schema->properties-and-required"Extract `:properties` and `:required` from a malli schema's JSON Schema.@@ -230,23 +253,61 @@[path](str/replace path #":([^/]+)" "{$1}"))+(defn- name->title+ "Default convention: convert a snake_case tool name to a Title Case title.+ `get_table` → `Get Table`."+ [tool-name]+ (->> (str/split tool-name #"_")+ (map str/capitalize)+ (str/join " ")))++(defn- assert-claude-connector-compliant!+ "Throw if `annotations` lack the readOnlyHint or destructiveHint that the Claude+ connector requires (every tool must declare one or the other)."+ [tool-name annotations]+ (let [{:keys [readOnlyHint destructiveHint]} annotations]+ (when-not (or (true? readOnlyHint) (boolean? destructiveHint))+ (throw (ex-info (str "Tool " tool-name+ " must declare :read-only? true or :destructive? <boolean> "+ "(Claude connector requirement).")+ {:tool tool-name :annotations annotations})))))+(defn endpoint->tool-definition"Convert a single endpoint info + prefix to a tool definition map."[prefix {:keys [form]}]- (let [method (:method form)- route-path (get-in form [:route :path])- tool-md (get-in form [:metadata :tool])- tool-name (:name tool-md)- _ (assert (string? tool-name) "Tool :name must be a string")- description (or (:description tool-md)- (:docstr form))- full-path (str prefix (route-path->endpoint-path route-path))- input-schema (merge-input-schemas form)- resp-schema (response-schema->json-schema (:response-schema form))- annotations (infer-annotations method (:annotations tool-md))- task-support (:task-support tool-md)- scope (get-in form [:metadata :scope])]+ (let [method (:method form)+ route-path (get-in form [:route :path])+ tool-md (get-in form [:metadata :tool])+ tool-name (:name tool-md)+ _ (assert (string? tool-name) "Tool :name must be a string")+ explicit-title (:title tool-md)+ inferred-title (name->title tool-name)+ _ (when (= explicit-title inferred-title)+ (throw (ex-info (str "Tool " tool-name " has redundant :title "+ (pr-str explicit-title)+ " — matches the title we'd infer from the name.")+ {:tool tool-name :title explicit-title})))+ description (or (:description tool-md)+ (:docstr form))+ full-path (str prefix (route-path->endpoint-path route-path))+ input-schema (merge-input-schemas form)+ resp-schema (response-schema->json-schema (:response-schema form))+ inferred (infer-annotations method (:annotations tool-md))+ annotations (:annotations inferred)+ _ (when (:contradictory? inferred)+ (throw (ex-info (str "Tool " tool-name+ " is marked both read-only and destructive — these can't both be true.")+ {:tool tool-name :method method})))+ _ (when (seq (:redundant inferred))+ (throw (ex-info (str "Tool " tool-name+ " has redundant :annotations matching defaults: "+ (pr-str (:redundant inferred)))+ {:tool tool-name :method method :redundant (:redundant inferred)})))+ _ (assert-claude-connector-compliant! tool-name annotations)+ task-support (:task-support tool-md)+ scope (get-in form [:metadata :scope])](cond-> {:name tool-name+ :title (or explicit-title inferred-title):description description:endpoint {:method (u/upper-case-en (name method)):path full-path}}diff --git a/src/metabase/mcp/tools.clj b/src/metabase/mcp/tools.cljindex f63243f2ee2..27250a8131c 100644--- a/src/metabase/mcp/tools.clj+++ b/src/metabase/mcp/tools.clj@@ -57,9 +57,11 @@(into [](comp (filter #(scope-matches? token-scopes (:scope %)))(map (fn [tool]- {:name (:name tool)- :description (:description tool)- :inputSchema (:inputSchema tool)})))+ (cond-> {:name (:name tool)+ :title (:title tool)+ :description (:description tool)+ :inputSchema (:inputSchema tool)}+ (:annotations tool) (assoc :annotations (:annotations tool))))))tools)))(defn- build-tool-index@@ -96,9 +98,13 @@returns `:specific-errors`/`:errors` for schema-validation 400s (see[[metabase.api.macros/decode-and-validate-params]]) and `:message`/`:error` forother failures — surfacing the validation detail turns \"Invalid body\" into an- actionable message for MCP clients."+ actionable message for MCP clients. String bodies (e.g. 404 \"Not found.\") are+ surfaced as the message rather than collapsed to a bare \"Agent API error: <status>\"."[response]- (let [{msg :message :keys [specific-errors errors error]} (:body response)+ (let [body (:body response)+ body-map (when (map? body) body)+ body-str (when (and (string? body) (not (str/blank? body))) body)+ {msg :message :keys [specific-errors errors error]} body-mapdetail (cond(seq specific-errors) (format-validation-detail specific-errors)(seq errors) (format-validation-detail errors))]@@ -107,6 +113,7 @@detail detailmsg msgerror error+ body-str body-str:else (str "Agent API error: " (:status response)))));;; ------------------------------------------------- Tool Dispatch -------------------------------------------------diff --git a/test/metabase/api/macros/defendpoint/tools_manifest_test.clj b/test/metabase/api/macros/defendpoint/tools_manifest_test.cljindex 8b33abad90b..a0e8d30a97f 100644--- a/test/metabase/api/macros/defendpoint/tools_manifest_test.clj+++ b/test/metabase/api/macros/defendpoint/tools_manifest_test.clj@@ -8,24 +8,37 @@(deftest ^:parallel infer-annotations-test(testing "GET defaults"- (is (= {:readOnlyHint true- :idempotentHint true}+ (is (= {:annotations {:readOnlyHint true :idempotentHint true}+ :redundant {}}(tools-manifest/infer-annotations :get nil))))(testing "DELETE defaults"- (is (= {:destructiveHint true- :idempotentHint true}+ (is (= {:annotations {:destructiveHint true :idempotentHint true}+ :redundant {}}(tools-manifest/infer-annotations :delete nil))))(testing "PUT defaults"- (is (= {:destructiveHint false- :idempotentHint true}+ (is (= {:annotations {:destructiveHint false :idempotentHint true}+ :redundant {}}(tools-manifest/infer-annotations :put nil))))- (testing "POST defaults (empty — MCP defaults apply)"- (is (= {}- (tools-manifest/infer-annotations :post nil))))- (testing "Explicit annotations override defaults"- (is (= {:readOnlyHint true- :idempotentHint true}- (tools-manifest/infer-annotations :post {:read-only? true :idempotent? true})))))+ (testing "POST defaults to non-destructive (opt in with :destructive? true)"+ (is (= {:annotations {:destructiveHint false} :redundant {}}+ (tools-manifest/infer-annotations :post nil)))+ (is (= {:destructive? false}+ (:redundant (tools-manifest/infer-annotations :post {:destructive? false})))))+ (testing "destructiveHint is dropped from output when readOnlyHint is true (per MCP spec it's only meaningful for non-read-only tools)"+ (is (= {:readOnlyHint true}+ (:annotations (tools-manifest/infer-annotations :post {:read-only? true})))))+ (testing "Flags :contradictory? when readOnlyHint and destructiveHint would both be true before the cleanup"+ (is (true? (:contradictory? (tools-manifest/infer-annotations :get {:destructive? true}))))+ (is (true? (:contradictory? (tools-manifest/infer-annotations :delete {:read-only? true})))))+ (testing "Explicit annotations are merged on top of method defaults"+ (is (= {:annotations {:readOnlyHint true :idempotentHint true}+ :redundant {}}+ (tools-manifest/infer-annotations :post {:read-only? true :idempotent? true}))))+ (testing "Reports redundant pairs that match what we'd already infer (using developer-facing keys)"+ (is (= {:read-only? true}+ (:redundant (tools-manifest/infer-annotations :get {:read-only? true}))))+ (is (= {:destructive? false}+ (:redundant (tools-manifest/infer-annotations :put {:destructive? false}))))))(deftest ^:parallel prefer-tool-descriptions-test(testing "tool/description replaces description in JSON schema output"@@ -213,6 +226,7 @@:body '(nil)}result (tools-manifest/endpoint->tool-definition "/api/agent" {:form form})](is (= {:name "get_table"+ :title "Get Table":description "Get a table.":endpoint {:method "GET" :path "/api/agent/v1/table/{id}"}:inputSchema {:type "object"@@ -246,6 +260,36 @@result (tools-manifest/endpoint->tool-definition "/api/test" {:form form})](is (nil? (:scope result))))))+(deftest ^:parallel endpoint->tool-definition-redundant-title-test+ (testing "Throws when an explicit :title matches the title we'd infer from :name"+ (let [form {:method :get+ :route {:path "/v1/table/:id"}+ :params {:route {:binding '{:keys [id]}+ :schema [:map [:id :int]]}}+ :docstr "Get a table."+ :metadata {:tool {:name "get_table"+ :title "Get Table"}}+ :body '(nil)}]+ (is (thrown-with-msg?+ ExceptionInfo+ #"redundant :title"+ (tools-manifest/endpoint->tool-definition "/api/agent" {:form form}))))))++(deftest ^:parallel endpoint->tool-definition-redundant-annotations-test+ (testing "Throws when explicit :annotations restate an HTTP-method default (e.g. :read-only? on GET)"+ (let [form {:method :get+ :route {:path "/v1/table/:id"}+ :params {:route {:binding '{:keys [id]}+ :schema [:map [:id :int]]}}+ :docstr "Get a table."+ :metadata {:tool {:name "get_table"+ :annotations {:read-only? true}}}+ :body '(nil)}]+ (is (thrown-with-msg?+ ExceptionInfo+ #"redundant :annotations"+ (tools-manifest/endpoint->tool-definition "/api/agent" {:form form}))))))+;; This test verifies the full pipeline with actual defendpoint endpoints.;; It requires the agent API namespace to be loaded.@@ -296,6 +340,7 @@:- [:map [:id :int] [:status ::test-status]]"Perform an action on a resource."{:tool {:name "test_resource_action"+ :annotations {:read-only? true}:task-support :parallel}}[{:keys [id]} :- [:map [:id :int]]_query-params@@ -364,6 +409,7 @@(deftest ^:parallel generate-tools-manifest-get-with-route-params-test(is (= {:name "test_get_thing"+ :title "Test Get Thing":description "A test endpoint for tools manifest generation.":annotations {:readOnlyHint true :idempotentHint true}:endpoint {:method "GET" :path "/api/test/v1/test/{id}"}@@ -374,6 +420,7 @@(deftest ^:parallel generate-tools-manifest-post-with-annotation-override-test(is (= {:name "test_action"+ :title "Test Action":description "A test POST action.":annotations {:readOnlyHint true}:endpoint {:method "POST" :path "/api/test/v1/test-action"}@@ -384,6 +431,7 @@(deftest ^:parallel generate-tools-manifest-delete-test(is (= {:name "delete_test"+ :title "Delete Test":description "Delete a test resource.":annotations {:destructiveHint true :idempotentHint true}:endpoint {:method "DELETE" :path "/api/test/v1/test/{id}"}@@ -394,6 +442,7 @@(deftest ^:parallel generate-tools-manifest-get-with-query-params-test(is (= {:name "test_search"+ :title "Test Search":description "Search for things.":annotations {:readOnlyHint true :idempotentHint true}:endpoint {:method "GET" :path "/api/test/v1/test-search"}@@ -409,7 +458,9 @@(deftest ^:parallel generate-tools-manifest-post-with-task-support-test(is (= {:name "test_resource_action"+ :title "Test Resource Action":description "Perform an action on a resource."+ :annotations {:readOnlyHint true}:endpoint {:method "POST" :path "/api/test/v1/test-resource/{id}/action"}:inputSchema {:type "object":properties {:id {:type "integer"}@@ -425,6 +476,7 @@(deftest ^:parallel generate-tools-manifest-put-with-three-way-merge-test(is (= {:name "test_resource"+ :title "Test Resource":description "Update a test resource.":annotations {:destructiveHint false :idempotentHint true}:endpoint {:method "PUT" :path "/api/test/v1/test-resource/{id}"}diff --git a/test/metabase/mcp/api_test.clj b/test/metabase/mcp/api_test.cljindex 80e62c05800..0ca9307256f 100644--- a/test/metabase/mcp/api_test.clj+++ b/test/metabase/mcp/api_test.clj@@ -4,6 +4,8 @@[clojure.test :refer :all][metabase.agent-api.settings :as agent-api.settings][metabase.api.macros.scope :as scope]+ [metabase.lib.core :as lib]+ [metabase.lib.metadata :as lib.metadata][metabase.mcp.api :as mcp.api][metabase.mcp.settings :as mcp.settings][metabase.mcp.tools :as mcp.tools]@@ -414,6 +416,25 @@(is (true? (:isError result)))(is (str/includes? (:text (first (:content result))) "Missing required path parameter")))))+(deftest tools-call-string-body-error-surfaces-actionable-message-test+ (testing (str "Claude's connector review explicitly rejects bare-status error messages — "+ "when the agent-api returns a string body (e.g. 404 \"Not found.\"), the MCP "+ "error content surfaces the body verbatim rather than collapsing to "+ "\"Agent API error: <status>\".")+ (let [[session-id _] (initialize!)+ response (mcp-request (jsonrpc-request "tools/call"+ {:name "get_table"+ :arguments {:id 999999}})+ {"mcp-session-id" session-id})+ result (get-in response [:body :result])+ message (:text (first (:content result)))]+ (is (= 200 (:status response)))+ (is (true? (:isError result)))+ (is (= "Not found." message)+ "string body should be surfaced verbatim")+ (is (not (str/includes? message "Agent API error"))+ "must not fall through to the bare-status fallback"))))+(deftest tools-list-no-refs-test(testing "tool inputSchemas have no $ref, no $defs, and root type is always object"(let [tools (mcp.tools/list-tools nil)]@@ -444,6 +465,71 @@(is (empty? (:fields table-data))"with-fields=false should return no fields")))))+(defn- orders-count-query+ "Simple count query on the orders table — used as the dataset_query for smoke-test metrics."+ []+ (-> (lib/query (mt/metadata-provider)+ (lib.metadata/table (mt/metadata-provider) (mt/id :orders)))+ (lib/aggregate (lib/count))))++(def ^:private smoke-tested-tools+ "Tools exercised by `tools-call-smoke-test`. New tools must be added here (and+ below) — the test compares this set against `mcp.tools/list-tools` and fails+ when they diverge, ensuring no tool ships without a basic invocation check."+ #{"get_table" "get_table_field_values" "get_metric" "get_metric_field_values"+ "search" "construct_query" "query" "execute_query"+ "create_question" "create_dashboard"})++(deftest tools-call-smoke-test+ (testing "every registered tool is exercised by the smoke test"+ (is (= (set (map :name (mcp.tools/list-tools nil)))+ smoke-tested-tools)+ "Add the missing tool to `smoke-tested-tools` and the call sequence below."))+ (testing "every tool returns a successful response with valid parameters"+ (search.tu/with-legacy-search+ (mt/with-temp [:model/Card metric {:name "Smoke Metric"+ :type :metric+ :database_id (mt/id)+ :dataset_query (orders-count-query)}]+ (let [[session-id _] (initialize!)+ orders-id (mt/id :orders)+ ;; Track write-tool outputs in atoms so the `finally` cleanup runs even if an+ ;; assertion in `call-tool` fails partway through the sequence.+ question-id (atom nil)+ dash-id (atom nil)]+ (try+ (let [;; Read tools — call-tool helper asserts (not :isError) internally.+ table-data (call-tool session-id "get_table" {:id orders-id})+ table-fid (-> table-data :fields first :field_id)+ _ (call-tool session-id "get_table_field_values"+ {:id orders-id :field-id (str table-fid)})+ metric-data (call-tool session-id "get_metric" {:id (:id metric)})+ metric-fid (-> metric-data :queryable_dimensions first :field_id)+ _ (call-tool session-id "get_metric_field_values"+ {:id (:id metric) :field-id (str metric-fid)})+ _ (call-tool session-id "search" {:term_queries ["orders"]})+ ;; Query construction + execution+ construct-data (call-tool session-id "construct_query"+ {:source {:type "table" :id orders-id}+ :operations [["limit" 5]]})+ _ (call-tool session-id "query"+ {:source {:type "table" :id orders-id}+ :operations [["limit" 5]]})+ _ (call-tool session-id "execute_query"+ {:query (:query construct-data)})+ ;; Write tools — record IDs as soon as they're known so the `finally` block+ ;; can clean up even if a later step throws.+ question-data (call-tool session-id "create_question"+ {:name "Smoke Question"+ :query (:query construct-data)})+ _ (reset! question-id (:id question-data))+ dash-data (call-tool session-id "create_dashboard"+ {:name "Smoke Dashboard"})]+ (reset! dash-id (:id dash-data)))+ (finally+ (when-let [qid @question-id] (t2/delete! :model/Card :id qid))+ (when-let [did @dash-id] (t2/delete! :model/Dashboard :id did)))))))))+(deftest tools-call-execute-query-test(testing "execute_query returns a streaming response captured as MCP text content"(let [streamed? (atom false)