Write Tool inputs as a contract

Input design

The model sees a schema. Your receiving system sees real values.

A parameter says what the Tool needs at call time. Good parameters make missing information obvious and keep visitor data out of trusted configuration. Poor parameters ask the model to guess permissions, destinations, IDs, or formats it cannot verify.

A parameter is a contract, not a form field

The visitor does not necessarily see a traditional form. The Assistant reads the conversation, asks for missing required information when appropriate, and supplies a JSON argument object when calling the Tool. Parameter names and descriptions become part of that model-facing contract.

Only ask for dynamic values. An email destination, webhook authentication header, internal queue name, or permission level should be fixed in reviewed configuration or enforced at the receiver. Never create a visitor parameter called is_admin, approved, or destination_url and trust the model’s value as authorization.

The four parts of every parameter

Parameter anatomy
Part	Runtime role	Good example	Common failure
Name	The JSON key used in Tool arguments and template placeholders.	`customer_email`	Renaming it without updating templates or the receiving API.
Description	Tells the model what the value represents and any format expectation.	“Visitor’s email address for the callback reply.”	“Email” with no explanation of whose address or purpose.
Type	Declares string, number, or boolean in the Tool schema.	`number` for an actual numeric quantity.	Using number for phone, postcode, booking reference, or other identifier where leading zeroes matter.
Required	Places the key in the required schema and enables missing-value checks before execution.	Name and reply email for a callback request.	Marking optional notes required, encouraging the model to invent filler.

Names are normalized to safe function keys. Use lowercase letters and underscores for clarity and consistency: appointment_date, order_reference, accept_terms. Stable names matter because email and webhook body templates refer to them exactly.

Choose a type for meaning, not appearance

Use string for text and for identifiers even when they contain only digits: email, phone, date text, order number, postcode, product code, and message. Use number for values you will calculate or validate numerically, such as quantity or approximate budget. Use boolean for a genuine yes/no value such as explicit consent to a clearly stated condition.

The schema helps the model provide the intended shape, but do not mistake it for full business validation. Required values are checked for absence and common empty/unknown placeholders; email-like required parameters are validated as email addresses. The runtime does not know your acceptable appointment range, product IDs, maximum quantity, consent wording, or customer account permissions. Validate those at the receiving system.

Required values and honest conversations

Before execution, required parameters cannot be null, blank, an empty list, or common nonanswers such as “unknown,” “n/a,” “not provided,” or “null.” This helps prevent an action built from obvious placeholders. It does not prevent plausible-looking invented data.

Write the Tool description and Assistant/Agent instructions so the model asks the visitor rather than guessing. If an action can safely proceed without a field, make it optional and handle absence at the receiver. A Contact Request can often accept an optional message; forcing one may encourage “No message provided” boilerplate that adds no value.

Placeholders: where they work and where they do not

Email templates can substitute parameter values in Subject, Body, CC, and Reply-To using a name inside braces—for example, {topic}. The To address is fixed configuration, which prevents a visitor from choosing an arbitrary recipient through normal parameters.

Webhook behavior differs:

GET adds Tool arguments as query parameters.
POST with an empty JSON template sends all arguments as JSON.
A JSON body template can place named parameters in a chosen structure.
Form URL encoded sends the argument set in form encoding.
Raw text replaces named placeholders in the text template.
No body sends no request body.
The webhook URL and custom headers are fixed configuration; parameter placeholders are not substituted into them.

In a JSON body template, a value that consists entirely of one placeholder can preserve the original type. For example, a boolean parameter can remain a JSON boolean. A placeholder embedded within a longer string becomes text.

A complete contact-request contract

A deliberately small parameter set
Name	Type	Required	Description and reason
name	string	Yes	Visitor’s name for the callback. The receiver can still enforce length and allowed characters.
email	string	Yes	Visitor’s reply address. Email-like required fields receive basic email validation.
topic	string	Yes	Short reason for contact; lets staff route the request without asking the model to select an internal inbox.
message	string	No	Additional context in the visitor’s own words; absence must be acceptable.

An email subject could be New inquiry from {name}: {topic}, while the body includes all four fields. Keep the fixed To address under administrator control. A real receiving workflow should sanitize display, guard against abuse, and avoid placing confidential details in subject lines.

Ask only for data the operation can justify

Each parameter creates another opportunity to collect, transmit, log, and retain visitor information. Do not ask for a phone number “in case” when the workflow replies only by email. Do not combine health, financial, identity, or free-form sensitive detail into a general message field unless the organization has approved that purpose and handling.

Make the Chat Display Label and surrounding conversation clear about what is happening. If the Tool submits information to another system, the visitor should not be led to believe they are merely chatting privately with a model. Parameter minimization improves completion rates as well as privacy: fewer justified inputs mean fewer chances for guessing, validation failure, and abandoned requests.

Build and challenge the contract

Write the operation in one sentence. Identify what must be known before it can safely happen.
Separate dynamic from trusted. Visitor values become parameters; endpoints, credentials, permissions, and fixed recipients do not.
Choose stable names. Use lowercase underscores and names that remain meaningful outside the chat.
Describe ownership and format. Say “visitor’s reply email,” not simply “email.”
Use the least surprising type. Keep identifiers as strings; use booleans only for a real binary choice.
Mark only true blockers Required. Every required input should have a reason execution cannot proceed without it.
Update templates. Check every placeholder after adding, renaming, or deleting a parameter.
Test adversarially. Try valid values, missing required keys, blank values, invalid email, very long text, unexpected characters, and repeated submission.
Validate at the receiver. Reject impossible values, unauthorized records, duplicates, and disallowed state changes there.

Diagnose mismatched inputs

When arguments and templates do not line up
Symptom	Likely cause	Correction
Placeholder appears literally	The name does not match a parameter or that field does not support substitution.	Compare spelling exactly and use templates only in supported email/body locations.
Required input rejected	The key is missing, blank, a common unknown marker, or an email-like field is invalid.	Supply a real value using the exact parameter name.
Leading zero disappears	An identifier was declared as number.	Change it to string and retest all templates/receiver expectations.
Webhook receives strings instead of boolean/number	The placeholder is embedded in a larger string or form/raw encoding is being used.	Use an exact-value placeholder in a JSON body template when type preservation matters.
Tool receives a value but the operation fails	Schema shape passed, while business validation failed remotely.	Read the receiver log and encode the rule at the trusted destination.

See the contract in the editor

Screenshot capture pending /images/screenshots/tools/parameters.webp

Tool Parameters and Placeholders

Capture: Show a fictional contact-request parameter list with name/email/topic required and message optional, plus a safe subject template.
Show: Parameter rows, types, Required toggles, template fields
Viewport: Desktop, 1440 × 900
Annotate: Use numbered callouts only for controls referenced in the procedure.
Redact: OpenAI keys, tokens, secrets, personal information, private URLs, IP addresses, and conversation text

Put the contract to work

Configure the three action types.
Understand the special risk of WP Option data.
Exercise valid and hostile cases with the testing ladder.