# Agent tools

The actions your agent can take, with permissions, workspace isolation and audit built in, so your module writes no security code.

A **tool** is one thing your agent can do: find a job, add a part, work out a quote. You write the business logic; the platform wraps it with everything else. Each tool checks the person's permission, works only in their workspace, and is recorded in the audit log, without a line of security code from you.

## Your screens' actions come free

Every action behind your module's screens is already offered to assistants: the in-app agent, Claude and ChatGPT through the connector, and the command line. Each runs as the person, with the same permission check as the screen. So **don't write a tool that just repeats one action**. Write a tool for a job no single action does:

- Find a record **by name** instead of by id
- **Preview** a bulk change before applying it
- A **calculated** answer, like *margin by job this quarter*
- Several steps in one go

## Writing a tool: one function, one decorator

A tool is one function with a short description and **one permission**. Then the platform:

1. Offers the tool only to people (and agents) holding that permission.
2. Points it at the right workspace's data, and only your module's tables.
3. Records every call: who, when, with what, and the result.
4. Turns errors into a clear message for the agent.

Two flags matter:

| Flag | Means | Shown as |
|---|---|---|
| **Reads only** | It changes nothing. Claude and ChatGPT may use it for people who allowed *Read your data*. | *Reads only* |
| **Asks first** | The agent stops and a person must approve before it runs. Use it for deletes and sending to customers. | *Asks first* |

Mark *reads only* honestly. A tool that writes anything, even "last viewed", isn't read-only.

**Loading lots of records?** Give the job two tools: a *preview* that saves nothing and shows every change, and an *apply* that does exactly what the preview showed.

## The platform tools you can grant

Your agent can also be given tools the platform offers:

- **Shared folders**: check what a person shared from their PC through the Bridge, ask them to share a folder (they answer *Once* or *Always*), list and read files, bring one into your module's [storage](article:4c8a50b6-7a7d-4f07-b1fe-b8748ecddd6f), or save one back to a folder shared as *Can edit*. Never delete.
- **Save file to module**: save a file attached to the chat, or a public web image, into one of your storage folders.
- **Website brand**: read a public website's colors, fonts and logo.

## Tools that run on a Bridge

A tool can run on the workspace's own computer through the [Bridge](article:e321ac18-ced4-47f4-9933-e3bdbe028c30), for jobs inside the company network. Bridge access is off until Data Visions approves your module's Bridge request. Bridge tools aren't offered through Claude or ChatGPT.

## Testing a tool without the platform

The developer kit includes a test harness: an in-memory stand-in for your module's tables and a pretend person whose permissions you choose. Call the tool directly, check its answer, and check it refuses someone without the permission. No server, no database.

## Ask the Module Builder

> *"Add a tool that finds a job by customer name or address and returns its status, crew and next visit. It only reads."*

## For developers

```python
@platform_tool(module_code="JOBS", permission_code="JOBS.READ",
               description="Find jobs by customer name or address.",
               read_only=True, label="Looking up jobs")
async def find_jobs(context: ToolContext, text: str, limit: int = 20) -> dict:
    rows = await context.tenant_data.query("jobs", filters={"status": "open"}, limit=200)
    hits = [r for r in rows if text.lower() in (r["customer"] + r["address"]).lower()]
    return {"jobs": hits[:limit]}
```

Tests: `make_tool_context(denied_permissions={"JOBS.READ"})` from the SDK's testing helpers.

## Good to know

- **The permission must be one your module declares.** The module check flags anything else.
- **A tool gets 60 seconds** unless it asks for more (up to 5 minutes).
- **Keep tools stateless.** Save working state in your tables after each call.


Source: https://datavisions.ai/docs/creators/platform-services/agent-tools
