Skip to content

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

[BOT-1871] Fix portable_entity_id being used for read_resource (#78074)

Tyler Plude8610bfc613b1
diff --git a/resources/metabot/prompts/llm_shape.selmer b/resources/metabot/prompts/llm_shape.selmer
index 74bcf1f09ca..4f7ab344198 100644
--- a/resources/metabot/prompts/llm_shape.selmer
+++ b/resources/metabot/prompts/llm_shape.selmer
@@ -282,7 +282,7 @@ or jargon that may be relevant to the user's questions.
</user>
{% endif %}
{% if is_search_result %}
-<{{search_tag_name}} id="{{search_id}}" name="{{search_name}}"{% if search_has_curated %} is_curated="{{search_curated}}"{% endif %}{% if search_has_verified %} is_verified="{{search_verified}}"{% endif %}{% if search_has_official %} is_official="{{search_official}}"{% endif %}{% if search_data_layer %} data_layer="{{search_data_layer}}"{% endif %}{% if search_data_authority %} data_authority="{{search_data_authority}}"{% endif %}{% if search_database_id %} database_id="{{search_database_id}}"{% endif %}{% if search_database_name %} database_name="{{search_database_name}}"{% endif %}{% if search_database_engine %} database_engine="{{search_database_engine}}"{% endif %}{% if search_fqn %} fully_qualified_name="{{search_fqn}}"{% endif %}{% if search_base_table_fqn %} base_table_fully_qualified_name="{{search_base_table_fqn}}"{% endif %}{% if search_portable_entity_id %} portable_entity_id="{{search_portable_entity_id}}"{% endif %}>
+<{{search_tag_name}} id="{{search_id}}"{% if search_uri %} uri="{{search_uri}}"{% endif %} name="{{search_name}}"{% if search_has_curated %} is_curated="{{search_curated}}"{% endif %}{% if search_has_verified %} is_verified="{{search_verified}}"{% endif %}{% if search_has_official %} is_official="{{search_official}}"{% endif %}{% if search_data_layer %} data_layer="{{search_data_layer}}"{% endif %}{% if search_data_authority %} data_authority="{{search_data_authority}}"{% endif %}{% if search_database_id %} database_id="{{search_database_id}}"{% endif %}{% if search_database_name %} database_name="{{search_database_name}}"{% endif %}{% if search_database_engine %} database_engine="{{search_database_engine}}"{% endif %}{% if search_fqn %} fully_qualified_name="{{search_fqn}}"{% endif %}{% if search_base_table_fqn %} base_table_fully_qualified_name="{{search_base_table_fqn}}"{% endif %}{% if search_portable_entity_id %} portable_entity_id="{{search_portable_entity_id}}"{% endif %}>
{% if search_description %}
{{search_description}}
{% endif %}
diff --git a/resources/metabot/prompts/shared/prompt_snippets/discovery.selmer b/resources/metabot/prompts/shared/prompt_snippets/discovery.selmer
index d11168b6ab6..3decae8b686 100644
--- a/resources/metabot/prompts/shared/prompt_snippets/discovery.selmer
+++ b/resources/metabot/prompts/shared/prompt_snippets/discovery.selmer
@@ -7,14 +7,14 @@ You have two ways to find data, with different strengths:
These play different roles, and the distinction matters:
-- **Choosing which data source answers an analytical question → start with `search`.** The curated layer — published metrics and models — is only discoverable by topic. Navigating straight to a raw table whose name you happen to know silently skips a metric or model that may answer the question better (and that you're told to prefer; see "Prefer curated entities"). Search first, *then* drill into the best hit with `read_resource`. Recognizing a raw table's name is not a reason to skip the search.
+- **Choosing which data source answers an analytical question → start with `search`.** The curated layer — published metrics and models — is only discoverable by topic. Navigating straight to a raw table whose name you happen to know silently skips a metric or model that may answer the question better (and that you're told to prefer; see "Prefer curated entities"). Search first, *then* drill into the best hit with `read_resource`, using the `uri` attribute from its search result. Recognizing a raw table's name is not a reason to skip the search.
- **Enumerating a structure you can already name → navigate directly.** "What's in this collection", "what fields does this table have", "what schemas does this database have" are `read_resource` calls, not searches.
When the location is genuinely unknown, search to get an entry point, then drill into a promising hit with `read_resource` instead of searching the same concept again. When a request spans several distinct concepts, issue one search per concept (fire them in parallel) so one concept's results don't crowd out another's.
## Read a source before you build on it
-Finding a candidate table, model, or metric is not the same as confirming it fits. Before you commit a source to a query, read its metadata with `read_resource` — its description, fields, and relationships — and weigh:
+Finding a candidate table, model, or metric is not the same as confirming it fits. Before you commit a source to a query, read its metadata with `read_resource` — its description, fields, and relationships — via the `uri` attribute on its search result. `read_resource` URIs always take the numeric id, never an alphanumeric entity-id. Weigh:
- **Caveats in the description** — freshness/ETL lag, retention windows, scope ("last 30 days only", "excludes today", "aggregated nightly"). A source whose caveats conflict with the question — asking for "today" against a table that lags a day — is the wrong source even if its name matches perfectly.
- **Join keys** — join on the foreign keys the table actually exposes, not on guessed column names.
diff --git a/resources/metabot/prompts/tools/construct_notebook_query.md b/resources/metabot/prompts/tools/construct_notebook_query.md
index 8058fea2649..5e558b7d2a0 100644
--- a/resources/metabot/prompts/tools/construct_notebook_query.md
+++ b/resources/metabot/prompts/tools/construct_notebook_query.md
@@ -3,7 +3,7 @@
Construct a Metabase MBQL 5 query as a JSON object describing the query shape. Metabase validates, repairs, and resolves it.
Return:
-- `query`: a JSON **object** (never a quoted string). The target database is inferred from the first stage's `source-table` (or `source-card`) — use the **exact** database name reported by `entity_details` / metadata tools.
+- `query`: a JSON **object** (never a quoted string). The target database is inferred from the first stage's `source-table` (or `source-card`) — use the **exact** database name reported by search / `read_resource` / metadata tools.
- `title`: required short, human-friendly title for the resulting chart, shown above it (e.g. `"Orders by month"`).
- `visualization`: optional `{"chart_type": "bar"}` (sibling of `query`, never embedded inside it).
@@ -155,7 +155,7 @@ Reference a field on a related table directly — when the source has exactly on
- If the FK column lives on a previous stage's output, write `{"source-field-name": "<col>"}` (not auto-filled).
- If multiple explicit joins all expose the target FK, `:ambiguous-fk-via-join` lists them — set `{"source-field-join-alias": "<alias>"}` to pick one.
-**Tip:** discover FKs with `entity_details` / `read_resource metabase://table/<id>/fields`. FK columns are tagged `fk_target_fully_qualified_name="schema.table.field"` — always look for one before assuming a column lives on the current table.
+**Tip:** discover FKs with `read_resource metabase://table/<id>/fields`. FK columns are tagged `fk_target_fully_qualified_name="schema.table.field"` — always look for one before assuming a column lives on the current table.
## Multi-stage queries
@@ -199,7 +199,7 @@ Re-aggregate — average daily total by month:
## Saved questions and models (`source-card`)
-Instead of `source-table`, use `source-card` to query an existing question or model. The value is the card's **portable entity id** — a 21-char opaque string reported by `entity_details` and search tools as `portable_entity_id`.
+Instead of `source-table`, use `source-card` to query an existing question or model. The value is the card's **portable entity id** — a 21-char opaque string reported by search and `read_resource` as `portable_entity_id`.
1. Get the `portable_entity_id` from a tool response. `search` and `read_resource` (`metabase://question/<id>`, `metabase://model/<id>`) include it on the result tag — reuse what's already in context, no extra call needed.
2. Copy it **verbatim** into `source-card`. The id is opaque — never guess, construct, or abbreviate.
@@ -270,10 +270,10 @@ Before the shape rules: map the user's wording to the right clause. These mismat
Shape rules:
- **Always include `{}` options in every clause**, even when empty. `["count"]` is wrong — it must be `["count", {}]`.
- **The query is a JSON object**, not a string. Send it directly as the `"query"` field of the call.
-- **Use the exact database name** reported by `entity_details` (e.g. `"Sample Database"`, not `"Sample"`) as the first element of every portable FK. Near-misses surface `Unknown database` instead of silently picking one. Cross-database queries are not supported.
+- **Use the exact database name** reported by search / `read_resource` (e.g. `"Sample Database"`, not `"Sample"`) as the first element of every portable FK. Near-misses surface `Unknown database` instead of silently picking one. Cross-database queries are not supported.
- **Use portable FKs**, not numeric IDs. Schemaless databases use `null` in the schema slot. JSON-unfolded fields append path segments.
- **Clause heads are lowercase, hyphenated**: `"count"`, `"sum-where"`, `"time-interval"`, `"get-day-of-week"`. Not underscores, not camelCase.
-- **Never invent a `source-card` entity_id.** It must be a 21-char string copied verbatim from `entity_details` / search — no patterns, no numeric ids, no `card__<id>`.
+- **Never invent a `source-card` entity_id.** It must be a 21-char string copied verbatim from search / `read_resource` — no patterns, no numeric ids, no `card__<id>`.
- **`source-card` columns are referenced by output name** (string in slot 3), not portable FK.
Anti-hallucination:
diff --git a/resources/metabot/skills/construct-notebook-query-advanced.md b/resources/metabot/skills/construct-notebook-query-advanced.md
index 01fe3465411..3ec636f7242 100644
--- a/resources/metabot/skills/construct-notebook-query-advanced.md
+++ b/resources/metabot/skills/construct-notebook-query-advanced.md
@@ -70,7 +70,7 @@ Reference a field on a related table directly — when the source has exactly on
- If the FK column lives on a previous stage's output, write `{"source-field-name": "<col>"}` (not auto-filled).
- If multiple explicit joins all expose the target FK, `:ambiguous-fk-via-join` lists them — set `{"source-field-join-alias": "<alias>"}` to pick one.
-**Tip:** discover FKs with `entity_details` / `read_resource metabase://table/<id>/fields`. FK columns are tagged `fk_target_fully_qualified_name="schema.table.field"` — always look for one before assuming a column lives on the current table.
+**Tip:** discover FKs with `read_resource metabase://table/<id>/fields`. FK columns are tagged `fk_target_fully_qualified_name="schema.table.field"` — always look for one before assuming a column lives on the current table.
## Multi-stage queries
@@ -135,7 +135,7 @@ Stage 2 references each stage-1 aggregation by the **output column name** it pro
## Saved questions and models (`source-card`)
-Instead of `source-table`, use `source-card` to query an existing question or model. The value is the card's **portable entity id** — a 21-char opaque string reported by `entity_details` and search tools as `portable_entity_id`.
+Instead of `source-table`, use `source-card` to query an existing question or model. The value is the card's **portable entity id** — a 21-char opaque string reported by search and `read_resource` as `portable_entity_id`.
1. Get the `portable_entity_id` from a tool response. `search` and `read_resource` (`metabase://question/<id>`, `metabase://model/<id>`) include it on the result tag — reuse what's already in context, no extra call needed.
2. Copy it **verbatim** into `source-card`. The id is opaque — never guess, construct, or abbreviate.
diff --git a/resources/metabot/skills/construct-notebook-query-core.md b/resources/metabot/skills/construct-notebook-query-core.md
index a21e040c17c..4d6a32364c7 100644
--- a/resources/metabot/skills/construct-notebook-query-core.md
+++ b/resources/metabot/skills/construct-notebook-query-core.md
@@ -12,7 +12,7 @@ Construct a Metabase MBQL 5 query as a JSON object describing the query shape. M
> Advanced topics — joins, implicit joins, multi-stage queries, `source-card`, metrics, measures/segments, expressions, and aggregation references — are in the **construct-notebook-query-advanced** skill. The full operator/function catalogs are in **construct-notebook-query-operators**. Load those skills when you need them.
Return:
-- `query`: a JSON **object** (never a quoted string). The target database is inferred from the first stage's `source-table` (or `source-card`) — use the **exact** database name reported by `entity_details` / metadata tools.
+- `query`: a JSON **object** (never a quoted string). The target database is inferred from the first stage's `source-table` (or `source-card`) — use the **exact** database name reported by search / `read_resource` / metadata tools.
- `visualization`: optional `{"chart_type": "bar"}` (sibling of `query`, never embedded inside it).
## Minimal example — count of orders by month
@@ -107,10 +107,10 @@ Order by — direction wraps a ref; works on field refs or aggregation refs:
Shape rules:
- **Always include `{}` options in every clause**, even when empty. `["count"]` is wrong — it must be `["count", {}]`.
- **The query is a JSON object**, not a string. Send it directly as the `"query"` field of the call.
-- **Use the exact database name** reported by `entity_details` (e.g. `"Sample Database"`, not `"Sample"`) as the first element of every portable FK. Near-misses surface `Unknown database` instead of silently picking one. Cross-database queries are not supported.
+- **Use the exact database name** reported by search / `read_resource` (e.g. `"Sample Database"`, not `"Sample"`) as the first element of every portable FK. Near-misses surface `Unknown database` instead of silently picking one. Cross-database queries are not supported.
- **Use portable FKs**, not numeric IDs. Schemaless databases use `null` in the schema slot. JSON-unfolded fields append path segments.
- **Clause heads are lowercase, hyphenated**: `"count"`, `"sum-where"`, `"time-interval"`, `"get-day-of-week"`. Not underscores, not camelCase.
-- **Never invent a `source-card` entity_id.** It must be a 21-char string copied verbatim from `entity_details` / search — no patterns, no numeric ids, no `card__<id>`.
+- **Never invent a `source-card` entity_id.** It must be a 21-char string copied verbatim from search / `read_resource` — no patterns, no numeric ids, no `card__<id>`.
- **`source-card` columns are referenced by output name** (string in slot 3), not portable FK.
Anti-hallucination:
diff --git a/src/metabase/agent_api/api.clj b/src/metabase/agent_api/api.clj
index d291c3a3f87..c2fd976ee3c 100644
--- a/src/metabase/agent_api/api.clj
+++ b/src/metabase/agent_api/api.clj
@@ -256,7 +256,7 @@
"`{\"query\": <object>}`; returns `{\"query_handle\": \"<uuid>\"}` to feed "
"`execute_query` or `visualize_query`.\n"
"\n"
- "Workflow: use search / entity_details first to discover the exact database, "
+ "Workflow: use search / read_resource first to discover the exact database, "
"schema, table, and column NAMES (not numeric IDs). Never invent identifiers.\n"
"\n"
"Shape: every clause is `[\"op\", {}, ...args]` with a MANDATORY empty options "
diff --git a/src/metabase/agent_lib/representations/repair.clj b/src/metabase/agent_lib/representations/repair.clj
index 299edb73072..649802ba2d0 100644
--- a/src/metabase/agent_lib/representations/repair.clj
+++ b/src/metabase/agent_lib/representations/repair.clj
@@ -1976,10 +1976,10 @@
;; Deliberately do NOT enumerate the candidate FK columns: the metadata provider
;; is un-sandboxed and any leaked `[db schema table field]` path could surface
;; bridge-table column names the caller is not permitted to see (`:agent-error?`
- ;; relays the message verbatim to the user). The LLM can recover by calling
- ;; `entity_details` on the source table to inspect available foreign-key columns.
+ ;; relays the message verbatim to the user). The LLM can recover by reading the
+ ;; source table's fields with `read_resource` to inspect available foreign-key columns.
(let [src-name (display-source-table mp source-table-id)]
- (throw (ex-info (tru "Field {0} can be reached from {1} via {2} foreign keys. Specify the `source-field` option on the field clause to disambiguate; call `entity_details` on the source table to list the available foreign-key columns."
+ (throw (ex-info (tru "Field {0} can be reached from {1} via {2} foreign keys. Specify the `source-field` option on the field clause to disambiguate; call `read_resource` with `metabase://table/<numeric id>/fields` for the source table to list the available foreign-key columns."
(display-portable fk)
(pr-str src-name)
(count candidates))
diff --git a/src/metabase/metabot/tools/construct.clj b/src/metabase/metabot/tools/construct.clj
index ecafcafca42..3c73866d777 100644
--- a/src/metabase/metabot/tools/construct.clj
+++ b/src/metabase/metabot/tools/construct.clj
@@ -146,16 +146,19 @@
(let [hint (case entity-type
"metric"
(str "Metrics are aggregations, not sources. To use metric " entity-id
- ", put its `base_table_portable_fk` (from `entity_details` on the metric) "
- "into `source-table:` and reference the metric as "
- "`aggregation: [[metric, {}, \"<portable_entity_id>\"]]`.")
+ ", put its base table into `source-table:` — combine the `database_name` "
+ "and `base_table_fully_qualified_name` attributes from its search result "
+ "or `read_resource metabase://metric/" entity-id "` — and reference the "
+ "metric as `aggregation: [[metric, {}, \"<portable_entity_id>\"]]`.")
("question" "model" "card")
(str "To reference saved " entity-type " " entity-id
- " as a query source, put its `portable_entity_id` (a 21-char "
- "string from `entity_details`) into `source-card:` — not a URI.")
+ " as a query source, put its `portable_entity_id` (the 21-char "
+ "string from its search result or `read_resource`) into "
+ "`source-card:` — not a URI.")
"table"
- (str "Use the portable FK `[<db-name>, <schema>, <table-name>]` from "
- "`entity_details` in `source-table:` — not a URI.")
+ (str "Use the portable FK `[<db-name>, <schema>, <table-name>]` in "
+ "`source-table:` — not a URI. `read_resource metabase://table/" entity-id
+ "` reports the exact names.")
(str "`source-table:` accepts a portable FK `[<db-name>, <schema>, <table-name>]` "
"or, via `source-card:`, a saved-card `portable_entity_id`."))]
(throw (ex-info (tru "`source-table:` does not accept URIs like `{0}`. {1}"
@@ -220,7 +223,7 @@
ids (t2/select-pks-vec :model/Database :name db-name)]
(case (count ids)
0 (throw (ex-info (tru (str "Unknown database: `{0}`. Use the exact database name as "
- "reported by `entity_details` / metadata tools (it appears "
+ "reported by search / `read_resource` (it appears "
"as the first element of every portable FK, e.g. "
"`source-table: [<db-name>, <schema>, <table>]`).")
db-name)
@@ -242,9 +245,10 @@
(if-let [card (tools.u/get-card-by-entity-id eid)]
(:database_id card)
(throw (ex-info (tru (str "No saved question or model found with entity_id {0}. Do not invent "
- "or guess entity_ids: call `entity_details` with `entity-type: question` "
- "or `entity-type: model` and the card''s numeric id first, then copy the "
- "exact `portable_entity_id` from the response into `source-card:`.")
+ "or guess entity_ids: call `read_resource` with "
+ "`metabase://question/<numeric id>` or `metabase://model/<numeric id>` "
+ "first, then copy the exact `portable_entity_id` from the response "
+ "into `source-card:`.")
(pr-str eid))
{:agent-error? true
:status-code 400
diff --git a/src/metabase/metabot/tools/resources.clj b/src/metabase/metabot/tools/resources.clj
index d7d78840dbb..64fcabc79a6 100644
--- a/src/metabase/metabot/tools/resources.clj
+++ b/src/metabase/metabot/tools/resources.clj
@@ -684,6 +684,29 @@
;; ----- Dispatch -----
+(def ^:private numeric-id-uri-types
+ "URI entity-type segments whose next segment must be a numeric id (see `dispatch`)."
+ #{"database" "collection" "table" "model" "question" "metric"
+ "measure" "segment" "transform" "dashboard"})
+
+(defn- check-numeric-id-segment!
+ "Entity URIs take numeric ids only. The common miss is the LLM pasting a 21-char entity id
+ where the numeric id belongs; without this check that fails downstream as a bare 404 the
+ LLM misreads as a permissions problem. Throw a directive error instead so it
+ self-corrects in one step."
+ [uri [type-seg id-seg]]
+ (when (and (numeric-id-uri-types type-seg)
+ (some? id-seg)
+ (nil? (parse-long id-seg)))
+ (throw (ex-info
+ (str "Invalid id `" id-seg "` in URI. read_resource URIs use the numeric entity "
+ "id — copy the `uri` attribute from a search result, or build the URI from "
+ "its numeric `id` attribute, e.g. metabase://" type-seg "/42.")
+ {:agent-error? true
+ :status-code 400
+ :uri uri
+ :id-segment id-seg}))))
+
(defn- dispatch
"Route a parsed URI to the right fetch handler. The match-one table is the canonical
list of supported URI shapes — adding a new URI = adding a clause here + a handler.
@@ -692,6 +715,7 @@
ones (with rest-binding) so the exact-length match wins for the no-extra-segments case."
[uri]
(let [{:keys [segments query-params]} (parse-uri uri)]
+ (check-numeric-id-segment! uri segments)
(match/match-one segments
;; Navigation
["databases"] (fetch-databases-list query-params)
@@ -831,8 +855,8 @@
: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` and other
- read_resource calls can be fed directly back here.
+ the instance and drill into specific entities. URIs returned by `search` can be fed directly
+ back here. Only numeric IDs accepted, never alphanumeric entity-id's.
Up to 5 URIs may be requested in one call. List responses are capped at 25 items per page.
When :truncated is true, append ?page=N to fetch the next page (e.g. metabase://database/1/tables?page=2).
diff --git a/src/metabase/metabot/tools/search.clj b/src/metabase/metabot/tools/search.clj
index f73b113e58b..af2a106f2ce 100644
--- a/src/metabase/metabot/tools/search.clj
+++ b/src/metabase/metabot/tools/search.clj
@@ -96,7 +96,7 @@
"Fetch and merge database engine + name info for search results that have database IDs.
`:database_name` is the human-readable name the LLM needs as the first slot of every
portable FK in `construct_notebook_query`; surfacing it on every table/model search
- result means the LLM doesn't need a separate `entity_details` round-trip just to learn
+ result means the LLM doesn't need a separate `read_resource` round-trip just to learn
the DB name."
[results]
(let [db-ids (->> results (keep :database_id) distinct)
@@ -113,7 +113,7 @@
"Attach `:portable_entity_id` (the card's `entity_id` NanoID) to saved-question, model,
and metric search results so the LLM can use it verbatim as `source-card:` (for
questions/models) or inside a `[metric, {}, <entity_id>]` aggregation clause (for
- metrics) without a follow-up `entity_details` / `read_resource` round-trip."
+ metrics) without a follow-up `read_resource` round-trip."
[results]
(let [carded-types #{"question" "model" "metric"}
card-ids (->> results
@@ -137,7 +137,7 @@
table's portable FK as the `source-table:` when it wants to use the metric. Without this
enrichment the LLM sees the metric's `portable_entity_id` in search but has to either
hallucinate the base table (observed failure mode: `[<db>, public, customers]`) or do an
- extra `entity_details` round-trip. We read the two columns directly from
+ extra `read_resource` round-trip. We read the two columns directly from
`report_card.table_id` + `metabase_table.{schema,name}` to keep the lookup O(1) extra
query per search call, regardless of number of metrics in the result set.
diff --git a/src/metabase/metabot/tools/shared/instructions.clj b/src/metabase/metabot/tools/shared/instructions.clj
index 6d767dcdf82..49c62d12ab4 100644
--- a/src/metabase/metabot/tools/shared/instructions.clj
+++ b/src/metabase/metabot/tools/shared/instructions.clj
@@ -13,6 +13,7 @@ When using results:
- **Be proactive with clear matches**: When the top result(s) have names or descriptions that clearly match the user's request, use them to achieve the users goal first, then list alternatives at the end. Don't ask for confirmation when there's an obvious best choice.
- **Collection metadata**: Results may include collection information (name, description, authority level) that can help you determine whether the result is relevant to the user's query. Use this context to assess relevance.
- **Present options for ambiguous results**: When search returns multiple plausible options without a clear best match, present them and ask the user to choose
+- **Drill in via the `uri` attribute**: To inspect a result's details, pass its `uri` attribute to `read_resource` (append `/fields` for a table/model/question's columns). URIs always use the numeric `id` — never put a `portable_entity_id` in a URI; that value belongs only in `construct_notebook_query` query text (`source-card:` and metric/measure/segment references)
- Reference results using the metabase protocol link format: [display name](metabase://type/id)
Examples: [Customer Metrics](metabase://metric/42), [Sales Dashboard](metabase://dashboard/158)")
diff --git a/src/metabase/metabot/tools/shared/llm_shape.clj b/src/metabase/metabot/tools/shared/llm_shape.clj
index 47fb68bce0d..992a3a495f1 100644
--- a/src/metabase/metabot/tools/shared/llm_shape.clj
+++ b/src/metabase/metabot/tools/shared/llm_shape.clj
@@ -400,7 +400,7 @@
"Format table for LLM consumption.
Matches Python Table.get_llm_representation exactly, except we additionally surface
`database_name` as a tag attribute so the LLM has the human-readable DB name available
- without a separate `entity_details` call — it's the first slot of every portable FK in
+ without a separate `read_resource` call — it's the first slot of every portable FK in
the representations-format `construct_notebook_query` tool."
[{:keys [id name database_id database_name database_engine database_schema
description fields related_tables related_tables_total
@@ -692,12 +692,27 @@
(clojure.core/name result-type)
"item")))
+(defn- search-result-uri-type
+ "Map a search-result type to the entity-type segment of its `read_resource` URI, or nil
+ when the type has no URI form (i.e. no dispatch clause in `metabot.tools.resources`)."
+ [result-type]
+ (let [t (some-> result-type clojure.core/name)]
+ (case t
+ ("model" "dataset") "model"
+ ("card" "question") "question"
+ ("database" "collection" "table" "metric"
+ "measure" "segment" "transform" "dashboard") t
+ nil)))
+
(defn search-result->xml
"Format a single search result as XML element.
+ Emits a `uri` attribute (the numeric-id `read_resource` URI) for every type that has a
+ URI form, so the LLM feeds it back verbatim instead of assembling URIs by hand — the
+ failure mode there is pasting the `portable_entity_id` NanoID into the id slot.
Includes database_id, database_engine, and fully_qualified_name for table/model results
to match Python AI Service search output. For saved-question and model results also
includes `portable_entity_id` so the LLM can paste it verbatim into `source-card:`
- without an extra `entity_details` call, and (when available) `database_name` — the
+ without an extra `read_resource` call, and (when available) `database_name` — the
human-readable name the LLM needs as the first slot of every portable FK in
`construct_notebook_query`.
@@ -705,7 +720,7 @@
`schema.table` of the table the metric aggregates). Combined with `database_name` this
gives the LLM the full portable FK `[database_name, schema, table]` it must put in
`source-table:` when using `[metric, {}, <portable_entity_id>]` as an aggregation —
- without a separate `entity_details` round-trip."
+ without a separate `read_resource` round-trip."
[{:keys [id type name description verified official curated data_authority data_layer collection
database_id database_name database_engine database_schema portable_entity_id
base_table_portable_fk]}]
@@ -726,6 +741,9 @@
:search_result
{:search_tag_name (search-result-tag-name type)
:search_id (str id)
+ :search_uri (when id
+ (when-let [uri-type (search-result-uri-type type)]
+ (metabase-uri uri-type id)))
:search_name name
:search_has_verified (some? verified)
:search_verified verified
diff --git a/src/metabase/models/serialization/resolve/mp.clj b/src/metabase/models/serialization/resolve/mp.clj
index 45eec8a3561..693ff05c361 100644
--- a/src/metabase/models/serialization/resolve/mp.clj
+++ b/src/metabase/models/serialization/resolve/mp.clj
@@ -118,10 +118,10 @@
candidates. Branching the wording on whether an inactive row exists would be an existence
oracle, so both get this identical message.
- The LLM can still self-correct in one turn by calling `entity_details` on the parent
- database; the message points it at that path."
+ The LLM can still self-correct in one turn by listing the parent database's tables with
+ `read_resource`; the message points it at that path."
[_metadata-provider [_path-db-name _path-schema _path-table-name :as path]]
- (ex-info (tru "No table found matching portable FK {0}. Call `entity_details` with entity-type `database` and the database''s numeric id to list available tables and schemas, then retry with an exact portable FK from the response."
+ (ex-info (tru "No table found matching portable FK {0}. Call `read_resource` with `metabase://database/<numeric id>/tables` to list available tables and schemas, then retry with an exact portable FK from the response."
(pr-str path))
{:status-code 400
:error :unknown-table
@@ -144,7 +144,7 @@
ids that don't exist as `metabase_database` rows, and the rare production case where the
provider's cache holds a table the app DB has fully dropped. In that last case the
provider's view becomes authoritative, since the alternative is a confusing `:unknown-table`
- raised for a table the caller can plainly see via `entity_details`."
+ raised for a table the caller can plainly see via `read_resource`."
[metadata-provider db-id schema table-name]
(if-let [app-db-rows (and db-id
(app-db-backed-provider? metadata-provider)
@@ -180,7 +180,7 @@
;; Deliberately do NOT enumerate the matching `[schema name id]` tuples — the metadata
;; provider is un-sandboxed, so a leaked candidate list could surface tables the caller
;; cannot otherwise see (parity with the `unknown-table-ex-info` strip above).
- (throw (ex-info (tru "Ambiguous portable table FK {0}: {1} candidates. Call `entity_details` with entity-type `database` to list available tables and retry with a more specific portable FK."
+ (throw (ex-info (tru "Ambiguous portable table FK {0}: {1} candidates. Call `read_resource` with `metabase://database/<numeric id>/tables` to list available tables and retry with a more specific portable FK."
(pr-str path) (count candidates))
{:status-code 400
:error :ambiguous-table
@@ -207,10 +207,10 @@
;; column name. The metadata provider is un-sandboxed, the `:agent-error?` flag
;; relays this message verbatim to the user, and a leaked FK-candidate path would
;; reveal table names the caller may not be permitted to see. The LLM can recover
- ;; by calling `entity_details` on the parent table to list its columns.
+ ;; by reading the parent table's fields with `read_resource`.
unknown-field-ex
(fn [segment]
- (ex-info (tru "No column {0} on table {1}.{2}.{3}. Call `entity_details` on this table to list its columns."
+ (ex-info (tru "No column {0} on table {1}.{2}.{3}. Call `read_resource` with `metabase://table/<numeric id>/fields` to list this table''s columns."
(pr-str segment) (pr-str db) (pr-str schema) (pr-str table-name))
{:status-code 400
:error :unknown-field
@@ -444,7 +444,7 @@
card-db-id (when card (or (:database-id card) (:database_id card)))]
(cond
(nil? card)
- (throw (ex-info (tru "No saved question or model found with entity_id {0}. Do not invent or guess entity_ids: call `entity_details` with `entity-type: question` or `entity-type: model` and the card''s numeric id first, then copy the exact `portable_entity_id` from the response into `source-card:`."
+ (throw (ex-info (tru "No saved question or model found with entity_id {0}. Do not invent or guess entity_ids: call `read_resource` with `metabase://question/<numeric id>` or `metabase://model/<numeric id>` first, then copy the exact `portable_entity_id` from the response into `source-card:`."
(pr-str entity-id))
{:agent-error? true
:status-code 400
@@ -480,7 +480,7 @@
current-db-id (:id (lib.metadata/database metadata-provider))]
(cond
(nil? measure)
- (throw (ex-info (tru "No measure found with entity_id {0}. Do not invent or guess entity_ids: call `entity_details` on the table that owns the measure and copy the exact `portable_entity_id` from the `<measure>` tag."
+ (throw (ex-info (tru "No measure found with entity_id {0}. Do not invent or guess entity_ids: read the table that owns the measure with `read_resource` (`metabase://table/<numeric id>`) and copy the exact `portable_entity_id` from its `<measure>` tag."
(pr-str entity-id))
{:agent-error? true
:status-code 400
@@ -579,7 +579,7 @@
current-db-id (:id (lib.metadata/database metadata-provider))]
(cond
(nil? segment)
- (throw (ex-info (tru "No segment found with entity_id {0}. Do not invent or guess entity_ids: call `entity_details` on the table that owns the segment and copy the exact `portable_entity_id` from the `<segment>` tag."
+ (throw (ex-info (tru "No segment found with entity_id {0}. Do not invent or guess entity_ids: read the table that owns the segment with `read_resource` (`metabase://table/<numeric id>`) and copy the exact `portable_entity_id` from its `<segment>` tag."
(pr-str entity-id))
{:agent-error? true
:status-code 400
diff --git a/test/metabase/metabot/tools/charts/edit_test.clj b/test/metabase/metabot/tools/charts/edit_test.clj
index d97e0ae2178..e770dbfa161 100644
--- a/test/metabase/metabot/tools/charts/edit_test.clj
+++ b/test/metabase/metabot/tools/charts/edit_test.clj
@@ -73,7 +73,7 @@
(tools.resources/read-resource-tool {:uris [table-fields-uri]})
;; Representations-format query: LLM-facing code should prefer the portable_fk path
- ;; over numeric field ids. Take them straight from the entity_details response.
+ ;; over numeric field ids. Take them straight from the read_resource response.
table-fk (:portable_fk table)
category-field-fk (some (fn [{:keys [display_name portable_fk]}]
(when (= "Category" display_name)
@@ -164,7 +164,7 @@
"example name) against the real `Sample Database` app DB. Per\n"
"`repr-plan.md` step 13 the YAML's `database:` is now strict - the lookup\n"
"fails fast with a clear `:agent-error?` message that nudges the LLM to\n"
- "use the canonical name from `entity_details`.")
+ "use the canonical name from search / `read_resource`.")
(mt/with-current-user (test.users/user->id :crowberto)
;; Verbatim the YAML the LLM produced in the bug report. Note: every portable FK uses
;; `Sample` (the prompt name), not `Sample Database` (the real one).
@@ -195,13 +195,13 @@
(is (re-find #"Sample" (:output result))
(str "error message should mention the offending DB name; got: "
(:output result)))
- (is (re-find #"entity_details|Unknown database" (:output result))
+ (is (re-find #"read_resource|Unknown database" (:output result))
(str "error message should hint at the recovery path; got: "
(:output result))))))))
(deftest construct-notebook-query-llm-uses-canonical-db-name-end-to-end-test
(testing (str "Symmetric to the previous test: the LLM writes `database: Sample Database`\n"
- "(the canonical name reported by `entity_details`) and the chart constructs\n"
+ "(the canonical name reported by search / `read_resource`) and the chart constructs\n"
"cleanly. This is the post-step-13 happy path the LLM should follow.")
(mt/with-current-user (test.users/user->id :crowberto)
(let [db-name (t2/select-one-fn :name :model/Database :id (mt/id))
@@ -239,7 +239,7 @@
"gets source-field auto-wired, produces a query that compiles to SQL with "
"a JOIN and executes successfully against the app DB.")
(mt/with-current-user (test.users/user->id :crowberto)
- (let [;; Discover portable FKs the same way the LLM does: via entity_details / fields.
+ (let [;; Discover portable FKs the same way the LLM does: via read_resource /fields.
{[{{orders-details :structured-output} :content}] :resources}
(tools.resources/read-resource-tool
{:uris [(str "metabase://table/" (mt/id :orders) "/fields")]})
@@ -277,7 +277,7 @@
query (get-in construct-result [:structured-output :query])
breakout-field (get-in query [:stages 0 :breakout 0])
field-opts (second breakout-field)]
- (testing "entity_details surfaced the FK target - sanity-check the inputs we fed in"
+ (testing "read_resource surfaced the FK target - sanity-check the inputs we fed in"
(is (= ["Product ID" "PRODUCTS"]
[(:display_name product-id-field)
(nth products-target-fk 2)])
diff --git a/test/metabase/metabot/tools/construct_representations_test.clj b/test/metabase/metabot/tools/construct_representations_test.clj
index 806889a5a72..9c1f0c55a40 100644
--- a/test/metabase/metabot/tools/construct_representations_test.clj
+++ b/test/metabase/metabot/tools/construct_representations_test.clj
@@ -217,7 +217,7 @@
"`source-table: [Sample, PUBLIC, ORDERS]` against an instance whose DB is named\n"
"`Sample Database`, the lookup fails fast with a clear `:unknown-database`\n"
"`:agent-error?`. The LLM gets a useful nudge in the error message; the prompt\n"
- "change to use the canonical name from `entity_details` is the real long-term fix.")
+ "change to use the canonical name from search / `read_resource` is the real long-term fix.")
;; This fixture's MP-name is "Sample Database". We DON'T stub `resolve-database-id-from-first-stage`
;; here - we want the actual function to run against `name = "Sample"` and observe the
;; not-found behaviour.
@@ -359,8 +359,8 @@
(is (= "metabase://metric/76" (:source-table d)))
(is (re-find #"aggregation" (ex-message e))
"message should point at aggregation-clause recovery")
- (is (re-find #"base_table_portable_fk" (ex-message e))
- "message should name the field the LLM needs to look up on the metric")))))
+ (is (re-find #"base_table_fully_qualified_name" (ex-message e))
+ "message should name the attribute the LLM needs to look up on the metric")))))
(testing "question / model URI - hint points at `source-card:`"
(doseq [t ["question" "model" "card"]]
(try
diff --git a/test/metabase/metabot/tools/resources_test.clj b/test/metabase/metabot/tools/resources_test.clj
index f894157343c..0f5d1cf8704 100644
--- a/test/metabase/metabot/tools/resources_test.clj
+++ b/test/metabase/metabot/tools/resources_test.clj
@@ -190,6 +190,33 @@
(is (thrown? Exception
(#'read-resource/dispatch "https://example.com")))))
+(deftest dispatch-rejects-non-numeric-id-test
+ (testing "a non-numeric id segment throws a directive error stating the numeric-id contract"
+ (is (thrown-with-msg? Exception #"URIs use the numeric entity id"
+ (#'read-resource/dispatch "metabase://model/VZbHZIeqQ2HhZv5r0pO6a")))
+ (is (thrown-with-msg? Exception #"URIs use the numeric entity id"
+ (#'read-resource/dispatch "metabase://model/VZbHZIeqQ2HhZv5r0pO6a/fields")))
+ (is (thrown-with-msg? Exception #"URIs use the numeric entity id"
+ (#'read-resource/dispatch "metabase://question/VZbHZIeqQ2HhZv5r0pO6a")))
+ (is (thrown-with-msg? Exception #"URIs use the numeric entity id"
+ (#'read-resource/dispatch "metabase://table/orders")))
+ (is (thrown-with-msg? Exception #"URIs use the numeric entity id"
+ (#'read-resource/dispatch "metabase://collection/root"))))
+ (testing "the error carries agent-error metadata"
+ (let [e (try
+ (#'read-resource/dispatch "metabase://model/VZbHZIeqQ2HhZv5r0pO6a")
+ (catch Exception e e))]
+ (is (= 400 (:status-code (ex-data e))))
+ (is (true? (:agent-error? (ex-data e))))))
+ (testing "the directive error text reaches read_resource output"
+ (let [{:keys [output]} (read-resource/read-resource {:uris ["metabase://model/VZbHZIeqQ2HhZv5r0pO6a/fields"]})]
+ (is (str/includes? output "URIs use the numeric entity id"))))
+ (testing "non-id segments are unaffected — schema names and field ids may be non-numeric"
+ (is (= ["database" "1" "schemas" "PUBLIC" "tables"]
+ (:segments (#'read-resource/parse-uri "metabase://database/1/schemas/PUBLIC/tables"))))
+ (is (nil? (#'read-resource/check-numeric-id-segment!
+ "metabase://table/3/fields/c75/17" ["table" "3" "fields" "c75" "17"])))))
+
(comment
(mt/with-current-user (mt/user->id :crowberto)
(read-resource/read-resource
diff --git a/test/metabase/metabot/tools/search_test.clj b/test/metabase/metabot/tools/search_test.clj
index 1141f4890c2..7d5d2a800cb 100644
--- a/test/metabase/metabot/tools/search_test.clj
+++ b/test/metabase/metabot/tools/search_test.clj
@@ -434,7 +434,7 @@
(is (= "No Description" (get-in no-desc-dash [:collection :name]))))))))))))
(deftest enrich-with-portable-entity-ids-test
- (testing "saved-question and model search results expose `portable_entity_id` (the card's NanoID)\nso the LLM can use it verbatim as `source-card:` without a follow-up entity_details call"
+ (testing "saved-question and model search results expose `portable_entity_id` (the card's NanoID)\nso the LLM can use it verbatim as `source-card:` without a follow-up read_resource call"
(mt/with-test-user :crowberto
(search.tu/with-temp-index-table
(mt/with-temp [:model/Card {q-id :id q-eid :entity_id} {:name "PortableEID Sample Question"
@@ -530,7 +530,7 @@
(deftest enrich-with-metric-base-tables-test
(testing (str "Metric search results carry `base_table_*` fields so the LLM can write\n"
- "`source-table:` without a separate entity_details call. We look up\n"
+ "`source-table:` without a separate read_resource call. We look up\n"
"`report_card.table_id` → `metabase_table.{schema,name}` and assemble the\n"
"portable FK `[database_name, schema, table_name]`. This closes the failure\n"
"mode where the LLM saw a metric in search, had its portable_entity_id, but\n"
diff --git a/test/metabase/metabot/tools/shared/llm_shape_test.clj b/test/metabase/metabot/tools/shared/llm_shape_test.clj
index 98356aa2c40..087b1448191 100644
--- a/test/metabase/metabot/tools/shared/llm_shape_test.clj
+++ b/test/metabase/metabot/tools/shared/llm_shape_test.clj
@@ -632,6 +632,25 @@
xml (llm-shape/search-result->xml result)]
(is (not (str/includes? xml "portable_entity_id"))))))
+(deftest ^:parallel search-result->xml-uri-test
+ (testing "search results carry a numeric-id read_resource uri attribute"
+ (are [result expected-uri] (str/includes? (llm-shape/search-result->xml result)
+ (str "uri=\"" expected-uri "\""))
+ {:id 133 :type "model" :name "Foundation MO"} "metabase://model/133"
+ {:id 11 :type :dataset :name "D"} "metabase://model/11"
+ {:id 5 :type "question" :name "Q"} "metabase://question/5"
+ {:id 13 :type :card :name "C"} "metabase://question/13"
+ {:id 7 :type :metric :name "M"} "metabase://metric/7"
+ {:id 9 :type "table" :name "T"} "metabase://table/9"
+ {:id 15 :type "dashboard" :name "Dash"} "metabase://dashboard/15"
+ {:id 17 :type "measure" :name "Meas"} "metabase://measure/17"
+ {:id 19 :type "segment" :name "Seg"} "metabase://segment/19"))
+ (testing "types without a read_resource URI form omit the uri attribute"
+ (is (not (str/includes? (llm-shape/search-result->xml {:id 3 :type "action" :name "A"})
+ "uri=")))
+ (is (not (str/includes? (llm-shape/search-result->xml {:id 3 :type nil :name "A"})
+ "uri=")))))
+
(deftest ^:parallel search-result->xml-test-9
(testing "non-table/model search results omit table-specific attributes"
(let [result {:id 50
diff --git a/test/metabase/metabot/tools/slackbot_query_test.clj b/test/metabase/metabot/tools/slackbot_query_test.clj
index f095153c3f4..4799e83cd50 100644
--- a/test/metabase/metabot/tools/slackbot_query_test.clj
+++ b/test/metabase/metabot/tools/slackbot_query_test.clj
@@ -163,7 +163,7 @@
"no stack trace, no data-parts.")
(with-repr-stub!
(fn [_external-query]
- (throw (ex-info "Unknown database: `Sample`. Use the exact database name as reported by entity_details."
+ (throw (ex-info "Unknown database: `Sample`. Use the exact database name as reported by search / read_resource."
{:agent-error? true
:status-code 400
:error :unknown-database
diff --git a/test/metabase/models/serialization/resolve/mp_test.clj b/test/metabase/models/serialization/resolve/mp_test.clj
index 516b5135709..90cfd735cca 100644
--- a/test/metabase/models/serialization/resolve/mp_test.clj
+++ b/test/metabase/models/serialization/resolve/mp_test.clj
@@ -121,7 +121,7 @@
(deftest import-table-fk-cache-collision-test
(testing "two real tables sharing a name across schemas: app-DB-backed resolver must not drop either"
;; Reproduces a production failure where `query` / `construct_query` returned
- ;; `:unknown-table` for a portable FK that `entity_details` had just emitted, then
+ ;; `:unknown-table` for a portable FK that a metadata read had just emitted, then
;; verifies the fix.
;;
;; Production wraps every `application-database-metadata-provider` with
@@ -162,7 +162,7 @@
(is (= :unknown-table (:error d)))
(is (= 400 (:status-code d)))
(is (true? (:agent-error? d)))
- (is (re-find #"entity_details" msg) "message points the LLM at entity_details to re-list")
+ (is (re-find #"read_resource" msg) "message points the LLM at read_resource to re-list")
(testing "inactive-row miss is indistinguishable from a never-existed miss (no oracle)"
(let [never-existed (try (resolve/import-table-fk r [(:name db) "PUBLIC" "never_existed_xyz"])
(catch clojure.lang.ExceptionInfo e2 (.getMessage e2)))]
@@ -228,8 +228,8 @@
(testing "ex-data carries only the rejected path — no candidates / schemas"
(is (nil? (:candidates d)))
(is (nil? (:available-schemas d))))
- (testing "message points the LLM at entity_details for self-correction"
- (is (re-find #"entity_details" msg)))))))))
+ (testing "message points the LLM at read_resource for self-correction"
+ (is (re-find #"read_resource" msg)))))))))
(deftest ^:parallel import-table-fk-error-test-2
(testing "schema does not exist in DB → still :unknown-table, no schema enumeration"