> ## Documentation Index
> Fetch the complete documentation index at: https://agentheya.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<CodeGroup>
  ```javascript JavaScript theme={null}
  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 };
  }
  ```

  ```python Python theme={null}
  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 }
  ```
</CodeGroup>

### 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](/custom-tools-ctx) — built-in tools accessible from your code.
* [Built-in tools](/builtin-tools) — the catalog the LLM can call alongside yours.