Add native vector chart
add_chartIdempotent
Create a single-page PDF containing a native vector chart from series data, with bar, line, area, scatter, pie or donut types plus axes, legends, labels and print options.
Instructions
Single-page PDF with a native vector chart (pure path operators, no raster): bar, barH, stackedBar, stackedBarH, line (markers), area, scatter, pie, donut. Multi-series, legends, 'nice' ticks, gridlines, negatives; per-series xValues with xAxis.type 'linear' | 'time' (ISO-8601), secondary right axis (axis2 + yAxis:'right'), axis.scale 'log', dataLabels, labelStride / labelRotation. Pie/donut take exactly one series. Colours: hex ('#3366cc'), 'C M Y K' / [c, m, y, k] under a print intent, { spot, tint } / { inks } declared in print.spotColours; series[].colors gives one colour per value on the bar family (its length must equal values.length on every chart type — CHART_ERROR otherwise). Tagged /Figure + /Alt (auto when altText is omitted). Engine cross-field rules surface as CHART_ERROR with the remedy. Inside a longer document use a 'chart' block in generate_basic_pdf. PDF/A (pdfA + embedFonts:true), print, metadata and creationDate as on every document tool.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| axis | No | Value-axis options (bar/line only). | |
| pdfA | No | PDF/A level: pdfa1b (simple text+images), pdfa2b/pdfa2u (richer; 2u = Unicode mapping), pdfa3b (attachments / Factur-X). Pair with embedFonts=true for a valid claim. Exclusive with encryption. See docs/guides/PDFA.md. | |
| pdfx | No | PDF/X-4 print exchange (ISO 15930-7). REQUIRES outputIntent with the printer's ICC profile (device class 'prtr'; CMYK or Gray — none is bundled); needs embedFonts:true for a conformant file (PDFX_NO_FONT_ENTRIES otherwise, strict:true refuses). Combines with pdfA:'pdfa2b' | 'pdfa2u' (dual claim) but not pdfa1b / pdfa3b; exclusive with encrypt; metadata.trapped must be 'True' or 'False'; TrimBox or ArtBox, not both. Links and form fields are reported (PDFX_ANNOTATIONS). Check with validate_pdf standard:'pdf-x-4'. See the print_ready prompt. | |
| align | No | Horizontal alignment within the content width. Default 'left'. | |
| axis2 | No | Secondary RIGHT value axis (drawn only when a series sets yAxis:'right'). | |
| debug | No | Draw margin / block / cell guide rectangles (unmarked content — not for PDF/UA output). Geometry unchanged. Default false. | |
| intro | No | Optional introductory paragraph rendered above the chart. The chart `title` (if any) is also used as the PDF metadata title. | |
| No | Print production (ISO 32000-1 §14.11): page boxes, `bleed` shorthand (TrimBox = MediaBox inset), crop/registration marks outside the TrimBox, /UserUnit for large formats (PDF 1.7; not under pdfa1b), `spotColours` ink declarations. See docs/guides/PRINT.md. | ||
| title | No | Chart title rendered above the plot. | |
| width | No | Plot width in points (clamped to content width). Default 460. | |
| xAxis | No | Horizontal axis. 'category' (default) positions points by index; 'linear' / 'time' position them by series xValues (line/area/scatter only). Time ticks are UTC-deterministic. | |
| colors | No | Palette override (per-series for bar/line, per-slice for pie/donut). | |
| height | No | Plot-area height in points. Default 240. | |
| legend | No | Legend placement. Defaults to 'bottom' for multi-series/pie, else 'none'. | |
| series | Yes | Data series. Pie/donut charts use exactly one series (each value becomes a slice). | |
| strict | No | Fail instead of producing a file the engine warns about: a PDFA_* diagnostic → PDF_A_COMPLIANCE_VIOLATION (e.g. PDFA_NO_FONT_ENTRIES without embedFonts), a PDFX_* one → PDF_X_COMPLIANCE_VIOLATION, any other (TYPOGRAPHY_FEATURE_INEFFECTIVE, TEXT_GLYPH_NOT_COVERED — a character no font covers, drawn as a box or '?') → DIAGNOSTIC_ESCALATED. Pair with embedFonts=true. | |
| altText | No | Alt text for the tagged-PDF /Figure /Alt. Auto-generated when omitted. | |
| encrypt | No | Encrypt at build time (AES-128 default / AES-256) and KEEP the AcroForm — unlike encrypt_pdf, which rebuilds the page tree. Exclusive with pdfA. Randomised output, never cached. | |
| margins | No | Margins in points, all four required (0–200). Default 45 / 36 / 35 / 36. | |
| markers | No | Draw point markers on line series. Default false. | |
| compress | No | FlateDecode the streams (smaller file, different bytes; PDF/A unaffected, XMP stays plain). Default false. | |
| metadata | No | /Info (+ XMP under PDF/A): author, subject, keywords, /Trapped. | |
| pageSize | No | Portrait page preset (points): A4 595.28×841.89 (default), Letter 612×792, Legal 612×1008, A3 841.89×1190.55, Tabloid 792×1224. print.* boxes must fit it. | |
| chartType | Yes | Chart kind. 'pie'/'donut' use exactly one series; 'bar'/'barH'/'stackedBar'/'stackedBarH'/'line'/'area'/'scatter' support multiple series. 'scatter' requires xValues on every series and a positional xAxis.type ('linear' or 'time'). | |
| direction | No | Base text direction (UAX #9): 'auto' reads each paragraph's first strong character and right-aligns RTL ones; 'ltr' / 'rtl' force it. A paragraph's own direction overrides it. Omitted = LTR (1.7.0 bytes). | |
| actualText | No | Untagged output: wrap reordered shaped runs and RTL runs in /ActualText so extract_text returns reading order. Default true; false = bare 1.7.0 glyph runs. No effect on tagged (pdfA) output. | |
| categories | No | Category / slice labels (x-axis). Defaults to 1-based indices when omitted. | |
| dataLabels | No | Per-point value labels: true for defaults, or an object to format them. | |
| embedFonts | No | Embed Noto Sans Latin instead of the viewer base-14 Helvetica. REQUIRED for a valid PDF/A or PDF/X claim (every font embedded) and for strict=true; adds ~0.3 MiB. | |
| outputMode | No | Either 'base64' (returns the PDF inline) or 'file' (writes into the PDFNATIVE_MCP_OUTPUT_DIR sandbox). | base64 |
| outputPath | No | Required when outputMode='file'. Relative path inside the sandbox; must end with .pdf. | |
| typography | No | Fine typography, all opt-in (omitted = unchanged bytes). kerning and fontFeatures need embedFonts:true ('fr' works on base-14 too). No hyphenation dictionary is installed: use soft hyphens (U+00AD). See the typography prompt. | |
| labelStride | No | Draw every Nth category label. Default: automatic (measured non-overlap); 1 draws every label. | |
| creationDate | No | ISO-8601 instant for /CreationDate (+ XMP, the trailer /ID and the {date} placeholder), written in UTC. Pin it for byte-identical output across calls and hosts; omitted = wall clock, so every call differs. | |
| outputIntent | No | Custom OutputIntent (under pdfA or pdfx): an RGB, CMYK or Gray ICC profile + condition strings, replacing the built-in sRGB intent. The profile must be a real ICC file ('acsp' signature, consistent size — PRINT_ERROR otherwise); pdfx needs device class 'prtr'. Under a CMYK / Gray intent RGB content is mapped through a calibrated default space. | |
| labelRotation | No | Rotate category labels counter-clockwise by this many degrees (disables the automatic stride). | |
| footerTemplate | No | Running footer on every page. Replaces the default footer: footerText is then ignored and page numbers appear only via {page}/{pages}. | |
| headerTemplate | No | Running header on every page (left / center / right zones); reserves 15 pt. | |
| includeDiagnostics | No | Return the diagnostics raised while building (PDFA_*, PDFX_*, TYPOGRAPHY_*, TEXT_GLYPH_NOT_COVERED) as `diagnostics[]` (possibly empty). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Public URL of the file (file mode, only when PDFNATIVE_MCP_OUTPUT_BASE_URL is set): base URL + sandbox-relative path, percent-encoded. | |
| mode | Yes | ||
| summary | No | Tool-specific summary, when produced. | |
| filePath | No | Sandboxed absolute path (file mode). | |
| sizeBytes | Yes | ||
| diagnostics | No | Engine diagnostics (when includeDiagnostics=true). |