Skip to main content
The deep_research endpoint is an intelligent code analysis agent that goes beyond simple search to provide comprehensive understanding of your codebase. Think of it as having a senior architect who has thoroughly studied every line of your code and can answer complex questions about architecture, patterns, and implementation strategies.

​
Key features

  • Code understanding: Comprehends code logic, architecture, and design patterns.
  • Cross-repository analysis: Can analyze relationships between different parts of your codebase.
  • Implementation planning: Helps plan new features based on existing code patterns.
  • Best practice recommendations: Suggests improvements based on codebase analysis.
  • Architecture insights: Provides high-level understanding of system design.

​
API/MCP reference

​
Request format

{
  "tool": "deep_research",
  "parameters": {
    "input": "How does the authentication flow work across our microservices? What security measures are in place?",
    "repositories": ["backend/api", "frontend/app"],  // Repos to analyze
    "session_id": "analysis-123"                      // Track conversation context
  }
}

​
Parameters

ParameterTypeRequiredDescription
inputstringYesYour question or research query. Be specific and detailed for best results.
repositoriesarrayNoList of repository identifiers to scope the search. Format: org/repo
session_idstringNoUnique identifier to maintain context across multiple queries in a conversation.

​
Best practices

  • Be specific and detailed - “How does user authentication work across our microservices?” provides richer insights than general queries
  • Include context about your goals - Mentioning why you need the information helps Deep Research tailor its analysis
  • Leverage session_id for complex investigations - Build on previous queries to dive deeper into specific areas
  • Specify repositories for focused analysis - When you know which repos are relevant, include them for more targeted results
  • Ask ‘why’ and ‘how’ questions - Deep Research excels at explaining design decisions and implementation reasoning

​
Avoid

  • Asking for simple keyword searches, use get_context instead
  • Asking the agent to modify your code, deep-research analyzes, and suggest code, it will not modify files
  • Asking about external services not in your codebase\s
  • Don’t use for real-time data - it analyzes code structure, not runtime behavior

​
Pattern 1: Architecture discovery

When to use: Understanding how your system works
{
  "input": "Explain our payment processing architecture. How do orders flow from the frontend through our services to the payment gateway?",
  "repositories": ["acme/frontend", "acme/api-gateway", "acme/payment-service"]
}
Returns: Complete flow diagram in text, service interactions, data transformations, error handling paths

​
Pattern 2: Security audit

When to use: Evaluating security implementation
{
  "input": "Analyze our JWT authentication implementation. Are we following security best practices? What vulnerabilities might exist?",
  "repositories": ["acme/auth-service", "acme/api-gateway"]
}
Returns: Security analysis, best practice violations, specific vulnerabilities, improvement recommendations

​
Pattern 3: Feature planning

When to use: Before implementing new features
{
  "input": "We need to add real-time notifications. Based on our current architecture, where should this be implemented and what patterns should we follow?",
  "repositories": ["acme/backend", "acme/frontend", "acme/websocket-service"]
}
Returns: Implementation strategy, integration points, consistent patterns to follow, potential challenges

​
Pattern 4: Performance analysis

When to use: Identifying bottlenecks and optimization opportunities
{
  "input": "What are the performance bottlenecks in our data processing pipeline? Focus on database queries and data transformations.",
  "repositories": ["acme/data-service", "acme/analytics-engine"]
}
Returns: Bottleneck identification, N+1 queries, inefficient algorithms, caching opportunities

​
Pattern 5: Dependency impact

When to use: Before upgrading dependencies or making breaking changes
{
  "input": "If we upgrade from Express 4 to Express 5, what parts of our codebase would be affected? What breaking changes should we prepare for?",
  "repositories": ["acme/api", "acme/admin-portal", "acme/webhook-service"]
}
Returns: Affected code sections, breaking changes, migration strategy, risk assessment

​
Pattern 6: Onboarding new developers

When to use: Explaining complex parts of the codebase
{
  "input": "Explain how our multi-tenant isolation works. How do we ensure data separation between clients?",
  "repositories": ["acme/core", "acme/tenant-service"]
}
Returns: Conceptual explanation, implementation details, key files and functions, potential gotchas

​
Pattern 7: Best practice validation

When to use: Ensuring code quality and consistency
{
  "input": "Are we following React best practices in our component architecture? Identify anti-patterns and suggest improvements.",
  "repositories": ["acme/web-app", "acme/mobile-web"]
}
Returns: Pattern analysis, anti-pattern identification, specific improvement suggestions, refactoring priorities