POST /api/agent/v2/construct-query

Request body for /v2/construct-query and the fresh-query branch of /v2/query. A single :query key whose value is a JSON object matching [[metabase.lib.schema/external-query]] — the canonical portable MBQL 5 wire format. The query is fully self-describing: the database is derived from the first stage's source-table: or source-card:, all field references are portable FKs ([<db-name>, <schema>, <table-name>, <column-name>]), and there is no auxiliary source_entity / referenced_entities envelope. See resources/metabot/prompts/tools/construct_notebook_query.md for the full format reference (including operators, joins, expressions, multi-stage queries, and FK conventions).

Closed map: any extra top-level keys (notably the legacy source_entity / referenced_entities envelope from before the repr migration) are dropped during request decoding, so a caller still sending the old shape is served.

The inner :query value is an opaque, string-keyed JSON object ([[ms/OpaqueJSONObject]]) at this boundary rather than ::lib.schema/external-query. Being open matters: a closed map with no declared entries would have every key stripped before the handler saw it. Reasons for not naming the real schema:

1. Deep MBQL-shape validation runs inside the representations pipeline (metabot.tools.construct/execute-representations-query calls repr/validate-query after the repair pass), so the boundary check would be redundant.

2. The strict-tool manifest lint (assert-optional-fields-nullable!) walks every map reachable from the tool input schema. ::external-query references ::query, which carries several :optional keys (:lib/metadata, :database, :settings, …) that are not [:maybe ...] — for sound reasons unrelated to this endpoint. Recursing into them would force a wide schema change just to satisfy the lint at the agent boundary.

Response containing a base64-encoded MBQL query for use with /v1/execute. The optional :prompt echoes the request's prompt back so the MCP layer can store it with the handle (see metabase.mcp.tools/make-store-construct-query-result).