I built a tool-routing graph for agents on HydraDB — what worked, what broke, and what I fixed

My agent was spending 27,000 tokens before it did any work.

Not on the task — on reading tool definitions. Connect an agent to real tools and it preloads every definition into its context first. In my catalog of 329 tools, that is 27,000 tokens per run, spent before the job even begins.

And the usual fix quietly fails. Similarity search finds lookalike tools — but tools don't work alone, they work in chains. To email a customer their invoice PDF, an agent needs six tools in the right order. On my 20-task benchmark, similarity search recovered the complete correct chain only 8 times out of 20.

So for the HydraDB Hackathon, I built Waypoint: hold three meta-tools, keep the tools in a graph, and traverse it.

Where HydraDB did the real work

Tools, data types and permission scopes are nodes in HydraDB. Typed PRODUCES and CONSUMES edges connect a tool to what it needs and what it makes. When a task arrives, the agent resolves the entities it mentions, then runs HydraDB's native multi-source path search (algo.MSpaths) over those edges to assemble the exact chain — 6 tools, 494 tokens for the invoice task instead of 27,000. Across the benchmark: 20 of 20 chains correct, 254 tokens on average, 106x fewer than preloading.

Two things only a graph gives you. First, permission scopes as nodes: traversal simply cannot pass through a scope the agent's role doesn't hold, so a support agent trying to void an invoice is stopped mid-chain, at the exact tool it may not use — 3 of 3 refusal cases pass. Second, learning that lives in the graph itself: every reported outcome reweights the edges that were used, so routing improves with use. And because seeding is MERGE/UNWIND, I could ingest real MCP servers' tool schemas (the official filesystem and memory servers) straight into the same graph — 329 tools became 352, and routing worked on them unchanged.

What broke, and what I did about it

1. The documentation that ranks first is stale. DeepWiki describes an older HydraDB. The current dialect rejects things I kept trying: RETURN *, MERGE and SET in one statement, count(n). I stopped trusting secondary docs, built a cheat sheet from the repo's own USING-HYDRADB and AGENTS files, and verified every query pattern against the live database before building on it.

2. My first learning rule made routing worse. Accuracy went 0.40, then down to 0.35: long detour chains kept harvesting shared edges and capturing the ranking. The fix was embarrassingly simple — rank shortest chain first, let edge weight break ties, and make failures cost weight. The rerun climbed 0.85 to 0.90 to 0.95. Both curves are in the repo. The failure is documented, not hidden.

3. Fifty agents at once broke it. My first load test produced 126 query timeouts: every resolution was re-pulling the whole graph. A snapshot cache over the bulk reads (path search and entity resolution still run live against HydraDB) took the same test to 0 errors at 33.2 resolutions per second.

4. The nastiest bug: after a restart, the store silently goes read-only. Reads keep working; every write returns HTTP 500, because the local filesystem layer in this build doesn't implement the storage engine's update mode. It cost me hours precisely because everything looked healthy. The workaround I shipped: treat a store as single-life — seed into a fresh store, never restart the node casually, and re-verify writes (not just reads) after any forced restart. If you build on HydraDB today, test your writes after a restart before you trust your demo.

5. One path search can silently drop a branch. For tasks where two chains join, a single path result can miss a needed tool. Seven of my twenty tasks needed a validated fallback resolver, with the method recorded per task — no silent gaps in the benchmark.

What I'd tell the next builder

Read the repo's own docs, not the summaries. Verify writes, not just reads. And benchmark against the honest baseline, including the version of your idea that failed — the failed learning curve taught me more than the winning one.

Waypoint is live: https://waypoint-nine-iota.vercel.app
Code: https://github.com/Aayu095/Waypoint
Walkthrough:

Built solo for the @hydra_db hackathon, Track 2. Agents pull only what the task needs.