docs(adk): tool results aren't auto-echoed; steer trace reads off raw dumps

skills/adk-debugger/references/trace-summarization.md

@@ -19,9 +19,19 @@ adk traces conversation=<id> --include-llm --format json
 adk traces --include-llm --format json
 ```
 
-**Always pass `--include-llm`** when summarizing. Without it, `think` spans are omitted and you lose the model's reasoning, which is essential for explaining _why_ the agent did what it did.
+**Always pass `--include-llm`** when summarizing. Without it, span `data` is omitted and you lose the model's reasoning, which is essential for explaining _why_ the agent did what it did.
 
-**Always pass `--format json`** for structured, parseable output.
+**Pass `--format json`** when piping into `jq`; for reading, the default text output is already condensed.
+
+**Keep it small.** Narrow to the spans you need instead of dumping the whole trace (`--format json` caps long `data` by default; `--full` for the complete blob):
+
+```bash
+# iteration/LLM/tool spans only, as a flat list (substring match on span name)
+adk traces trace=<id> span=iteration,cognitive,tool --include-llm
+
+# or jq to a specific span (the field is `name`, not `type`)
+adk traces trace=<id> --include-llm --format json | jq '.spans[] | select(.name=="autonomous.tool")'
+```
 
 ---
 

skills/adk/references/autonomous-execution.md

@@ -722,6 +722,7 @@ await execute({
 
 ## Pitfalls
 
+- **Tool results are not auto-echoed into the reply.** Declare a typed `output` schema and instruct the agent to answer with the real values, never placeholders — see [Surfacing Tool Results](./tools.md#surfacing-tool-results-to-the-user).
 - **Do not redefine built-in exits.** Creating an exit named `listen`, `think`, or `done` will conflict with the built-in ListenExit, ThinkExit, and DefaultExit.
 - **Exits require good descriptions.** The LLM decides which exit to use based on the `description`. Vague descriptions lead to wrong exit selection.
 - **Writable properties need a schema.** If `writable: true` without `type`, the sandbox cannot validate writes and they will be unchecked.

skills/adk/references/cli.md

@@ -545,13 +545,15 @@ adk traces [tokens...] [options]
 - `trigger=<name>` — filter by trigger name
 - `conversation=<id>` — filter by conversation id
 - `trace=<id>` — drill into a specific trace (shows the full span tree)
+- `span=<type>` — drill-in only: keep only spans whose name/label matches (comma-separated substring, e.g. `tool,cognitive`). Renders as a flat list.
 - `since=<duration>` / `until=<duration>` — e.g. `30s`, `5m`, `1h`, `2d`, `1w`
 - `limit=<n>` — max traces to show (default: 20)
 
 **Options:**
 
 - `-f, --follow` — stream new traces as they complete
 - `--include-llm` — include LLM instructions, code, and tools in drill-in mode
+- `--full` — with `--include-llm --format json`: don't truncate large `data` fields. Omitted, long strings are capped by default.
 - `--format <format>` — `json` only (omit for default text output)
 
 **Examples:**
@@ -562,10 +564,18 @@ adk traces error                          # error traces only
 adk traces workflow=onboarding            # traces for a workflow
 adk traces conversation=<id> --format json
 adk traces trace=<id> --include-llm       # drill into one trace with LLM content
+adk traces trace=<id> span=iteration,cognitive,tool --include-llm   # only those spans
 adk traces since=1h limit=50 --format json
 adk traces error --follow                 # stream errors live
 ```
 
+> For a drill-in, prefer smaller output over the raw JSON dump:
+>
+> - Default text output (`adk traces trace=<id> --include-llm`) is already condensed — start here.
+> - Narrow with `span=` (e.g. `span=iteration,cognitive,tool`) to drop noise.
+> - `--format json` caps long `data` by default; add `--full` only for the complete blob.
+> - `jq` to specific spans, e.g. `... --format json | jq '.spans[] | select(.name=="autonomous.tool")'`.
+
 ### adk workflows
 
 Inspect workflow definitions and runs on the linked dev bot. All `adk workflows ...` commands target the dev bot (same credentials path as `adk dev`) and only accept `--format json` — any other `--format` value is rejected.

skills/adk/references/tools.md

@@ -65,7 +65,7 @@ export default new Autonomous.Tool({
 | **name**              | `string`              | Yes         | Unique TypeScript-compatible identifier                  |
 | **description**       | `string`              | Recommended | Helps AI understand when and how to use the tool         |
 | **input**             | `z.ZodType`           | No          | Zod schema for input validation (defaults to `z.any()`)  |
-| **output**            | `z.ZodType`           | No          | Zod schema for output validation (defaults to `z.any()`) |
+| **output**            | `z.ZodType`           | Recommended | Zod schema for output validation (defaults to `z.any()`) |
 | **handler**           | `function`            | Yes         | Async function implementing tool logic                   |
 | **aliases**           | `string[]`            | No          | Alternative names the AI can use to call this tool       |
 | **metadata**          | `Record<string, any>` | No          | Custom information for tool categorization               |
@@ -151,6 +151,22 @@ export const anotherTool = new Autonomous.Tool({
 | Typical use       | Internal functions, any context | AI-callable, conversation context                        |
 | Handler signature | `handler({ input, client })`    | `handler(input, ctx?)` or `handler({ ...fields }, ctx?)` |
 
+## Surfacing Tool Results to the User
+
+A tool's return value is **not** auto-echoed — only the text the model explicitly emits reaches the user. Left to itself the model often sends a placeholder ("see the tool output above"), an empty `<></>`, or `[object Object]`. To keep the real values in the reply:
+
+1. Declare a typed `output` schema (not the `z.any()` default) so the model can read fields like `result.count`.
+2. Instruct the conversation to answer in plain text with the concrete returned values, never placeholders.
+
+```typescript
+export const queryVendors = new Autonomous.Tool({
+  name: 'queryVendors',
+  input: z.object({ term: z.string() }),
+  output: z.object({ results: z.array(z.object({ name: z.string(), rate: z.number() })), count: z.number() }),
+  handler: async ({ term }) => queryRows(term),
+})
+```
+
 ## Accessing Context in Tools
 
 Tools can use global runtime proxies directly, but conversation-specific values should be loaded through `context.get(...)`: