Word Documents

When to Use

| Tool | Use When | |------|----------| | create_word_document | User asks to create/generate a NEW Word document | | modify_word_document | User asks to edit/update an EXISTING document or add content | | list_my_word_documents | User asks what documents are available | | read_word_document | User wants to download a document or read its comments | | preview_word_page | Check actual page appearance (charts, images, complex layouts) |

Workflow

Before modifying: call preview_word_page to check current layout.
After creation/modification: call preview_word_page to verify.
Run tools sequentially (never parallel) to prevent file race conditions.

Page Setup

python-docx defaults to A4. For US Letter size:

from docx.shared import Inches
section = doc.sections[0]
section.page_width = Inches(8.5)
section.page_height = Inches(11)
# Set 1-inch margins
section.top_margin = Inches(1)
section.bottom_margin = Inches(1)
section.left_margin = Inches(1)
section.right_margin = Inches(1)

Professional Formatting

Font: Arial as default. Set via style.font.name = 'Arial'.
Headings: Use proper heading styles for TOC compatibility: doc.add_heading('Title', level=1) or doc.add_paragraph(style='Heading 1').
Bullet lists: doc.add_paragraph(style='List Bullet'). NEVER insert unicode bullet characters.
Numbered lists: doc.add_paragraph(style='List Number').
Always preserve existing styles, fonts, and colors when modifying.

Images

from docx.shared import Inches
paragraph = doc.add_paragraph()
run = paragraph.add_run()
run.add_picture('file.png', width=Inches(6))

Code Rules

The document is pre-initialized as doc = Document() (create) or loaded as doc (modify). Do NOT include Document() or doc.save().
Available libraries: python-docx, matplotlib, pandas, numpy (seaborn NOT available)
Use add_paragraph(style='List Bullet') for bullet lists. NEVER insert unicode bullet characters.
NEVER use paragraph.text = 'new text' (destroys formatting). Use runs instead.
Filenames: letters, numbers, hyphens only.

Tool Reference

create_word_document

Create a new Word document using python-docx code.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | python_code | str | Yes | Python code using python-docx (see Code Rules above) | | document_name | str | Yes | Filename without extension (letters, numbers, hyphens only) |

Example tool_input:

{
  "python_code": "doc.add_heading('Quarterly Report', 0)\ndoc.add_paragraph('This report summarizes Q4 performance.')\ndoc.add_heading('Revenue', level=1)\ndoc.add_paragraph('Total revenue: $1.2M')",
  "document_name": "quarterly-report"
}

WARNING: Parameter is document_name, NOT filename or name.

modify_word_document

Modify an existing Word document and save with a new name.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | source_name | str | Yes | Existing document name (without .docx) | | output_name | str | Yes | New output name (MUST differ from source) | | python_code | str | Yes | Python code to modify the document |

Example tool_input:

{
  "source_name": "quarterly-report",
  "output_name": "quarterly-report-v2",
  "python_code": "doc.add_paragraph('Additional notes added.')"
}

list_my_word_documents

List all Word documents in workspace. No parameters needed.

read_word_document

Read document content. With include_comments=True, also shows all comments with author, date, text, and which paragraph they're attached to.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | document_name | str | Yes | Document name without extension | | include_comments | bool | No | If true, extract and display comments with paragraph mapping (default: false) |

preview_word_page

Get page screenshots for visual inspection before editing.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | document_name | str | Yes | Document name without extension | | page_numbers | list[int] | Yes | 1-based page numbers to preview |

UI Guidance (from tools-config)

Sequential Execution Required: Run modification tools sequentially, never in parallel (prevents race conditions on S3 file read/write).

When to Use:

create_word_document: User asks to create/generate a NEW Word document
modify_word_document: User asks to edit/modify/update an EXISTING document or add content to existing document
list_my_word_documents: User asks what documents are available
read_word_document: User wants to download a document
preview_word_page: Check actual page appearance when editing (charts, images, complex layouts)

Before Modifying: Always use preview_word_page first to see the current layout.

Page Setup:

python-docx defaults to A4. For US Letter: section.page_width = Inches(8.5); section.page_height = Inches(11)
Set 1" margins: section.top_margin = section.bottom_margin = section.left_margin = section.right_margin = Inches(1)

Professional Formatting:

Font: Arial as default. Set via style.font.name = 'Arial'
Use proper heading styles for TOC compatibility: document.add_heading('Title', level=1) or add_paragraph(style='Heading 1')
Lists: use add_paragraph(style='List Bullet') or add_paragraph(style='List Number'). NEVER insert unicode bullet characters manually.

Formatting Preservation:

ALWAYS preserve existing styles, fonts, colors
NEVER use paragraph.text = 'new text' (destroys formatting)
Use runs to modify text while preserving formatting

Filenames: Letters, numbers, hyphens only (e.g., "sales-report.docx")

Available Libraries: python-docx, matplotlib, pandas, numpy (seaborn NOT available)

Images: If workspace has relevant images: run.add_picture('file.png', width=Inches(6))

QA: Always use preview_word_page after creation to verify appearance.