Tools and Permissions

Agent definitions control what tools an agent can use. You can grant access to built-in tools or define custom workflow tools.

The model only sees the tools you explicitly provide.

Built-in permissions

Grant built-in permissions directly on the agent definition.

permissions: {
  'fs:read': true,
  'web:fetch': true,
}

Permission map

Permission	Tool names
*	All built-in tools
fs:read	readFile, listDirectory, glob, grep
fs:write	writeFile
shell:execute	executeCommand
web:fetch	webFetch
web:crawl	webCrawl

Start narrow. Avoid * unless the agent runs in a tightly controlled environment.

Restrict tools

Use allowedTools to narrow a permission category. For example, fs:read grants access to four tools. You can restrict it to just grep.

permissions: {
  'fs:read': true,
},
allowedTools: ['grep'],

Permission boundaries

Permissions are scoped to the agent. A primary agent cannot use a tool granted only to a secondary agent, and vice versa.

If the primary agent needs to read files, it must delegate to a secondary agent that has the fs:read permission, or you must grant fs:read to the primary agent directly.

Workflow tools

Use defineWorkflowTool() to connect an agent to a workflow.

import { defineWorkflowTool } from '@culvii/kit';

const runSupportWorkflow = defineWorkflowTool({
  name: 'runSupportWorkflow',
  description: 'Run the approved support workflow for a customer request.',
  workflowId: 'workflow-id',
  triggerNodeName: 'Manual Trigger',
});

Attach the tool to an agent definition.

tools: {
  runSupportWorkflow,
}

Write clear descriptions. The model reads the description to decide when to use the tool.

Input schema

Add an inputSchema when the workflow expects structured data. Keep schemas small so the model can easily fill them.

const runSupportWorkflow = defineWorkflowTool({
  name: 'runSupportWorkflow',
  description: 'Run the approved support workflow for a customer request.',
  workflowId: 'workflow-id',
  inputSchema: {
    type: 'object',
    required: ['customerId', 'priority'],
    properties: {
      customerId: {
        type: 'string',
        description: 'The customer id from the request.',
      },
      priority: {
        type: 'string',
        enum: ['low', 'normal', 'high'],
      },
    },
    additionalProperties: false,
  },
});

Use serializable workflow tool declarations for shared agent definitions. This allows the definitions to cross process and service boundaries.

Tool call timeout

A workflow tool call has 5 minutes to resolve. If the workflow it runs doesn't complete in that time, the platform treats the call as failed and the agent gets an error result rather than waiting indefinitely.

This matters most for workflows that pause on a human-in-the-loop step. If a runSupportWorkflow-style tool triggers a workflow that waits on approval, make sure that approval can realistically happen within 5 minutes, or design the workflow to resolve the tool call immediately and handle the wait asynchronously (e.g. notify back via a separate channel) instead of blocking on it.