fix: polish native tool descriptions for discoverability and turn efficiency

[jkyberneees]

Summary

Adversarial polish of the native tool descriptions — the strings injected into every LLM turn as tool schemas. Three sequential review sub-agents (discoverability, token-economy, behavioral accuracy; 5 validated findings each), findings applied centrally, then a fourth verification sub-agent audited the final diff: CLEAN, 0 defects.

Highlights (15 findings applied across 12 files)

Turn-efficiency routing

• shell: steering fixed — file inspection now points at zero-fork tools (read_file/glob/tree); long-running work (builds, full test suites, dev servers) routed to bg_start instead of the timeout dead-end. bg_start's use-list gains builds/test suites.
• batch_patch: trigger-first phrasing — prefer over N sequential patch calls; same-file multi-edits stated explicitly.
• search_files: cross-reference to multi_grep for multi-pattern sweeps.
• memory: cross-pointer to session_search for past-session content (kills the memory-vs-session-search confusion).
• web_search: no longer dead-ends into http_batch for content (bodies are metadata-only) — browser only.

Factual corrections (description vs code drift)

• browser: description named nonexistent tools (browser_navigate/browser_snapshot/browser_click) — models following it emitted wrong tool names; replaced with the real action flow.
• session_search: "semantic vector search" → "thresholded keyword scoring" (code is explicitly bag-of-words + 0.40 threshold); adds use-distinctive-terms guidance.
• delegate_tasks artifacts: "Text artifacts up to 32 KB are inlined in full" → "Only text/* artifacts ≤32 KB are inlined (JSON/binary are metadata-only)" — matches the actual text/* gate and 128 KiB/call inline budget.
• bg_status: unknown now also documented as "finished record evicted" (oldest jobs pruned past the per-session cap) — prevents re-running completed work.
• bg_start: completion notices drain into a later iteration, not instantly — poll before ending dependent turns.
• transcribe: native formats are WAV/MP3/FLAC (others auto-converted via ffmpeg) — both description and schema param.
• vision: video analysis requires ffmpeg+ffprobe in PATH — convert/extract-frames instead of blind retries.

Token economy

• delegate_tasks description trimmed ~30% (config-key spellings, trust formalism, defaults narration) while keeping every operative rule: approvals/denials, budgets, trust non-increase, depth cap, artifact contract.
• Deduplication: http_batch body rule, file_glob/path guidance, write_file EXACT-path rule, glob examples, vision format list.
• Removed the session-work identifier sentence from multi_grep ("Directly targets the multi_search benchmark").

Verification

• 4th sub-agent diff audit vs code: CLEAN (every numeric limit, dependency claim, and behavior claim re-verified — incl. maxBatchPatches=10, subagentHeadlineMaxRunes=2048, pruneLocked eviction, text/* inline gate).
• Description strings only — no Schema structure or Call() logic touched.
• go build, go vet, full cmd/odek + internal/memory suites green (-count=1); no test pinned the old strings.

Follow-up (out of scope here)

The browser tool's runtime jsonError strings still reference the phantom browser_navigate name (browser_tool.go:282,303) — code-side strings, needs its own fix.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	odek	2914334	Commit Preview URL Branch Preview URL	Sep 03 2026, 06:41 AM