Tool_code investigation for Gemini

I’ve asked Gemini to return the full list of the tool_code for Google Search. (se work by Dan Petrovic)

When we talk about the “full list” of objects within GoogleSearch as used by tool_code, it’s important to clarify the distinction between:

1. What’s explicitly returned and structured by the tool_code output I show you: This is the most direct answer to your question.
2. All possible data fields that could theoretically be part of a raw, comprehensive Google Search API response: This includes fields that might be present in a deeper, more granular API interaction but are often simplified or not directly exposed in the tool_code output I display.

Let’s break down the “full list” with this distinction in mind.

I. Objects Explicitly and Commonly Returned via tool_code

These are the objects and their key attributes that you will most frequently see in the tool_code output generated by me:

1. GoogleSearch.SearchResults
   • Purpose: The primary container for all results of a search action.
   • Attributes:
     • query (string): The exact query string(s) that were executed.
     • results (list of GoogleSearch.PerQueryResult): The core list of individual search results.
2. GoogleSearch.PerQueryResult
   • Purpose: Represents a single, distinct search result.
   • Attributes:
     • index (string): A unique identifier (e.g., “1.1”, “1.2”) for the result within the overall search.
     • snippet (string): A brief descriptive summary of the webpage’s content.
     • source_title (string): The title of the website or publication (e.g., “Wikipedia”, “The New York Times”).
     • url (string): The full URL of the webpage.
     • publication_time (string, optional): The time or date the content was published, if available (e.g., “2 days ago”, “May 27, 2025”). This is very frequently present and useful for timeliness.
     • image_url (string, optional): A URL to an image associated with the result, if prominent (e.g., for news articles with a featured image, or sometimes in image-heavy searches).
     • display_url (string, optional): A simplified or more user-friendly version of the url (e.g., “example.com” instead of “https://www.example.com/some/path“).

II. Potential / Less Commonly Exposed / Internal Objects & Fields

These are attributes or objects that might exist in a more comprehensive Google Search API response, or are implicitly handled by my internal logic but not always surfaced in the structured tool_code output I show you:

• GoogleSearch.ImageResult (Conceptual / Less Common in General Web Search tool_code):
  • Purpose: If the search was specifically for images, or if a very prominent image is the primary result, this might be a distinct object. In my current tool_code display for general web search, image_url within PerQueryResult is more common.
  • Possible Attributes:
    • thumbnail_url (string)
    • full_size_image_url (string)
    • width (int)
    • height (int)
    • alt_text (string)
    • source_url (string)
• GoogleSearch.VideoResult (Conceptual / Less Common):
  • Purpose: For video search results (e.g., YouTube videos).
  • Possible Attributes:
    • title (string)
    • url (string)
    • thumbnail_url (string)
    • duration (string)
    • channel_name (string)
    • views (int)
    • upload_date (string)
• GoogleSearch.NewsArticleResult (Conceptual / Less Common):
  • Purpose: Specifically structured for news articles.
  • Possible Attributes:
    • title (string)
    • url (string)
    • publisher (string)
    • published_date (string)
    • authors (list of strings)
    • image_url (string)
• GoogleSearch.KnowledgePanelResult (Conceptual / Less Common):
  • Purpose: Represents information from a Google Knowledge Panel (the information box often shown on the right side of search results for entities like people, places, or things). This is often synthesized by me from multiple search results rather than returned as a single distinct object via tool_code.
  • Possible Attributes:
    • title (string)
    • description (string)
    • attributes (list of key-value pairs for facts)
    • image_url (string)
    • links (list of URLs to official sites/related entities)
• Metadata / Pagination / Status Fields (Internal to API but not usually exposed):
  • status_code (int): HTTP status code of the API call.
  • error_message (string): If an error occurred.
  • total_results (int): The total number of results found by Google, not just those returned.
  • start_index (int): The starting index of the current batch of results.
  • next_page_token (string): A token to retrieve the next set of results for pagination.
  • search_time (float): Time taken to execute the search query.

When I use tool_code for Google Search, I’m primarily focused on extracting the most relevant and immediate information needed to answer your query. This means I’ll leverage the snippet, source_title, url, publication_time, and sometimes image_url from the PerQueryResult objects, which are the most universally useful data points. The other conceptual objects represent more specialized search types or deeper API structures that aren’t typically summarized in the tool_code output you directly observe.

You’re diving into the structured data that comes back from the Google Search tool! This is excellent for understanding how I process and utilize information.

Based on the common patterns of Google Search API responses and what I’ve observed in my own internal workings, here are the likely objects and their key attributes you’d encounter:

Primary GoogleSearch Objects

1. GoogleSearch.SearchResults (The top-level container)
   • Purpose: This object holds all the results for a particular set of queries that were executed by the Google Search tool. It’s the overall response for a search action.
   • Attributes:
     • query (string): The original query string (or a representation of the queries) that was passed to the Google Search tool. This is useful when multiple queries are executed in a single tool_code block.
     • results (list of GoogleSearch.PerQueryResult objects): This is the most important attribute. It contains a list of individual search results, each represented by a PerQueryResult object.
2. GoogleSearch.PerQueryResult (Individual Search Result)
   • Purpose: Represents a single, distinct search result returned by Google.
   • Attributes:
     • index (string): A unique identifier for the search result within the context of the overall SearchResults. It often follows a “query_index.result_index” format (e.g., “1.1”, “1.2”, “2.1”), which helps me internally track which result came from which original query if multiple were made.
     • snippet (string): A concise summary or description of the content found at the url. This is what’s often displayed below the title in standard Google search results.
     • source_title (string): The title of the webpage or publication where the result was found (e.g., “Wikipedia”, “The New York Times”, “developers.google.com”).
     • url (string): The full URL of the webpage or resource associated with the search result.
     • publication_time (string, optional): The time or date when the content was published, if available. This can be in various formats (e.g., “2 days ago”, “Monday, May 26, 2025 at 3:00:00 AM”). This is incredibly useful for providing timely information.
     • image_url (string, optional): For image search results, or results with prominent images, this might contain a direct URL to the image. (Less common in general web search results unless explicitly a visual search).
     • rating (float, optional): Some APIs might provide a relevance score or rating for the search result. (Less commonly exposed directly in the simplified GoogleSearch tool I use for general purposes).
     • display_url (string, optional): A more user-friendly version of the URL, sometimes truncated.

Other Potential (Less Common or Internal) Objects/Parameters

While not always directly exposed or used in every interaction, these concepts are part of how search APIs work and how I might leverage them:

• Query Parameters within Google Search: When I construct a search query, I’m effectively setting parameters even if you only see queries=['your search term']. Behind the scenes, these might include:
  • num_results: How many results to fetch (e.g., 10, 20).
  • lang: Language of the search results (e.g., ‘en’, ‘es’).
  • safe_search: Filtering for explicit content.
  • site_filter: Limiting results to a specific website (e.g., site:example.com).
  • date_restrict: Limiting results by publication date (e.g., ‘past-month’).
  • tld (Top Level Domain): e.g., ‘com’, ‘co.uk’.