Skip to content

feat(runtime): defer low-frequency catalog tools behind tool_search #4091

Description

@Astro-Han

Problem

Discussion #3621 agreed on the target state: a small direct baseline of frequent tools stays visible at step 0, and every other available tool is deferred behind tool_search by default — "Defer other available tools by default, including low-frequency tools such as WriteStdin."

#3765 delivered the provider-independent, turn-scoped tool_search contract and moved catalog surfaces (agent, browser, computer_use, rive) and dynamic client groups behind it. But that first slice deliberately left every ungrouped bound tool eagerly visible. A default session still advertises ~30 tool schemas on every provider request, including low-frequency ones:

  • memory_remember, memory_extract
  • task_create, task_update, task_list, task_get
  • GoalSet, GoalClear, GoalStatus, GoalPause, GoalResume
  • ScheduledTask
  • MakaSettingsGet, MakaSettingsUpdate
  • SearchHistory, ReadHistory
  • ExploreAgent, FormatJson, WriteStdin, WebSearch, request_sandbox_boundary

Desired outcome

Defer available tools by default unless they are in the direct baseline.

  • Every catalog tool outside DIRECT_TOOL_NAMES joins the deferred search space. Add natural catalog surfaces (e.g. session, memory, history, settings) so the search inventory stays scannable instead of one flat pool.
  • Skill/SkillSearch stay direct, per Simplify Maka tool discovery: direct baseline + turn-scoped tool_search #3621's carve-out pending the separate skill-discovery discussion.
  • DIRECT_TOOL_NAMES remains the never-deferred baseline.
  • Context-required tools may still be injected directly for a turn through the existing requiredToolNames hook when runtime state requires them.
  • Hosted-execution ceilings (boundTools / tool profiles) remain authoritative; discovery never escapes the bound set.
  • No new config knob; the feat(runtime): add turn-scoped tool_search activation #3765 search contract is the only mechanism.

Semantics to settle during implementation

  • Which runtime states auto-promote a deferred tool to direct for that turn (open question from Simplify Maka tool discovery: direct baseline + turn-scoped tool_search #3621): e.g. a background PTY exists → WriteStdin; a sandbox-boundary prompt is live → request_sandbox_boundary; goal tools while an autonomous goal is active.
  • How memory extraction flows behave when memory_remember/memory_extract are deferred, including the Runtime-reserved memory trigger tools built in ai-sdk-backend.ts.
  • Prompt updates so the model knows to tool_search before relying on deferred flows (task ledger, memory, scheduled tasks, goals).

Acceptance

  • In a default session, the step-0 provider request contains only DIRECT_TOOL_NAMES, Skill/SkillSearch, tool_search, and any turn-activated tools.
  • toolAvailability telemetry shows the schema-char reduction versus current main.
  • Task ledger, scheduled tasks, memory extraction, goals, and history flows all still work after tool_search activation; focused Runtime and Runtime Host suites pass.

Follows up #3621 and #3765. Tracker: #1382.

AI assistance disclosure

Maka helped audit the current implementation against the #3621 agreement and draft this issue. I reviewed the scope and final text.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions