Verify & tune agent knowledge-graph tool usage (neighbors/path_between) after prompt change (#34)

[gangtao]

Context

PR #34 loosened agent.py system-prompt Rule 1 ("LEAN ON THE GRAPH") to encourage the agent to use neighbors / path_between for exploration generally — not only for literal "what calls X" questions — after observing that architecture / "how does X work" questions were answered with search_entities + read_source alone, never touching the graph edges.

This is a prompt nudge, so its real effect is probabilistic and can only be confirmed from live traces. Keeping this open to track that verification and any follow-up tuning.

What to verify (from live chat traces, now that the thinking/tool trace shows every tool call — #33)

• On architecture / conceptual questions (e.g. "How do materialized view checkpoints work?", "How does replication work?", "What is the checkpoint coordinator responsible for?"), does the agent now call neighbors (or path_between) at least once when relationships would help — vs the pre-feat(agent): encourage graph traversal beyond explicit call-path questions #34 baseline of search_entities/read_source/get_entity only?
• On relationship / call-path questions ("what calls prepareCheckpoint?", "trace X → Y"), does it still reliably use neighbors/path_between (the hard REQUIRE)?
• No runaway: it shouldn't burn extra tool calls on neighbors when it returns little — the sparse-C++-graph caveat should still make it fall back to read_source. Watch the tool-call counts vs the ~12 soft budget.

Possible follow-ups depending on findings

• Tune the prompt wording (dial the encouragement up/down) if it over- or under-uses graph traversal.
• If neighbors/path_between consistently return thin results for C++ nodes, that's the extraction-coverage limitation tracked in Deep call-path queries (e.g. "trace HTTP insert → nativelog write") return no result — sparse C++ call graph + agent doesn't use path_between #17 (sparse AST call graph, ~38% of functions have outgoing edges) — richer extraction would make graph traversal pay off more.
• Consider a small offline eval harness: run a fixed set of questions through the agent and record the tool-call distribution, to measure changes objectively rather than by eyeballing traces.

Notes

• Verifying live requires the stack up with the agent image rebuilt on the merged code (docker compose build agent && up -d).
• Extended thinking is redacted on the current Bedrock/Opus gateway, so the visible reasoning in the trace is the model's between-tool narration (see feat: agent thinking content in chat, interleaved + collapsible (mockup t7) #33) — the tool calls themselves are what matter here.