Tool designGuide5 min

Decide when to use built-in tools vs custom tools

A decision guide for choosing between OpenAI-provided tools and product-specific functions.

Real workflow example

A customer success assistant needs to answer questions from product docs and create a renewal-risk task when a customer is blocked.

Use OpenAI-provided or platform-level retrieval for general documentation, then use a custom tool for create_renewal_risk_task because that action depends on account ownership, workspace policy, and audit logging.

The system avoids rebuilding generic capabilities while keeping product-specific actions under your authorization model.

Implementation approach

This guide is anchored in OpenAI tools guide. Use the official API behavior as the boundary, then design the surrounding product state so the feature can be reviewed, retried, and improved.

Write the exact job the model must complete and mark which steps require your private data.
Use built-in tools for generic capabilities that do not need product-specific authorization.
Use custom tools for business actions, tenant-scoped data, approvals, and workflow transitions.
Keep the orchestration layer responsible for permissions, retries, and final writes.
Review logs after launch to see which tool decisions need tighter descriptions.

Workflow state shape

type built_in_tools_vs_custom_tools_workflow_state = {
  sourceId: string;
  status: "draft" | "needs_review" | "approved" | "blocked";
  evidence: Array<{ source: string; summary: string }>;
  nextAction: string;
};

Field notes

Built-in tools are strongest when the capability is generic and well-defined.
Custom tools are better when the model must operate on your business rules and private workflow state.
A mixed approach works when retrieval, browsing, files, or product actions need different controls.

Mistakes to avoid

Do not use custom tools for generic work that an existing OpenAI tool already solves well.
Do not use built-in tools for business actions that require tenant-specific permissions.
Do not let the model choose tools without logging which one it used and why.

Ready checklist

Capability mapped to risk
Private data stays behind custom tools
Tool descriptions are unambiguous
Retries are bounded
Audit log captures tool choice

Practical note

Ask one question for each capability: would I trust a generic assistant with this, or does it need my product's permission model?

Use this as an implementation constraint, not just advice. The interface, server code, and validation path should make the same behavior true.

Apply this to a build