Create a tool
By the end of this page you will have a custom Project tool saved as a draft, ready to test and publish.
Prerequisites
- A project created (Create your first project).
- Owner, Admin, or Developer role. Without permission you’ll see “You don’t have permission to create tools in this project.”
The wizard at a glance
From the Tools registry, click Create Tool. The Create Agent Tool wizard opens. Its header shows Step {n} of {total} and the current step’s title.
The wizard has seven steps:
| # | Step | What you define |
|---|---|---|
| 1 | Basic Info | Name and description |
| 2 | Classification | Category and data type |
| 3 | Input Parameters | Define input fields |
| 4 | HIL Config | Human-in-the-Loop settings (optional) |
| 5 | Implementation | HTTP or Python handler |
| 6 | Output Schema | Define output format |
| 7 | Review | Confirm and create |
You can click Save Draft at any time — the header shows “Draft saved” with a timestamp. Move between steps with Back and Next.
Steps
Step 1 — Basic Info
Give your tool a unique identity. The heading reads “Basic Information” with the note “Give your tool a unique identifier and describe what it does.”
| Field | Notes |
|---|---|
| Tool Key (required) | Unique identifier in snake_case, 3–50 characters. Must match ^[a-z][a-z0-9_]{'{'}2,49{'}'}$ — start with a letter, then lowercase letters, digits, or underscores. Example: get_customer_data. |
| Display Name (required) | Human-readable name shown in the UI. Example: Get Customer Data. |
| Description (required) | What the tool does. This description is shown to the LLM to help it decide when to use the tool — write it for the model, not just for people. |
The description isn’t just documentation — an AI Agent reads it to decide whether to call your tool. Be specific about what the tool does and when it applies.
Step 2 — Classification
Declare the tool’s behavior and data sensitivity. The heading reads “Classification.”
Tool Category — pick one:
| Category | Meaning |
|---|---|
| Function | Pure computation, cacheable, idempotent |
| Data Pull | Read-only data fetch, TTL cached |
| Action | Side-effect operation, never cached |
Data Classification — choose Public, Internal, Confidential, or Restricted.
Data Types — tag the kinds of data the tool handles: General, PII (Personal Info), PHI (Health Info), Financial, or Credentials.
Step 3 — Input Parameters
Define the inputs your tool accepts. Downstream, these are referenced as {{input.param_name}}.
Click Add Parameter (or Add First Parameter on an empty list) and configure each field:
| Field | Notes |
|---|---|
| Parameter Name | e.g. user_id |
| Type | Text, Number, Boolean, Array, or Object |
| Description | What the parameter is for |
| Default Value | Optional default |
| Example | An example value |
| Allowed Values | Comma-separated list to restrict values (text type only); leave empty for any |
| Required | Toggle |
Step 4 — HIL Config (optional)
Configure whether the tool requires human approval before it runs. The heading reads “Human-in-the-Loop Configuration”; a live preview appears on the right.
Turn on Human-in-the-Loop Required to pause execution and require approval. Then choose an Interaction Type:
| Interaction type | How the human responds |
|---|---|
| Approval | Simple approve/reject buttons |
| Form Input | Structured form with JSON Schema |
| Question | Free-form text answer |
| Choice | Multiple-choice selection |
| Confirmation | Checkbox acknowledgment |
| Verification | Verify extracted data |
You can also set a Risk Level (Low/Medium/High/Critical), an Approval Message, and — under Advanced Settings — a Conditional Mode (Always / When Data Incomplete / Never) and a Timeout (hours) (default 24 hours).
For form-based approvals you can generate the JSON Schema from a natural-language description with AI Generate, or start from a built-in template.
Step 5 — Implementation
Choose how the tool actually runs. Pick one execution target:
- HTTP API — call an external endpoint. See HTTP tools.
- Native Python — run a sandboxed Python handler. See Python tools.
You also set an Execution Location:
| Location | Meaning |
|---|---|
| Auto (Platform Decides) | The platform picks. |
| Local (Platform) | Runs on qRaptor infrastructure. |
| Remote (Executor) | Runs on one of your registered executors. |
Remote (Executor) is what lets a tool reach something inside your own network — an internal API, a private database. See Custom tools on a remote executor for how to choose an executor, test against it, and what happens when none is online.
In your implementation you can reference inputs as {{input.xxx}} and secrets as {{config.xxx}}. Referenced config keys are auto-detected and listed as required secrets.
Remote Python has limits. On remote executors, ctx["db"], ctx["llm"], and ctx["config"] are not available. Use {{config.xxx}} templates for secrets instead.
The two implementation types have dedicated pages — read the one you need before finishing:
Step 6 — Output Schema
Define what the tool returns so agents can use the result. The heading reads “Output Schema.”
Click Add Output Field and give each field a name, type, and description. A new tool starts with a single result field (type Text, “Result of the operation”). The Generated Output Schema card shows the resulting schema.
Step 7 — Review
The final step, “Review & Create,” summarizes everything: Basic Info, Classification (including whether HIL is required), Input Parameters, and Implementation.
If any secrets are referenced, a Required Configs card lists them and warns if any are “not found in project settings” — add those under Configuration before using the tool.
Click Create Tool to finish. The tool is saved as a Draft.
What happens next
Your tool exists as a Draft — visible in Studio but not yet usable by agents. Next, test it, then publish it.
Common issues
- Invalid Tool Key — must be
snake_case, 3–50 characters, starting with a letter. - “Please complete all required steps” — the Review step blocks creation until Basic Info, Classification, Input Parameters, Implementation, and Output Schema are all valid.
- Required config not found — a
{{config.xxx}}reference has no matching value. Add it under Configuration.