Clarify generated UI mutation state guidance

Author: RhysSullivan

packages/core/execution/src/description.ts

@@ -68,6 +68,9 @@ const formatDescription = (sources: readonly Source[]): string => {
     "- Fetch live data with TanStack options from the tool proxy: `useQuery(tools.<namespace>.<tool>.queryOptions(args))`. Do not call tools before generating the UI and paste returned data into JSX.",
     "- For user-triggered writes or actions, use `useMutation(tools.<namespace>.<tool>.mutationOptions({ onSuccess }))` and call `mutate(input)` from event handlers.",
     "- Invalidate or refetch reads with `useQueryClient()` and stable keys from `tools.<namespace>.<tool>.queryKey(args)`.",
+    "- Use the discovered output shape exactly. Do not invent wrapper fields like `data.domain` or `data.items` unless the schema/sample shows them.",
+    "- For toggles and switches, mutate with the checked value from the event instead of inverting possibly stale query data.",
+    "- For optimistic writes, use TanStack `onMutate` / `onError` / `onSettled`: cancel the query, snapshot old data, `setQueryData`, roll back on error, then invalidate.",
     "- Only hardcode small display constants like labels, colors, tab names, and chart configuration. Never embed tool response rows, API results, summaries, or dashboard data as literals in the component.",
     "- Always render loading and error states from `useQuery` / `useMutation`; do not replace them with hardcoded fallback data.",
     "- Tools: `tools.<namespace>.<tool>(args)` — call any configured API tool (never use raw `fetch`). Tool helpers: `.queryOptions(args, options)`, `.mutationOptions(options)`, `.queryKey(args)`, `.pathKey()`, and `.mutationKey()`.",

packages/hosts/mcp/src/server.test.ts

@@ -247,6 +247,8 @@ describe("MCP host server — client with elicitation", () => {
         expect(renderUi?.description).toContain(
           "useQuery(tools.<namespace>.<tool>.queryOptions(args))",
         );
+        expect(renderUi?.description).toContain("Use discovered result shapes exactly");
+        expect(renderUi?.description).toContain("For optimistic UI, use `onMutate`");
         expect(renderUi?.description).toContain("Do not call API tools first");
         expect(renderUi?.description).toContain("server rejects obvious hardcoded live-data");
         expect(renderUi?.description).toContain("- `axiom_mcp`");

packages/plugins/dynamic-ui/src/mcp.ts

@@ -78,6 +78,9 @@ export const buildRenderUiDescription = (executeDescription: string): string =>
       "- Fetch live data with TanStack options from the tool proxy: `useQuery(tools.<namespace>.<tool>.queryOptions(args))`.",
       "- For user-triggered writes, use `useMutation(tools.<namespace>.<tool>.mutationOptions({ onSuccess }))` and call `mutate(input)` from event handlers.",
       "- Invalidate or refetch reads with `useQueryClient()` and stable keys from `tools.<namespace>.<tool>.queryKey(args)`.",
+      "- Use the discovered output shape exactly. Do not invent wrapper fields like `data.domain` or `data.items` unless the schema/sample shows them.",
+      "- For toggles and switches, mutate with the checked value from the event instead of inverting possibly stale query data.",
+      "- For optimistic writes, use TanStack `onMutate` / `onError` / `onSettled`: cancel the query, snapshot old data, `setQueryData`, roll back on error, then invalidate.",
       "- Only hardcode small display constants like labels, colors, tab names, and chart configuration. Never embed tool response rows, API results, summaries, or dashboard data as literals in the component.",
       "- Always render loading and error states from `useQuery` / `useMutation`; do not replace them with hardcoded fallback data.",
       `- shadcn/ui components available by name: ${SHADCN_COMPONENTS}`,
@@ -103,8 +106,17 @@ export const buildRenderUiDescription = (executeDescription: string): string =>
     "- `render-ui` is for the final interactive surface. Do not paste discovery results into JSX as literal rows, cards, summaries, metrics, or chart series.",
     "- After discovering an API call with `execute`, put the same call in TanStack Query options inside the generated component.",
     "- Example discovery: call `execute` with `return await tools.axiom_mcp.querydataset({ ... })` to confirm columns, then call `render-ui` with `useQuery(tools.axiom_mcp.querydataset.queryOptions({ ... }))`.",
+    "- Use discovered result shapes exactly. If a sample or schema returns `{ renew, expiresAt }`, read `data?.renew`, not `data?.domain?.renew`.",
     "- Keep discovery small. Use limits, narrow time ranges, or schema/list tools when possible.",
     "",
+    "## TanStack Query State",
+    "",
+    "- Use `const queryClient = useQueryClient()` when a mutation changes data shown by a query.",
+    "- For simple writes, invalidate with `queryClient.invalidateQueries(tools.<namespace>.<queryTool>.queryFilter(args))` in `onSuccess` or `onSettled`.",
+    "- For toggles and switches, pass the new checked value into `mutate`: `onCheckedChange={(checked) => mutation.mutate({ body: { enabled: checked } })}`.",
+    "- For optimistic UI, use `onMutate` to `cancelQueries`, snapshot `getQueryData`, and `setQueryData`; return the snapshot, restore it in `onError`, and invalidate in `onSettled`.",
+    "- Do not show success text by combining `mutation.isSuccess` with stale query data. Either update the query cache optimistically or show a neutral saved state after invalidation.",
+    "",
     "## Available UI Components",
     "",
     `- shadcn/ui components available by name: ${SHADCN_COMPONENTS}`,