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.

Start Here

Quick Start

  1. 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.”
  2. Wait for the create page. Tool AI signs you in anonymously if needed, sends the prompt, and streams a generated project into the preview.
  3. Refine with follow-ups. Ask for scoped changes such as “Keep the layout, add validation and a mobile-friendly summary.”
  4. Save or download. Anonymous users get local autosave. Signed-in users can save to cloud projects and optionally publish to the gallery.

Runtime

Generation Flow

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.

Recovery

Troubleshooting

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.

FAQ

Common Questions

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.