3 posts tagged with "Best Practices"

When you're building MCP tools, there's a moment where you realize something counterintuitive: the description field isn't just documentation—it's instruction. Every parameter description you write is a teaching moment where the AI learns not just what a parameter is, but when to use it, why it matters, and how it impacts the operation.

This shift in thinking—from documenting to teaching—changes how you design tools. Let me show you what that looks like in practice.

Here's a problem I kept running into: when you're building an MCP server, you face this weird tension between giving AI agents enough control and not drowning them in options. Build 20 different tools and you're burning context window on redundant functionality. Build 3 tools with no parameters and the AI can't do anything useful.

After shipping dozens of MCP integrations, I found something that actually works: six core tools that balance OpenAI's single-string requirements with rich, parameter-driven operations. It's not arbitrary—there's a reason this number keeps working.

Design Philosophy​

We designed the Weaviate MCP tools following a modern, AI-first approach that prioritizes:

1. Rich, Actionable Descriptions - Every tool and parameter has extensive descriptions that tell AI agents not just what something is, but when to use it, why it matters, and how it impacts the operation
2. OpenAI MCP Connector Compatibility - search and fetch tools follow OpenAI's ChatGPT Connectors and Deep Research specification
3. Smart ID Routing - Universal fetch tool uses colon-separated IDs (weaviate:object:uuid, weaviate:schema:CollectionName) to encode multiple resource types in a single endpoint
4. Consolidated CRUD Operations - Single weaviate_upsert tool handles insert/update and single/batch operations intelligently
5. Granular List Tools - Object-specific parameters for fine-grained control over discovery and browsing
6. Maximum Tool Count = 10 - Design constraint to ensure focus and avoid overwhelming AI agents with too many options