mcp-google-multi 6.0.0-beta.1 → 6.0.0-beta.2

package/dist/tools/contacts.js

@@ -3,9 +3,12 @@ import { people as peopleClient } from '@googleapis/people';
 import { accountAliasSchema } from '../accounts.js';
 import { getClient } from '../client.js';
 import { coerceBoolean } from './_coerce.js';
-import { handleGoogleApiError } from './_errors.js';
+import { handleGoogleApiError, invalidParams } from './_errors.js';
+import { listResult } from '../trim.js';
 const accountEnum = accountAliasSchema.optional();
 const PERSON_FIELDS = 'names,emailAddresses,phoneNumbers,organizations,addresses,photos,memberships';
+// people.getBatchGet rejects more than 200 resource names per call.
+const BATCH_GET_LIMIT = 200;
 function formatContact(person) {
     return {
         resourceName: person.resourceName,
@@ -143,9 +146,15 @@ export function registerContactsTools(server) {
                 readMask: PERSON_FIELDS,
                 pageSize: pageSize ?? 10,
             });
+            const limit = pageSize ?? 10;
             const contacts = (res.data.results ?? []).map((r) => formatContact(r.person));
             return {
-                content: [{ type: 'text', text: JSON.stringify(contacts, null, 2) }],
+                content: [{ type: 'text', text: JSON.stringify(listResult('contacts', contacts, {
+                            // searchContacts returns no token and no total, so a full page is
+                            // the only evidence that the cap, not the address book, ended it.
+                            capped: contacts.length >= limit,
+                            hint: `The page is full at ${limit} of a possible 30, so more contacts may match. Raise pageSize or narrow the query. This search endpoint has no pageToken, so there is no next page to fetch.`,
+                        }), null, 2) }],
             };
         }
         catch (error) {
@@ -200,7 +209,7 @@ export function registerContactsTools(server) {
         description: 'Get a single contact by resource name',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            resourceName: z.string().describe('Contact resource name (e.g. "people/c1234567890")'),
+            resourceName: z.string().min(1).describe('Contact resource name (e.g. "people/c1234567890")'),
         },
     }, async ({ account, resourceName }) => {
         try {
@@ -307,7 +316,7 @@ export function registerContactsTools(server) {
         description: 'Update an existing contact (reads current etag automatically)',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            resourceName: z.string().describe('Contact resource name (e.g. "people/c1234567890")'),
+            resourceName: z.string().min(1).describe('Contact resource name (e.g. "people/c1234567890")'),
             givenName: z.string().optional().describe('Updated first name'),
             familyName: z.string().optional().describe('Updated last name'),
             email: z.string().optional().describe('Updated email address'),
@@ -354,12 +363,7 @@ export function registerContactsTools(server) {
                 updateFields.push('organizations');
             }
             if (updateFields.length === 0) {
-                return {
-                    content: [{ type: 'text', text: JSON.stringify({
-                                error: 'No fields to update. Provide at least one of: givenName, familyName, email, phone, organization, jobTitle',
-                            }, null, 2) }],
-                    isError: true,
-                };
+                return invalidParams(account, 'No fields to update: every optional field was omitted, so the request would have been a no-op.', 'Pass at least one of: givenName, familyName, email, phone, organization, jobTitle.');
             }
             const res = await people.people.updateContact({
                 resourceName,
@@ -379,7 +383,7 @@ export function registerContactsTools(server) {
         description: 'Delete a contact (permanent, cannot be undone)',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            resourceName: z.string().describe('Contact resource name (e.g. "people/c1234567890")'),
+            resourceName: z.string().min(1).describe('Contact resource name (e.g. "people/c1234567890")'),
         },
     }, async ({ account, resourceName }) => {
         try {
@@ -429,7 +433,7 @@ export function registerContactsTools(server) {
         description: 'List members of a contact group',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            groupResourceName: z.string().describe('Contact group resource name (e.g. "contactGroups/abc123")'),
+            groupResourceName: z.string().min(1).describe('Contact group resource name (e.g. "contactGroups/abc123")'),
             maxMembers: z.number().min(1).max(1000).default(100).optional()
                 .describe('Max member resource names to return (default: 100)'),
         },
@@ -442,26 +446,49 @@ export function registerContactsTools(server) {
                 maxMembers: maxMembers ?? 100,
             });
             const memberResourceNames = groupRes.data.memberResourceNames ?? [];
-            if (memberResourceNames.length === 0) {
-                return {
-                    content: [{ type: 'text', text: JSON.stringify({
-                                group: groupRes.data.name,
-                                members: [],
-                            }, null, 2) }],
-                };
+            const members = [];
+            let fetchFailures = 0;
+            let firstError;
+            // getBatchGet caps at 200 names while maxMembers goes to 1000, so a
+            // large group used to fail outright rather than come back in pages.
+            for (let i = 0; i < memberResourceNames.length; i += BATCH_GET_LIMIT) {
+                const chunk = memberResourceNames.slice(i, i + BATCH_GET_LIMIT);
+                try {
+                    const membersRes = await people.people.getBatchGet({
+                        resourceNames: chunk,
+                        personFields: PERSON_FIELDS,
+                    });
+                    const got = (membersRes.data.responses ?? []).filter((r) => r.person);
+                    fetchFailures += chunk.length - got.length;
+                    for (const r of got)
+                        members.push(formatContact(r.person));
+                }
+                catch (chunkError) {
+                    firstError ??= chunkError;
+                    fetchFailures += chunk.length;
+                }
             }
-            const membersRes = await people.people.getBatchGet({
-                resourceNames: memberResourceNames,
-                personFields: PERSON_FIELDS,
-            });
-            const members = (membersRes.data.responses ?? [])
-                .filter((r) => r.person)
-                .map((r) => formatContact(r.person));
+            // Every chunk failed, so there is no partial answer to report honestly.
+            if (firstError && members.length === 0 && memberResourceNames.length > 0)
+                throw firstError;
+            const total = groupRes.data.memberCount ?? memberResourceNames.length;
+            const namesTruncated = total > memberResourceNames.length;
+            const causes = [];
+            if (namesTruncated)
+                causes.push(`the maxMembers cap returned ${memberResourceNames.length} of ${total} member names`);
+            if (fetchFailures > 0)
+                causes.push(`${fetchFailures} member record(s) could not be fetched`);
             return {
-                content: [{ type: 'text', text: JSON.stringify({
-                            group: groupRes.data.name,
-                            members,
-                        }, null, 2) }],
+                content: [{ type: 'text', text: JSON.stringify(listResult('members', members, {
+                            totalItems: total,
+                            extra: {
+                                group: groupRes.data.name,
+                                ...(fetchFailures > 0 ? { fetchFailures } : {}),
+                            },
+                            hint: causes.length > 0
+                                ? `Incomplete because ${causes.join(' and ')}.${namesTruncated ? ' Raise maxMembers to see the rest.' : ''}`
+                                : undefined,
+                        }), null, 2) }],
             };
         }
         catch (error) {

package/dist/tools/docs.js

@@ -3,7 +3,7 @@ import { coerceBoolean, coerceJson } from './_coerce.js';
 import { docs as docsClient } from '@googleapis/docs';
 import { accountAliasSchema } from '../accounts.js';
 import { getClient } from '../client.js';
-import { handleGoogleApiError } from './_errors.js';
+import { handleGoogleApiError, invalidParams } from './_errors.js';
 import { capText } from '../trim.js';
 const accountEnum = accountAliasSchema.optional();
 // A single very large insertText has been observed to apply only partially while
@@ -199,7 +199,7 @@ export function registerDocsTools(server) {
         description: 'Get document metadata (title, revision, named ranges). Optionally include tab content and choose a suggestionsViewMode.',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            documentId: z.string().describe('Google Docs document ID'),
+            documentId: z.string().min(1).describe('Google Docs document ID'),
             includeTabsContent: coerceBoolean.optional()
                 .describe('Include full content for every tab (default: false — first tab only)'),
             suggestionsViewMode: z.enum([
@@ -236,7 +236,7 @@ export function registerDocsTools(server) {
         description: 'Read document content as plain text with a heading index (returns up to maxChars characters per call). Pass heading or headingIndex to read one section, tabId to read a specific tab.',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            documentId: z.string().describe('Google Docs document ID'),
+            documentId: z.string().min(1).describe('Google Docs document ID'),
             heading: z.string().optional()
                 .describe('Read only the section under this heading (case-insensitive; exact match first, then substring)'),
             headingIndex: z.number().int().min(0).optional()
@@ -251,13 +251,7 @@ export function registerDocsTools(server) {
     }, async ({ account, documentId, heading, headingIndex, tabId, maxChars, offset }) => {
         try {
             if (heading !== undefined && headingIndex !== undefined) {
-                return {
-                    content: [{ type: 'text', text: JSON.stringify({
-                                error: 'invalid_params',
-                                message: 'Provide either heading or headingIndex, not both',
-                            }, null, 2) }],
-                    isError: true,
-                };
+                return invalidParams(account, 'Both heading and headingIndex were supplied, and they address different sections.', 'Pass heading to look a section up by its text, or headingIndex to address one by position. Not both.');
             }
             const auth = await getClient(account);
             const docs = docsClient({ version: 'v1', auth });
@@ -272,7 +266,10 @@ export function registerDocsTools(server) {
                     return {
                         content: [{ type: 'text', text: JSON.stringify({
                                     error: 'not_found',
-                                    message: `Tab "${tabId}" not found in document ${documentId}`,
+                                    message: `Tab "${tabId}" was not found in document ${documentId}.`,
+                                    hint: 'Pick a tabId from availableTabs below, or omit tabId to read the first tab.',
+                                    retriable: false,
+                                    account: account,
                                     availableTabs: listTabs(res.data.tabs),
                                 }, null, 2) }],
                         isError: true,
@@ -288,7 +285,10 @@ export function registerDocsTools(server) {
                     return {
                         content: [{ type: 'text', text: JSON.stringify({
                                     error: 'invalid_params',
-                                    message: `headingIndex ${headingIndex} is out of range (document has ${headings.length} headings)`,
+                                    message: `headingIndex ${headingIndex} is out of range: the document has ${headings.length} heading(s).`,
+                                    hint: 'Indexes are zero-based. Pick one from the headings list below, or omit headingIndex to read the whole document.',
+                                    retriable: false,
+                                    account: account,
                                     headings: headings.map(({ i, level, text }) => ({ i, level, text })),
                                 }, null, 2) }],
                         isError: true,
@@ -300,10 +300,17 @@ export function registerDocsTools(server) {
                 if ('error' in resolved) {
                     return {
                         content: [{ type: 'text', text: JSON.stringify({
-                                    error: resolved.error === 'ambiguous' ? 'ambiguous_heading' : 'not_found',
+                                    // 'ambiguous', not 'ambiguous_heading': the slug vocabulary is
+                                    // shared, and a one-off name buckets as `other` in metrics.
+                                    error: resolved.error === 'ambiguous' ? 'ambiguous' : 'not_found',
                                     message: resolved.error === 'ambiguous'
-                                        ? `Heading "${heading}" matches multiple headings; use headingIndex to disambiguate`
-                                        : `Heading "${heading}" not found in document ${documentId}`,
+                                        ? `Heading "${heading}" matches ${resolved.candidates.length} headings in document ${documentId}.`
+                                        : `Heading "${heading}" was not found in document ${documentId}.`,
+                                    hint: resolved.error === 'ambiguous'
+                                        ? 'Pass headingIndex with the i value of the one you want, from candidates below.'
+                                        : 'Pick a heading from candidates below (it lists every heading in the document), or pass headingIndex.',
+                                    retriable: false,
+                                    account: account,
                                     candidates: resolved.candidates.map(({ i, level, text }) => ({ i, level, text })),
                                 }, null, 2) }],
                         isError: true,
@@ -338,7 +345,7 @@ export function registerDocsTools(server) {
         description: 'Insert text into a document at a specific position or at the end',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            documentId: z.string().describe('Google Docs document ID'),
+            documentId: z.string().min(1).describe('Google Docs document ID'),
             text: z.string().describe('Text to insert'),
             index: z.number().min(1).optional()
                 .describe('Character index to insert at (1-based). Omit to append at the end'),
@@ -377,7 +384,7 @@ export function registerDocsTools(server) {
         description: 'Find and replace all occurrences of text in a document',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            documentId: z.string().describe('Google Docs document ID'),
+            documentId: z.string().min(1).describe('Google Docs document ID'),
             findText: z.string().describe('Text to search for'),
             replaceText: z.string().describe('Replacement text'),
             matchCase: coerceBoolean.default(true).optional()
@@ -414,7 +421,7 @@ export function registerDocsTools(server) {
         description: 'Delete content in a character index range within a document',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            documentId: z.string().describe('Google Docs document ID'),
+            documentId: z.string().min(1).describe('Google Docs document ID'),
             startIndex: z.number().min(1).describe('Start index (inclusive, 1-based)'),
             endIndex: z.number().min(2).describe('End index (exclusive)'),
         },
@@ -447,7 +454,7 @@ export function registerDocsTools(server) {
         description: 'Update text formatting (bold, italic, underline, font, size) for a range',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            documentId: z.string().describe('Google Docs document ID'),
+            documentId: z.string().min(1).describe('Google Docs document ID'),
             startIndex: z.number().min(1).describe('Start index (inclusive, 1-based)'),
             endIndex: z.number().min(2).describe('End index (exclusive)'),
             bold: coerceBoolean.optional().describe('Set bold'),
@@ -483,12 +490,7 @@ export function registerDocsTools(server) {
                 fields.push('weightedFontFamily');
             }
             if (fields.length === 0) {
-                return {
-                    content: [{ type: 'text', text: JSON.stringify({
-                                error: 'No style properties provided. Set at least one of: bold, italic, underline, fontSize, fontFamily',
-                            }, null, 2) }],
-                    isError: true,
-                };
+                return invalidParams(account, 'No style properties to apply: every optional property was omitted.', 'Pass at least one of: bold, italic, underline, fontSize, fontFamily.');
             }
             const res = await docs.documents.batchUpdate({
                 documentId,
@@ -518,7 +520,7 @@ export function registerDocsTools(server) {
         description: 'Insert a table into a document at a specific position',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            documentId: z.string().describe('Google Docs document ID'),
+            documentId: z.string().min(1).describe('Google Docs document ID'),
             rows: z.number().min(1).describe('Number of rows'),
             columns: z.number().min(1).describe('Number of columns'),
             index: z.number().min(1).optional()
@@ -555,7 +557,7 @@ export function registerDocsTools(server) {
         description: 'Tag a range of text with a name. Multiple ranges can share the same name. Used as a template anchor for docs_replace_named_range_content.',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            documentId: z.string().describe('Google Docs document ID'),
+            documentId: z.string().min(1).describe('Google Docs document ID'),
             name: z.string().describe('Name (1-256 chars). Need not be unique.'),
             startIndex: z.number().min(1).describe('Range start (inclusive)'),
             endIndex: z.number().min(2).describe('Range end (exclusive)'),
@@ -588,14 +590,14 @@ export function registerDocsTools(server) {
         description: 'Delete a named range by its ID or by name. Removes every range matching the identifier.',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            documentId: z.string().describe('Google Docs document ID'),
+            documentId: z.string().min(1).describe('Google Docs document ID'),
             namedRangeId: z.string().optional().describe('Specific named range ID'),
             name: z.string().optional().describe('Name (deletes ALL named ranges with this name)'),
         },
     }, async ({ account, documentId, namedRangeId, name }) => {
         try {
             if (!namedRangeId && !name) {
-                return { content: [{ type: 'text', text: JSON.stringify({ error: 'Either namedRangeId or name must be supplied' }) }], isError: true };
+                return invalidParams(account, 'Neither namedRangeId nor name was supplied, so no named range is addressed.', 'Pass namedRangeId to delete one specific range, or name to delete every range carrying that name.');
             }
             const auth = await getClient(account);
             const docs = docsClient({ version: 'v1', auth });
@@ -620,7 +622,7 @@ export function registerDocsTools(server) {
         description: 'Replace the content of every named range matching the identifier with the supplied text. Real mail-merge primitive — far more robust than replaceAllText for templated docs.',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            documentId: z.string().describe('Google Docs document ID'),
+            documentId: z.string().min(1).describe('Google Docs document ID'),
             namedRangeId: z.string().optional().describe('Specific named range ID'),
             namedRangeName: z.string().optional().describe('Name to match (replaces ALL ranges with this name)'),
             text: z.string().describe('Replacement text'),
@@ -628,7 +630,7 @@ export function registerDocsTools(server) {
     }, async ({ account, documentId, namedRangeId, namedRangeName, text }) => {
         try {
             if (!namedRangeId && !namedRangeName) {
-                return { content: [{ type: 'text', text: JSON.stringify({ error: 'Either namedRangeId or namedRangeName must be supplied' }) }], isError: true };
+                return invalidParams(account, 'Neither namedRangeId nor namedRangeName was supplied, so no named range is addressed.', 'Pass namedRangeId to replace one specific range, or namedRangeName to replace every range carrying that name.');
             }
             const auth = await getClient(account);
             const docs = docsClient({ version: 'v1', auth });
@@ -654,7 +656,7 @@ export function registerDocsTools(server) {
         description: 'Update paragraph styling (alignment, heading, indents, spacing) across a range. Only supplied fields are applied.',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            documentId: z.string().describe('Google Docs document ID'),
+            documentId: z.string().min(1).describe('Google Docs document ID'),
             startIndex: z.number().min(1),
             endIndex: z.number().min(2),
             namedStyleType: z.enum([
@@ -679,7 +681,7 @@ export function registerDocsTools(server) {
             const docs = docsClient({ version: 'v1', auth });
             const built = buildParagraphStyle(style);
             if (built.fields.length === 0) {
-                return { content: [{ type: 'text', text: JSON.stringify({ error: 'No paragraph style properties supplied' }) }], isError: true };
+                return invalidParams(account, 'No paragraph style properties to apply: every optional property was omitted.', 'Pass at least one of: namedStyleType, alignment, lineSpacing, spaceAbove, spaceBelow, indentStart, indentEnd, indentFirstLine, direction, keepLinesTogether, keepWithNext, avoidWidowAndOrphan.');
             }
             await docs.documents.batchUpdate({
                 documentId,
@@ -705,7 +707,7 @@ export function registerDocsTools(server) {
         description: 'Update document-level styling (page size, margins, headers/footers behavior). Only supplied fields are applied.',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            documentId: z.string().describe('Google Docs document ID'),
+            documentId: z.string().min(1).describe('Google Docs document ID'),
             pageWidth: z.number().optional().describe('Page width in points (e.g. 595 = A4)'),
             pageHeight: z.number().optional().describe('Page height in points (e.g. 842 = A4)'),
             marginTop: z.number().optional().describe('Margin in points'),
@@ -725,7 +727,7 @@ export function registerDocsTools(server) {
             const docs = docsClient({ version: 'v1', auth });
             const built = buildDocumentStyle(style);
             if (built.fields.length === 0) {
-                return { content: [{ type: 'text', text: JSON.stringify({ error: 'No document style properties supplied' }) }], isError: true };
+                return invalidParams(account, 'No document style properties to apply: every optional property was omitted.', 'Pass at least one of: pageWidth, pageHeight, marginTop, marginBottom, marginLeft, marginRight, marginHeader, marginFooter, pageNumberStart, useFirstPageHeaderFooter, useEvenPageHeaderFooter, useCustomHeaderFooterMargins.');
             }
             await docs.documents.batchUpdate({
                 documentId,
@@ -751,7 +753,7 @@ export function registerDocsTools(server) {
         description: 'Turn paragraphs in a range into a bulleted or numbered list',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            documentId: z.string().describe('Google Docs document ID'),
+            documentId: z.string().min(1).describe('Google Docs document ID'),
             startIndex: z.number().min(1),
             endIndex: z.number().min(2),
             bulletPreset: z.enum([
@@ -799,7 +801,7 @@ export function registerDocsTools(server) {
         description: 'Strip bullet/number formatting from paragraphs in a range',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            documentId: z.string().describe('Google Docs document ID'),
+            documentId: z.string().min(1).describe('Google Docs document ID'),
             startIndex: z.number().min(1),
             endIndex: z.number().min(2),
         },
@@ -830,7 +832,7 @@ export function registerDocsTools(server) {
         description: 'Insert a publicly-accessible image (PNG/JPEG/GIF, <50MB, <25MP, URL <2KB) inline at an index or at the document end',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            documentId: z.string().describe('Google Docs document ID'),
+            documentId: z.string().min(1).describe('Google Docs document ID'),
             uri: z.string().url().describe('Public image URL'),
             index: z.number().min(1).optional().describe('Insert position; omit to append at the end'),
             width: z.number().optional().describe('Width in points (omit for natural size)'),
@@ -869,7 +871,7 @@ export function registerDocsTools(server) {
         description: 'Insert a page break at a position or at the document end',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            documentId: z.string().describe('Google Docs document ID'),
+            documentId: z.string().min(1).describe('Google Docs document ID'),
             index: z.number().min(1).optional().describe('Insert position; omit to append'),
         },
     }, async ({ account, documentId, index }) => {
@@ -897,7 +899,7 @@ export function registerDocsTools(server) {
         description: 'Insert a section break at a position. CONTINUOUS keeps the same page; NEXT_PAGE starts a new page.',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            documentId: z.string().describe('Google Docs document ID'),
+            documentId: z.string().min(1).describe('Google Docs document ID'),
             index: z.number().min(1).optional(),
             sectionType: z.enum(['CONTINUOUS', 'NEXT_PAGE']).default('NEXT_PAGE').optional(),
         },
@@ -927,7 +929,7 @@ export function registerDocsTools(server) {
         description: 'Create a header for the document or for a specific section. The new header is empty; insert text into it with docs_insert_text targeting its segmentId.',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            documentId: z.string().describe('Google Docs document ID'),
+            documentId: z.string().min(1).describe('Google Docs document ID'),
             sectionBreakIndex: z.number().min(1).optional().describe('Anchor to a specific section break; omit to apply to the document'),
         },
     }, async ({ account, documentId, sectionBreakIndex }) => {
@@ -954,8 +956,8 @@ export function registerDocsTools(server) {
         description: 'Delete a header by its headerId',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            documentId: z.string().describe('Google Docs document ID'),
-            headerId: z.string().describe('Header ID (from docs_get or createHeader reply)'),
+            documentId: z.string().min(1).describe('Google Docs document ID'),
+            headerId: z.string().min(1).describe('Header ID (from docs_get or createHeader reply)'),
         },
     }, async ({ account, documentId, headerId }) => {
         try {
@@ -977,7 +979,7 @@ export function registerDocsTools(server) {
         description: 'Create a footer for the document or a specific section',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            documentId: z.string().describe('Google Docs document ID'),
+            documentId: z.string().min(1).describe('Google Docs document ID'),
             sectionBreakIndex: z.number().min(1).optional(),
         },
     }, async ({ account, documentId, sectionBreakIndex }) => {
@@ -1004,8 +1006,8 @@ export function registerDocsTools(server) {
         description: 'Delete a footer by its footerId',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            documentId: z.string().describe('Google Docs document ID'),
-            footerId: z.string().describe('Footer ID'),
+            documentId: z.string().min(1).describe('Google Docs document ID'),
+            footerId: z.string().min(1).describe('Footer ID'),
         },
     }, async ({ account, documentId, footerId }) => {
         try {
@@ -1030,7 +1032,7 @@ export function registerDocsTools(server) {
         description: 'Mutate a table by operation: insertRow, insertColumn, deleteRow, deleteColumn, mergeCells, unmergeCells. Locate the cell with tableStartIndex (the table\'s start index in the doc) plus rowIndex/columnIndex (0-based).',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            documentId: z.string().describe('Google Docs document ID'),
+            documentId: z.string().min(1).describe('Google Docs document ID'),
             operation: z.enum(['insertRow', 'insertColumn', 'deleteRow', 'deleteColumn', 'mergeCells', 'unmergeCells']),
             tableStartIndex: z.number().min(1).describe('Start index of the table in the document'),
             rowIndex: z.number().min(0).describe('Target row (0-based)'),
@@ -1103,7 +1105,7 @@ export function registerDocsTools(server) {
         description: 'Add a new tab to a document. Can be a top-level tab or nested as a child of an existing tab.',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            documentId: z.string().describe('Google Docs document ID'),
+            documentId: z.string().min(1).describe('Google Docs document ID'),
             title: z.string().describe('Tab title'),
             parentTabId: z.string().optional().describe('Parent tab ID (omit for top-level)'),
             index: z.number().min(0).optional().describe('Position among siblings'),
@@ -1134,8 +1136,8 @@ export function registerDocsTools(server) {
         description: 'Delete a tab and all of its descendant tabs',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            documentId: z.string().describe('Google Docs document ID'),
-            tabId: z.string().describe('Tab ID'),
+            documentId: z.string().min(1).describe('Google Docs document ID'),
+            tabId: z.string().min(1).describe('Tab ID'),
         },
     }, async ({ account, documentId, tabId }) => {
         try {
@@ -1157,8 +1159,8 @@ export function registerDocsTools(server) {
         description: 'Rename a tab, change its position, or move it under a different parent',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            documentId: z.string().describe('Google Docs document ID'),
-            tabId: z.string().describe('Tab ID'),
+            documentId: z.string().min(1).describe('Google Docs document ID'),
+            tabId: z.string().min(1).describe('Tab ID'),
             title: z.string().optional(),
             index: z.number().min(0).optional(),
             parentTabId: z.string().optional(),
@@ -1182,7 +1184,7 @@ export function registerDocsTools(server) {
                 fields.push('parentTabId');
             }
             if (fields.length === 0) {
-                return { content: [{ type: 'text', text: JSON.stringify({ error: 'No tab property supplied' }) }], isError: true };
+                return invalidParams(account, 'No tab property to update: title, index and parentTabId were all omitted.', 'Pass at least one of: title, index, parentTabId.');
             }
             await docs.documents.batchUpdate({
                 documentId,
@@ -1210,7 +1212,7 @@ export function registerDocsTools(server) {
         description: 'Generic documents.batchUpdate pass-through. Accepts the full Request union (40 types). See https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/request',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            documentId: z.string().describe('Google Docs document ID'),
+            documentId: z.string().min(1).describe('Google Docs document ID'),
             requests: coerceJson(z.array(z.record(z.string(), z.any()))).describe('Array of Request objects, each with one request-type key'),
             writeControl: z.object({
                 requiredRevisionId: z.string().optional(),