Skip to content

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

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.clj
index 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-params
body :- ::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.clj
index 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.clj
index 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` for
other 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-map
detail (cond
(seq specific-errors) (format-validation-detail specific-errors)
(seq errors) (format-validation-detail errors))]
@@ -107,6 +113,7 @@
detail detail
msg msg
error 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.clj
index 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.clj
index 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)