Maintain reusable team tools
A team tool is a shared callable definition with parameters, instructions and executable code. Use it when several flows need the same approved operation. Keep reusable integration behavior here; per-conversation values and a flow's choice of when to call the tool remain with the flow author.
Availability: open Settings → Tools in the intended team. Creating, updating and deleting a team tool require Team Admin or platform administrator authority; read-only platform access does not grant editing. See Access and teams. Do not infer the same authorization contract for every historical version operation solely from the toolbar.
Prepare a team tool
Agree on the operation, external service, permitted inputs, credential owner and affected flows before writing code. Tool code is trusted administrative code. Save-time validation is not a security boundary for untrusted code, nor proof that its HTTP calls, permissions or business effects are correct.
Maintain a platform-wide tool
For a shared operation available across teams, a Super Admin opens Admin Settings → Tools (/admin-settings). This is a separate platform library, not the selected team's Settings → Tools. Super Viewers can read the platform list; ordinary create, update and delete endpoints require Super Admin authority. Team Admin authority alone does not permit maintaining the platform library.
The platform list uses the same Name, Type, Status, Version, Usage and Updated columns and Create/Edit/Delete workflow. The list does not calculate a usage count, so a blank Usage cell is not proof of zero consumers. Version is the latest snapshot number plus one, not an execution count or product release. Identify affected teams and flows before changing or deleting a platform definition.
Choose Create, or edit the intended row, then use the shared Name, Available, Description, Instructions, Parameters and Code controls described below. The platform editor uses the same field editor and version-history sidebar. Ordinary update snapshots the previous definition before writing the new one; Restore is a separate server mutation, not an unsaved preview. Do not infer every historical-version permission from the ordinary create/update controls.
Active platform tools appear alongside the team's active tools when a flow author selects a shared action. Attach the intended scope in the agent action editor; a copied or detached flow-local definition is independent of future library edits. Name-only references can prefer a team tool over a platform tool with the same name, so verify which definition is resolved. Saving or restoring the platform library does not synchronize every consuming flow automatically. Coordinate publication/synchronization and verify a new controlled invocation in the intended team.
Read the tools list
The list shows Name, Type, Status, Version, Usage and Updated. Status reflects the library entry's active state; Version is the latest stored tool version, not a product release. Usage is the returned reference count, not evidence of live executions or a complete inventory of copied code. Updated is the stored modification time.
Use search to locate the intended shared definition. With write authority, choose its row or edit icon to open the editor; the delete icon opens a confirmation. Read-only access disables these mutation controls. Before deleting, inspect consumers and the recovery guidance below rather than assuming a zero Usage value means no deployed code can still use the operation.
Define the shared contract
Choose Create and use the editor fields to make the operation understandable to both the flow author and the model that may call it.
| Control | What to define |
|---|---|
| Name | Stable callable name using letters, digits, underscores or hyphens; no spaces. Renaming requires reviewing references. |
| Available | Whether the shared definition is active for runtime resolution. This is not a kill switch for code already loaded by a conversation. |
| Description | The purpose and when the model should use the operation. Avoid promising results the code cannot establish. |
| Instructions | Shared guidance for calling/using the tool. A flow reference may have its own instructions override; review it too. |
| Parameters | Named inputs, their types/descriptions and required-input selection. Use the editor's supported schema shape rather than assuming every JSON Schema construct is accepted. |
| Code | JavaScript or TypeScript implementation supported by the editor. Review source and compiled output where applicable. |
Provide an explicit result for expected business failure, and distinguish it from a successful operation. Do not return success merely because a network request or queued side effect was attempted.
The server checks submitted executable code statically before ordinary create/update persistence. Rejected syntax or forbidden host-access constructs must be corrected; do not work around validation by moving the same unsafe code into another field. This check does not call the external API or exercise every input.
Use HTTP APIs without exposing credentials
Keep service credentials in team secrets. Use their supported server-side references in authentication configuration; never ask the caller/model to supply the team's API key as an ordinary tool parameter. Avoid including credentials in URLs, descriptions, source literals, returned results or logs.
The runtime provides a fetch helper for HTTP requests. Its response wrapper supports ok, status, statusText, plain-object headers, and asynchronous json()/text(). It is not a full browser Response object or an Axios response: do not assume response.data or headers.get() exists. HTTP and network failures can throw, so handle exceptions as well as checking the returned result. Parsing JSON can also fail.
A standalone Webhook node uses a different response path: non-success HTTP status with valid JSON can still complete without _lastError. For that node, follow Branch on a webhook response; do not copy the shared-tool fetch error behavior onto it.
For an integration review, check:
- The intended server URL, HTTP method, header/body mapping and response shape.
- That authentication goes only to the intended service and is excluded from user-visible results.
- How invalid input, permission denial, timeout, non-JSON response and service failure are reported.
- Whether repeating the operation could create duplicate business effects. A retry must follow the external service's actual idempotency contract.
Use a controlled external test service and synthetic inputs. A saved tool or an HTTP success status alone does not prove the requested business operation completed. Validate the response and, where necessary, the service's resulting record.
Connect it to a flow and activate deliberately
Saving a tool does not automatically make every agent call it. The flow author must select/reference the shared tool on the intended node, review its parameters and any per-node instructions override, then follow the application change procedure.
Runtime preparation resolves active shared tools. For name-only references without an explicit scope, a matching team tool takes precedence over a platform tool of the same name. Explicit scoped or ID references have their own resolution; use deliberate names/scope instead of relying on accidental collisions.
Ordinary team-tool create/update/delete saves persist the library change; they do not themselves synchronize every consuming flow. Arrange synchronization/publication of affected flows through the approved workflow, then verify a new controlled conversation. Do not promise an in-progress call will switch implementations mid-call.
Use Review a conversation to inspect the actual invocation, result and related error. Verify the external business effect too, especially for writes, transfers or queued messages.
Versions and safe recovery
Editing an existing tool snapshots its prior name, description, instructions, parameters and code. Version history is useful for recovering those fields; it is not an application release history or a complete snapshot of every tool property.
Restore performs a server-side change: it snapshots the current content and restores the selected version's supported fields/code. It is not merely a preview loaded into an unsaved dialog. Review availability/type and any other settings separately because they are not all part of that restored snapshot. Recheck consumers and synchronize deliberately before considering recovery complete.
For a failed update or restore, inspect the saved library state before retrying. For an unavailable tool at runtime, check Available, the reference name/scope and the last successful flow synchronization. For an API failure, preserve the conversation/trace ID and redacted error and use Logs and diagnostics.
Before deletion or deactivation, identify consumers and prepare an approved replacement. Removing a shared definition does not cleanly rewrite every reference or prove that already-loaded runtime code has stopped. Retain the working configuration needed for a deliberate rollback.
For flow-local definitions and per-node instruction overrides, use Manage an agent’s actions. That dialog is distinct from editing the shared library here.
Verify the change
- Publish or synchronize each flow that references the tool, as described in the application change procedure.
- Start a new controlled conversation that exercises the tool with synthetic inputs.
- Open the conversation record and confirm the tool invocation, its returned result and the expected external effect.
Related
- Manage shared team variables and secrets — to store the credentials a tool uses without exposing them.
- Review a conversation — to confirm the tool was invoked and inspect its result or error.
- Manage an agent's actions — to attach the shared tool to a flow node.
- Logs and diagnostics — to investigate a failed invocation with its trace ID.