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:
- Offers the tool only to people (and agents) holding that permission.
- Points it at the right workspace's data, and only your module's tables.
- Records every call: who, when, with what, and the result.
- 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, 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, 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
For developers
@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.