Building MCP Servers on Workato: Scope, Tool Design, and Prompting
An MCP server's reliability depends on three decisions made before writing a single tool: what the server's scope is, what each tool should and should not handle, and how much prompting guidance to embed at each level.
What Makes an MCP Server Well-Scoped?
A well-scoped MCP server has a clear, single-domain responsibility. The LLM using the server should be able to determine from the server description alone whether this is the right server for a given task — without reading individual tool descriptions.
| Good Example | Poor Example | |
|---|---|---|
| Server Description | "CRM MCP Server: tools for searching, creating, updating, and archiving customer records in Salesforce. Does not handle billing, contracts, or support tickets." | "Business MCP Server: tools for business operations" |
| Why It Matters | LLM can determine scope without reading all tools; easy to maintain; composable with other servers | LLM must inspect all tools to determine scope; overlaps with other servers cause routing errors; hard to maintain |
The 3 Levels of Prompting in MCP Servers
Prompting in an MCP server happens at three levels, each serving a different purpose:
- Server level: The server description. What this server handles and doesn't handle. Written for the LLM selecting which server to use. Keep it precise and boundary-explicit.
- Tool level: Each tool's name, description, when-to-use, and when-not-to-use. Written for the LLM selecting which tool to call within the server. Include preconditions, expected inputs, and what the tool returns.
- Field level: Each input field's name, description, data type, and validation rules. Written to help the LLM construct a valid call. Flag which fields are required vs. optional and what format is expected.
When to Use a Tool vs. When Not To
| Use a Tool When | Do Not Use a Tool When |
|---|---|
| Action requires data from an external system | Data is already available in the LLM's current context |
| Action has side effects (create, update, delete, send) | The answer can be derived from prior tool output without a new call |
| Input requires real-time or user-specific values | The operation is better handled by a recipe or deterministic workflow |
| Operation needs an audit trail | Tool would be called on every turn with static, unchanging inputs |
| Result depends on current system state | The cost and latency of the call outweigh the value of fresh data |
Tool Description Best Practices
Write tool descriptions the way you'd write a well-specified function signature: what it does, what it requires, what it returns, and what it does not do. Include ordering or prerequisite notes when tools must be called in sequence.
Example of a well-specified tool description: "search_customers: Search for customer records by name, email, or company. Use BEFORE get_customer_details — you need a customer ID from this tool to call that one. Returns up to 20 matches ordered by relevance. Do not use for exact ID lookups — use get_customer_by_id instead."
Input Design: Required vs. Optional
Mark inputs as required only when the tool genuinely cannot execute without them. Optional inputs that the LLM omits cause unnecessary failures. Define sensible defaults for optional inputs in the tool's implementation rather than relying on the LLM to provide them.
For inputs the LLM must collect from the user (not derive from context), add an instruction in the tool description: "Collect [field] from the user before calling this tool."
Defining Output: Semantic Outcomes and Pagination
Semantic outcomes: Define what each possible output means. "Returns null" is not enough — does null mean "no results found," "user doesn't have permission," or "the query failed"? Each outcome needs a distinct response so the LLM can communicate accurately to the user.
Pagination signaling: When results are paginated, include a signal in the response (e.g., has_more: true, next_page_token) and document it in the tool description. The LLM should know when to offer "show more" without inferring it from partial results.