# Reading a tool's source

> Every authored tool is a small module you can read: what it calls, with which method, and why it holds neither a credential nor a host.

Source: https://docs.getgraft.ai/graft/toolbox/reading-a-tools-source

An authored tool is a small module of code making one call against one connection, written by Graft's model and kept in your toolbox with every version. The agent reads the current version back with `read_tool_source { vendor, name }`, which answers the tool's wire name, version number, path, annotations and its files as text. It sits in the advanced set, marked as such in its description, and it is read-only: reading source asks nobody.

The agent reaches for it in two cases: when a helper in one tool is worth reusing in the next, and when you want to know what a tool actually calls. Ask for that in plain words and the agent reads the module and tells you.

## What a module looks like

A version is a directory, `tools/<vendor>/<name>/v<N>` in your toolbox, holding at least `index.ts`. The entry's default export takes the tool's input and a context and returns whatever the vendor answered:

```ts
export default async (input: Input, ctx: Context) => {
  const response = await ctx.fetch(`/v1/orders?limit=${input.limit}`);
  return response.json();
};
```

`Input` is generated from the JSON Schema the tool was published with. `Context` is the module's whole route out, and it carries four things: `ctx.fetch(path, init)`, which takes a vendor-relative path and nothing before it; `ctx.proxyBase(host?)`, the base URL an SDK is pointed at; `ctx.proxyKey`, the credential an SDK is constructed with; and `ctx.connection`, the connection id. There is no vendor host in the module and no key, because the proxy supplies both from the connection when the request leaves the sandbox.

A module that uses a package has a `package.json` with a `dependencies` table, and the published version carries its own `node_modules` and lockfile, installed at publish. A module that imports nothing has neither.

## What to look for

**The paths.** Each `ctx.fetch` names a vendor-relative path such as `/v1/orders`, which resolves against the connection's primary host at the proxy. A literal `https://` anywhere in a `ctx.fetch` call would have been refused by the check as `fetch-absolute-url` before the tool was published.

**The methods.** They decide whether, and about what, the tool asks. The check reads every call the module makes: a module whose calls are all `GET` or `HEAD` publishes as read-only and never asks; any `DELETE` marks it destructive, and its ask says so; anything else, a method the check cannot read, or any call into an SDK counts as a write. Write and destructive tools alike ask once, and the answer holds unless you set the tool to ask every time. These annotations come from the code, never from what the model said about it.

**The description.** The description the console shows, and the one the harness reads, was written by Graft's model. The console marks it *written by the agent's model* wherever it appears in an ask, so read it as the model's account and check it against the source when a write matters.

## Versions

Every publish writes a new version and moves the tool's pointer to it. `read_tool_source` reads the current version, and the console's working-set table shows that version's description and annotations. Older versions stay in the toolbox and are never removed by the system; a self-hoster finds them under `GRAFT_TOOLBOX_ROOT` in the toolbox volume, one directory per version.

A long module comes back truncated with a note, and the agent then reads it one file at a time with `read_file` from the version's path on its sandbox.

## Prompts to try

```text
Show me the source of the xero__list-invoices tool and tell me which endpoint it calls.
```

```text
Before I approve it, read the unleashed__create-sales-order tool and explain what it sends.
```

```text
Read the source of github__get-repo and reuse its error handling in a tool that lists issues.
```

## Where next

- [Tools and the toolbox](https://docs.getgraft.ai/graft/concepts/tools-and-the-toolbox.md): What an authored tool is, how it is named, and what the toolbox keeps.
- [How approvals work](https://docs.getgraft.ai/graft/approvals/how-approvals-work.md): Reads pass, everything else asks once, and asking every time is your opt-in.