Research Integration

Overview

The research integration provides higher-level web research capabilities for topics, contacts, and competitive analysis.

web.research API

@mcp.tool()
async def research(
    topic: str,
    depth: str = 'standard',
    context: dict = None
) -> dict:
    """Research a topic using web intelligence.

    Args:
        topic: What to research (person, company, concept)
        depth: Research depth level
        context: Additional context (location, industry, etc.)

    Returns:
        Structured research results with entities and confidence
    """

Depth Levels

Level	Description	Use Case
basic	Quick search, top results	Friends, family contacts
standard	Multi-source, cross-reference	Leads, vendors, partners
deep	Comprehensive, competitor analysis	Clients, pending clients

basic

Single search query
Top 3-5 results
Basic entity extraction
~5-10 seconds

standard

Multiple search queries
10-20 results analyzed
Cross-reference validation
Entity relationship mapping
~30-60 seconds

deep

Comprehensive search strategy
50+ results analyzed
Competitor identification
Market position analysis
Social presence scan
~2-5 minutes

Contact Enrichment Mapping

When enriching contacts, depth is determined by category:

Category	Depth	Rationale
CLIENT	deep	Full business intelligence needed
PENDING_CLIENT	deep	Sales prep requires comprehensive data
LEAD	standard	Qualification data, not full analysis
VENDOR	standard	Service verification, basic background
PARTNER	standard	Collaboration context
FRIEND	basic	Simple contact verification
FAMILY	skip	No business research needed

Output Structure

{
  "topic": "Chris Ravsten Retirement Planning Resources",
  "depth": "deep",
  "entities": {
    "person": {
      "name": "Chris Ravsten",
      "title": "President",
      "confidence": 0.95
    },
    "company": {
      "name": "Retirement Planning Resources, Inc.",
      "address": "7200 S Alton Way, Suite A250, Centennial, CO 80112",
      "phone": "(720) 536-4961",
      "website": "https://www.RetirePR.com",
      "confidence": 0.98
    },
    "competitors": [
      {"name": "A&I Wealth Management", "location": "Lone Tree, CO"},
      {"name": "Wealth Enhancement Group", "location": "Centennial, CO"}
    ]
  },
  "sources": ["bbb.org", "linkedin.com", "yellowpages.com"],
  "confidence_overall": 0.92,
  "researched_at": "2026-01-08T12:00:00Z"
}

Integration with Contact Enrichment Protocol

Contact created with category
web.research called with appropriate depth
Results structured and stored in contact notes
Competitors saved to contact metadata
Sources documented for audit trail