HTTP Tools

An HTTP tool is an HTTP request the Simba agent can call, defined by an input schema and a templated request.

An HTTP tool is content, prefixed HTT_. It exposes one external HTTP endpoint to the agent under a tool name and description the model reads when it decides whether to call it. The inputSchema declares the parameters the model supplies. The url, headers, and body are LiquidJS templates that render against those parameters into a concrete request, which Perpetual sends with the configured method. A {{ credential.<name> }} reference in any template resolves against a stored credential, so secrets never sit in the template text. HTTP tools sit alongside skills and MCP servers as the tools the agent can invoke while working a case.

Templating

The url, headers values, and body are LiquidJS templates. Two kinds of reference resolve when the agent calls the tool.

Reference	Resolves to
{{ <field> }}	A parameter of the call, matching a property of inputSchema. Any Liquid filter applies, so {{ user_email | json }} escapes a value for a JSON body.
{{ credential.<name> }}	A stored credential by name. Use bracket notation ({{ credential["my-key"] }}) when the name is not a valid identifier. Text and OAuth2 credentials substitute their value string. For an AwsRole or HmacSignature credential, Perpetual computes a signed request header over the final request.

Inputs

Field	Type	Required	Description
name	string	Required	Tool name the model sees. Lowercase letters, digits, underscores, and hyphens only (^[a-z0-9_-]+$).
description	string	Required	Free-text description of what the tool does. The model reads it to decide when to call the tool.
inputSchema	object	Required	A JSON Schema object describing the parameters the model supplies when calling the tool. Its properties are the values the request templates render against.
url	string	Required	The request URL, a Liquid template. Renders against the call parameters and any credential.* references.
method	enum	Required	HTTP method for the request: GET, POST, PUT, PATCH, DELETE.
headers	object	Optional	Request headers as a string-to-string map. Each value is a Liquid template.
body	string	Optional	The request body, a Liquid template.
readOnlyHint	boolean	Required	Declares whether the request only reads state.
requiresApproval	boolean	Required	When true, Perpetual holds each call to the tool and renders an approval card in the chat, naming the tool and listing the input parameters the model supplied. The card offers Approve and Deny. Approval is per call.
folderPath	string	Optional	Folder location within the Space, e.g. Tools/Enrichment.

TODO ‼️

Could not verify what readOnlyHint does on an HTTP tool. Nothing reads the value: buildHttpCustomTool attaches no annotation or metadata derived from it, and approval gating uses the separate requiresApproval field. Sources checked: packages/contracts/src/z-schemas/contract-features/z-http-tool-config.ts and apps/backend/src/services/custom-tools-loader.ts.

Outputs

Field	Type	Description
folderId	string	ID of the folder holding the tool. Null for none.

Plus the common resource fields.

Related

• Credentials, the secrets a credential.* reference injects.
• Skills and MCP servers, the other tool kinds the Simba agent can call.
• The Simba agent, the agent that calls HTTP tools while working a case.
• Changesets, how HTTP tool edits are staged and committed.