# Tool Design Guidelines
## Philosophy: Specialized Workflow Tools
We use **specialized workflow tools** instead of 30+ API-endpoint tools.
**Traditional** (API-centric): `add-project`, `update-project`, `delete-project`, `get-project`...
**Our approach** (workflow-centric): `add-projects`, `update-projects`, `delete-object` (universal deletion)
## Core Principles
1. **User Intent Over API Structure** - Match workflows, not API organization
2. **Batch Operations** - Support multiple items when logical (`add-tasks` takes array)
3. **Explicit Intent** - Clear action verbs (`add-projects` vs `update-projects` for explicit operations)
4. **Context-Aware Responses** - Provide next-step suggestions after operations
5. **Universal Patterns** - Unify similar operations (`delete-object` handles all entity types)
## Implementation Pattern
```typescript
// Explicit tools for specific operations
// add-projects: creates new projects
// update-projects: modifies existing projects
// Always return both structured data AND human-readable text with next steps
return {
textContent: `Action completed: ${result}\n${formatNextSteps(suggestions)}`,
structuredContent: { data, metadata },
};
```
## Key Design Decisions
| Choice | Rationale |
| --------------------------------------------------- | ------------------------------------------------------------------ |
| `add-projects` + `update-projects` vs combined tool | Explicit intent reduces ambiguity, clearer tool selection for LLMs |
| `delete-object` (universal) vs type-specific tools | Deletion logic similar across types, reduces LLM cognitive load |
| `add-tasks` (batch) vs single task | Common to add multiple related tasks at once |
| Rich responses with next steps | Maintains workflow momentum, helps LLMs choose follow-up actions |
## Guidelines
### When to Create New Tool
- Represents distinct user workflow
- Can't elegantly extend existing tools
- Has unique parameter requirements
### When to Extend Existing Tool
- Closely related to existing tool's purpose
- Can be handled with additional parameters
- Follows same workflow pattern
### Naming & Design
- **Action verbs**: `find-`, `add-`, `manage-`, `complete-`
- **User terminology**: `complete-tasks` not `close-tasks`
- **Batch support**: When users commonly do multiple items
- **Smart defaults**: Optional parameters, auto-detect intent
- **Rich responses**: Structured data + human text + next steps
## OpenAI MCP Tools
**Exception to the Design Philosophy**: The `search` and `fetch` tools follow the [OpenAI MCP specification](https://platform.openai.com/docs/mcp) which requires specific return formats:
- **`search`**: Returns JSON-encoded array of results with `id`, `title`, `url`
- **`fetch`**: Returns JSON-encoded object with `id`, `title`, `text`, `url`, `metadata`
These tools return raw JSON strings instead of rich responses with next steps, as required by OpenAI's protocol. They use composite IDs (`task:{id}` or `project:{id}`) to distinguish between entity types.
## Anti-Patterns ❌
- One-to-one API mapping without added value
- Overly complex parameters for basic operations
- Inconsistent interfaces across similar tools
- Raw API responses without context
- Forcing multiple tool calls for related operations
