The Problem
Model Context Protocol (MCP) lets an AI agent call structured tools instead of guessing from raw text dumped into a context window. Fine in theory — but most MCP integrations just expose "read file" and "search," which barely improves on copy-pasting code into a chat window.
The real question: what tools should an agent actually have access to, for codebase work specifically?
Architecture: Three Tool Categories
Spiderbrain's MCP server exposes 28 tools, split into three functional groups:
Codebase Tools (17)
Structural queries a flat context window literally cannot answer:
blast_radius(path) // reach, callers, transitive impact
score_summary() // keystones, blindspots, node scores
communities() // clusters, boundary edges, paths
insights(area) // summaries, diffs, navigation, search
Memory Tools (9)
Access to the Memory Tree — a project's accumulated decisions and constraints, persisted across sessions:
memory_recall(files) // scoped brief for current context
memory_search(query) // semantic search over the full tree
memory_add(node) // write with explicit user ratification
memory_browse(scope) // browse by scope or recency
Blueprint Tools (2)
spiderbrain_blueprint_read() // current nodes, edges, annotations
spiderbrain_blueprint_draw() // AI proposes canvas edits — requires human acceptance
Implementation: Which Tools to Call, and When
Don't call all 28 on every turn — that's noise, not context. Here's the practical dispatch table:
| Situation | Call |
|---|---|
| New project |
score_summary() + top_spikescore(10)
|
| Before editing a file |
node(path) + blast_radius(path)
|
| Session start | memory_recall(files) |
| Planning a refactor |
communities() + boundary_edges()
|
| Onboarding to unfamiliar code |
blueprint_read() + insights(area)
|
This mapping matters more than tool count. An agent with 28 tools and no dispatch logic will either call none of them or call all of them — both are worse than an agent with 5 tools it actually reaches for at the right moment.
Learnings
The pattern that generalizes beyond this specific server: structure your MCP tools around the moments in a workflow, not around your data model. "New project," "before editing," "session start," "refactor," and "onboarding" are moments a developer or agent actually hits. "Get node," "get edge," "get community" are just database operations wearing a tool-call costume.
Resources
- Spiderbrain is free on Local, hosted brain available on Pro and Cortex.
- Related: Every AI Coding Assistant Sees Your Files, Not Your Architecture (for the underlying graph model these tools query) 🚀 Free on Local · ☁️ Hosted on Pro & Cortex
Link : https://spiderbrain.ai/
Linkedin : https://www.linkedin.com/company/spiderbrain
Discuss: has anyone else settled on a "moment-based" tool dispatch pattern for their own MCP servers? Curious what situations you gate on.
Top comments (0)