# Tools and the toolbox

> Meta-tools, authored tools, and the toolbox that keeps every version of every tool Graft's model has written for you.

Source: https://docs.getgraft.ai/graft/concepts/tools-and-the-toolbox

Everything in an agent's MCP tool list is one of two kinds. **Meta-tools** are fixed, and every agent has them. **Authored tools** are what Graft's model wrote for you, and each agent sees exactly the ones promoted into its working set.

## The meta-tools

| Tool | Input | What it does |
| --- | --- | --- |
| `acquire` | `connectionId`, `goal`, `hints?` | Asks Graft's model to author the tool you lack against one of your connections. Returns a job at once. |
| `acquire_status` | `jobId` | The job's status, the progress lines so far, and the tool when it is done. |
| `find_tool` | `query` | Searches your whole toolbox by vendor, name and description, demoted tools included. |
| `promote` | `vendor`, `name` | Moves a tool from the toolbox into the agent's working set. |
| `demote` | `vendor`, `name` | Takes a tool out of the working set. It stays in the toolbox. |
| `run_tool` | `vendor`, `name`, `input?`, `dryRun?`, `detached?`, `timeoutSeconds?` | Runs a tool by name, promoted or not; the turn a tool was just published, before the list refreshes. |
| `request_connection` | `vendor`, `primaryHost`, `scheme`, `displayName?`, `hosts?`, `schemeConfig?`, `docsUrl?` | Proposes a new connection and returns a handoff link for you to confirm it and enter the secret. |
| `request_credential` | `connectionId`, `reason?` | Asks you to re-enter a connection's credential after a vendor 401 or 403. |

Beside these is a low-level authoring set (`write_file`, `read_file`, `run_command`, `wait_for_process`, `read_web_page`, `check_tool`, `publish_tool`, `read_tool_source`) and one `execute__<connection id>` tool per connection in scope. `acquire` drives these itself; they stay available for a person running a strong model who wants their own agent to hold the pen.

## Authored tools

An authored tool is a small TypeScript module making one call against one vendor: the fields this task needs, no pagination, no client for the rest of the API. It reaches the vendor through `ctx.fetch` with a vendor-relative path, or through an official SDK bound to the proxy. It never holds a credential and never names a host.

On the wire it is `<vendor>__<name>`: two kebab-case halves joined by a double underscore, `github__list-issues`. It carries a real input schema, so the harness validates every call, and two annotations:

- `readOnlyHint` is true when the module's calls are all `GET` or `HEAD`.
- `destructiveHint` is true when it uses `DELETE`.

Any other method is a write, and so is every SDK call and any method that is not a literal. The static check derives both from the code; nothing the model says about the tool changes them. These annotations are what decide whether a call asks you first. See [How approvals work](https://docs.getgraft.ai/graft/approvals/how-approvals-work.md).

The tool's **description** is written by the agent's model. Wherever the console shows it, it is marked as the agent's account of what the tool does, not a person's.

## The toolbox

The **toolbox** is your store of authored tools, one per person, every version kept. Republishing a tool under the same name writes the next version and moves the pointer; a run already on the old version finishes on it. Nothing is ever deleted by the system. A demoted tool, a tool whose connection was revoked, a version that was superseded: all still there.

`find_tool` searches the whole of it, promoted or not, and answers each tool's vendor and name, whether it is in the working set, and its two hints. A tool that is not promoted is one `promote` call from appearing in the list, and `run_tool` runs it without promoting it.

The console shows the toolbox from two sides: each connection card under **Connections** lists the tools authored against its vendor, and each agent's page shows which of them are in that agent's working set.

- [Promote and demote](https://docs.getgraft.ai/graft/toolbox/promote-and-demote.md): Moving tools in and out of a working set by hand.
- [Reading a tool's source](https://docs.getgraft.ai/graft/toolbox/reading-a-tools-source.md): What `read_tool_source` returns and how to read a module.

## Try it

```text
What tools do you have for GitHub, including ones not in your list?
```

```text
Show me the source of the tool that lists my orders.
```

```text
Is the tool you just built read-only, or will it ask me before it runs?
```