find_and_replace_doc
Locate and substitute specific text within a Google Doc. Specify user email, document ID, and text to find and replace. Optionally match case for precise adjustments. Returns replacement count for confirmation.
Instructions
Finds and replaces text throughout a Google Doc.
Args: user_google_email: User's Google email address document_id: ID of the document to update find_text: Text to search for replace_text: Text to replace with match_case: Whether to match case exactly
Returns: str: Confirmation message with replacement count
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | ||
| find_text | Yes | ||
| match_case | No | ||
| replace_text | Yes | ||
| user_google_email | Yes |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- gdocs/docs_tools.py:444-487 (handler)The main handler function for the 'find_and_replace_doc' tool. It is registered via @server.tool(), requires Docs write access, handles the find-and-replace logic using the Google Docs batchUpdate API, and returns the number of replacements made.
@server.tool() @handle_http_errors("find_and_replace_doc", service_type="docs") @require_google_service("docs", "docs_write") async def find_and_replace_doc( service, user_google_email: str, document_id: str, find_text: str, replace_text: str, match_case: bool = False, ) -> str: """ Finds and replaces text throughout a Google Doc. Args: user_google_email: User's Google email address document_id: ID of the document to update find_text: Text to search for replace_text: Text to replace with match_case: Whether to match case exactly Returns: str: Confirmation message with replacement count """ logger.info(f"[find_and_replace_doc] Doc={document_id}, find='{find_text}', replace='{replace_text}'") requests = [create_find_replace_request(find_text, replace_text, match_case)] result = await asyncio.to_thread( service.documents().batchUpdate( documentId=document_id, body={'requests': requests} ).execute ) # Extract number of replacements from response replacements = 0 if 'replies' in result and result['replies']: reply = result['replies'][0] if 'replaceAllText' in reply: replacements = reply['replaceAllText'].get('occurrencesChanged', 0) link = f"https://docs.google.com/document/d/{document_id}/edit" return f"Replaced {replacements} occurrence(s) of '{find_text}' with '{replace_text}' in document {document_id}. Link: {link}" - gdocs/docs_helpers.py:157-181 (helper)Supporting helper function that constructs the exact Google Docs API request object for the replaceAllText operation used by the find_and_replace_doc handler.
def create_find_replace_request( find_text: str, replace_text: str, match_case: bool = False ) -> Dict[str, Any]: """ Create a replaceAllText request for Google Docs API. Args: find_text: Text to find replace_text: Text to replace with match_case: Whether to match case exactly Returns: Dictionary representing the replaceAllText request """ return { 'replaceAllText': { 'containsText': { 'text': find_text, 'matchCase': match_case }, 'replaceText': replace_text } }