Codex Tool Reference

Before rendering a report or dashboard artifact, call validate_artifact with the complete manifest and bounded snapshot. Fix validation errors there first; do not use render_artifact as an iterative validator because failed render attempts can create visible placeholder cards. After validation passes outside Work Mode, use render_artifact to host the complete Data Analytics dashboard or report manifest with a bounded snapshot inside the MCP app; this is the default reader handoff outside Work Mode and should be attempted before static HTML, localhost, or file:// delivery. When mode = work_mode is positively identified, regardless of surface, do not call render_artifact, render_chart, or render_table to deliver visuals or reports; the trusted Work Mode rendering path may drop standalone plugin widgets that lack appContext. Preserve the delivery mode already selected by the owning workflow. For already-selected inline visuals with exactly one supported bar, line, pie, or scatter chart, treat charts_widget_v2 as directly surfaced and emit its live genui content reference before fallback; use the outer shape genui "area"  without Markdown backticks, not standalone assistant text; do not self-declare it unavailable, search for it, or print its payload as bare JSON. Keep app_block conditional on the host surfacing it for a richer composition. For a durable report or dashboard in Work Mode, publish the validated artifact through Sites when the full Sites building and hosting lifecycle is callable, with HTML as the automatic fallback. Use image-based/static charting only after an emitted native reference is rejected or fails to render, or when no suitable native renderer exists; then use a compact table or other non-MCP fallback only when no visual renderer can be delivered. Use image-based/static charting for that native-render failure fallback or when the user explicitly requests Python, a static image/file, notebook-oriented output, or export. Do not say a visual rendered above unless the selected non-MCP or native Work Mode surface actually rendered. Artifact snapshots must be bounded: at most 50 datasets, 2,000 rows per dataset, 3MB total payload, and 200k total inline source characters. Use the canonical artifact snapshot shape: snapshot.datasets is an object keyed by dataset id, and each value is a plain array of row objects like  null; . Do not put  null; metric_definitions?: unknown; sql?: string  objects inside artifact snapshot datasets; table-shaped dataset objects are rejected. Use snapshot.accessIssues only when required report/dashboard data is missing and the snapshot status is partial or blocked. Do not use accessIssues for optional source limitations, denied exploratory joins, methodology caveats, or provenance notes when the artifact is otherwise ready; put those in manifest sources or markdown body blocks instead. All artifacts must declare a reader-facing manifest.title plus top-level manifest.blocks. Cards, charts, and tables define reusable renderable assets; blocks establish the artifact reading order. Report artifacts must include at least one chart data visualization block and a first markdown block whose body is a # heading matching manifest.title. Give each independently editable major report section its own markdown block. Do not put multiple peer ## headings in one markdown body; reserve ### headings for subordinate content that should remain in the same card. One headline metric does not mean one metrics[] entry: keep short, directly relevant directional comparisons as later labeled badge metrics, especially when the same comparison appears in the executive summary or findings. Native artifact charts must use encodings.x.field plus encodings.y.field or encodings.y.fields, with optional encodings.color.field for grouped tidy data. Legacy manifest chart fields xField and series are rejected; use validate_artifact to check chart shape before rendering. Give each native artifact table a defaultSort with a declared column field and asc or desc direction chosen to make the initial row order describe the data clearly. When a validated MCP artifact report or dashboard needs a hosted Sites link, call export_artifact_package and deploy that package instead of hand-rolling standalone HTML. In ChatGPT Desktop outside Work Mode, render the MCP artifact first and publish to Sites only after the user explicitly requests or accepts the optional coworker-sharing follow-up. The exporter preserves the real artifact runtime and serves /api/manifest, /api/snapshot, /api/package, /api/presentation, /api/source-file, and /api/inline-chart-widget, with db/schema.ts when presentation editing is enabled. Use render_chart after a Data Analytics workflow has already produced a small, shareable source query result. Pass source, table, chart, and display for chart widgets. Default every chart title to a neutral, descriptive label that identifies what is plotted, such as the metric, comparison, dimension, or time scope. Do not infer a narrative takeaway, claim, clever headline, or new jargon for the title unless the user explicitly requests one. Chart subtitles should add a reader-facing insight or takeaway not already covered by the title. Do not use subtitles for source names, query ids, table names, SQL intent, metric definitions, or provenance; put those details in source.query/source metadata instead. For chart widgets, make table exploration-ready: include useful dimensions, measures, time columns, and grouping columns returned by the reviewed query, not only the plotted chart fields. For scatter widgets, prefer one row per meaningful observation rather than a few broad aggregates, with a stable point label, numeric x and y measures at the same grain, denominator or sample-size fields, one volume/size candidate, and one interpretable grouping or filter field when safe. Treat by  in a chart title, subtitle, or visible header as an encoding contract. An x/y axis dimension already satisfies that contract. If  is not on an axis and is not otherwise visibly encoded through color/series, grouped or stacked marks, faceting, or direct labels, remove by  from the visible text. For render_chart, a time or category x-axis chart titled ... by segment or ... by market must bind that second dimension through chart.fields.color.field or an equivalent visible grouping rather than only retaining it in the source table. When a grouped chart uses color, series, grouped, stacked, or faceted behavior, make the group names visible with a legend or direct labels. Only set chart.fields.color.field when it is a meaningful grouping dimension such as segment, product_line, or series; omit color for single-series charts. For trend charts, chart.fields.lineStyle.field may point to a text column with solid, dashed, or dotted values so grouped lines and their legends use different stroke styles. Use chart.type "bar" plus chart.options.orientation and chart.options.grouping for bar-family charts. Prefer tidy long rows, keep the payload compact, set row_count and truncated when sampling, and order sampled rows deterministically. After running a durable query, use render_table to show a compact preview of reviewed rows before or alongside interpretation. Source SQL belongs in source.query.sql and must be runnable SQL, not prose. Put the human-readable query summary in source.query.description. Source metadata should name actual tables such as example.analytics.fact_revenue, and metric definitions should state calculations, windows, units, denominators, and material exclusions. Include reviewed analytical dimensions such as customer, account, company, segment, and product names when relevant. Do not send hidden reasoning, credentials, secrets, or direct personal contact/payment identifiers to widgets.

