Skip to main content
Tools let an Agent request work. Choose a Tool by what it does, who executes it, and whose account it uses. An Agent can combine supported choices. Their execution and authorization boundaries remain distinct. Check capability status for the selected harness, Tool release, and execution path.

​
Check the action

Suppose an Agent needs to create an issue in your team’s repository. Finding an issue-creation Tool is only the first step: Approval applies to the exact action, account, material arguments, and destination. Changing the repository or issue content does not reuse the old decision. An approved call still needs current permission and a supported execution path. A Tool wait and its matching response retain the original public Run. Internal tool rounds and recovery do not create another Run; an independent follow-up request has its own Run intent. The JSON examples below are update bodies for POST /v1/agents/{agent_id}. tools and mcp_servers are replacement lists: retain every entry you intend to keep. See Agents for creating and selecting an immutable AgentVersion.

​
Choose built-in Tools

Built-in Tools come from the selected harness release and are constrained by the Environment. This example selects read while disabling the toolset’s other Tools:
The selected harness must support the Tool. Admission freezes the Session’s capability ceiling; selection does not grant a logged-in account, broader filesystem access, or permission to spend. A native Tool and a host-executed Tool are different paths. A harness may ask a host to execute work, or execute a supported native operation itself. Delivering an approval to a harness does not prove that Checkfu intercepts every shell, browser, or guest action. Protection depends on the qualified resource-owner checks and actual isolation of that path, not prompts or after-the-fact events.

​
Bind a connected account

A connected Tool uses an exact Connection. Select the personal or Workspace account and review its Tools before saving the Agent configuration. Neither the provider name nor the Tool name identifies an account. Missing, stale, ambiguous, or unauthorized bindings must not fall back to another account. For the issue example, bind the team’s Connection to a named MCP server and select its Tool:
Current native Session admission accepts only read-only connected offerings that are neither destructive nor marked as requiring approval. The issue-creation example above demonstrates the Agent update format; native connected writes remain unsupported through this path. Existing policy checks and approvals still govern supported calls. Replace the example Connection ID and illustrative Tool name with your selected account and a Tool returned by its qualified offering. A familiar provider name is not an availability claim. Each mcp_servers entry needs a unique name, and each mcp_toolset must name its intended server. Connect a provider account walks through setup, Tool selection, and access review. Connecting an account, refreshing it, or selecting it does not grant permission. A changed binding may require a new AgentVersion and Session; it cannot silently replace the account of active or recovering work. Connected calls check PermissionAssignments, then ActionPolicy and any required ActionApproval. Checkfu rechecks the exact Connection revision, Tool/schema, revocation, egress, and spending authority before provider I/O. It checks current authority again after waits or recovery and before releasing a result. Approval is not a lease on revoked authority. On the governed MCP tools/call path, approval records a decision without executing the operation. Retry the identical original call with its original ToolInvocationId and returned requestState where applicable. A completed identical retry is refused as already_executed, not dispatched again. Model BYOK chooses model access; tool Connections choose external accounts. Ordinary Tools OAuth, refresh, reconnect, and revocation remain supported contracts despite the retirement of Checkfu-custodied model-subscription credentials. An outbound account credential and a webhook verification secret also have different purposes. A healthy Tool account does not by itself authorize provider webhook registration.

​
Serve a Custom tool

Use a Custom tool when your application should execute the operation. For example, your issue-creation handler could apply your own repository rules:
The Tool is declared by the admitted Agent. Its call has no Connection, ToolSource, platform-held provider Credential, or PermissionAssignment check. Session admission is separate; the Tool call evaluates ActionPolicy directly:
  • With no restricting ActionPolicy, it proceeds to the application-result wait.
  • deny means the application must not execute the handler.
  • require_approval creates an ActionApproval for the exact recorded call.
On the approved branch, run.action_authorized records authorization. Approval does not execute your handler or manufacture its result. Your handler still enforces its own tenant, account, row, and downstream-provider rules. Keep its credentials in your trusted application runtime. Return the result for the original tool_use_id. The matching user.custom_tool_result continues the same public Run. An exact result retry must retain the original identity and content; it does not authorize running the handler again. A recorded result can prevent duplicate handler execution, but it cannot prove what happened in a remote service before that result was recorded. See Serve tools from your app.

​
Use Managed Tools

