Tools (Beta) — let the agent look things up

A tool lets the agent look something up off the screen. If a task names a product, a brand or a place the agent does not recognise, or that may be misspelt, it can search first instead of scrolling through results. It uses a tool only when it cannot go on well without one, and at most 3 times per task.

Find them in Settings › Model › Tools, or on the Give Me a Brain page during setup.

Built-in tools

Tool	What it needs
Handsy Search	A Handsy key. On by default once the key is set; it uses your plan like any other run.
Web Search (Exa)	Your own Exa API key. Press and hold the row, choose Set Key…, paste the key.

With no tool on, the agent works exactly as before.

Import your own tool

Any HTTPS endpoint that takes a query and returns text or JSON can be a tool. Describe it in a small JSON file, put the file in Files (iCloud Drive, AirDrop, …), then tap Import Tools…. A file can hold one tool or a list of them; a list is added whole or not at all.

{
  "id": "docs",
  "title": "Our Docs",
  "about": "Search our product docs: names, prices and how-tos.",
  "url": "https://example.com/api/search"
}

Field	Required	Meaning
id	yes	The name the agent uses: 2–24 lowercase letters, digits or _. Not search or web.
title	yes	Shown in the list.
about	yes	One line telling the agent what the tool is good for. Keep it specific.
url	yes	Must be https.
method	no	POST (default) sends {"query": "…"} as JSON. GET adds ?query=….
query_field	no	The name of the query field. Default query.
body	no	Extra fields sent with every POST, as strings, for example {"limit": "5"}. Numbers are sent as numbers.
key_header	no	The header for your API key. Default Authorization. Set to null for a tool without a key.
key_prefix	no	Put before the key. Default Bearer . Use "" for a bare key.

If the tool needs a key, set it after importing: press and hold the row, Set Key…. The key stays in the iPhone’s Keychain and is sent only to the tool’s own address.

What the agent reads

The answer is cut to about 1,500 characters. Search-shaped JSON reads best:

{
  "answer": "optional one-line answer",
  "results": [
    { "title": "…", "url": "https://…", "content": "a short snippet" }
  ]
}

snippet, text or description also work in place of content. Anything else is passed on as plain text. If a call fails, the agent is told so and goes on without it.

To remove an imported tool, swipe it left. Importing a file with the same id replaces the tool.

Export

Export Tools… saves your imported tools as one handsy-tools.json (a list) to share or to import on another iPhone. Keys are not in it: set them again there.