docs: sharpen query routing, output budget, and field-name pitfalls

references/pitfalls.md

@@ -139,6 +139,7 @@ Default to compact evidence. Raw/full access is a conscious escalation.
 Common wrong guesses:
 
 - Summaries: use `source` and `content`; do not use `summary_type` or `text`.
+- Tool call name: use `tool_calls.name`. `tool_name` is only a safe alias in `SELECT tc.name AS tool_name`; `tc.tool_name` is not a table column.
 - Tool result timestamps: `tool_results` has no timestamp. Join `messages`.
 - Tool call timestamps: `tool_calls` has no timestamp. Join `messages`.
 - Workflow agent message counts: `workflowTree()` returns `messageCount` for agents.

references/query-patterns.md

@@ -32,7 +32,8 @@ Use this for conclusion, broad history, failure investigation, or file evolution
 questions. The goal is to reduce conversation turns: keep intermediate search
 results inside the query script, then return only a compact task-local evidence
 view. This does not create stored semantic entities; the agent still reads the
-evidence and forms the conclusion.
+evidence and forms the conclusion. Expect 1-2 runtime queries: one broad compact
+evidence pass, and optionally one targeted detail pass by stable IDs.
 
 ```js
 const project = '%quiet-zero%';