Documentation
Build, refine, save, and share small web tools with AI.
Tool AI turns prompts into multi-file HTML, CSS, and JavaScript
projects. The create page keeps conversation context, streams the
model response into a preview, and lets you continue editing with
follow-up prompts. Generated tools can also request API keys, use
the visitor's Tool AI account, and store shared project data.
-
Describe the tool.
Start on the homepage with a direct prompt like “Build a mortgage
calculator for first-time buyers with taxes, insurance, and a
downloadable summary.”
-
Wait for the create page.
Tool AI signs you in anonymously if needed, sends the prompt, and
streams a generated project into the preview.
-
Refine with follow-ups.
Ask for scoped changes such as “Keep the layout, add validation
and a mobile-friendly summary.”
-
Save or download.
Anonymous users get local autosave. Signed-in users can save to
cloud projects and optionally publish to the gallery.
1. Context is assembled
The server receives your current prompt, existing project files,
and prior chat messages. Follow-ups can refer to “the previous
version,” “that form,” or “keep the same layout.”
2. Web tools may run
If the prompt asks for current facts, docs, sources, or
research, the server can search the web and read public
documentation pages before final generation.
3. A provider generates files
The selected model returns a JSON project with a title,
explanation, thumbnail keyword, and a files object containing
complete project files.
4. Output is normalized
File paths are checked, HTML passes a light markup filter, file
sizes are bounded, and the preview is written to a temporary
project URL.
Research
Web Search and Documentation Reading
Tool AI supports two web endpoints. The AI can request these on the
server before generation, and generated tools can also call them at
runtime when a tool needs search or documentation lookup.
GET /api/search-web
Searches the public web and returns source titles, URLs,
snippets, and provider metadata.
/api/search-web?query=MDN Fetch API documentation&count=3
GET /api/read-web
Reads a public HTTP or HTTPS page, extracts readable text, and
returns a source URL, title, content type, and text excerpt.
/api/read-web?url=https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API&maxChars=8000
Documentation workflow:
For docs-heavy requests, ask Tool AI to search for the relevant docs
page, read it, and cite the source link in the generated UI.
Generated Tools
APIs Available to Generated Tools
Generated browser tools can request API keys, use the visitor's Tool
AI account, and store shared project data. Every capability is
explicit: the tool references a client script or global, and the
trusted Tool AI host handles credentials, dialogs, and permissions.
API keys — window.toolaiKeys
Tool AI loads the key client before project scripts. Ask for a
key at runtime from async initialization; the host opens a
password dialog with Cancel,
Edit code manually, and
Use for this preview.
async function initialize() {
const MANUAL_API_KEY = "";
const key = MANUAL_API_KEY || await window.toolaiKeys.get("google_maps");
// Use the key only with the intended provider.
}
initialize().catch(() => {
// Show setup instructions without logging credentials.
});
Account and private storage — toolaiAuth
Include the auth client before the application script, then read
the signed-in user, prompt sign-in or sign-out, and store
private per-user/per-tool data.
<script src="/api/tool-auth/client.js"></script>
const user = await toolaiAuth.ready(); // null for guests
await toolaiAuth.signIn(); // host confirms, then redirects
await toolaiAuth.storage.set("notes", [...]); // private, per tool
Shared project data — cloud
Include the cloud client for public shared key/value data such
as counters, votes, or public item lists. Anyone who knows a key
can read or change it, so never store private information here.
<script src="/api/cloud/client.js"></script>
await cloud.ready();
const views = await cloud.increment("my-project:views", 1);
await cloud.set("my-project:items", [{ title: "Shared item" }]);
What is never exposed
Generated code never receives an ID token, refresh token,
password, or Firebase configuration. The host supplies the tool
ID and scopes every request; generated code cannot pass a user
ID of its own.
Key safety: use browser-safe, restricted keys. A
running tool and its third-party scripts can read any key you
approve. Tool AI does not save entries or send them to the AI.
Private server secrets belong on your own backend; WebContainer
server code also runs in your browser.
Better Results
Prompting Guide
Strong prompts describe the user, output, required controls, data
states, and constraints. Follow-ups should say what must stay
unchanged.
Build a [tool type] for [target user].
Must include: [feature 1], [feature 2], [feature 3].
Data states: empty, editing, validation error, success.
Style: [layout], [tone], [visual constraints].
Behavior: [exact interactions and edge cases].
Keep unchanged: [things the AI must preserve].
“Build a habit tracker with empty state, weekly grid, streak
counter, local persistence, and mobile-friendly editing.”
“Improve spacing and button states only. Do not change the color
palette, form fields, or calculation logic.”
“Use current MDN Fetch API documentation. Include examples for
GET, POST, async error handling, and one visible source link.”
Design
Themes and Styling
Pick a Theme in the create toolbar (or beside the
prompt on the home page) to apply a preset design system to the
generated tool. The preset supplies its own classes, variables, and
components, so the tool's style.css holds only the
additional or overriding CSS the request needs.
-
Default — no preset; the tool generates its complete stylesheet.
-
Blueprint, Glasswave, Midnight, Modern, Paper, Playful, RetroOS,
Soft UI, Studio, and Terminal presets.
-
In the prompt, describe styling concretely — for example “warm
editorial paper with terracotta accents” or “brutalist buttons
with hard offset shadows.”
-
Switching back to Default removes the preset CSS instead of
leaving it in the project.
Prefer a subject-specific palette and typography over a generic
purple-and-blue gradient, and always keep contrast and focus styles
usable.
Models
Models and Providers
Choose a model from the selector on the create page, or manage your
personal list in the Model Shop. Model
preferences are stored in this browser.
Automatic selection
Picks an available Tool AI model for the request and switches
routes automatically when a provider is unavailable.
Model Shop
Browse hosted and connected models, filter by cost,
intelligence, and image input, then add the ones you want to
your personal list.
Free routes
Guests stay on free OpenRouter coder routes. Signed-in users can
also select DeepSeek V4.1 Flash within the same spark limits.
Vision
Image-aware models handle screenshots, visual references, and
quick multimodal iterations. The selector marks which models
accept images.
Connected accounts
Connect ChatGPT or another supported account in Settings or the
Model Shop to use those models from Tool AI selectors.
Advanced
Large hosted models support bigger builds, deeper reasoning, and
complex repairs at a higher spark cost.
Projects
Saving, Downloads, and Publishing
| Action |
Requirement |
What happens |
| Local autosave |
Any user |
The browser stores the current project, files, metadata, and
message history locally.
|
| Cloud save |
Signed-in, non-anonymous account |
Project files, preview HTML, metadata, and messages are
saved to Firestore.
|
| Download ZIP |
A generated project |
The server normalizes project files and returns a ZIP with
safe relative paths.
|
| Publish to gallery |
Cloud project owner |
The project becomes public with a generated thumbnail image
and gallery metadata.
|
| Export to GitHub |
Signed-in, non-anonymous account |
Creates a new repository in your GitHub account from the
current source files. See
Export to GitHub.
|
Source Control
Export to GitHub
In the editor, choose Export to GitHub beside
Download ZIP. Signed-in users create a new
repository in their personal GitHub account and push the current
source files, including unsaved edits and nested folders. This
exports source only; Tool AI cloud storage and hosted services are
not migrated or deployed.
-
Choose private (the default) or public repository visibility.
-
Provide a GitHub classic personal access token with
repo scope, or public_repo for public
repositories only.
-
The token is used for that export request only and is never saved
or logged. No server-side GitHub configuration is required.
- Up to 500 text files and 900 KB of serialized source.
-
Exports never overwrite an existing repository. If an upload fails
after creation, open the repository to inspect it and retry with a
new name.
- Export does not establish ongoing sync with GitHub.
Integrations
Use Tool AI from Other AI Clients
Settings → Connections lets you authorize outside AI clients to
reach your existing Tool AI account and projects. Tools and projects
are the same resources you see in Tool AI.
GPT Connect
Use the Tool AI Builder GPT in ChatGPT to create, find, edit,
run, and delete your tools. Sign in when ChatGPT prompts you and
review the requested permissions before approving.
Remote MCP clients
MCP-compatible clients can connect to
https://toolai.us/mcp and authorize with a normal
browser sign-in. Access is granted per client.
You stay in control: Connections shows the
permissions each client received, and revoking access blocks its
later requests. Revocation does not cancel an operation that is
already running.
Quotas
Rate Limits and Size Limits
Daily sparks
40,000
Per signed-in user, tracked by UTC day.
Weekly sparks
120,000
Per signed-in user, tracked from Sunday UTC.
Session sparks
20,000
Per signed-in user in fixed UTC buckets starting at 00:00,
05:00, 10:00, 15:00, and 20:00.
Minimum request cost
500 sparks
Cost rises with prompt, project context, conversation history,
and model cost.
How spark cost is estimated
The server estimates one input token per four characters of prompt,
project source, and conversation history. Cost is the larger of 500
or the estimated input tokens, multiplied by the model cost, with a
minimum charge of 500 sparks. Model multipliers range from 0.6x to
3.5x; unknown models use 1.2x. A short request costs 500–1,750
sparks, allowing up to 80 minimum-cost requests per day and 40 per
session for signed-in users. Larger projects cost more. Signed-in
users share 200,000 sparks per UTC day and 600,000 per UTC week.
Guests retain 4,000 daily, 12,000 weekly, and 2,000 per session,
with a separate shared pool of 10,000 daily and 30,000 weekly.
DeepSeek also has separate shared spending limits. These are
conservative app allowances, not a guarantee of provider
availability. Failed generations still consume their reservation
because providers may have used quota.
Other limits
- Prompt text area: 4,000 characters.
- Saved message history: up to 100 messages.
- Generated project: up to 80 files.
- Single generated file: up to 300,000 bytes.
- Total generated project payload: up to 750,000 bytes.
- Temporary streamed preview lifetime: about 10 minutes.
- Web page reader: up to 12,000 returned characters.
- Web fetch body cap: 1 MB.
- Web reader timeout: 10 seconds.
- AI-requested web tool calls: up to 4 per generation.
-
NVIDIA server-side guard: up to 40 requests per minute by default.
-
API key entry: up to 4,096 characters; service names use lowercase
letters, digits, and underscores (up to 64 characters).
-
Private tool storage: 64 KiB per signed-in user per tool; keys up
to 200 characters.
-
Shared cloud values: keys up to 100 characters, and up to 100 keys
in one state read.
- GitHub export: up to 500 text files and 900 KB of source.
Guardrails
Security and Privacy Boundaries
-
Generated HTML passes through a light markup filter before preview
and save. It intentionally preserves executable code, inline
handlers, and modern CSS, so treat generated tools like any
untrusted web page.
-
Executable URL schemes such as
javascript: are
filtered from links, scripts, and forms.
-
Project file paths must be safe relative paths, and file and
project size limits are enforced.
-
Tool AI cannot be embedded by other sites because frame ancestors
are restricted to itself.
-
The web reader blocks localhost, private IP ranges, and private
redirect targets.
-
Cloud project saving requires a verified, non-anonymous Firebase
user.
-
Private tool storage requires a signed-in user and is scoped to
the verified user and tool.
-
Public gallery publishing requires ownership of the saved project.
API keys approved in the host dialog live only in that preview
document; reloading clears them and a new document asks again. They
are never saved, sent to the AI, or written into project source.
Approve a key only if you trust the tool, and prefer restricted,
browser-safe keys.
| Issue |
What it means |
What to do |
| Prompt is too long |
The message is above the 4,000-character input limit. |
Split the work into smaller follow-up prompts. |
| Usage limit reached |
The request would exceed daily, weekly, or session sparks.
|
Wait for the relevant reset or use a shorter
prompt/lower-cost model.
|
| Invalid JSON returned by model |
The model response could not be parsed into project files.
|
Retry with a more direct prompt asking for a complete
working tool.
|
| No tool to save |
There is no generated project in the preview yet. |
Generate a tool first, then save or download. |
| Project not found |
The project was deleted or belongs to another account.
|
Return to Projects and open a project owned by the current
account.
|
| API key request cancelled |
The key prompt was dismissed, the preview was replaced, or
the preview navigated away.
|
Reload the preview to be asked again, or use the manual
override constant in the tool's code.
|
| Sign in to use private storage |
Private storage needs a verified, non-anonymous Tool AI
account.
|
Use the tool's sign-in button or sign in through Tool AI,
then retry the request.
|
| Authentication is unavailable |
The tool is running outside the Tool AI editor or viewer,
such as a standalone export.
|
Open the tool in Tool AI to use account features, or remove
them for the export.
|
| GitHub export could not finish |
GitHub rejected the token, the repository name is taken, or
the upload was interrupted.
|
Check the token scope and repository permissions, then check
GitHub before retrying with a new repository name.
|
Can I edit an existing project?
Yes. Open a saved project from Projects and continue with follow-up
prompts. The current files and prior conversation are included as
context.
Can Tool AI read documentation?
Yes. It can search for public pages and read public documentation
text before generation. It cannot read private sites, localhost, or
private-network URLs.
Why did the AI redesign something I wanted to keep?
Follow-ups should explicitly say what must remain unchanged. For
example: “Keep the current layout and calculations. Only add error
messages.”
Can a generated tool use my Tool AI account?
Yes. With the auth client, a tool can show sign-in and sign-out
prompts, read the signed-in profile, and store private data per user
and per tool. Guests appear as null, and the tool never receives
tokens, passwords, or Firebase configuration. Account features work
in the Tool AI editor and viewer, not in standalone exports.
Can generated tools share data between visitors?
Yes, through the shared cloud client. Values are public to anyone
who knows the key, so prefix keys by project and never store private
records or secrets there. Use account private storage for per-user
data.
How do I connect ChatGPT or another AI client?
Use GPT Connect or Connections in Settings. You authorize the client
with a normal browser sign-in, review the requested permissions, and
can revoke access at any time.