"""Informational tools for SERP API."""

from core.server import mcp


@mcp.tool()
async def serp_list_search_types() -> str:
    """List all available Google search types.

    Shows all available search types and their use cases.
    Use this to understand which search type to use for your query.

    Returns:
        Table of all search types with descriptions.
    """
    # Last updated: 2026-04-05
    return """Available Google Search Types:

| Type      | Description                                    | Use Case                           |
|-----------|------------------------------------------------|------------------------------------|
| search    | Regular web search (default)                   | General queries, finding websites  |
| images    | Image search                                   | Finding pictures, photos, graphics |
| news      | News articles                                  | Current events, recent news        |
| maps      | Map/location results                           | Finding locations on maps          |
| places    | Local businesses and places                    | Restaurants, shops, services       |
| videos    | Video results                                  | YouTube, video content             |

Example Usage:
- "What is AI?" → type: search
- "Pictures of cats" → type: images
- "Latest tech news" → type: news
- "Coffee shops near me" → type: places
- "How to cook pasta video" → type: videos
"""


@mcp.tool()
async def serp_list_countries() -> str:
    """List commonly used country codes for Google search.

    Shows common country codes that can be used to localize search results.

    Returns:
        Table of country codes and their countries.
    """
    # Last updated: 2026-04-05
    return """Common Country Codes for Google Search:

| Code | Country           | Code | Country           |
|------|-------------------|------|-------------------|
| us   | United States     | jp   | Japan             |
| uk   | United Kingdom    | kr   | South Korea       |
| cn   | China             | in   | India             |
| de   | Germany           | br   | Brazil            |
| fr   | France            | mx   | Mexico            |
| es   | Spain             | it   | Italy             |
| ca   | Canada            | au   | Australia         |
| ru   | Russia            | nl   | Netherlands       |
| sg   | Singapore         | hk   | Hong Kong         |
| tw   | Taiwan            | th   | Thailand          |

Usage: Pass the country code to the `country` parameter.
Example: serp_google_search(query="news", country="uk")
"""


@mcp.tool()
async def serp_list_languages() -> str:
    """List commonly used language codes for Google search.

    Shows common language codes that can be used to get results in specific languages.

    Returns:
        Table of language codes and their languages.
    """
    # Last updated: 2026-04-05
    return """Common Language Codes for Google Search:

| Code    | Language              | Code    | Language              |
|---------|----------------------|---------|----------------------|
| en      | English              | ja      | Japanese             |
| zh-cn   | Chinese (Simplified) | ko      | Korean               |
| zh-tw   | Chinese (Traditional)| hi      | Hindi                |
| es      | Spanish              | pt      | Portuguese           |
| fr      | French               | ru      | Russian              |
| de      | German               | ar      | Arabic               |
| it      | Italian              | th      | Thai                 |
| nl      | Dutch                | vi      | Vietnamese           |
| pl      | Polish               | tr      | Turkish              |

Usage: Pass the language code to the `language` parameter.
Example: serp_google_search(query="news", language="zh-cn")
"""


@mcp.tool()
async def serp_list_time_ranges() -> str:
    """List available time range filters for Google search.

    Shows all time range options that can be used to filter results by date.

    Returns:
        Table of time range codes and their meanings.
    """
    # Last updated: 2026-04-05
    return """Time Range Filters for Google Search:

| Code    | Time Range   | Description                    |
|---------|--------------|--------------------------------|
| qdr:h   | Past Hour    | Results from the last hour     |
| qdr:d   | Past Day     | Results from the last 24 hours |
| qdr:w   | Past Week    | Results from the last 7 days   |
| qdr:m   | Past Month   | Results from the last 30 days  |
| (none)  | Any Time     | No time restriction (default)  |

Usage: Pass the time range code to the `time_range` parameter.
Example: serp_google_search(query="AI news", time_range="qdr:d")

Note: Time range is most useful for:
- News searches (recent events)
- Trending topics
- Time-sensitive information
"""


@mcp.tool()
async def serp_get_usage_guide() -> str:
    """Get a comprehensive guide for using the Google SERP tools.

    Provides detailed information on how to use the SERP search tools
    effectively, including parameters, examples, and best practices.

    Returns:
        Complete usage guide for SERP tools.
    """
    # Last updated: 2026-04-05
    return """# Google SERP Tools Usage Guide

## Available Tools

### Main Search Tool
**serp_google_search** - Flexible search with all options
- query: Search query (required)
- search_type: search, images, news, maps, places, videos
- country: Country code (us, uk, cn, etc.)
- language: Language code (en, zh-cn, etc.)
- time_range: Time filter (qdr:h, qdr:d, qdr:w, qdr:m)
- number: Results per page (default: 10)
- page: Page number (default: 1)

### Specialized Tools (Shortcuts)
- **serp_google_images** - Image search
- **serp_google_news** - News search
- **serp_google_videos** - Video search
- **serp_google_places** - Local places/businesses
- **serp_google_maps** - Map locations

## Example Usage

### Basic Web Search
```
serp_google_search(query="artificial intelligence")
```

### News Search with Time Filter
```
serp_google_news(query="tech news", time_range="qdr:d")
```

### Localized Search
```
serp_google_search(
    query="best restaurants",
    country="uk",
    language="en"
)
```

### Image Search
```
serp_google_images(query="sunset photography")
```

### Paginated Results
```
serp_google_search(query="python tutorials", number=20, page=2)
```

## Response Contents

### Regular Search (type: search)
- **knowledge_graph**: Entity information (company, person, etc.)
- **answer_box**: Direct answers
- **organic**: Regular search results
- **people_also_ask**: Related questions
- **related_searches**: Related queries

### Image Search (type: images)
- **images**: Image results with URLs and thumbnails

### News Search (type: news)
- **news**: News articles with source and date

### Video Search (type: videos)
- **videos**: Video results with duration and source

### Places Search (type: places)
- **places**: Local business/place information

## Best Practices

1. **Be specific**: More specific queries yield better results
2. **Use localization**: Set country/language for relevant results
3. **Time filtering**: Use for news and current events
4. **Pagination**: Use number/page for browsing many results
5. **Choose right type**: Use specialized types for specific content

## Credits Note
- Standard searches (10 results): 1 credit
- Extended results (>10): May cost additional credits
"""
