Reecall
Tools and MCPs

HTTP request tool

Use send_http_request to let an Assistant book appointments, look up records, or call other external APIs during a conversation.

Overview

The tool sends an HTTP request and returns the response body to the LLM.

Set the URL, HTTP method, headers, and parameter schemas in the Tool's configuration. The platform merges pathSchema, paramSchema, and bodySchema into one flat set of LLM parameters, then routes the supplied values to the path, query string, or request body.


Naming and describing the tool

Set nameOverride and descriptionOverride to describe the action your HTTP endpoint performs. The LLM sees these values in the tool schema and uses them to decide when to call the tool.

FieldTypeRequiredLLM-facingDescription
nameOverridestringNoYesReplaces the tool's function name as seen by the LLM. Should read like a function name.
descriptionOverridestringNoYesReplaces the tool's description as seen by the LLM. Should explain when and why to call it.

Writing effective overrides

The nameOverride should read like a function name: short, lowercase with underscores, and descriptive of the action (book_appointment, register_client, check_availability). Avoid generic names like do_request or call_api.

In descriptionOverride, state when to call the tool and what result to expect.

Example:

JSONCode
{ "nameOverride": "book_appointment", "descriptionOverride": "Book an appointment for the caller. Call this tool when the caller confirms a date and time for their appointment." }

Where to set overrides

nameOverride and descriptionOverride are set at the tool-association level (alongside assistantId, definitionId, and configuration). They are not part of the configuration object itself.


Configuration schema

The configuration object you provide when attaching the tool to an Assistant accepts the following fields.

FieldTypeRequiredDefaultDescription
urlstringYesRequest URL. Use :param for path parameters and {variable} for dynamic variable resolution at config load time.
methodstringNoGETHTTP method: GET, POST, PUT, PATCH, or DELETE.
headersobjectNo{}Key-value pairs sent as request headers. Supports {variable} resolution.
timeoutnumberNo10Request timeout in seconds.
messagestringNoText the agent vocalises while the HTTP request runs. The tool waits for both the request and playback to finish.
pathSchemaJSON SchemaNoDescribes the :param path placeholders in the URL.
paramSchemaJSON SchemaNoDescribes the query parameters appended to the URL.
bodySchemaJSON SchemaNoDescribes the JSON request body.
responseSchemaJSON Schema or stringNoDescribes the expected response structure. Appended to the LLM-facing tool description so the model can interpret responses reliably.

Parameter schemas

The three schema fields, pathSchema, paramSchema, and bodySchema, each describe a different part of the outgoing HTTP request. All three follow standard JSON Schema syntax with type, properties, and required.

Path parameters (pathSchema)

Path parameters map to :param placeholders in the url. At call time, each placeholder is replaced with the value the LLM provides.

Given a URL of https://api.example.com/clients/:clientId, the following schema lets the LLM supply clientId:

JSONCode
{ "type": "object", "properties": { "clientId": { "type": "string", "description": "Unique client identifier" } }, "required": ["clientId"] }

If the LLM passes clientId = "abc-123", the resolved URL becomes https://api.example.com/clients/abc-123.

Query parameters (paramSchema)

Query parameters are appended to the URL as a standard query string. They are useful for filtering, pagination, or any parameter that belongs in the URL rather than the body.

JSONCode
{ "type": "object", "properties": { "status": { "type": "string", "enum": ["pending", "confirmed", "cancelled"], "description": "Filter orders by status" }, "limit": { "type": "integer", "description": "Maximum number of results to return" } } }

Request body (bodySchema)

The body schema describes the JSON payload sent in the request body. This is typically used with POST, PUT, and PATCH methods.

JSONCode
{ "type": "object", "properties": { "firstName": { "type": "string", "description": "Customer first name" }, "lastName": { "type": "string", "description": "Customer last name" }, "email": { "type": "string", "description": "Customer email address" } }, "required": ["firstName", "lastName"] }

Response schema (responseSchema)

Set responseSchema to describe the response fields the LLM should expect. The platform appends it to the tool description under "Response format:". Without it, the model receives the response body without a description of its structure.

Example:

