@@ -1,6 +1,6 @@
 # LlamaIndex Tools Integration: Serpex
 
-Search the web from a LlamaIndex agent with [Serpex](https://serpex.dev), a real-time web search API for AI agents and data enrichment. Each search returns ranked web results (title, URL and snippet) as LlamaIndex `Document` objects.
+Search the web from a LlamaIndex agent with [Serpex](https://serpex.dev), a real-time web search API for AI agents. Each search returns ranked web results (title, URL and snippet), optionally with the top pages' content as markdown, as LlamaIndex `Document` objects.
 
 ## Installation
 
@@ -11,35 +11,75 @@ pip install llama-index-tools-serpex
 ## Usage
 
 ```python
+import asyncio
+
+from llama_index.core.agent.workflow import FunctionAgent
+from llama_index.llms.openai import OpenAI
 from llama_index.tools.serpex import SerpexToolSpec
-from llama_index.agent.openai import OpenAIAgent
 
-# Initialize the tool
 serpex_tool = SerpexToolSpec(api_key="your_serpex_api_key")
 
-# Create agent with the tool
-agent = OpenAIAgent.from_tools(serpex_tool.to_tool_list(), verbose=True)
-
-# Use the agent
-response = agent.chat("What are the latest AI developments?")
-print(response)
+agent = FunctionAgent(
+    tools=serpex_tool.to_tool_list(), llm=OpenAI(model="gpt-4.1")
+)
+print(asyncio.run(agent.run("What are the latest AI developments?")))
 ```
 
+The agent sees one tool, `search(query, num_results)`.
+
 ### Search directly
 
 ```python
-# Search with a time filter
-results = serpex_tool.search(
-    "recent AI news",
-    num_results=10,
-    time_range="day",  # 'day', 'week', 'month', 'year'
-)
+results = serpex_tool.search("recent AI news after:2026-09-01", num_results=5)
 
 for doc in results:
     print(doc.metadata["title"], doc.metadata["url"])
 ```
 
-The `engine` argument is deprecated. It is still accepted so existing code keeps working, but the Serpex API ignores it and routes every search itself.
+Search operators go inside the query: `site:example.com`, `-site:example.com`,
+`after:YYYY-MM-DD` and `before:YYYY-MM-DD`. `num_results` (1 to 10) limits how many
+results are returned; the API returns at most 10.
+
+### Page content
+
+```python
+serpex_tool = SerpexToolSpec(include_content=True, content_results=5)  # or 10
+docs = serpex_tool.search("what is retrieval augmented generation")
+```
+
+The first `content_results` documents carry the page markdown after the snippet. A page that
+could not be fetched keeps only the snippet and has `metadata["content_error"]` (for example
+`"robots_disallowed"`). Credits: 1 per search; with page content, 1 when no page came back, 3 for
+1-5 pages, 6 for 6-10 pages.
+
+### Document metadata
+
+`title`, `url`, `snippet`, `position`, `number_of_results`, `response_time`, `credits_used`,
+`query`, plus `content_error` when a page could not be fetched. `engine` is deprecated and always
+`"auto"`.
+
+### Errors
+
+A failed request raises `SerpexAPIError`, a subclass of `requests.exceptions.HTTPError`, whose
+message says what happened, whether it was charged and whether to retry:
+
+| Status | Example message                                                                                             |
+| ------ | ----------------------------------------------------------------------------------------------------------- |
+| 400    | `Serpex rejected the request (HTTP 400): content_results must be 5 or 10.`                                  |
+| 401    | `Serpex rejected the API key (HTTP 401): Invalid or inactive API key. Check SERPEX_API_KEY.`                |
+| 402    | `Out of Serpex credits (HTTP 402). Balance: 0 credits. Top up at https://app.serpex.dev/dashboard/billing.` |
+| 429    | `Serpex rate limit exceeded (limit: 5 requests per second). Retry in 292 ms.`                               |
+| 5xx    | `Serpex is temporarily unavailable (HTTP 503): ... Not charged.`                                            |
+
+`SerpexAPIError` also carries `status_code`, `details` (the API's error body) and `retryable`.
+Rate limits are 5, 25 or 50 requests per second depending on the plan.
+
+### Deprecated arguments
+
+`engine` (constructor and `search()`) and `time_range` (`search()`) are deprecated and ignored
+by the Serpex API. They are still accepted so existing code keeps working, emit a
+`DeprecationWarning` and are not sent. For a date filter, put `after:YYYY-MM-DD` /
+`before:YYYY-MM-DD` in the query.
 
 ## API Key
 
@@ -51,13 +91,6 @@ Set it as an environment variable:
 export SERPEX_API_KEY=your_api_key
 ```
 
-## Features
-
-- **Real-time results**: live web results for every query
-- **Time filtering**: day, week, month or year
-- **Structured data**: clean JSON, returned as LlamaIndex `Document` objects
-- **Pay per use**: 1 credit per search; failed requests are not charged
-
 ## Links
 
 - [Serpex website](https://serpex.dev)
 
@@ -1,112 +1,93 @@
-"""Example usage of SERPEX tool with LlamaIndex."""
+"""Example usage of the Serpex tool with LlamaIndex."""
 
 import os
 
 from llama_index.tools.serpex import SerpexToolSpec
 
-# Set your API key (or use environment variable SERPEX_API_KEY)
-os.environ["SERPEX_API_KEY"] = "your_api_key_here"
 
-
-def basic_search_example():
-    """Basic search example."""
+def basic_search_example() -> None:
+    """Basic search: title, URL and snippet per result."""
     print("=" * 60)
     print("Basic Search Example")
     print("=" * 60)
 
-    # Initialize tool
     tool = SerpexToolSpec()
-
-    # Perform search
     results = tool.search("latest developments in artificial intelligence", num_results=5)
 
     for doc in results:
         print(doc.text)
     print()
 
 
-def location_search_example():
-    """Location-based search example."""
+def operators_example() -> None:
+    """Search operators go inside the query: site:, -site:, after:, before:."""
     print("=" * 60)
-    print("Location-Based Search Example")
+    print("Search Operators Example")
     print("=" * 60)
 
-    # Initialize tool
     tool = SerpexToolSpec()
-
-    # Search with location
-    results = tool.search_with_location(
-        query="best Italian restaurants", location="San Francisco, CA", num_results=5
-    )
+    query = "llamaindex release notes site:github.com after:2026-09-01"
+    results = tool.search(query, num_results=5)
 
     for doc in results:
-        print(doc.text)
+        print(doc.metadata["title"], doc.metadata["url"])
     print()
 
 
-def international_search_example():
-    """International search with country and language."""
+def page_content_example() -> None:
+    """Also fetch the top pages as markdown (3 credits for 5 pages, 6 for 10)."""
     print("=" * 60)
-    print("International Search Example")
+    print("Page Content Example")
     print("=" * 60)
 
-    # Initialize tool
-    tool = SerpexToolSpec()
-
-    # Search with country and language
-    results = tool.search(
-        query="noticias de tecnología",
-        num_results=5,
-        gl="es",  # Spain
-        hl="es",  # Spanish
-    )
+    tool = SerpexToolSpec(include_content=True, content_results=5)
+    results = tool.search("what is retrieval augmented generation", num_results=5)
 
     for doc in results:
-        print(doc.text)
+        if "content_error" in doc.metadata:
+            print(f"{doc.metadata['url']}: no content ({doc.metadata['content_error']})")
+        else:
+            print(f"{doc.metadata['url']}: {len(doc.text)} characters")
     print()
 
 
-def agent_example():
-    """Example with LlamaIndex agent."""
+def agent_example() -> None:
+    """Example with a LlamaIndex agent."""
     print("=" * 60)
     print("Agent Example")
     print("=" * 60)
 
     try:
-        from llama_index.agent.openai import OpenAIAgent
+        from llama_index.core.agent.workflow import FunctionAgent
         from llama_index.llms.openai import OpenAI
-
-        # Initialize SERPEX tool
-        serpex_tool = SerpexToolSpec()
-
-        # Create agent
-        llm = OpenAI(model="gpt-4")
-        agent = OpenAIAgent.from_tools(serpex_tool.to_tool_list(), llm=llm, verbose=True)
-
-        # Ask question that requires web search
-        response = agent.chat(
-            "What are the latest features announced for LlamaIndex? Search the web for recent news."
-        )
-        print(response)
-
     except ImportError:
         print("OpenAI dependencies not installed. Install with:")
-        print("pip install llama-index-agent-openai llama-index-llms-openai")
+        print("pip install llama-index-llms-openai")
+        return
+
+    import asyncio
+
+    agent = FunctionAgent(
+        tools=SerpexToolSpec().to_tool_list(),
+        llm=OpenAI(model="gpt-4.1"),
+    )
+    response = asyncio.run(
+        agent.run("What are the latest features announced for LlamaIndex? Search the web.")
+    )
+    print(response)
     print()
 
 
-def main():
+def main() -> None:
     """Run all examples."""
-    # Make sure API key is set
     if not os.environ.get("SERPEX_API_KEY"):
         print("Please set SERPEX_API_KEY environment variable")
         print("Get your API key at: https://serpex.dev/dashboard")
         return
 
-    # Run examples
     basic_search_example()
-    location_search_example()
-    international_search_example()
+    operators_example()
+    page_content_example()
     agent_example()