Tools · Agents and tools

tool_search

Read-only

Search the current agent's available tools and return a ranked shortlist of the best matches for a task. Use this when many tools are available and no loaded tool fits. Call an already loaded matching tool directly instead of searching again.

When to use: Use this when many tools are available and you need to identify the right one before acting. Pass a plain-language query describing what you want to do.

Example

Run for real by scripts/tool-examples.py in a small demo project, with Haiku 5.5 where the tool calls a model. The output is exactly what the tool returned, in 2.6s.

The call

tool call
{
  "tool": "tool_search",
  "arguments": {
    "query": "edit a jupyter notebook"
  }
}

Real output

Best tools for 'edit a jupyter notebook' (ranked by relevance):
1. notebook_edit (score=22.831; files & code, action) — Read, edit, add, or delete cells in a Jupyter notebook (.ipynb).
   ↳ when to use: Use for .ipynb files instead of edit_file — it edits cells structurally. Always `list` first, then `read` the target cell, then `edit` with the full new source.
2. edit_file (score=7.874; files & code, action) — Apply an exact string replacement patch to an existing file.
   ↳ when to use: Use this for surgical edits after reading the file. Prefer exact replacements over full rewrites.
3. multi_edit (score=7.874; files & code, action) — Apply several exact string-replacement edits to ONE file atomically. Edits apply in order to the same file; if any old_text is missing or ambiguous, nothing is written.
   ↳ when to use: Batch edits to one file: pass path and edits=[{old_text, new_text, replace_all?}]. Order matters; each edit sees the result of the ones before it.
4. image_generate (score=3.596; artifacts & content, action) — Generate an image from a text description. Returns the image so you can see it and the user can view it. Use for illustrations, diagrams, mockups, icons — not for editing an existing file.
   ↳ when to use: Use image_generate to CREATE a new image from a description — an illustration, diagram, mockup, icon, or concept art. Write a specific prompt (subject, style, colours, composition). The result is returned to you as an image you can see, and shown to the user. Pick a size that fits the subject (squar
5. open_url (score=0.971; web & browsing, read-only) — Fetch a URL and return a clean text excerpt.
   ↳ when to use: Use this when you need exact content from a specific URL. Prefer this after search results identify a likely source.

Loaded and now directly callable (full definitions available from your next step):
- notebook_edit(path: string, action: string, index?: integer, source?: string, cell_type?: string)
- multi_edit(path: string, edits: array)
- image_generate(prompt: string, size?: string, provider?: string)
- open_url(url: string, max_chars?: number)

Parameters

NameTypeDescription
query*stringWhat you are trying to do, in plain language.
limitintegerMaximum number of matching tools to return (1-10, default 5).

* required

Hand work to sub-agents and find the right tool when there are many.