JSONCode
{ "responseSchema": { "type": "object", "properties": { "status": { "type": "string", "description": "Appointment status" }, "id": { "type": "string", "description": "Unique appointment identifier" }, "date": { "type": "string", "description": "Confirmed date in YYYY-MM-DD format" }, "time": { "type": "string", "description": "Confirmed time in HH:MM format" } } } }

Description only

responseSchema describes the response but does not validate or transform it. The tool returns the response text, truncated after 5,000 characters when necessary.

Schema merging

The LLM does not see three separate schemas. When the tool is built, all properties from pathSchema, paramSchema, and bodySchema are merged into a single flat parameters object. The required arrays are combined with duplicate names removed.

For a tool named register_client with path parameter clientId, query parameter category, and body parameter names, the LLM-facing schema becomes:

JSONCode
{ "name": "register_client", "description": "Registers a list of client names under an existing client account.", "parameters": { "type": "object", "properties": { "clientId": { "type": "string", "description": "The client ID" }, "category": { "enum": ["prospect", "client", "churned"] }, "names": { "type": "array", "description": "Client names collected during the conversation.", "items": { "type": "string" } } }, "required": ["clientId", "names"], "additionalProperties": false } }

Property name collisions

If the same property name appears in more than one schema, the last one wins following the merge order: pathSchema → paramSchema → bodySchema. A warning is logged, but the tool still builds. Avoid reusing property names across schemas. A parameter declared in pathSchema is also substituted into the URL even when its definition is overwritten by a query or body schema.


Dynamic variables

Use {variable} placeholders in string values anywhere in configuration. The platform resolves them from variables and injected data when loading the configuration, before building the tool.

For example, if you have:

  • a Project-scoped variable with key api_token
  • injected data with key foo

You can reference them in configuration.headers:

JSONCode
{ "headers": { "Authorization": "Bearer {api_token}", "X-Foo": "{foo}" } }

Unresolved variables

An unresolved {variable} placeholder becomes an empty string. The tool still attempts the request, even if the resulting header or URL is incomplete.


Limitations

ConstraintLimit
Response body sizeTruncated at 5 000 characters.
Default timeout10 seconds. Configurable via the timeout field.
Request body formatJSON only. No form-data or file uploads.
Streaming responsesNot supported. The full response is awaited before returning.
Property name collisionsLast schema wins (bodySchema > paramSchema > pathSchema).
Unresolved path placeholdersLeft as literal :param in the URL, likely causing a 404.

Full example

Attach an appointment-booking tool to an Assistant. Fetch the send_http_request definition with GET /data_next/ai/toolDefinitions?where={"name":"send_http_request"} and use its id as definitionId. Replace the example Assistant ID and token with your own, and define the scheduling_api_key variable before testing.

Code
POST https://newprd.reecall.io/data_next/ai/tools Authorization: Bearer {token} Content-Type: application/json
JSONCode
{ "definitionId": "a1b2c3d4-5678-4def-9abc-def012345678", "assistantId": "<your-assistantId>", "nameOverride": "book_appointment", "descriptionOverride": "Book an appointment for the caller. Use this tool when the caller confirms a date and time for their appointment.", "configuration": { "url": "https://scheduling.example.com/api/v1/appointments", "method": "POST", "headers": { "Authorization": "Bearer {scheduling_api_key}", "Content-Type": "application/json" }, "timeout": 8, "message": "I'm booking that appointment for you now.", "bodySchema": { "type": "object", "properties": { "date": { "type": "string", "description": "Appointment date in YYYY-MM-DD format" }, "time": { "type": "string", "description": "Appointment time in HH:MM format (24h)" }, "customerName": { "type": "string", "description": "Full name of the customer" }, "reason": { "type": "string", "description": "Brief description of the appointment reason" } }, "required": ["date", "time", "customerName"] }, "responseSchema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique appointment identifier" }, "status": { "type": "string", "description": "Booking status (e.g. confirmed, pending)" }, "date": { "type": "string", "description": "Confirmed date in YYYY-MM-DD format" }, "time": { "type": "string", "description": "Confirmed time in HH:MM format" }, "customerName": { "type": "string", "description": "Customer name as recorded" } } } } }
Last modified on