> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clickflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Agents

> Synchronous AI tools for titles, meta descriptions, FAQs, images, and competitive analysis.

AI agent tools run synchronously and return results directly. They are slower than data queries (15-60 seconds) because they invoke LLM-powered agents.

## agents\_optimize\_blog\_title

Optimize a blog post title for SEO and click-through rate.

### Parameters

| Name               | Type   | Required | Default | Description                           |
| ------------------ | ------ | -------- | ------- | ------------------------------------- |
| `target_keyword`   | string | Yes      | —       | The keyword to optimize for           |
| `current_title`    | string | Yes      | —       | The existing title                    |
| `content`          | string | No       | `""`    | Page content for better context       |
| `business_context` | string | No       | `""`    | Additional business context           |
| `user_prompt`      | string | No       | `""`    | Custom instructions for the optimizer |

### Response

```json theme={null}
{
  "success": true,
  "error": null,
  "output": {
    "original_title": "CRM Tools Review",
    "optimized_title": "Best CRM for Startups: 7 Tools Compared (2026)",
    "target_keyword": "best CRM for startups",
    "reasoning": "Front-loaded the target keyword for SEO strength...",
    "metrics": {
      "ux_alignment": "High",
      "seo_strength": "High",
      "keyword_integration": "Natural",
      "character_count": 52,
      "estimated_improvement": "80%"
    },
    "alternative_versions": [
      "Top CRM Tools for Startups — Honest Comparison",
      "Which CRM Is Best for Your Startup? We Tested 7"
    ],
    "content_alignment": {
      "matches_numerical_claim": true,
      "identified_sections": 7,
      "suggestion": "Title claim matches content structure"
    }
  }
}
```

### Usage

