docx — Word documents

Best practices for create_document / read_document / edit_document: structure, styles, and what these tools can't do yet.

Content model

A .docx here is just an ordered list of paragraphs. Each paragraph has:

text — plain text (no inline bold/italic within one paragraph — see Limitations; bold/italic/underline apply to the whole paragraph).
style — one of normal, heading1, heading2, heading3, bullet. Defaults to normal.
bold — bolds the whole paragraph. Implied true for headings; set it explicitly on a normal/bullet paragraph if you want it bold too.
italic — italicizes the whole paragraph. Defaults to false.
underline — underlines the whole paragraph. Defaults to false. Combine freely with bold/italic and with any style.

There is no separate "title page" or "section" concept — structure a document the way you'd structure Markdown: one heading1 for the document title, heading2/heading3 for subsections, bullet paragraphs for lists, normal for body copy.

Writing a good structured document

Lead with a heading1. Don't put the document's title in a normal paragraph — it won't render distinctly and won't show up in Word's navigation pane.
Keep paragraphs as actual paragraphs, not single giant blocks — split by idea the way you would in prose, not by sentence.
Use bullet for genuinely list-shaped content (steps, options, short items), not as a substitute for paragraph breaks.
A short memo doesn't need every heading level — heading1 + normal/bullet is often enough. Reach for heading2/heading3 only when the document actually has that many levels of nesting.

Editing an existing document

edit_document supports exactly two operations:

append_paragraph — adds one new paragraph at the end. Same fields as a create_document paragraph (including bold/italic/underline). This preserves everything already in the file — tables, images, headers, other formatting — untouched; only a new paragraph is added.
replace_text — a literal, case-sensitive find/replace across every text run in the document, including text inside table cells. This is the structured analogue of edit_file's old_string/new_string: it matches plain text only, not formatting, and every occurrence is replaced (there's no "exactly one match" requirement the way edit_file has). One real caveat: Word sometimes splits what reads as one phrase across more than one internal text run (spell-check and revision tracking both do this), and find only matches within a single run — if a replacement you expect to apply doesn't, try a shorter, more literal substring, or read_document first to see the text as the model sees it.

There's no "insert paragraph at position N" or "delete paragraph" operation yet — if a document needs real restructuring (not just adding to the end or swapping text), the practical option today is read_document to get the current content, then create_document a replacement with the full new paragraph list (after confirming with the person you're overwriting it, the same judgment call you'd make before write_file-replacing an existing text file).

Always read_document first if you're not certain what's already in the file — don't guess at existing paragraph text before a replace_text call.

Redlining (Track Changes)

Two of edit_document's operations record the edit as a reviewable tracked change instead of rewriting the text in place:

append_paragraph_tracked — same fields as append_paragraph, but the new paragraph shows up in Word as a pending insertion (Review > Track Changes), not as ordinary content.
replace_text_tracked — same fields as replace_text, but instead of silently rewriting matching text it marks the containing run as changed: the old text struck through (a deletion) and the new text inserted beside it. This works at whole-run granularity, not a minimal character diff — in practice a run is usually already one coherent span of matching formatting, so this reads as a natural redline rather than an oversized strikethrough.
Both accept an optional author (defaults to "enkly agent") — the reviewer name Word shows on hover and in the Reviewing pane.

Resolving changes: accept_all_changes makes every pending tracked change in the document permanent (deletions removed, insertions kept as ordinary text); reject_all_changes discards every pending insertion and restores every pending deletion. Both act on every tracked change in the file at once — there's no per-change accept or reject yet, so say so if someone asks for that.

read_document automatically reports any pending tracked changes (author + the affected text) after the plain text, so you don't need a separate call to discover a document already has open redlines before deciding whether to add more, accept, or reject them.

Converting Markdown into a document

create_document accepts markdown as an alternative to paragraphs: pass a Markdown document's source text and headings (#/##/###), paragraphs, and bullet/numbered lists are converted into the matching paragraph styles automatically (numbered lists come out as bullets — there's no numbered-list style yet). Inline formatting (**bold**, *italic*, links, inline code) is flattened to plain text, the same whole-paragraph-only limit paragraphs already has. Tables and raw HTML blocks in the source are dropped, not approximated — say so if a Markdown document being converted has either.

Limitations (so you don't promise more than the tool does)

No inline run-level formatting — a paragraph is bold/italic/underline or it isn't; there's no bolding one word mid-sentence.
Can't create tables, images, headers/footers, footnotes, page breaks, or columns. read_document and replace_text do see and reach text already inside a table in a file you didn't create with this tool (e.g. a user upload) — they just can't add a new table.
No numbered lists — bullet is always a bullet, never 1./2./3..
read_document extracts plain text only (bullets prefixed "- ", one line per paragraph wherever it occurs, table cells included); images and complex formatting in a real user-uploaded .docx are still invisible to it — just the text survives.

If someone explicitly asks for one of these (a table, an image, inline bold mid-paragraph), say plainly that today's document tool doesn't support it rather than silently producing something close but different.

6.5 KiB Raw Permalink Blame History