/**
* Tool descriptions for Harmonic MCP server.
*
* These descriptions are kept separate for readability and maintainability.
* Each description provides comprehensive documentation for LLMs including:
* - What the tool does
* - Example inputs
* - Return schema
* - When to use / when not to use
* - Error handling guidance
*/
// ============================================================================
// Search Tools
// ============================================================================
export const SEARCH_COMPANIES_DESCRIPTION = `Search for companies using natural language queries. This is the primary entry point for discovering companies.
**What it does:**
Searches Harmonic's database using AI-powered natural language understanding. You can describe what you're looking for in plain English.
**Example queries:**
- "AI startups in San Francisco"
- "fintech companies with Series A funding"
- "B2B SaaS companies founded after 2020"
- "healthcare startups in Boston with 50-100 employees"
**Returns:**
- Company URNs (use harmonic_get_company to get full details)
- Total count of matching companies
- Query interpretation showing how your query was parsed
- Pagination cursor for more results
**Returns (JSON):**
{
"data": [{ "urn": "urn:harmonic:company:123", "id": "123" }],
"count": number,
"totalAvailable": number,
"hasMore": boolean,
"nextCursor": string | null,
"queryInterpretation": { "semantic": string, "faceted": [...] }
}
**Next Steps:**
Use the numeric ID from URN with harmonic_get_company for full company details.`;
export const SEARCH_TYPEAHEAD_DESCRIPTION = `Quick autocomplete search for companies by name or domain. Use this for fast lookups when you know part of the company name.
**What it does:**
Returns company matches ranked by relevance. Lower ranking_score = better match.
**Example queries:**
- "Harmonic" - finds companies with Harmonic in the name
- "stripe.com" - finds by domain
- "Str" - partial name search
**Returns (JSON):**
{
"data": [
{
"entity_urn": "urn:harmonic:company:1",
"text": "Harmonic",
"ranking_score": 10.0
}
],
"count": number
}
**When to use:**
- Quick lookup by known company name
- Autocomplete suggestions
- Finding company by domain
**When NOT to use:**
- Complex searches with multiple criteria (use harmonic_search_companies instead)
- Searching by funding stage, location, etc.`;
export const FIND_SIMILAR_COMPANIES_DESCRIPTION = `Find companies similar to a given company. Core use case for VCs: "I like this company, find me more like it."
**What it does:**
Uses Harmonic's similarity algorithm to find companies with similar characteristics (industry, stage, business model, etc.).
**Input:**
- company_id: Either numeric ID (e.g., "1") or full URN (e.g., "urn:harmonic:company:1")
**Returns (JSON):**
{
"data": ["urn:harmonic:company:763898", "urn:harmonic:company:11578442", ...],
"count": number
}
**Next Steps:**
Use harmonic_get_company with each URN to get full company details.
**Example workflow:**
1. Find a company you like: harmonic_lookup_company with domain
2. Get similar: harmonic_find_similar_companies with that company's ID
3. Get details: harmonic_get_company for each similar company`;
// ============================================================================
// Company Tools
// ============================================================================
export const LOOKUP_COMPANY_DESCRIPTION = `Look up a company by domain, website URL, or social media URL. This is a READ operation (does not create data).
**What it does:**
Finds and enriches a company profile by any of its known identifiers. Returns full company details including funding, headcount, location, and contact info.
**Supported identifiers (use ONE):**
- website_domain: e.g., "harmonic.ai", "stripe.com"
- website_url: Full URL like "https://www.stripe.com"
- linkedin_url: LinkedIn company page
- crunchbase_url: Crunchbase profile
- pitchbook_url: Pitchbook profile
- twitter_url: Twitter/X profile
- instagram_url: Instagram profile
- facebook_url: Facebook page
- angellist_url: AngelList profile
**Returns full company data including:**
- Basic info: name, description, logo
- Contact: emails, primary_email, exec_emails
- Funding: total amount, stage, investors, rounds
- Social: LinkedIn, Twitter with follower counts
- Metrics: headcount, web_traffic
**Example Response (JSON):**
{
"id": 1,
"entity_urn": "urn:harmonic:company:1",
"name": "Harmonic",
"description": "...",
"headcount": 67,
"funding": {
"funding_total": 30150000,
"funding_stage": "SERIES_A",
"investors": [...]
},
"contact": {
"primary_email": "max@harmonic.ai",
"emails": [...]
}
}
**HTTP 404 Note:**
If company not found, Harmonic may trigger background enrichment. Try again later or use a different identifier.`;
export const GET_COMPANY_DESCRIPTION = `Get company details by ID with field filtering for optimal response size.
**Input:**
- company_id: Numeric ID (e.g., "1") or full URN (e.g., "urn:harmonic:company:1")
- include_fields: Optional array of fields to include (e.g., ["name", "funding", "headcount"])
**Response sizes:**
- Default (basic fields): ~3KB per company
- All fields: ~368KB per company (not recommended)
**Default fields returned:**
name, description, website, headcount, location, funding, stage, founding_date, company_type, customer_type, contact, socials
**When to use:**
- After harmonic_search_companies to get full details
- After harmonic_find_similar_companies
- When you have a company ID from another source
**Note:** Uses batch endpoint internally for proper field filtering. The GET endpoint ignores include_fields.`;
export const GET_COMPANY_EMPLOYEES_DESCRIPTION = `Get employees of a company with filtering options.
**Input:**
- company_id: Numeric ID or URN
- employee_group_type: Filter by role (ALL, FOUNDERS_AND_CEO, EXECUTIVES, FOUNDERS, LEADERSHIP, NON_LEADERSHIP, ADVISORS, NON_PARTNERS)
- employee_status: Filter by status (ACTIVE, NOT_ACTIVE, ACTIVE_AND_NOT_ACTIVE)
Note: Filter values confirmed via API testing. Documentation had incorrect values (EMPLOYEES, CURRENT, PAST do not work).
**Returns:**
Person URNs that you can use with harmonic_get_person to get full details.
**Example Response (JSON):**
{
"data": [
{ "urn": "urn:harmonic:person:113554", "id": "113554" },
{ "urn": "urn:harmonic:person:155348322", "id": "155348322" }
],
"count": 72,
"hasMore": false
}
**Common workflows:**
1. Get founders: employee_group_type="FOUNDERS_AND_CEO"
2. Get leadership: employee_group_type="LEADERSHIP"
3. Get former employees: employee_status="NOT_ACTIVE"`;
export const GET_COMPANY_CONNECTIONS_DESCRIPTION = `Find which team members have connections to a company. Key for warm introductions in VC deal flow.
**What it does:**
Returns your team's network connections to people at the target company, showing who knows whom and how they're connected.
**Returns:**
{
"data": [
{
"user_urn": "urn:harmonic:user:17115",
"target_person_urn": "urn:harmonic:person:73639745",
"target_person_email_address": "mike@harmonic.ai",
"connection_sources": ["EMAIL", "LINKEDIN"]
}
]
}
**Connection sources:**
- EMAIL: Connected via email correspondence
- LINKEDIN: LinkedIn connection
- CALENDAR: Met via calendar events
**Use case:**
Before reaching out to a company, find if anyone on your team has a warm intro path.`;
// ============================================================================
// Person Tools
// ============================================================================
export const LOOKUP_PERSON_DESCRIPTION = `Look up a person by their LinkedIn URL. This is a READ operation (does not create data).
**What it does:**
Finds and enriches a person's profile by their LinkedIn URL. Returns full profile including work history, education, contact info, and social links.
**Input:**
- linkedin_url: Full LinkedIn profile URL (e.g., "https://linkedin.com/in/username")
**Returns:**
{
"id": 161780079,
"entity_urn": "urn:harmonic:person:161780079",
"full_name": "Max Ruderman",
"contact": {
"emails": ["max@harmonic.ai"],
"primary_email": "max@harmonic.ai"
},
"location": {
"city": "New York",
"state": "New York",
"country": "United States"
},
"education": [
{
"school": { "name": "Cornell University" },
"degree": "Bachelor of Science (B.S.)",
"field": "Labor and Industrial Relations"
}
],
"experience": [
{
"title": "Chief Executive Officer",
"company": "urn:harmonic:company:1",
"company_name": "Harmonic",
"is_current_position": true,
"start_date": "2022-07-01T00:00:00Z"
}
]
}
**HTTP 404 Note:**
If person not found, Harmonic may trigger background enrichment. Try again later.
**Use cases:**
- Research a founder or executive before a meeting
- Find contact information for outreach
- Verify a person's current role and company`;
export const GET_PERSON_DESCRIPTION = `Get full person details by ID. Use after getting person URNs from company employees.
**Input:**
- person_id: Numeric ID (e.g., "161780079") or full URN (e.g., "urn:harmonic:person:161780079")
**Returns same data as harmonic_lookup_person:**
- Full name and profile picture
- Contact info (emails)
- Location
- Education history
- Work experience with company links
**When to use:**
- After harmonic_get_company_employees to get full details on each person
- When you have a person ID from another Harmonic response
- To expand on a person URN from search results`;
// ============================================================================
// Saved Search Tools
// ============================================================================
export const LIST_SAVED_SEARCHES_DESCRIPTION = `Get all saved searches accessible to your Harmonic account. Saved searches enable monitoring deal flow and tracking companies over time.
**What it does:**
Returns all saved searches (also called "Saved Views" in Harmonic UI) that your team has created. Each saved search has specific filter criteria.
**Returns:**
{
"data": [
{
"id": 141648,
"name": "Stealth Feed",
"type": "COMPANIES_LIST",
"is_private": false,
"created_at": "2024-10-10T18:48:38.438102",
"updated_at": "2025-06-16T00:53:15.505131"
}
],
"count": number
}
**Search types:**
- COMPANIES_LIST: Search for companies
- PERSONS: Search for people
**Next steps:**
Use harmonic_get_saved_search_results with the search ID to get matching companies/persons.
**Use cases:**
- List all team deal flow monitors
- Find a specific saved search by name
- Check when a search was last updated`;
export const GET_SAVED_SEARCH_RESULTS_DESCRIPTION = `Get results from a saved search. Returns full company/person data matching the search criteria.
**WARNING: Response sizes are LARGE:**
- size=3 (default): ~81KB
- size=5 (max): ~135KB
Field filtering does NOT work on this endpoint. Each result contains full company data (~27KB).
Use pagination (cursor) for more results rather than large sizes.
**Input:**
- search_id: The saved search ID (get from harmonic_list_saved_searches)
- size: Number of results (default: 3, max: 5)
- cursor: Pagination cursor for more results
**Returns (for COMPANIES_LIST type):**
{
"data": [
{
"id": 65200417,
"name": "Stealth Company (John Smith)",
"description": "...",
"headcount": 1,
"funding": {
"funding_total": 0,
"funding_stage": "STEALTH"
},
"location": {
"city": "San Francisco",
"country": "United States"
},
"contact": {
"primary_email": "john@example.com"
}
}
],
"count": number,
"totalAvailable": number,
"hasMore": boolean,
"nextCursor": string | null
}
**Use cases:**
- Monitor deal flow with pre-defined criteria
- Get companies matching specific investment thesis
- Track stealth companies or recent launches`;
export const GET_SAVED_SEARCH_NET_NEW_RESULTS_DESCRIPTION = `Get only NEW results from a saved search since your last check. This is the incremental/delta endpoint for monitoring deal flow.
**PREREQUISITE:** You must subscribe to the saved search via Harmonic web UI first. Returns 404 if not subscribed.
**What "net new" means:**
Returns companies/people that have NEWLY matched your search criteria since you subscribed (or since new_results_since date). For example, if your search looks for companies with >100 headcount, this returns companies that recently grew past 100.
**Input:**
- search_id: The saved search ID (get from harmonic_list_saved_searches)
- size: Number of results (default: 3, max: 5)
- cursor: Pagination cursor for more results
- new_results_since: Optional UTC datetime (e.g., 2024-09-21T00:00:00Z)
**Response sizes:** ~27KB per result (same as regular results)
**Workflow:**
1. Call this tool to get new matches
2. Process the results
3. Call harmonic_clear_saved_search_net_new to mark as "seen"
4. Repeat on your monitoring schedule
**Use cases:**
- Daily deal flow monitoring for investors
- Trigger deep research agents on new matches
- Alert on companies meeting investment criteria`;
export const CLEAR_SAVED_SEARCH_NET_NEW_DESCRIPTION = `Mark all net new results as "seen" so they won't appear in future calls to harmonic_get_saved_search_net_new_results.
**When to use:**
Call this AFTER you've processed net new results to reset the queue. Future calls to harmonic_get_saved_search_net_new_results will only return results that become new matches after this point.
**Input:**
- search_id: The saved search ID
**Workflow:**
1. harmonic_get_saved_search_net_new_results → get new matches
2. Process/analyze the results
3. harmonic_clear_saved_search_net_new → mark as seen
4. Repeat on schedule`;
