Tool parameters

How the parameters you define on a tool reach the underlying Code function or HTTP endpoint.

Every custom tool has a Parameters section. The parameters you declare there become the typed input the LLM is asked to fill in when it calls the tool — and they reach your runtime in different ways depending on the tool’s Action type.

Declaring a parameter

In the dashboard, each parameter has:

Field	What it is
Name	The identifier. Must be a valid JS/Python identifier ([a-zA-Z_][a-zA-Z0-9_]*).
Type	One of string, number, integer, boolean, array, object.
Description	Free-text. Shown to the LLM — write this for the model, not for humans. A clear description is the single biggest lever on tool-call quality.
Required	If unchecked, the LLM may omit the field. Your code/endpoint should treat the value as possibly missing.

Parameters are validated against the schema you declared before your tool runs. A type mismatch is rejected upstream and your handler is never invoked.

Code tools

For code tools, your function receives a single input object with one field per declared parameter, keyed by the Name you typed in.

The entry point is fixed:

JavaScript

export async function handle(input, ctx) {
  // Parameters declared above arrive as fields on `input`:
  const userId   = input.user_id;        // string / number / etc.
  const limit    = input.max_results;
  const verbose  = input.verbose ?? false; // optional param fallback

  // ctx.tools.<name>(args) invokes any built-in tool you enabled.
  // ctx.audit(event, data) writes a structured log line.

  return { ok: true, userId, limit };
}

async def handle(input, ctx):
    user_id  = input["user_id"]
    limit    = input["max_results"]
    verbose  = input.get("verbose", False)  # optional param fallback

    return { "ok": True, "user_id": user_id, "limit": limit }

Type mapping (Code)

Declared type	JavaScript value	Python value
string	string	str
number	number (float)	float
integer	number (int)	int
boolean	boolean	bool
array	Array<unknown>	list
object	plain object	dict

Notes

• Optional parameters may be undefined (JS) / missing (Python). Use ?? or .get() to provide defaults.
• Required parameters are guaranteed present — no need to null-check.
• You cannot rename input or ctx in the signature.
• There is no {{name}} placeholder syntax — params do not get string-substituted into your code body. They arrive as runtime values on input.

HTTP (API endpoint) tools

For api_endpoint tools, the parameters are serialized into the outbound HTTP request. How they are serialized depends on the chosen Method.

GET — parameters become URL query string

Each declared parameter is appended to endpoint_url as a query parameter. The key is the Name you typed; the value is stringified.

GET https://api.example.com/users?user_id=42&max_results=10

• Primitives (string, number, integer, boolean) are converted with String(value).
• object and array values are JSON-stringified into the query value.
• undefined / null parameters are skipped entirely.
• If your URL already contains a ?, additional params are appended with &.

POST / PUT / DELETE — parameters become JSON body

The full input object is sent as the request body, JSON-encoded. Content-Type: application/json is set automatically unless you defined a Content-Type header yourself.

POST https://api.example.com/users
Content-Type: application/json

{ "user_id": 42, "max_results": 10 }

If your endpoint expects a different shape (form-encoded, XML, nested under a single key, etc.), the recommended pattern is to wrap the call in a code tool — define your friendly parameter names on the tool, then translate them into the shape the upstream API wants inside handle().

Custom headers

Headers you configure on the tool are sent verbatim. They do not see your parameters — headers cannot reference input.<name>. For per-call header values (e.g. signing a request), use a code tool.

Type mapping (HTTP)

Declared type	GET (query string)	POST/PUT/DELETE (body)
string	?key=hello	{ "key": "hello" }
number	?key=3.14	{ "key": 3.14 }
integer	?key=42	{ "key": 42 }
boolean	?key=true	{ "key": true }
array	?key=%5B1%2C2%5D (JSON-stringified, then URL-encoded)	{ "key": [1, 2] }
object	?key=%7B%22a%22%3A1%7D (JSON-stringified, then URL-encoded)	{ "key": { "a": 1 } }

Choosing Code vs HTTP

• Use HTTP when the upstream API accepts your parameter names directly as query string or JSON body.
• Use Code when you need to transform parameters, sign requests, fan out to multiple endpoints, call other built-in tools, or apply business logic before responding.

See also

• Custom-tools ctx reference — built-in tools accessible from your code.
• Built-in tools — the catalog the LLM can call alongside yours.