Tool & Integration Security

Tools let agents read context and take action. A tool might search a connected app, update a ticket, call a customer API, send a message, or modify Duckie configuration through MCP. Use this guide when enabling tools for an agent or assistant.

​

Choose The Right Tool Boundary

Duckie supports four tool categories: Pick the narrowest tool boundary that fits the workflow. Prefer a specific update tool over a broad generic API caller when the action is repetitive and high impact.

​

Control Which Agents Can Use Tools

App tools and custom tools become usable only after they are connected or created and enabled for the agent or assistant that should use them. For each agent:

1. Open the agent’s tool access settings.
2. Enable only the tools needed for that support role.
3. Keep write tools separate from lookup tools.
4. Test the agent with the exact tool-enabled workflow.

This lets one agent investigate while another agent can update external systems only after additional controls are in place.

​

Connect App Tools Deliberately

Connected apps inherit the access of the external account, token, workspace, repository, project, channel, or knowledge source you connect. Before connecting an app:

• Decide which external workspace or account Duckie should access.
• Use provider-side permissions to limit access where possible.
• Enable only the app tools the agent needs.
• Review runs after launch to confirm expected tool use.

Manage connected apps in Settings -> Connections.

​

Design Custom Tools Safely

Custom tools call HTTP endpoints that you define. Use them for internal services, third-party APIs, or API actions that are not covered by connected integrations. For safe custom tool design: Custom tool endpoint URLs must use http or https. Duckie blocks local, private, and internal network addresses before making server-side requests. For custom tool execution, Duckie validates the configured URL, resolves variables and parameters, and validates the final URL before the HTTP call. See Custom Tools.

​

Handle Credentials Carefully

Use the credential mechanism that matches the external API: For static secrets, prefer org variables over AI-generated parameters. Sensitive org variables are encrypted at rest and masked in Duckie API responses. OAuth token URLs must use HTTPS, cannot contain org variables, and are validated before use.

​

Mark Write Actions

Use Write Action for tools that change external state, such as updating an account, issuing a refund, creating a ticket, sending a message, closing a conversation, or changing a record. Marking write actions makes the tool’s impact explicit and supports safer testing and review. Batch test runs execute in testing mode and skip write app tools, custom tools, and MCP tools. See Deployment Modes and Batch Testing.

​

Require Approval For Sensitive Side Effects

Use Requires Approval when a human should approve the tool call before it runs. Require approval for actions such as:

• Billing changes, refunds, or credits.
• Plan, entitlement, or ownership changes.
• Security setting changes.
• Customer-visible messages in sensitive workflows.
• Destructive or hard-to-reverse external updates.
• MCP write actions that modify Duckie configuration.

When approval is enabled, the run pauses before execution and resumes after the action is approved or rejected.

​

Use Workflows For High-Risk Paths

Use workflows when an action must follow a consistent verification path. A high-risk tool workflow should usually:

1. Look up the current requester, ticket, customer, or account.
2. Extract the requested target or requested change.
3. Compare the requested target to verified context.
4. Continue only on the approved branch.
5. Require approval when the action is sensitive.
6. Escalate or send a safe response when verification fails.

For customer/account updates, follow Account-Safe Actions.

​

Tool Security Checklist

​

Related Docs