Developers Implementation Guides

​

Overview

​

Available Implementation Methods

​

OpenAI Integration

• Automatic tool discovery
• Natural language queries
• Built-in response formatting
• Minimal setup required

• Customer service chatbots
• Sales intelligence assistants
• Automated research agents
• Interactive data exploration

​

Python SDK

• Asynchronous operations
• Full control over tool execution
• Ideal for data pipelines
• Comprehensive error handling

• Data enrichment pipelines
• Batch processing systems
• Custom analytics tools
• Integration with existing Python applications

​

LangGraph Integration

• Stateful conversations
• Multi-step workflows
• Conditional logic
• Tool chaining

​

Quick Comparison

​

Getting Started

​

Prerequisites

1. AgentSource API Key - Get your API key
2. Development Environment - Python 3.8+ recommended
3. Basic Understanding - Familiarity with REST APIs and async programming

​

Core Concepts

​

What is MCP?

• Dynamic Tool Discovery - Tools are discovered at runtime, not hardcoded
• Standardized Interface - Consistent API across all tools
• Type Safety - Structured inputs and outputs
• Streaming Support - Real-time data updates via SSE

​

Available Tool Categories

• Company search and matching
• Firmographic enrichment
• Technology stack analysis
• Financial metrics (public companies)
• Competitive landscape insights

• Employee search by role/department
• Contact information enrichment
• Professional profile data
• Work history and experience
• Social media activity

• Industry trends and statistics
• Company events and news
• Website changes monitoring
• Workforce trend analysis
• Funding and acquisition data

​

Common Use Cases

​

Sales Intelligence

• Identify decision makers at target accounts
• Get verified email addresses and phone numbers
• Monitor job changes and company updates
• Analyze technology stack for better positioning

​

Market Research

• Company segmentation by size, revenue, location
• Technology adoption trends
• Competitive landscape analysis
• Industry-specific insights

​

Lead Enrichment

• Bulk company matching and enrichment
• Contact verification and updates
• Organizational structure mapping
• Technographic segmentation

​

Due Diligence

• Financial metrics and performance
• Leadership and organizational changes
• Technology infrastructure
• Growth indicators and challenges

​

Best Practices for Integrating AgentSource MCP

​

System Prompt Guidelines

The assistant is **AgentSource**, created by Explorium.
Current date: {currentDateTime}

You are an interactive Explorium data agent. Your job is to help users find and research
companies and people using Explorium's B2B data, and to demonstrate that data's value through
accurate, real-time research.

## 1. Tools you have

Business tools:
- `autocomplete` — resolve valid filter values BEFORE filtering. Required before using
  google_category, naics_category, linkedin_category, company_tech_stack_tech,
  business_intent_topics, or job_title.
- `fetch-businesses` — find companies by filters (location, size, revenue, industry category,
  tech stack, intent). Returns business IDs plus minimal fields.
- `enrich-business` — add firmographics, descriptions, financials, tech stack, etc. to business
  IDs returned by fetch-businesses or match-business.
- `match-business` — resolve specific company names/domains to business IDs.
- `fetch-businesses-statistics` — aggregate counts by industry, size, revenue, geography.
- `fetch-businesses-events` — funding, hiring, M&A, and other company events.

Prospect tools:
- `fetch-prospects` — find people at companies by role, department, seniority, location.
- `match-prospects` — resolve specific named people to prospect IDs.
- `enrich-prospects` — add contact details and profile data to prospect IDs.
- `fetch-prospects-statistics`, `fetch-prospects-events` — aggregates and events for people.

## 2. Core workflow

For a list of companies:
  1. Resolve every filter value that needs it with `autocomplete` (industry category, tech,
     intent topics).
  2. Call `fetch-businesses` ONCE with the resolved filters to get business IDs.
  3. Call `enrich-business` on those IDs to get the attributes the user asked for (employee
     count, revenue, description, etc.).

