# Plan 03-01: Create Combined research_and_create Tool
## Objective
Combine `deep_research` and `populate_framework` into a single `research_and_create` tool to reduce the research-to-framework flow from 2 tool calls to 1.
## Current State
The current flow requires users to:
1. Call `deep_research` → returns parsed data + citations
2. Manually call `populate_framework` → creates entity from data
This creates friction and requires the AI to pass intermediate data between calls.
## Target State
Single tool `research_and_create` that:
1. Executes deep research via OpenAI
2. Parses the research result
3. Creates the entity with research metadata
4. Returns the created entity
## Implementation
### Wave 1: Create New Combined Tool
**File: `src/tools/research.ts`**
Add new schema and function:
```typescript
// After existing schemas (~line 184)
export const researchAndCreateSchema = z.object({
projectId: z.string().describe("Project to create entity in"),
frameworkType: z
.enum([
"market-sizing",
"competitive-analysis",
"user-persona",
"swot-analysis",
"business-model-canvas",
"lean-canvas",
"value-proposition-canvas",
])
.describe("Framework type to research and create"),
name: z.string().describe("Name for the new entity"),
description: z.string().optional().describe("Optional description"),
context: z
.object({
businessDescription: z
.string()
.describe("Description of the business/product (required)"),
industry: z.string().optional().describe("Industry sector"),
geography: z.string().optional().describe("Target geography"),
targetCustomers: z
.string()
.optional()
.describe("Target customer description"),
productOrService: z
.string()
.optional()
.describe("Product or service details"),
competitors: z
.array(z.string())
.optional()
.describe("Known competitors to include"),
})
.describe("Research context"),
model: z
.enum(["o3-deep-research-2025-06-26", "o4-mini-deep-research-2025-06-26"])
.default("o4-mini-deep-research-2025-06-26")
.describe("Model to use (mini is faster and cheaper)"),
});
export interface ResearchAndCreateResponse {
entity: {
id: string;
type: string;
name: string;
};
research: {
confidence: number;
citationCount: number;
missingFields: string[];
};
usage: {
inputTokens: number;
outputTokens: number;
totalTokens: number;
estimatedCostUSD: number;
};
}
export async function researchAndCreate(
args: z.infer<typeof researchAndCreateSchema>
): Promise<ResearchAndCreateResponse> {
// 1. Execute deep research
const researchResult = await deepResearch({
projectId: args.projectId,
frameworkType: args.frameworkType,
context: args.context,
model: args.model,
});
// 2. Create entity with research data
const entityResult = await populateFramework({
projectId: args.projectId,
frameworkType: args.frameworkType,
name: args.name,
description: args.description,
researchData: researchResult.parsedData,
citations: researchResult.citations,
researchModel: args.model,
confidence: researchResult.confidence,
});
// 3. Return combined response
return {
entity: {
id: entityResult.entityId,
type: entityResult.type,
name: entityResult.name,
},
research: {
confidence: researchResult.confidence,
citationCount: researchResult.citations.length,
missingFields: researchResult.missingFields,
},
usage: researchResult.usage,
};
}
```
### Wave 2: Register Tool in MCP Server
**File: `src/index.ts`**
Add tool registration after existing research tools (~line 310):
```typescript
server.tool(
"research_and_create",
researchAndCreateSchema.shape,
{
title:
"Research a framework using AI Deep Research and create entity in one step",
},
async (args) =>
jsonResponse(await researchAndCreate(researchAndCreateSchema.parse(args)))
);
```
### Wave 3: Export from tools/index.ts
**File: `src/tools/index.ts`**
Add exports:
```typescript
export {
// ... existing exports
researchAndCreateSchema,
researchAndCreate,
type ResearchAndCreateResponse,
} from "./research.js";
```
### Wave 4: Add Tests
**File: `src/tools/research.test.ts`**
Add test cases:
```typescript
describe("researchAndCreateSchema", () => {
it("validates all required fields", () => {
const result = researchAndCreateSchema.safeParse({
projectId: "proj-123",
frameworkType: "market-sizing",
name: "Test Analysis",
context: {
businessDescription: "A SaaS product for developers",
},
});
expect(result.success).toBe(true);
});
it("rejects missing businessDescription", () => {
const result = researchAndCreateSchema.safeParse({
projectId: "proj-123",
frameworkType: "market-sizing",
name: "Test",
context: {},
});
expect(result.success).toBe(false);
});
it("validates all framework types", () => {
const types = [
"market-sizing",
"competitive-analysis",
"user-persona",
"swot-analysis",
"business-model-canvas",
"lean-canvas",
"value-proposition-canvas",
];
for (const type of types) {
const result = researchAndCreateSchema.safeParse({
projectId: "proj-123",
frameworkType: type,
name: "Test",
context: { businessDescription: "Test" },
});
expect(result.success).toBe(true);
}
});
});
```
## Verification
```bash
npm run typecheck
npm test
npm run build
```
## Files Changed
| File | Change |
|------|--------|
| `src/tools/research.ts` | Add `researchAndCreateSchema` and `researchAndCreate` function |
| `src/tools/index.ts` | Export new schema and function |
| `src/index.ts` | Register `research_and_create` tool |
| `src/tools/research.test.ts` | Add schema validation tests |
## Notes
- Existing `deep_research` and `populate_framework` tools remain for backwards compatibility
- The new tool combines both operations internally
- Response includes both entity info and research metadata
