Google Workspace MCP Server - Control Gmail, Calendar, Docs, Sheets, Slides, Chat, Forms & Drive

Inspect Doc Structure

inspect_doc_structure

Read-onlyIdempotent

Inspect a Google Doc's structure before editing to identify safe insertion points, existing tables, headers, footers, tabs, and paragraph statistics.

Instructions

Essential tool for finding safe insertion points and understanding document structure.

USE THIS FOR:

Finding the correct index for table insertion
Understanding document layout before making changes
Locating existing tables and their positions
Getting document statistics and complexity info
Inspecting structure of specific tabs

CRITICAL FOR TABLE OPERATIONS: ALWAYS call this BEFORE creating tables to get a safe insertion index.

WHAT THE OUTPUT SHOWS:

total_elements: Number of document elements
total_length: Maximum safe index for insertion
tables: Number of existing tables
table_details: Position and dimensions of each table
headers / footers: Real segment IDs and previews for header/footer editing
tabs: List of available tabs in the document (if no tab_id specified)
empty_paragraphs: newline-only count, excluding existing/suggested object anchors
empty_paragraph_ranges: start/end extents, capped at 100
empty_paragraph_ranges_truncated: whether ranges were omitted
last_paragraph: is_list_item and is_empty, or null if no body paragraphs

Paragraph statistics cover top-level body paragraphs and appear at the top level in basic mode or under "statistics" in detailed mode. Ranges can include required empty paragraphs. Before cleanup, use detailed=true to check adjacent elements, formatting, and object anchors. Preserve the final newline and newlines before tables, tables of contents, or section breaks. The final range has end == total_length and may be omitted by truncation.

WORKFLOW FOR TABLE INSERTION: Step 1: Call this function Step 2: Note the "total_length" value Step 3: Use an index < total_length for table insertion Step 4: Create your table

FORMATTING WORKFLOW: After inserting all text via batch_update_doc with end_of_segment=true, call this tool with detailed=true to get exact start_index and end_index for every paragraph. Use those indices directly in format_text and update_paragraph_style operations in a second batch_update_doc call.

HEADER/FOOTER WORKFLOW: For ordinary header/footer text, use update_doc_headers_footers. If you need low-level segment editing, call this tool first and use the real segment_id values returned under headers/footers. Do not invent IDs.

The detailed output includes elements[].start_index and elements[].end_index with text_preview for each paragraph, making it easy to identify which ranges to format.

SUB-PARAGRAPH FORMATTING: text_preview is truncated to 100 characters by default. To compute the index of a token inside a longer paragraph, pass preview_chars=0 or None for untruncated text, then add the token's UTF-16 offset within that text to the paragraph's start_index (non-BMP characters such as emoji occupy two UTF-16 units).

Input Schema

TableJSON Schema

Name	Required	Description
`tab_id`	No	Optional ID of the tab to inspect. If not provided, inspects main document.
`detailed`	No	Whether to return detailed structure information
`document_id`	Yes	ID of the document to inspect
`preview_chars`	No	Maximum characters of paragraph, header and footer text preview. Pass 0 or None for the full text, needed to locate a token inside a paragraph longer than the default 100 characters.
`user_google_email`	Yes	User's Google email address

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.26.0Sep 6, 2026

addedInput schema / properties / preview_chars

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": 100,
+  "description": "Maximum characters of paragraph, header and footer text\npreview. Pass 0 or None for the full text, needed to locate a token inside a\nparagraph longer than the default 100 characters."
+}

Addedv1.0.1Jul 31, 2026

TDQS

A4.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only, idempotent, and non-destructive behavior, and the description adds substantial context on top: total_length as a safe insertion bound, output truncation behavior, empty_paragraph_ranges semantics, and required newline preservation. It also warns against inventing segment IDs and explains UTF-16 offset handling for non-BMP characters.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-organized with clear sections and front-loaded purpose. Most content earns its place given the complexity of the tool and its output. There is some redundancy across the output-shows list and the workflow sections, but not to a degree that harms usability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex inspection tool with an output schema, the description is exceptionally complete: it documents output fields, detailed vs basic modes, safe insertion index guidance, formatting and header/footer workflows, truncation caveats, and even sub-paragraph token index calculation. An agent has everything it needs to call this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds real value beyond the schema by explaining preview_chars truncation and the need to pass 0/None for full text, clarifying what detailed=true provides, and specifying tab_id default behavior. It does not meaningfully elaborate on document_id or user_google_email, but the schema already covers those adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'finding safe insertion points and understanding document structure.' It clearly describes the tool's role and lists concrete use cases. However, it does not explicitly differentiate itself from adjacent siblings like debug_table_structure or get_doc_content.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance: ALWAYS call before creating tables, after batch_update_doc for formatting indices, and before low-level header/footer segment editing. It also names an alternative (update_doc_headers_footers) for ordinary header/footer text, making the routing decision explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server