For people at companies: fetch-businesses → fetch-prospects → enrich-prospects.
For a specific named company or person: use match-business / match-prospects first to get the
ID, then enrich.

`fetch-businesses` and `fetch-prospects` return MINIMAL data by design. Missing fields like
revenue or description are EXPECTED, not an error — retrieve them with the matching enrich tool.
Do NOT re-run the search to try to fill them in.

## 3. Filter rules (hard constraints)

- Always call `autocomplete` for valid values before using: google_category, naics_category,
  linkedin_category, company_tech_stack_tech, business_intent_topics, job_title. Pass EVERY
  concept from the user's request into autocomplete.
- Use only ONE industry category type per request — google_category OR naics_category OR
  linkedin_category, never more than one.
- Never use both country_code and region_country_code in the same request.
- Buying intent or interest (e.g. "interested in Salesforce", "evaluating CRM") is NOT an
  industry. Resolve it with `autocomplete` on `business_intent_topics` with semantic_search=true,
  then pass it as the intent filter. Do not try to express intent as an industry category.
- Map fuzzy sizes to the API's buckets (e.g. "50 to 200 employees" → "51-200").

## 4. Loop prevention (important)

- Never call the same tool twice with identical arguments. If you already have a result, use it.
- Make at most ONE attempt to reformulate a search. If a fetch returns zero results, do NOT keep
  retrying with new filter guesses. Stop, tell the user what you searched for, and ask them to
  relax or clarify one constraint.
- If a constraint cannot be expressed with the available filters, say so explicitly instead of
  looping to approximate it.
- Plan the full tool sequence before you start, then execute it once. A normal company-list
  answer is: a few autocomplete calls → one fetch-businesses → one enrich-business → final answer.

## 5. Response style

- Say you're using "Explorium's database" — never expose internal tool or function names to the
  user.
- Write in Markdown. Use a table for multi-row results, e.g.:

  | Company | Location | Employees | Revenue |
  |---------|----------|-----------|---------|
  | …       | …        | …         | …       |

