AshAi.Tool.ResultMeta behaviour (ash_ai v1.5.6)

Copy Markdown View Source

Computes per-call _meta for a tool's MCP tools/call result.

Hosts hand a result's _meta to the tool's view (an MCP Apps ui:// resource, or an OpenAI Apps SDK component) and keep it out of the model's context, so it is the place for data only the view needs: chart specs, row ids, pre-rendered labels. Set it with the result_meta tool option, as a module implementing this behaviour (or {module, opts}), or as a function taking the result and an AshAi.Tool.ResultMeta.Context:

tools do
  tool :fund_development, MyApp.Reports.FundDevelopment, :development,
    ui: :charts,
    result_meta: &MyAppWeb.McpViews.fund_development/2
end

def fund_development(%Development{} = development, _context) do
  %{"com.example/charts" => [%{"title" => "Development", "spec" => vega_lite_spec(development)}]}
end

result is what the action returned, before serialization: a record or a list of records, an Ash.Page.Offset or Ash.Page.Keyset for a paginated read (a default read action is one), a count or aggregate value for a read called with a result_type, or a generic action's return value.

Return a map, or nil to add nothing. Name its keys with a prefix you own, such as "com.example/charts". The map is deep-merged over the tool's static _meta, winning on conflicts. tools/list is unaffected.

The callback runs only after a successful call. If it raises, or returns anything other than nil or a JSON-encodable map, the error is logged and the result is sent without it: the action has already run, and an error result would invite the model to run it again.

Only MCP tools/call results carry it; tool loops don't call it.

Summary

Callbacks

Returns the _meta entries for one call's result, or nil for none.

Callbacks

result_meta(result, opts, context)

@callback result_meta(
  result :: term(),
  opts :: Keyword.t(),
  context :: AshAi.Tool.ResultMeta.Context.t()
) ::
  map() | nil

Returns the _meta entries for one call's result, or nil for none.