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

Inspect Doc Structure

inspect_doc_structure

Read-onlyIdempotent

Inspect Google Docs structure to find safe insertion points, table positions, tabs, and paragraph indices before editing or formatting.

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. If the body ends with an empty paragraph, that paragraph's range has end == total_length; truncation may omit that range.

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

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

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.28.0Sep 24, 2026
- removedInput schema / properties / preview_chars / anyOf
```
Removed value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedInput schema / properties / preview_chars / type
```
Added value: +"integer"
```

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.6/5.0

Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description still adds real behavior: truncation caps (empty_paragraph_ranges capped at 100), the truncated flag, the end == total_length edge case, and the UTF-16 offset caveat for emoji. It does not cover auth or performance considerations, but for a read-only inspector this is substantial beyond the annotations.

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?

Front-loaded with purpose before mechanics, and the sectioned layout (USE THIS FOR / OUTPUT / WORKFLOW) is scannable. It is long, and the Step 1-4 table insertion walkthrough is padded ('Call this function', 'Note the total_length value'), but almost every block carries distinct information.

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 5-param inspection tool with an output schema, the description covers the ambiguity that matters: where paragraph statistics live in each mode, how to derive sub-paragraph offsets, and the safety constraint on insertion indices. An agent can call it correctly from this alone.

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 3 is the baseline. The description earns extra by explaining the consequence of preview_chars=0 (untruncated text needed to locate a token) and by tying detailed=true to the statistics location and element indices, which the schema does not say.

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

Purpose5/5

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

States a specific verb+resource (inspect document structure) and immediately distinguishes itself from content-reading siblings by framing the job as 'finding safe insertion points'. The 'USE THIS FOR' list makes the resource scope concrete (indices, tables, tabs, statistics).

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?

Explicit when-to-use list plus named alternatives: ordinary header/footer text goes to update_doc_headers_footers, this tool is only for low-level segment IDs. The table workflow even mandates ordering ('ALWAYS call this BEFORE creating tables').

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

Deploy Server