Agent tools

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

Copy page for AIUpdated November 8, 2026

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:

FlagMeansShown as
Reads onlyIt changes nothing. Claude and ChatGPT may use it for people who allowed Read your data.Reads only
Asks firstThe 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

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.

Can't find what you need? Contact support.