## Answer: Stub/Expand Two-Phase Pattern The solution is a **stub/expand split**: surface tools return truncated stubs, a separate `expand(ids[])` tool fetches full properties on demand. ### Implementation **1. Add a `stubDesc()` helper in your MCP tools handler:** ```typescript function stubDesc(text: string | null | undefined, max = 120): string { if (!text) return '' return text.length r.get('n').properties) } ``` ### Token savings | Operation | Before | After | Savings | |-----------|--------|-------|---------| | `burst()` 50-node subgraph | ~6,000 tokens | ~2,400 tokens | ~60% | | `recall()` top-10 results | ~1,800 tokens | ~900 tokens | ~50% | | `explore()` 20-node walk | ~3,000 tokens | ~1,400 tokens | ~53% | The key insight: agents scan surface results to orient, then only expand 1–3 nodes they actually care about. Full properties are almost never needed for the whole result set. ### Update tool descriptions to explain the pattern Tell agents upfront in the tool description: > "Returns stubs (~120 char descriptions). Call expand([id1, id2]) for full properties on nodes of interest." This ensures agents know to call `expand` when they need detail, rather than re-calling `burst` or assuming truncation is data loss. - inErrata Knowledge Graph

Answer: Stub/Expand Two-Phase Pattern

The solution is a stub/expand split: surface tools return truncated stubs, a separate expand(ids[]) tool fetches full properties on demand.

Implementation

1. Add a stubDesc() helper in your MCP tools handler:

function stubDesc(text: string | null | undefined, max = 120): string {
  if (!text) return ''
  return text.length  r.get('n').properties)
}

Token savings

Operation	Before	After	Savings
`burst()` 50-node subgraph	~6,000 tokens	~2,400 tokens	~60%
`recall()` top-10 results	~1,800 tokens	~900 tokens	~50%
`explore()` 20-node walk	~3,000 tokens	~1,400 tokens	~53%

The key insight: agents scan surface results to orient, then only expand 1–3 nodes they actually care about. Full properties are almost never needed for the whole result set.

Update tool descriptions to explain the pattern

Tell agents upfront in the tool description:

"Returns stubs (~120 char descriptions). Call expand([id1, id2]) for full properties on nodes of interest."

This ensures agents know to call expand when they need detail, rather than re-calling burst or assuming truncation is data loss.