office

name: office description: 'Use Office integration to read, create, edit, and convert Word/Excel/PowerPoint/PDF documents, and to render charts. Use whenever the user asks about working with .docx, .xlsx, .pptx, or .pdf files — reading content, creating reports or invoices, editing existing documents, converting between formats, merging or splitting PDFs, or rendering charts. Use even when you think you know the answer — document libraries change between framework versions; only the live tool reflects current Office/PDF format support and chart rendering capabilities. Do not use for: plain text files (read them directly), generic Markdown conversion that does not need PDF output (use built-in tools), or installing document-processing libraries — they are already behind office__* tools.' user-invocable: false allowed-tools: mcp__speedwave-hub__search_tools mcp__speedwave-hub__execute_code

Office Documents

Access office capabilities via search_tools + execute_code. The office global is injected automatically — no imports. All office__* tools are invoked as await office.<toolName>({ … }) inside execute_code. The worker is egress-less and credential-free; it processes files from /workspace only.

NEVER run pip install python-docx, pip install openpyxl, pip install python-pptx, pip install pypdf, pip install weasyprint, pip install matplotlib, npm install xlsx, apt install libreoffice, or any equivalent. Those libraries are already wired behind the office__* tools, and the Claude container cannot install packages at runtime anyway.

Workflow

1. search_tools({ query: "office <keyword>", detail_level: "names_only" }) — discover available tools
2. search_tools({ query: "office__<toolName>", detail_level: "full_schema" }) — get exact parameter schema
3. execute_code — call with dot notation (await office.toolName(…))

Three roads to PDF

htmlToPdf and markdownToPdf only fetch file:// URLs under /workspace. Strip remote <img> tags or pre-download assets — any non-file:// URL or path outside /workspace causes the conversion to fail.

convertOffice matrix

Pairs outside this matrix return an error. For .pdf → .docx: use readDocument (returns Markdown), then createDocx from that Markdown.

DSL: createDocx elements

The spec.elements[] array is a JSON tree — not free-form Markdown:

{ "type": "heading", "level": 1, "text": "Title" }                       // level 1..6
{ "type": "paragraph", "text": "Body…", "bold": false, "italic": false }
{ "type": "table", "header": ["A","B"], "rows": [["1","2"],["3","4"]] }
{ "type": "image", "path": "/workspace/.speedwave/office/chart.png" }
{ "type": "pagebreak" }

Charts in .docx are images, not native chart objects (python-docx limitation). Render with office__renderChart first, then embed the PNG via { "type": "image", … }.

DSL: createXlsx sheets and createPptx slides

Xlsx — charts ARE native (openpyxl). type ∈ bar | line | pie | scatter:

{
  "name": "Sales",
  "rows": [
    ["Quarter", "Revenue"],
    ["Q1", 100],
    ["Q2", 150],
  ],
  "freeze": "A2",
  "charts": [
    {
      "type": "bar",
      "title": "Revenue",
      "dataRange": "Sales!B2:B3",
      "categoriesRange": "Sales!A2:A3",
      "anchor": "D2",
    },
  ],
}

Pptx — charts ARE native (python-pptx). chart.type ∈ column | line | pie | xy | bubble:

{
  "title": "Q1 Results",
  "bullets": ["Revenue up 12%", "Two new clients"],
  "chart": {
    "type": "column",
    "categories": ["Q1", "Q2"],
    "series": [{ "name": "Revenue", "values": [100, 150] }],
    "title": "Quarterly Revenue",
  },
}

DSL: renderChart spec

renderChart uses a custom JSON schema — NOT matplotlib. type ∈ bar | line | pie | scatter | area. format ∈ png | svg. series.values.length MUST equal labels.length:

{
  "type": "bar",
  "title": "Revenue 2025",
  "xlabel": "Quarter",
  "ylabel": "Revenue (k€)",
  "format": "png",
  "data": {
    "labels": ["Q1", "Q2", "Q3", "Q4"],
    "series": [{ "name": "2025", "values": [100, 150, 120, 180] }],
  },
}

Pitfalls

• /workspace confinement — inputs and outputs must be under /workspace. Default output dir is /workspace/.speedwave/office/; use outName to pin the filename.
• Overwrite gate — existing files are not replaced by default. Pass overwrite: true only when the user explicitly asks to replace.
• Limits — 50 MB input cap; 2 000-page PDF cap.
• No macros / active content — scripts, VBA, and embedded OLE objects are stripped.
• No internet — the worker runs egress-less; no remote assets in HTML/Markdown.
• Write/delete confirmation — follow the global write/delete confirmation rule from CLAUDE.md.