Managed Tools are connection-free, pay-per-use capabilities backed by Checkfu-operated provider supply. Select an exact Tool and release, inspect its terms, and set a per-call spending ceiling. A catalog entry or saved selection does not authorize a purchase. Checkfu reuses Executor for regular tool integration and suitable Monid open-source components for Managed Tools. Customers do not need Executor or Monid SaaS accounts; Checkfu’s account, approval, spending, and recovery contracts govern the call. Inspect GET /v1/managed-tools/{managed_tool_id}/releases/{managed_tool_release_id}. The exact release reports customer_terms_status: available, not_installed, or revoked. Available terms include the price in micro-USD, billing rule, valid-empty-result treatment, rate-card identity/version, and effective window. One US dollar is 1,000,000 micro-USD. customer_terms: null means no offered quote, not a free operation. A technical failure remains an error. These observed terms do not reserve money or guarantee a later price. Invocation freezes its original terms and separately checks use_tool, allow_spend, policy, approval where required, and financial admission. A per-call ceiling is not an approval or a Budget reservation. Commercial activation and provider qualification remain separate prerequisites for paid use. The direct invocation body uses selection, arguments, maximum_charge_microusd, and acted_as_principal_id. The authenticated owner checks the acting identity; the body cannot grant delegation. See Managed Tools for the served endpoint, statuses, approval continuation, and same-call recovery.
Catalog lists are metadata-only. Open an exact release to inspect customer terms under catalog-read authority; Principal MCP invocation compatibility does not grant Principal catalog access. The billing basis is valid_result or admitted_dispatch. Polling and recovery of the same invocation do not create another logical purchase.A release’s schema can be broader than its execution profile. The Firecrawl Map profile does not support threatProtection, and an explicit timeout must fit its execution duration. A displayed price or valid upstream schema does not permit unsupported options.An AutomationGraph uses invoke_managed_tool with selection, arguments, maximum_charge_microusd, and optional argument_bindings and join. Named bindings require object arguments; multiple named producers require all_completed. These fields describe intent, not credentials, acting authority, or a dispatch grant. The original firing owner supplies identity. An unavailable catalog does not justify replacing the selected release.Managed result inputs for a Check or Decision select a bounded JSON pointer allowed by the release’s output schema. Each stays bound to its original invocation and destination. All selected inputs are rechecked before use. This does not imply support for arbitrary copies or Agent inputs. Native registration and direct invocation have their own capability requirements.

​
Handle refusals and retries

Input acceptance, completed work, and permission to read the result are different facts. A refusal before dispatch prevents that operation. A refusal at result release does not undo an effect that already happened or erase its charge. Retain the original call, selected account or release, executable arguments, result identity, and financial terms across waits, cancellation, and recovery. If provider acceptance or settlement is uncertain, reconcile the original invocation through provider lookup or its supported idempotency mechanism. A connected ToolInvocation can record this uncertainty as indeterminate. Do not create a new invocation key to repeat an uncertain action. A local transaction cannot make a remote provider call atomic with a local receipt. A verified completed Managed effect whose result cannot be released can return tool_invocation_id, status: "completed_withheld", and provider_effect: "completed", without a result body. This does not erase the original charge or authorize another call. Current authority is required even to disclose that completion; an unverified effect cannot use this response. For governed MCP results, isError: true and structuredContent.checkfu.status identify a mapped refusal. policy_denied differs from authorization_unavailable; checkfu.message is guidance, not a stable code. Transport failures outside this mapping retain their own error behavior. If checkfu.provider_effect is completed, reconcile the original ToolInvocationId: the effect completed but its result was withheld. A refusal code alone does not prove that the provider did nothing.
exec.tool_invocation records structural settlement and original invocation coordinates without argument or result bodies. Apply a later upgrade: true correction to the earlier record with the same tool_invocation_id. Tool-result status and settlement disposition describe different boundaries. argument_fingerprint is opaque correlation evidence, not a hashing API or an invented link to agent.tool_use.Audit exports correlate connection_id, Run, and tool_invocation_id. A pre-dispatch denial records capability_gateway.denied against the Run; terminal records name the Connection and use capability_gateway.executed or capability_gateway.execution_<disposition>. They record Checkfu’s observed disposition, not independent provider verification. The actor identifies the authenticated Principal. Optional declared_caller values (model or code) are caller-authored diagnostics, not proof of causality or authority. Not every refusal produces one Connection record.

​
Keep secrets out of Tool data

Checkfu-custodied credentials attach at the trusted outbound boundary, not in Agent configuration or Tool arguments. Provider and customer results are not automatically secret-free. The response path bounds content and checks release authority, but does not generally scrub credential echoes or live sandbox result spills. Return only authorized, non-sensitive values; keep secrets out of results, Files, Memory, instructions, and Session events. See Connections and Billing for account custody and charges.

​
Skills are not Tools

A Skill supplies versioned instructions and optional files. Loading one grants no Tool, transport, Connection, or approval. Executable Skill content can cause an Agent to request a Tool; that Tool still follows its own authorization and execution path.