Custom Tools — Technical Reference
This page describes how custom tools work beneath the UI, in technical terms, for developers and technically-inclined users. It focuses on the model and observable behavior, not implementation internals.
Architecture model
A custom tool is a single named REST call the agent can invoke on demand. It carries everything needed to make the call and everything the agent needs to decide when to call it:
| Field | Purpose |
|---|---|
| Name + alias | Human-readable name and a stable identifier the agent uses to call it |
| Description | One-paragraph summary — what the tool does in plain language |
| Usage notes | Longer guidance the agent reads to know when to use it (and any caveats) |
| Method | The kind of request (GET / POST / PUT / PATCH / DELETE) |
| URL | The specific address the request goes to |
| Parameters | Path / query / header / body fields, each typed and marked AI-visible or fixed |
| Credential | Optional — the saved login the tool uses to authenticate |
| Tags | Used to group tools by provider for display |
Each parameter is either AI-visible (the agent decides the value at call time, based on the conversation) or fixed (always the same value, baked into the tool definition).
Body parameters must contain named fields, not a single blob. Each field has its own type, required flag, and AI/fixed flag — same as path, query and header parameters. This lets the agent fill in individual fields without having to construct a whole JSON object.
The AI-assisted creation flow
The AI helper builds tools in batches, one toolkit at a time. A toolkit is the set of tools created together for one provider + credential pair (e.g., "HubSpot Contacts" or "Stripe Customers").
The flow is phase-batched — operations are grouped by type across all tools in the toolkit, rather than running each tool end-to-end. For a 3-tool toolkit, this is roughly 6 steps instead of ~18.
Key behaviors:
- Research first, configure later — the AI never guesses parameter names from the tool's label. It reads the provider's own documentation (a quick search + scrape of each endpoint page) before writing the request shape.
- Real test calls — every tool is tested with one real call to the configured URL before being marked validated. A passing test produces a slim response preview kept with the tool; a full response is stored separately for review.
- Sample outputs — when a tool's test produces a useful artifact (image, PDF, document, structured data), the AI attaches it to the tool's record so the Toolkit Guide can show it as a preview.
- Warnings — non-obvious limitations (pagination, async behavior, sandbox-only access, deprecated alternatives) are attached to the tool as
info/warning/criticalnotes. They appear as banners in the Toolkit Guide and are appended to the tool's usage notes so the consumer agent sees them at runtime. - Async / queue endpoints — if a provider's "do the work" endpoint is async-only, the AI either prefers a sync variant, or splits the work into a
submit_*+get_*_resultpair, or marks the tool with a critical warning. Async-only tools are never shipped without a warning.
The session is long-lived: a user can come back later and add more toolkits to the same conversation, finalize each one independently, or restart from the landing if they want to start over.
Tool draft lifecycle
Inside a session, each tool moves through a state machine:
| Status | Meaning |
|---|---|
| draft | Blank template, no endpoint yet |
| configured | Method, URL and parameters filled in (warnings may be attached here) |
| tested | A real call ran; the slim response preview is stored with the draft |
| validated | The test passed; sample-output previews can be attached here |
| created | The user clicked Create; the tool now exists in their account and can be assigned to agents |
A failed test sends the tool back to configured so the AI (or the user) can fix the parameters and retest.
How an agent uses a custom tool at runtime
When an agent decides to call a custom tool, the platform:
- Reads the tool's stored definition and the credential it references (if any).
- For each parameter, picks the AI-visible ones from the agent's intent and uses the fixed ones as-is.
- Substitutes the credential into the right slot for its auth family (header, query parameter, or signed token — see Credentials Technical Reference).
- Sends the request to the configured URL.
- Returns the response to the agent.
- If the response is large, the agent sees a compact preview and a handle to the full content rather than dumping the whole payload into context.
The agent never sees the credential's secret in its context — only that the call was authenticated.
Toolkit and tool grouping
Tools created together via the AI flow are kept under a toolkit key (provider + credential). The toolkit is the unit shown in the Toolkit Guide; finalizing it creates each tool independently as a separate, named tool in the user's account.
After finalization:
- Tools are standalone — they don't depend on the toolkit they came from.
- A tool can be assigned to any agent the user owns.
- A tool can be edited later through the manual builder.
- Warnings attached at creation time become part of the tool's usage notes and travel with it.
Assignment, shared 25-tool limit
A custom tool only runs as part of an agent. Each agent has a shared budget of 25 tools spanning custom tools and database tool connections:
| Slot | Counts as |
|---|---|
| Custom tool | 1 |
| Database connection (read) | 2 |
| Database connection (write) | 5 |
| Database connection (full) | 7 |
The limit is enforced when the user assigns a tool or changes a database permission; trying to exceed 25 fails fast with a clear message. The tool catalog itself can contain many more tools; the limit only applies to what a single agent has attached at one time.
Templates
Templates are pre-configured tool definitions for common services — the method, URL and parameter shape are already filled in. Installing a template clones it into the user's account; the user still attaches their own credential and can edit any field. Templates speed up the manual path; they have no special runtime behavior once installed.
Limits and guarantees
- A tool is one REST call — multi-step orchestration belongs in an agent or an automation.
- Body parameters must be named fields, not a single blob.
- Every tool is tested with a real call before being marked validated.
- Warnings attached at creation time are visible to the consumer agent at runtime, as part of the tool's usage notes.
- Sample output previews live with the toolkit guide for review and do not affect runtime behavior.
- Each agent has a shared 25-tool budget across custom tools and database connections.
- The agent never sees a credential's secret value — only the credential ID it should use.
What's next
- Creating with AI — the guided build flow
- Creating manually — the manual builder
- Credentials Technical Reference — how the credential side works