Agents & Tool Use
Tool Interface Design and MCP Integration
Writing effective tool descriptions, structured error responses, MCP server scoping, and the distinction between MCP tools and resources.
intermediate · 9 min read
Tool descriptions are the primary mechanism LLMs use for tool selection. Getting them right is the highest-leverage, lowest-effort optimization in agent design.
Tool Description Quality
Minimal descriptions ("Retrieves customer info") cause unreliable selection between similar tools. Effective descriptions include:
- Input formats: What types of identifiers does the tool accept?
- Example queries: "Use when the user asks about order status"
- Edge cases: "Returns null if no active orders exist"
- Boundaries: "Do NOT use for subscription queries; use get_subscription instead"
When two tools have overlapping functions, either rename them to eliminate ambiguity or split generic tools into purpose-specific variants.
Structured Error Responses
MCP tools must return structured error metadata, not generic "Operation failed" messages. Every error response should include:
- isError: true (MCP flag)
- errorCategory: transient, validation, business, or permission
- isRetryable: boolean indicating whether retrying makes sense
- description: human-readable explanation
The distinction between an access failure (database unreachable - needs retry decision) and a valid empty result (query succeeded, no matches found) is critical. Returning empty results as success when the tool actually failed prevents any error recovery.
MCP Server Scoping
- Project scope (
.mcp.json): Shared team tooling, version-controlled, uses${ENV_VAR}expansion for credentials - User scope (
~/.claude.json): Personal/experimental servers, not shared via version control - Both are available simultaneously - all tools are discovered at connection time
Resources vs Tools
MCP resources expose content catalogs (issue summaries, documentation hierarchies, database schemas) to reduce exploratory tool calls. MCP tools expose actions (search, create, update, delete). Resources help agents understand what data is available without having to discover it through trial and error.