All pages
Chat tools
craving AI replies to Visitors in a Resident’s chats. With chat_tools (and scope chat.tools), your app gives craving AI live tools: when a Visitor asks a question your app can answer (an order status, an open slot, a product catalog), craving AI calls your endpoint and weaves the result into its reply.
Declaring tools
Declare up to 8 tools in your manifest. Each tool has a snake_case name (3 to 48 characters), a description (10 to 400 characters) that craving AI reads to decide when to invoke it, a JSON Schema parameters object (type: "object"), and an invoke_url on a declared origin. Write specific descriptions: "Look up an item by name and return its price and link." works much better than "Product helper".
The installer can turn your chat tools on or off on the app’s page in Your apps. On an agency installation, each managed Resident can mute the tools for their own chats.
Invocation
When craving AI calls a tool, craving sends a signed POST to invoke_url:
POST <invoke_url>
X-Craving-Signature: t=1757793600,v1=…
X-Craving-Event: tool.invoke
{
"type": "tool.invoke",
"installation_id": "…",
"tool": "lookup_item",
"arguments": { "query": "black hoodie" },
"chat_id": "…",
"fan": { "ref": "fan_5f2c…" },
"creator_id": "…",
"context": {},
"invoked_at": "2026-09-13T20:06:04Z"
}fan.ref is a per-app pseudonymous identifier (fan_<32 hex chars>): the same Visitor always maps to the same ref for your app across chats, and never matches another app’s ref. When the installer also granted the heavy fans.read scope, fan includes "name" and "id" (the Visitor’s display name and user UUID), and you can look up their summary at GET /v1/fans/{ref}.
Respond within timeout_ms (500 to 8000 ms, default 8000 ms):
{
"ok": true,
"result": {
"items": [{ "name": "Black hoodie", "price": "$45", "url": "https://shop.example.com/i/123" }]
},
"user_visible": { "link": "https://shop.example.com/i/123" }
}result is the structured data craving AI uses to compose its answer; keep it concise and factual. user_visible carries optional data that can be shown directly to the Visitor (such as a link). Any non-2xx status, timeout or { "ok": false } drops the tool for that turn: craving AI replies without it and your app’s daily stats record a tool failure.
Dry runs
During automated review, craving POSTs { "type": "tool.invoke", "dry_run": true, "sent_at": "…" } to every invoke_url (and { "type": "channel.history", "dry_run": true } / { "type": "channel.send", "dry_run": true } for channel connectors). Verify the signature and answer 2xx with any valid JSON object.
Rules
- Never return paid content directly in a tool result; return the price and a craving checkout link instead.
- Scope every lookup to the
creator_idandinstallation_idin the request so one Resident’s Visitors never see another Resident’s data. - Tool invocations are rate limited to 60 calls per minute per installation (Rate limits).