# Plan 03-02: Update Tool Descriptions for Better Discoverability
## Objective
Improve tool descriptions to make the research workflow clearer and help users discover the new combined `research_and_create` tool.
## Current State
Tool descriptions are functional but don't clearly indicate:
- Which tool to use for different workflows
- The relationship between research tools
- When to use the combined tool vs separate tools
## Target State
Clear, concise descriptions that:
- Guide users to the right tool
- Explain the research workflow
- Highlight the recommended approach (combined tool)
## Implementation
### Wave 1: Update Tool Descriptions in src/index.ts
**File: `src/index.ts`**
Update the Deep Research section tool descriptions:
```typescript
// DEEP RESEARCH TOOLS section (~line 290)
// Update configure_openai description
server.tool(
"configure_openai",
configureOpenAISchema.shape,
{
title: "Configure OpenAI API key for Deep Research (not needed if OPENAI_API_KEY env var is set)",
},
async (args) => jsonResponse(await configureOpenAI(configureOpenAISchema.parse(args)))
);
// Update check_openai_config description
server.tool(
"check_openai_config",
{},
{
title: "Check if OpenAI API key is configured for Deep Research",
},
async () => jsonResponse(await checkOpenAIConfig())
);
// Update deep_research description
server.tool(
"deep_research",
deepResearchSchema.shape,
{
title: "Research a framework using AI (returns data for populate_framework). Use research_and_create instead for simpler workflow.",
},
async (args) => jsonResponse(await deepResearch(deepResearchSchema.parse(args)))
);
// Update populate_framework description
server.tool(
"populate_framework",
populateFrameworkSchema.shape,
{
title: "Create entity from deep_research results. Use research_and_create instead for simpler workflow.",
},
async (args) => jsonResponse(await populateFramework(populateFrameworkSchema.parse(args)))
);
// Add research_and_create with clear description (from 03-01)
server.tool(
"research_and_create",
researchAndCreateSchema.shape,
{
title: "RECOMMENDED: Research and create a framework entity in one step using AI Deep Research",
},
async (args) => jsonResponse(await researchAndCreate(researchAndCreateSchema.parse(args)))
);
```
### Wave 2: Update README Documentation
**File: `README.md`**
Add Deep Research section:
```markdown
### Deep Research (AI-Powered)
Requires OpenAI API key (set `OPENAI_API_KEY` env var or use `configure_openai`).
- `research_and_create` - **Recommended**: Research and create any framework in one step
- `deep_research` - Run AI research (use with `populate_framework`)
- `populate_framework` - Create entity from research results
- `configure_openai` - Set API key at runtime
- `check_openai_config` - Verify API key configuration
```
Update Example Usage section:
```markdown
## Example Usage
```
> Create a project called "My Startup"
> Use AI to research and create a market sizing analysis for a B2B SaaS product
> Create user personas for technical buyers and end users
> Run a SWOT analysis for entering the market
> Export the project to markdown
```
```
## Verification
```bash
npm run build
```
Manual verification: Check tool descriptions appear correctly in MCP client.
## Files Changed
| File | Change |
|------|--------|
| `src/index.ts` | Update tool descriptions for research tools |
| `README.md` | Add Deep Research section, update examples |
## Notes
- Descriptions include "RECOMMENDED" for the new combined tool
- Old tools remain available but descriptions point users to new tool
- No code logic changes, only documentation