- Keep prose after a table minimal.
- State how many matches were found.
- On a tool error or no data, give a short, honest message (e.g. "I couldn't find companies
  matching all of those criteria — want me to widen the location or drop the intent filter?").
  Do not retry silently.
- Be transparent about gaps: if you couldn't satisfy part of the request (e.g. an intent signal
  wasn't available), say so rather than returning loosely-matching results as if they fit.

## 6. Web usage

Only use the public web if Explorium's data can't answer the question, and tell the user when
you do.

• Replace the date placeholder: Update {currentDateTime} with your actual date/time variable or remove if not needed
• Adjust the identity: Modify “The assistant is AgentSource” to match your agent’s branding
• Tailor the workflow: Add or modify workflow steps based on your specific use case
• Customize response style: Adapt formatting and verbosity requirements to match your application’s UX
• Add domain-specific instructions: Include any industry or use-case specific guidance relevant to your users

​

Model Selection

• Claude 4.6 Sonnet (primary recommendation)

• OpenAI GPT-5.4
• OpenAI GPT-5

​

Model Parameters

• Recommended range: 0.0 - 0.1
• Explorium uses: 0.05
• Why this matters: Higher temperature values may cause the agent to query MCP tools incorrectly or inconsistently

​

Other Parameters

• Max tokens: Set appropriately for your use case - we recommend not limiting the number of tokens.
• Top-p: If used, keep at 0.9 or lower for consistent behavior

​

Prompt Engineering Best Practices

​

Tool Calling Instructions

1. Be explicit about workflow: Clearly define when and how each MCP tool should be used
2. Handle errors gracefully: Provide clear instructions on error handling and fallback behavior

​

Response Formatting

1. Specify output format: Be explicit about Markdown formatting, table usage, and response structure
2. User experience: Include guidelines on when to wait for user input vs. proceeding automatically

​

Testing and Iteration

1. Test common queries: Validate your integration with typical user queries in your domain
2. Edge case testing: Test with complex, multi-filter queries
3. Error scenarios: Verify behavior when API calls fail or return no results
4. Consistency checks: Run the same query multiple times to ensure consistent behavior

1. Monitor tool calling patterns: Ensure the agent is calling tools in the optimal sequence
2. Review response quality: Check that responses are well-formatted and user-friendly
3. Iterate on the system prompt: Refine instructions based on observed agent behavior
4. A/B test variations: Try different prompt formulations to find what works best for your use case

​

Common Pitfalls to Avoid

• ❌ Using high temperature settings (> 0.1)
• ❌ Exposing internal function names in user-facing responses
• ❌ Insufficient error handling instructions
• ❌ Vague or ambiguous workflow instructions

​

Troubleshooting: tool-call loops (“safety limit” / “recursion limit” errors)

​

Symptom

​

What’s actually happening

• LangGraph / LangChain → recursion_limit
• OpenAI Agents SDK → max_turns
• Custom loops → your own iteration counter

​

Common causes

1. An intent/interest constraint is treated as an industry. Requests like “companies interested in Salesforce” describe buying intent, not a firmographic. If the model tries to find an industry category for it, it will autocomplete and re-search repeatedly and never converge. Resolve intent with autocomplete on business_intent_topics (semantic_search=true) and pass it as the intent filter.
2. Industry taxonomy thrash. Only one category type (google_category, naics_category, or linkedin_category) may be used per request. If the model can’t get a clean match from one taxonomy, it may keep switching taxonomies and re-searching. Pin the workflow to a single category type.
3. Empty enrichment fields misread as failure. fetch-businesses and fetch-prospects return minimal data by design — fields like revenue, employee range, and description are empty until you call enrich-business / enrich-prospects. If your prompt doesn’t make the fetch→enrich split explicit, the model may read the sparse result as a failed search and re-query.
4. No “stop” condition on empty results. When a search legitimately returns zero matches, the model will often keep guessing new filter combinations. Instruct it to stop after one reformulation and ask the user to relax a constraint.
5. An outdated or mismatched system prompt. If your prompt references tools that don’t exist on the server, the model can’t find them and improvises in a loop. Make sure your prompt’s tool names match the tools the MCP server actually exposes (autocomplete, fetch-businesses, enrich-business, match-business, fetch-prospects, …).
6. High temperature or a non-recommended model. Temperatures above ~0.1 and non-Claude models produce inconsistent tool calling. Use a low temperature (Explorium uses 0.05) and a Claude Sonnet model.

​

How to prevent it

• Never call the same tool twice with identical arguments.
• Allow at most one search reformulation; on zero results, stop and ask the user to relax a constraint.
• Treat missing fields from fetch tools as expected — enrich, don’t re-fetch.
• Use one industry category type per request; never combine country_code and region_country_code.
• Resolve buying intent via business_intent_topics + semantic_search, not as an industry.

• Keep a sane iteration cap — a correct company-list answer needs only a handful of tool calls (a few autocomplete → one fetch → one enrich).
• Catch the cap and return a friendly message instead of surfacing a raw framework error.

• Temperature 0.0–0.1, Claude Sonnet 4.6 and above, and don’t cap max_tokens.

​

How to debug a loop

1. Log every tool call with its arguments. A loop almost always shows up as the same tool called repeatedly with near-identical inputs — commonly alternating autocomplete ↔ fetch-businesses.
2. Check for an intent phrase being forced into an industry filter (the most common trigger).
3. Confirm your prompt’s tool names match the server’s tools.
4. For real API errors (4xx/5xx), capture the correlation_id from the response and include it when contacting support@explorium.ai.

​

Need Help?

​

Resources

​

Support

• Technical Support: support@explorium.ai
• Community Forum: Coming Soon!

​

What’s Next?

1. Choose your implementation method based on your use case
2. Follow the specific guide for detailed instructions
3. Start with simple queries and gradually increase complexity
4. Join our community to share experiences and get help