Defining Tighter Boundaries Using Intention

Scope boundaries

Before writing any code, our intention helps us define what belongs in our MCP server and what doesn’t.

The Goldilocks test for server scope

Too broad: “Help with text processing”

• Can’t list 10 specific tools without getting vague
• LLMs can’t determine when to use it

Too narrow: “Validate Python 3.11 async functions in .md files between 1-5KB”

• Too specific to last 6 months
• Not enough tools to justify a server

Just right: “Help developers validate code examples in their documentation”

• Clear tool ideas: ValidateCode, CheckImports, VerifyOutput
• Natural boundaries between validation and fixing
• Room to grow with more languages

One server or many?

Signs we need multiple servers:

• Different user personas (developers vs. marketing)
• Conflicting constraints (read vs. write)
• No natural workflow between tool groups
• Different core purposes

Signs we need one server:

• Tools naturally chain: Parse → Analyze → Report
• Same user persona throughout
• Shared constraints (all read-only, same file types)
• Combined value exceeds individual tools

Example: Eduardo’s decision

Eduardo considered adding documentation fixing to DocQualityAdvisor:

Three mismatches = separate server. DocQualityAdvisor finds problems, DocFixer solves them. They chain beautifully but maintain clear boundaries.

Scoping features

When requests arrive, we can also run them through the filter:

Request: “Can DocQualityAdvisor check Python code examples?”

• WHO: ✓ Developers writing docs
• WHAT: ✓ Quality includes working examples
• CONSTRAINTS: ✓ Still read-only analysis
• WHY: ✓ Reduces documentation issues

Decision: Yes, add ValidateCodeExamples

Implementation boundaries

Once we know our scope, intention also guides how we structure our tools.

Tool granularity decisions

// Intention: Help SREs debug production issues quickly and safely

// Clear boundaries from intention

func FindErrorPatterns(logs LogQuery) ([]ErrorPattern, error)

// Serves WHO (SREs), enables WHAT (find issues),

// respects CONSTRAINTS (read-only), advances WHY (faster identification)

// Would violate intention

func AutoFixErrors(pattern ErrorPattern) error

// Different WHAT (fixing vs debugging), violates CONSTRAINTS (modifies production)

Parameter design choices

Choice: Return all metrics in one call vs separate tools?

• One call serves “quick overview” (aligns with WHY: fast understanding)
• Separate tools serve “detailed analysis” (aligns with WHAT: thorough checking)

Decision: Both: GetOverview for quick checks, individual tools for deep dives

Communication boundaries

Clear communication helps LLMs understand and use our tools effectively.

Writing tool descriptions

// Weak: Generic description

“Analyzes text for various metrics”

// Strong: Intention-aligned description

“Analyzes API documentation to identify quality issues that frustrate developers,

including broken examples, missing parameters, and unclear descriptions”

// – Clear WHO: developers reading API docs

// – Clear WHAT: quality issues

// – Clear WHY: reduce frustration

Error message as guide

// Weak: Technical error

“Error: Invalid parameter type”

// Strong: Intention-guiding error

“Error: Code validation requires a markdown file with code blocks.

Supported languages: Python, JavaScript, Go”

// Reinforces WHAT: validating code in documentation

// Clarifies CONSTRAINTS: specific file types