Skip to main content

Documentation Index

Fetch the complete documentation index at: https://tinytalk.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

A Custom Tool is a tool you define yourself by pointing Tiny Talk at an HTTP endpoint — your own backend, a SaaS API, or any HTTPS service. The agent calls it whenever the conversation calls for it, passing in arguments the AI model extracts from the chat. Use Custom Tools to:
  • Look up records — order status, account balance, ticket state, inventory
  • Update systems — append a note to a CRM, mark a ticket resolved, log an event
  • Trigger workflows — kick off a webhook, send a transactional email, schedule a job
For a high-level overview of how tools work, plan limits, and the security model that applies to every tool type, see Tools.

​
Creating a Custom Tool

Go to Agent → Tools and click New tool. The editor has six sections, top to bottom.
1

Metadata

The metadata describes the tool to the AI model and to you.
  • Name — A human-readable name (e.g. Check Order Status). Up to 100 characters; letters, digits, and spaces only.
  • Slug — Auto-generated from the name. This is the identifier the model uses to call the tool. Read-only and shown only after the tool is saved.
  • When to use — The single most important field for tool-calling accuracy. Describe the situations where the agent should invoke this tool. Be specific about the kinds of questions or intents it should match. Up to 1,000 characters.
  • Description — A short summary of what the tool does. Concatenated with When to use into the description the model sees at tool-selection time. Up to 1,000 characters.
Use When to use for when to call (intents, triggers) and Description for what the tool does (the action). The model reads both together when deciding whether to invoke the tool.
2

Request

Defines the HTTP request Tiny Talk sends when the agent invokes the tool.
  • Method — GET, POST, or PATCH.
  • URL — Full HTTPS URL of the endpoint. Supports {{params.name}} placeholders (see Templating). HTTPS only; IP addresses are not allowed.
  • Body (JSON) — Required for POST and PATCH. Must be valid JSON. Supports both {{params.name}} and {{secrets.name}}. Up to 32 KB.
3

Headers

Add HTTP headers as key-value pairs. Both keys and values support templating, so you can inject secrets without hard-coding them.Common patterns:
HeaderValue
AuthorizationBearer {{secrets.api_key}}
X-API-Key{{secrets.api_key}}
Acceptapplication/json
A Content-Type: application/json header is added automatically for POST and PATCH requests if you don’t set one yourself.Up to 20 headers per tool.
4

Parameters

Parameters are the inputs the AI model collects from the conversation and passes into your tool. They become part of the function signature the model sees.For each parameter, set:
  • Name — Lowercase letters, digits, and underscores only (e.g. order_id). Up to 64 characters. Reference it in your URL, headers, and body as {{params.order_id}}.
  • Type — string, number, integer, boolean, or enum.
  • Description — What value the agent should collect. The model reads this to decide what to ask the user.
  • Required — If on, the model must provide the parameter before it can call the tool.
  • Enum values — For the enum type only. Comma-separated list of allowed values (e.g. pending, shipped, delivered).
Up to 20 parameters per tool.
Write parameter descriptions from the model’s perspective: “The unique order number the user wants to check, formatted like ORD-12345.” Concrete examples help the model extract the right value from a free-form message.
5

Secrets

Secrets are credentials — API keys, bearer tokens, basic-auth strings — that you don’t want exposed in the tool definition. Reference them as {{secrets.name}} in headers and body.For each secret, set:
  • Name — Lowercase letters, digits, and underscores only (e.g. api_key).
  • Value — The secret value. Up to 4,096 characters.
Up to 20 secrets per tool.
Secrets are encrypted at rest with AES-256 and decrypted only at the moment a tool is invoked. After saving, the dashboard shows only a masked preview (••••1234) — the raw value is never sent back to the browser. Editing other fields without re-entering a secret keeps the existing value.
Secrets are not allowed in the URL — they would leak into access logs and analytics. Put them in headers or the request body instead.
6

Response

Controls what part of the response the AI model sees.
  • Full response visible to the agent — The model receives the entire response body (default).
  • Only selected fields visible — The model receives only the fields you list. Useful when the API returns a large object but only a few values matter for the conversation.
When you choose selected, list the fields as comma-separated dot-paths:
status, shipping.tracking_url, customer.email
Dot-paths reach into nested objects. Array indexing isn’t supported — pass arrays through whole or restructure your response.Responses are capped at 20 KB. Larger responses are truncated, and the model is told the response was truncated so it can react accordingly.
After saving, the tool appears in the agent’s tool list and is enabled by default.

​
Templating

Tiny Talk replaces {{params.NAME}} and {{secrets.NAME}} placeholders in your URL, headers, and body before sending the request.
LocationParamsSecretsNotes
URL✓—Param values are URL-encoded. Secrets are blocked here.
Headers✓✓Newlines (\r, \n) are rejected to prevent header injection.
Body (JSON)✓✓Type-preserving — a placeholder alone in a string keeps its native type.
In a JSON body, a value of "{{params.count}}" where count is an integer is sent as a JSON number, not a string. Mixed strings ("id-{{params.order_id}}") are interpolated textually and sent as strings. Special characters in values are JSON-escaped automatically — there’s no way for a value to break out of the surrounding JSON structure.

​
Testing your tool

