cursor-google-docs

Codex capability boundary

This is source guidance, not an installed connector or a runtime proof. Resolve tools against the current host and read their actual schemas before using them. Preserve the named product and requested outcome. If a required operation is unavailable, report its exact name and leave that step incomplete. Do not invent tool names, connect accounts, install helpers, spend money, or broaden access from this document alone. Current operator authorization and native permissions govern every action.

Use the official Codex Google plugin and its owning skill when available. The tool names and schema details below describe the upstream connector; they are not promises about the Codex plugin. Map each operation only after inspecting the exposed schema. If the official plugin lacks the operation, name the gap; do not fall back to GOG or another credential route without explicit authorization. Never widen sharing or make a private image public to satisfy an image URL requirement. For visual work, apply available design guidance and inspect exported output.

Google Docs authoring

Locate text, never compute indexes (the #1 source of bugs)

Docs edits address zero-based UTF-16 index ranges within one tab, and every write SHIFTS later indexes. Guessed or stale indexes silently hit the wrong paragraphs - the classic symptom is two lists merging into one continued numbering. The tools remove the need for index math:

• find_text returns FRESH {start, end} ranges for exact text - the direct source of indexes for apply_text_style, apply_paragraph_style, delete_content, and set_paragraph_format. Locate, then edit, in back-to-back calls.
• create_list takes firstItemText/lastItemText anchors and resolves the range itself: name the first and last item paragraphs and no index ever touches your hands. Use one create_list per list with the right preset (BULLET_* for bullets, NUMBERED_* for numbers); never stretch one call across two visually separate lists.

When a range must come from structure instead of a phrase (styling a whole paragraph, addressing a table), read it from read_document elements: a paragraph's {start, end} is the range for paragraph-level tools. END IS EXCLUSIVE: one short misses the last character, one long styles the character after the phrase (the classic italic-or-link off-by-one).

When raw indexes are unavoidable: read_document first, compute ONE edit, pass requiredRevisionId, apply, and re-read before the next positional edit. Order multi-part positional work BACK-TO-FRONT (highest index first) when re-reading between steps is too expensive; earlier ranges stay valid.

Creating a document

create_document makes a BLANK doc (its API ignores content), so plan:

• Content known up front: prefer google-drive google_drive_create_file with Markdown (target_mime_type: ...document), which imports headings, lists, and tables in one call and can target a folder.
• Building incrementally: create_document, then insert_text with index omitted to APPEND each paragraph; append mode reads the tail itself and is revision-guarded automatically. paragraphStyle styles the new paragraphs and bold/italic style the inserted text in the same call, so a well-structured document is a sequence of appends with no styling pass.
• Doc creates cannot set a parent folder. When placement matters, create and then google-drive google_drive_move_or_rename with destination_folder_id.

Structure is not optional

A document without hierarchy reads as a text dump. Default shape for any report/memo/notes request: a TITLE paragraph, an italic byline or date line, HEADING_2 per section, short body paragraphs with bold on the phrases that matter, and bulleted lists for enumerations. Use insert_text's paragraphStyle/bold/italic arguments as you write rather than styling afterwards.

Styling

• Character styling (apply_text_style): bold/italic/underline/strike, fontSize, fontFamily, textColor/backgroundColor as #RRGGBB, linkUrl. Exclusive END index: to style one paragraph without its trailing newline, use end - 1 from the read.
• Paragraph styling: apply_paragraph_style for named styles (TITLE/HEADING_1..6), set_paragraph_format for alignment, indents, and line spacing (percent, 100 = single).
• Lists: create_list over the paragraphs' range; each newline-separated paragraph becomes one item. Insert the plain lines first, then bullet them.
• The preset is part of correctness: enumerations get a BULLET_* preset by default; NUMBERED_* only when the content is ordered (steps, rankings) or the request says numbered.
• Before bulleting, check the read for paragraphs that ALREADY show a leading bullet - text appended directly after a list inherits its membership, and create_list over such paragraphs restyles the ORIGINAL list, continuing its numbering (a second list showing 4, 5, 6). Strip first: create_list with remove: true over exactly the new paragraphs, then apply the wanted preset.

Tables and images

• insert_table inserts an EMPTY grid. To fill it: re-read (cells appear with their own index ranges) and insert_text into cells from the LAST cell to the first, so earlier cell indexes stay valid.
• Style a table AFTER filling it, addressing it by the table element's start from read_document: set_table_cell_shading the header row (pick the row's text color against that fill), merge_table_cells for a title cell spanning columns (top-left content survives, the rest is dropped), set_table_column_width for fixed widths in points. Structural edits (merge) shift indexes: re-read before further text edits.
• insert_image needs a PUBLICLY fetchable URL (Google fetches it; auth walls and private hosts fail), PNG/JPEG/GIF. Size with width/height in points (aspect kept when only one is set).
• insert_page_break starts a new page at an index.

Headers and footers

set_header_footer sets the default header or footer in one call: it creates the segment when the doc has none, replaces the text otherwise, and empty text clears it. The text is static (no page-number fields exist in the API); it applies to the first tab. Never insert_text a fake header into the body - it scrolls away with the content.

Bulk text ops

replace_text replaces literal strings everywhere (or in named tabs) with no index math; prefer it for renames and corrections. delete_content rejects ranges that split table structure or surrogate pairs; deleting a paragraph's final newline merges it with the next.

Verify your work

Re-read with read_document for structure and styles, or google-drive google_drive_read_file for the whole doc as Markdown, or google_drive_export_file (pdf) when the visual result matters. After any styling call, confirm the styled span covers exactly the intended text before moving on.