toolsets/docx-toolkit/doc.md

# docx‑toolkit

Create, edit, extract, and analyze Word (.docx) documents programmatically —
with code bindings replacing the throw‑away scripts agents previously wrote.

---

## When to Use This Toolset

- Extracting text from a .docx for search, analysis, or conversion
- Inspecting document structure before editing (paragraphs, tables, images)
- Extracting tables as structured data
- Creating new Word documents from markdown‑like content
- Working with tracked changes and comments

---

## Process

### Creating a Document

```
Determine structure → Choose approach → Build → Save → Verify
```

1. **Determine**: What sections? Tables? Headings? Lists?
2. **Choose**: Simple → `docx_create`, Complex → python-docx directly
3. **Build**: Content paragraphs (strings starting with `#` become headings, `-` become bullets)
4. **Save** with `docx_create` to the target path
5. **Verify** with `docx_read` — confirm paragraph count and content

### Editing a Document

```
Open → Inspect → Change → Verify
```

1. **Open** with `docx_info` to understand structure
2. **Inspect** with `docx_read` to see content
3. **Change** values (python-docx preserves existing styles when editing)
4. **Verify** by reading back with `docx_read`

---

## Function Reference

### `docx_read`

Extract full text from a Word document.

**When to use:** Before editing — understand what's in the document.

**Args:** `filepath` (str)

**Returns:** `{text, paragraphs, sections}`

### `docx_info`

Inspect structure without extracting content.

**When to use:** Quick overview — tables count, images, author metadata.

**Args:** `filepath` (str)

**Returns:** `{paragraphs, tables, sections, styles_count, images, core_properties, filename}`

### `docx_extract_tables`

Pull tables as structured row data.

**When to use:** Extracting data from document tables for analysis.

**Args:** `filepath` (str), `table_index` (int, -1 = all)

**Returns:** `{tables: [{index, rows, columns, data}], count}`

### `docx_create`

Create a new document from structured content.

**When to use:** Report generation, document export, template filling.

**Args:** `filepath` (str), `title` (str), `content` (list of strings/dicts), `author` (str)

**Content format:**
- `"# Heading"` → h2 heading
- `"- Item"` → bullet point
- `"Plain text"` → paragraph
- `{rows, columns}` → styled table

---

## Guidelines

### Do
- Inspect with `docx_info` before editing unfamiliar documents
- Use `docx_read` to verify content after changes
- Handle tracked changes explicitly — accept/reject before extracting
- Preserve formatting when editing existing documents

### Don't
- Don't assume first paragraph is the title — check heading styles
- Don't overwrite without confirming if the file exists
- Don't strip existing styles unless explicitly asked

### Edge Cases
- **Tables in headers/footers**: Not extracted by `docx_extract_tables`
- **Embedded objects**: Charts, equations — text not extractable
- **Password-protected**: Cannot be opened by python-docx