Once saved, the tool editor shows a Test card. Fill in sample values for each parameter and click Run test. The response panel shows:
  • The HTTP status code and the resolved request line
  • The full response body (compacted JSON or text)
  • The filtered body, if you’re using selected-fields response mode
  • A truncation notice, if the response exceeded the 20 KB cap
Use the test runner before attaching a tool to a production agent — interpolation mistakes, auth header typos, and unexpected response shapes show up here, where the model isn’t yet involved.

​
Disabling and deleting

Toggle the Enabled switch on a tool to stop the agent from calling it without losing the configuration. Disabled tools will count against your plan limit. To remove a tool entirely, open it and use Delete tool in the Danger Zone. Active conversations stop referencing the tool immediately and the action can’t be undone.

​
Example use cases

​
Single tool: order lookup

A typical e-commerce setup. The agent looks up order status when a visitor asks about their shipment.
FieldValue
NameCheck Order Status
When to useWhen the visitor asks about the status, shipment, or delivery of a specific order. They’ll usually mention an order number like ORD-12345.
DescriptionLooks up an order by its ID and returns the current status, tracking URL, and estimated delivery date.
MethodGET
URLhttps://api.example.com/orders/{{params.order_id}}
HeadersAuthorization: Bearer {{secrets.api_key}}
Parametersorder_id (string, required) — The order number the user wants to check, formatted like ORD-12345.
Secretsapi_key
ResponseSelected: status, shipping.tracking_url, estimated_delivery
A visitor message like “hey, what’s going on with my order ORD-58821?” triggers the tool with order_id = "ORD-58821". The agent reads the filtered response and replies in plain English.

​
Multiple tools: customer support kit

Three coordinated tools let an agent handle most account questions end-to-end.
  1. Look up customer — GET /customers?email={{params.email}} — returns the customer ID, plan, and current balance.
  2. List recent orders — GET /customers/{{params.customer_id}}/orders?limit=5 — returns the most recent orders for a customer.
  3. Open a support ticket — POST /tickets with body { "customer_id": "{{params.customer_id}}", "subject": "{{params.subject}}", "body": "{{params.body}}" } — files a ticket the support team can pick up.
The agent chains them. When a visitor describes a billing issue, it looks up the customer by email (tool 1), retrieves their recent orders (tool 2), and either resolves the question on the spot or files a ticket with the relevant context (tool 3).
When chaining tools, name your parameters consistently across tools — customer_id everywhere, not a mix of customerId, cust_id, and id. The model passes outputs from one tool into another based on naming and semantic match; consistency reduces ambiguity.

​
Internal HR assistant

For an internal-facing agent, Custom Tools can hit your private APIs as long as they’re reachable on the public internet.
  • Look up time-off balance — GET /hr/employees/{{params.employee_id}}/pto — returns the employee’s available, used, and pending PTO.
  • Submit a time-off request — POST /hr/pto-requests with the start date, end date, and reason — files a request that routes through your existing approval flow.
Pair this with a system prompt that asks for the employee ID up front, and the agent handles routine PTO questions without HR involvement.

​
Troubleshooting

The model decides whether to invoke a tool based on the Name, Description, and When to use fields. If it never picks the tool, the description is usually too vague or doesn’t match the kinds of messages visitors actually send.
  • Rewrite When to use with concrete examples: “When the visitor asks about the status of an order, mentions an order number, or asks where their package is.”
  • Make sure the tool is enabled on the agent.
  • Check that the model you’ve selected supports tool calling — most modern models do, but some smaller or older models do not. The agent runtime skips tool registration on unsupported models.
  • Confirm the URL is HTTPS and the hostname is publicly resolvable. The runtime blocks IP literals, private addresses, and cloud-metadata endpoints.
  • If the endpoint requires VPN or IP allowlisting, expose it via a public gateway with auth — Tiny Talk’s tool runtime calls from public infrastructure.
  • Check your endpoint isn’t returning a redirect (3xx). Configure the final URL directly; the runtime does not follow redirects.
The default timeout is 10 seconds. If your endpoint is slow:
  • Make the work asynchronous on your side — return a job ID immediately, and have a second tool that checks the status.
  • Tighten queries or add caching at the API layer.
  • The maximum timeout is 15 seconds and is set by the platform; tools cannot exceed this limit.
  • Make the When to use fields explicitly distinct: each one should describe situations the other tool wouldn’t match.
  • Consider merging them into a single tool with an enum parameter that switches behavior. One well-described tool with a mode enum is often clearer to the model than two near-duplicate tools.
Responses over 20 KB are cut off, and the model sees a [Response truncated] marker. To work around this:
  • Switch the Response mode from full to Selected fields and list only the fields the model needs.
  • Adjust your endpoint to return a slimmer response — pagination, projection, or summary fields.
  • Tighten the parameter Description with examples and format hints.
  • Use the right Type — enum constrains the model to a fixed set; integer rejects decimals; boolean is a true on/off.
  • Mark essential parameters as Required so the model collects them before calling.
Not yet. The current secret model fits API keys, bearer tokens, and basic-auth credentials carried in headers. OAuth flows that require dynamic token refresh are on the roadmap. As a workaround, you can rotate long-lived tokens via the API or schedule them externally and update the secret in the dashboard.
Not yet. Custom Tools support GET, POST, and PATCH only. PUT and DELETE are intentionally not supported — they need an approval flow before the agent should be allowed to call them. That’s planned for a future release.