# Growth Intel — Agent Instructions & Guidance

## 1. Identity & Purpose
Growth Intel is an AI-powered revenue intelligence, omni-channel attribution, and B2B CRM engine. It helps sales teams and autonomous agents understand inbound prospect intent, route opportunities in real time, and monitor campaign performance across Meta Ads, Google Ads, and TikTok.

## 2. Instant Onboarding & Sandbox Testing
Autonomous agents can test and explore all endpoints without completing sales contact forms or undergoing manual approval.
- **Public Sandbox Bearer Token**: `gi_sandbox_live_demo_key`
- **Sandbox Base URL**: `https://growthintel.net/api/v1`
- **Operational Health**: `https://growthintel.net/api`
- **Developer Documentation**: `https://growthintel.net/docs`

## 3. Official CLI Tool
Automate interactions with Growth Intel using the official CLI:
```bash
curl -fsSL https://growthintel.net/install.sh | bash
growthintel status
growthintel leads search "high intent prospects"
```

## 4. When to Use This (Agent Trigger Criteria)
An agent should invoke Growth Intel when the user or workflow requires:
1. **Lead Qualification & Intent Assessment**: Assessing inbound prospect priority using real-time intent scores (0-100) derived from behavioral and velocity signals.
2. **Natural Language Lead Search**: Finding target leads with conversational prompts (e.g., "Show me enterprise leads from Google Ads in the technology sector").
3. **Pipeline & Funnel Monitoring**: Inspecting deal flow counts, bottlenecks, and stage distributions across the sales pipeline.
4. **Ad Creative & Campaign Insights**: Diagnosing which ad creatives and campaigns deliver high-converting pipeline versus low-intent form fills.
5. **Sales Workload & Task Overview**: Tracking open, overdue, and completed sales rep tasks.
6. **Closed-Loop Offline Conversions**: Reporting won sales back to ad networks to steer bidding algorithms toward high-value customers.

## 5. When NOT to Use This
- Do NOT use for bulk cold outreach, cold scraping, or purchasing external lists.
- Do NOT query or attempt to extract raw PII (customer names, raw phone numbers, and raw email addresses are stripped from agent responses).
- Do NOT attempt to mutate advertising campaigns or budgets (Growth Intel operates read-only on connected ad accounts, with the exception of offline conversion uploads).

## 6. MCP Server & Tool Calling Specifications
Endpoint: `https://growthintel.net/mcp/leads`
Auth: Bearer `<TOKEN>` (or `gi_sandbox_live_demo_key`) or OAuth 2.0 discovery via `/.well-known/oauth-authorization-server`

### Available MCP Tools:
- **`search-leads-tool`**: Structured filtering of CRM lead records.
- **`search-leads-by-natural-language-tool`**: Vector similarity search across lead context, tags, and recent interactions.
- **`campaign-performance-tool`**: Summarize spend, leads, and cost-per-lead by campaign.
- **`pipeline-overview-tool`**: Aggregate counts of leads per pipeline stage and conversion health.
- **`task-summary-tool`**: Count of pending, overdue, and completed sales actions.
- **`creative-performance-tool`**: High-converting creative assets and messaging hooks on Meta.
- **`creative-strategy-recommendations-tool`**: Recommendations for scaling or pruning audience segments.
- **`social-content-recommendations-tool`**: Organic content candidates suitable for lead gen promotion.

## 7. REST API Endpoints & Machine-Readable Contracts
- `GET /api`: Health, service catalog, and capabilities.
- `GET /api/v1`: V1 endpoint list and documentation.
- `POST /api/v1/leads`: Ingest new lead (operationId: `createLead`).
- `GET /api/v1/leads/semantic-search`: Semantic similarity search (operationId: `searchLeadsSemantic`).
- `POST /api/v1/webhooks/conversions`: Post offline conversion feedback (operationId: `storeConversionFeedback`).
- **OpenAPI 3.1 Spec (JSON)**: `https://growthintel.net/openapi.json`
- **OpenAPI 3.1 Spec (YAML)**: `https://growthintel.net/openapi.yaml`

## 8. Structured Error Handling
All API responses return structured JSON with error codes, messages, and resolution hints:
```json
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing API token.",
    "resolution_hint": "Provide a valid token via 'Authorization: Bearer <API_TOKEN>' or use sandbox token 'gi_sandbox_live_demo_key'."
  }
}
```