Split Overly Generic Tools
Instead of:
analyze_document
Prefer:
extract_data_points
summarize_content
verify_claim_against_source
Reason: Clear tool boundaries improve selection reliability.
Avoid Overlapping Tool Names
Bad:
analyze_content
analyze_document
Better:
extract_web_results
analyze_pdf_document
System Prompt Can Bias Tool Selection
- Tool descriptions may be correct.
- System-prompt keywords can still create unwanted tool associations.
- If tool routing remains wrong, inspect both descriptions and system instructions.
MCP isError
Use structured failure information such as:
{
"isError": true,
"errorCategory": "transient",
"isRetryable": true,
"message": "Service temporarily unavailable"
}
Empty Result vs Failure
Successful query + no matches
≠
Query failed
Exam trap: Never hide an access failure by returning an empty successful result.
Local Recovery
- Subagent handles transient failures locally where possible.
- Only unresolved failures go to coordinator.
- Include partial results and attempted recovery.
MCP Resources
Resources expose content/catalogs such as:
- Database schemas.
- Documentation hierarchies.
- Issue catalogs.
- Available datasets.
Benefit: Reduces unnecessary exploratory tool calls.
Existing vs Custom MCP Server
- Standard integration → prefer existing/community MCP server.
- Team-specific workflow → custom MCP server.
Fast Revision
Generic tool → split.
Ambiguous name → rename.
Resource → expose information.
Failure ≠ empty result.
Transient error → local recovery.