Render a compact Data Analytics chart from already-reviewed provenance and table data. Pass source.query.sql with the actual SQL used to produce the chart table, plus source.query.description for the human-readable query summary, an exploration-ready table, chart, and display. Do not call this tool for inline visual delivery whenever mode = work_mode is positively identified, regardless of surface; for an already-selected inline visual with exactly one supported bar, line, pie, or scatter chart, treat charts_widget_v2 as directly surfaced and emit its live genui content reference before fallback; use the outer shape genui null; engine?: string  without Markdown backticks, not standalone assistant text; do not self-declare it unavailable, search for it, or print its payload as bare JSON. Keep app_block conditional on the host surfacing it for a richer composition. Use image-based/static charting only after an emitted native reference is rejected or fails to render, or when no suitable native renderer exists, with a compact table or other non-MCP fallback only when no visual renderer can be delivered. Use image-based/static charting for that native-render failure fallback or when the user explicitly requests Python, a static image/file, notebook-oriented output, or export. A successful tool result is not delivery confirmation in that runtime. Default the title to a neutral, descriptive label that identifies what is plotted, such as the metric, comparison, dimension, or time scope. Do not infer a narrative takeaway, claim, clever headline, or new jargon unless the user explicitly requests a takeaway-led title. Use the subtitle for a reader-facing insight or takeaway not covered by the title, not for source names, query ids, table names, SQL intent, metric definitions, or provenance. The table should retain useful dimensions, measures, time columns, and grouping columns so users can change chart fields in the expanded widget. Only pass chart.fields.color.field for meaningful grouping dimensions like segment, product_line, or series; omit it for single-series charts. For scatter charts, prefer one row per meaningful observation rather than a few broad aggregates; retain a stable point label, numeric x and y measures at the same grain, denominator or sample-size fields, one volume/size candidate, and one interpretable grouping or filter field when safe. Treat by  in a visible chart title, subtitle, or header as an encoding contract: if that dimension is not on an x/y axis, visibly encode it through chart.fields.color.field or equivalent grouped, stacked, faceted, or direct-label behavior; when grouped, show a legend or direct labels. For line, area, stackedArea, and sparkline charts, chart.fields.lineStyle.field can reference a column with solid, dashed, or dotted values. Use chart.type "bar" plus chart.options.orientation and chart.options.grouping for bar-family charts. This tool is part of plugin `Data Analytics`.

exec tool declaration:
```ts
declare const tools: { mcp__dataAnalyticsWidgets__render_chart(args: { chart:  columns?: Array; row_count?: number ; display?: 💬; source:  null; id?: string ; subtitle?: string | null; table:  null; [key: string]: unknown; ; title: string; }): Promise; };
```