<Tabs>
  <Tab title="MCP">
    ```json theme={null}
    {
      "target_keyword": "best CRM for startups",
      "current_title": "CRM Tools Review"
    }
    ```
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    curl -X POST https://api.clickflow.com/v1/api/optimize-blog-title \
      -H "Authorization: Bearer cf_ak_your_key_here" \
      -H "Content-Type: application/json" \
      -d '{"target_keyword": "best CRM for startups", "current_title": "CRM Tools Review"}'
    ```
  </Tab>
</Tabs>

<Note>Takes 20-30 seconds.</Note>

***

## agents\_optimize\_meta\_description

Optimize a meta description for SEO and click-through rate. Returns a 150-160 character description.

### Parameters

| Name                  | Type   | Required | Default | Description                   |
| --------------------- | ------ | -------- | ------- | ----------------------------- |
| `target_keyword`      | string | Yes      | —       | The keyword to optimize for   |
| `current_description` | string | Yes      | —       | The existing meta description |
| `content`             | string | No       | `""`    | Page content for context      |
| `business_context`    | string | No       | `""`    | Additional business context   |

### Response

```json theme={null}
{
  "success": true,
  "error": null,
  "output": {
    "original_description": "A review of CRM tools for startups.",
    "optimized_description": "Compare the 7 best CRM tools for startups in 2026. We tested pricing, features, and ease of use to help you pick the right one.",
    "target_keyword": "best CRM for startups",
    "reasoning": "Included target keyword naturally, added specificity with numbers...",
    "metrics": {
      "ux_alignment": "High",
      "seo_strength": "High",
      "keyword_integration": "Natural",
      "character_count": 128,
      "estimated_improvement": "75%"
    },
    "alternative_versions": [
      "Looking for the best CRM for your startup? We compared 7 top tools on pricing, features, and ease of use.",
      "Startup CRM comparison: 7 tools tested side-by-side for pricing, features, and usability in 2026."
    ]
  }
}
```

<Note>Takes 15-25 seconds.</Note>

***

## agents\_generate\_faqs

Generate FAQ question-answer pairs from content. Returns 7 structured pairs optimized for SEO.

### Parameters

| Name      | Type   | Required | Default | Description            |
| --------- | ------ | -------- | ------- | ---------------------- |
| `content` | string | Yes      | —       | The full text content  |
| `title`   | string | No       | `""`    | Page title for context |

### Response

```json theme={null}
{
  "success": true,
  "error": null,
  "output": "[{\"question\": \"What is the best CRM for startups?\", \"answer\": \"The best CRM for startups depends on your team size and budget...\"}]",
  "faqs": [
    {
      "question": "What is the best CRM for startups?",
      "answer": "The best CRM for startups depends on your team size and budget..."
    }
  ]
}
```

<Note>Takes 20-30 seconds.</Note>

***

## agents\_research\_company

Research a company from its website URL. Returns a multi-paragraph text summary covering who they are, their products, target customers, and digital marketing approach.

### Parameters

| Name  | Type   | Required | Description               |
| ----- | ------ | -------- | ------------------------- |
| `url` | string | Yes      | The company's website URL |

### Response

```json theme={null}
{
  "success": true,
  "error": null,
  "output": "Acme Corp is a B2B SaaS company specializing in project management tools for mid-market teams.\n\nTheir core products include TaskFlow (project management) and TeamSync (collaboration suite), serving mid-market B2B companies with 50-500 employees.\n\nTheir primary audience is operations managers and team leads at growing companies who need to streamline workflows.\n\nAcme employs a content-led growth strategy with a strong SEO presence, publishing in-depth guides and comparison content targeting commercial-intent keywords.",
  "result": "Acme Corp is a B2B SaaS company specializing in project management tools..."
}
```

<Note>Takes 20-40 seconds.</Note>

***

## agents\_generate\_image

Generate an image from a text prompt using AI.

### Parameters

| Name      | Type   | Required | Default       | Description                                           |
| --------- | ------ | -------- | ------------- | ----------------------------------------------------- |
| `prompt`  | string | Yes      | —             | Text description of the image                         |
| `style`   | string | No       | `""`          | `stock_photo`, `watercolor`, `illustration`, `sketch` |
| `size`    | string | No       | `"1024x1024"` | Image dimensions                                      |
| `quality` | string | No       | `"standard"`  | Image quality level                                   |

### Response

```json theme={null}
{
  "success": true,
  "error": null,
  "output": {
    "url": "https://storage.googleapis.com/clickflow-images/generated/abc123.png"
  }
}
```

<Note>Takes 20-30 seconds.</Note>

***

## agents\_analyze\_competitors

Analyze top-ranking pages for a keyword. Returns competitive landscape including content gaps, ranking factors, and opportunities.

### Parameters

| Name             | Type   | Required | Default   | Description                |
| ---------------- | ------ | -------- | --------- | -------------------------- |
| `keyword`        | string | Yes      | —         | The keyword to analyze     |
| `analysis_depth` | string | No       | `"basic"` | `basic` or `comprehensive` |

### Response

```json theme={null}
{
  "success": true,
  "error": null,
  "output": {
    "target_keywords": ["best CRM for startups"],
    "competitor_urls": ["https://competitor1.com/crm-guide", "https://competitor2.com/crm-review"],
    "serp_analysis": [
      {
        "keyword": "best CRM for startups",
        "results": [
          {
            "position": 1,
            "title": "Best CRM for Startups of 2026",
            "url": "https://competitor1.com/crm-guide",
            "domain": "competitor1.com",
            "description": "Compare the top CRM tools designed for startup teams...",
            "serp_features": []
          }
        ]
      }
    ],
    "content_gaps": ["Missing pricing comparison table", "No user testimonials section"],
    "competitive_advantages": ["Deeper technical analysis possible", "More recent data available"],
    "content_recommendations": ["Add interactive comparison tool", "Include ROI calculator"],
    "positioning_opportunities": ["Target underserved mid-market segment"],
    "analysis_metadata": {
      "keywords_analyzed": 1,
      "competitors_found": 8,
      "analysis_depth": "basic"
    }
  }
}
```

<Note>Takes 30-60 seconds. `comprehensive` depth takes longer.</Note>

***

## agents\_analyze\_search\_intent

Analyze the search intent behind a keyword. Returns user questions from Google PAA and social sources, grouped by source.

### Parameters

| Name      | Type   | Required | Description            |
| --------- | ------ | -------- | ---------------------- |
| `keyword` | string | Yes      | The keyword to analyze |

### Response

```json theme={null}
{
  "success": true,
  "error": null,
  "output": {
    "questions": [
      {
        "question": "What is the best CRM for small businesses?",
        "source": "paa",
        "answer": "The best CRM depends on your business size and needs...",
        "url": "https://example.com/crm-guide"
      },
      {
        "question": "How much does a CRM cost?",
        "source": "social",
        "answer": "CRM pricing ranges from free to $300/user/month...",
        "url": "https://reddit.com/r/smallbusiness/..."
      }
    ],
    "questions_by_source": {
      "paa": ["What is the best CRM for small businesses?"],
      "social": ["How much does a CRM cost?"]
    },
    "total_count": 2
  }
}
```

<Note>Takes 20-40 seconds.</Note>

***

## Error handling

All agent tools return a consistent shape. On failure:

```json theme={null}
{
  "success": false,
  "error": "Description of what went wrong",
  "output": null
}
```

Agents never return fallback data — they fail explicitly with a clear error message.