Tool reference

Every built-in tool's inputs, valid values, output shape, and the errors each call path can return — the complete reference behind the quick-start guides.

The earlier guides get you to a working call fast. This page is the reference you come back to once you’re integrating for real: every tool’s inputs and valid values, what each one outputs, and exactly which errors you can get back — split by whether you’re calling anonymously or with a key, because those two paths behave differently.

The tools

All tools below are callable anonymously (no API key, rate-limited) via the pattern in Your first SDK call, and are the same ones shown on the public Tools page. They’re also callable authenticated (API key/JWT) — see Get your API key and Choose your auth mode.

Tool (`pipeline`)	Credits
`translate`	1
`summarize`	1
`rewrite`	1
`grammar-fix`	1
`email-generator`	2
`knowledge-base-qa`	2

Credits are what a run actually costs against your plan/wallet — check the number before you build a feature around a tool.

translate

Input	Type	Required	Valid values	Notes
`text`	string	yes	up to 5000 characters	The source text. Language is auto-detected — you don’t specify a source language.
`target_language`	string	yes	`en`, `es`, `de`, `ja`, `fr`, `pt`, `zh-Hans`, `zh-Hant`, `ko`, `ar`, `vi`, `th`, `ms`	The language code to translate into.
`glossary_inline`	string	no	up to 4000 characters	Optional term overrides, one pair per line as `source=target` or `source,target`. Not stored — applies to this call only.

Output: translation (the translated text), applied_terms (which glossary terms, if any, were applied).

const out = await ai.run({
  pipeline: "translate-string",
  inputs: { text: "Hello", target_language: "de" },
});
// out.translation === "Hallo"

summarize

Input	Type	Required	Valid values	Notes
`text`	string	yes	up to 5000 characters	The source text to summarize.
`length`	string	no	`short`, `medium`, `long`	Omit for the default length.
`language`	string	no	`""` (keep original) or any code from the translate table above	Output language. Empty string keeps the source text’s language.
`extract`	string[]	no	`action_items`, `decisions`, `risks`, `timeline`	Zero or more extra structured sections. Send them in this exact order — a different order counts as a different request for caching purposes, even if the values are otherwise identical.

Output: tldr, key_points, and whichever of action_items / decisions / risks / timeline you asked for in extract.

rewrite

Input	Type	Required	Valid values	Notes
`text`	string	yes	up to 5000 characters	The source text to rewrite.
`action`	string	no	`rephrase`, `shorten`, `expand`, `simplify`, `formalize`, `bulletize`	The rewrite operation.
`tone`	string	no	`professional`, `casual`, `friendly`, `concise`	The target tone.
`language`	string	no	`""` (keep original) or any code from the translate table above	Output language.
`glossary_inline`	string	no	up to 4000 characters	Same format as translate’s `glossary_inline` above.

Output: rewrite (the rewritten text), applied_terms.

grammar-fix

Input	Type	Required	Valid values	Notes
`text`	string	yes	up to 5000 characters	The source text to correct.
`glossary_inline`	string	no	up to 4000 characters	Same format as translate’s `glossary_inline` above.

Output: corrected (the corrected text), changes (a list of what changed), applied_terms.

email-generator

Input	Type	Required	Valid values	Notes
`purpose`	string	yes	up to 2000 characters	What the email is about and what it should cover.
`recipient`	string	no	up to 500 characters	Who it’s addressed to. Omit for a generic recipient.
`tone`	string	no	`formal`, `friendly`, `persuasive`	The tone of the drafted email.
`glossary_inline`	string	no	up to 4000 characters	Same format as translate’s `glossary_inline` above.

Output: subject, body, applied_terms.

knowledge-base-qa

Input	Type	Required	Valid values	Notes
`question`	string	yes	up to 1000 characters	The question to answer.
`context`	string	yes	up to 6000 characters	The single document the answer must be grounded in.

Output: answer, grounded (whether the answer is actually supported by context), citation (where in context the answer came from).

There’s no search index or external knowledge behind this tool — it only ever answers from the context text in the same request. For anything beyond a single ~6000-character document, chunk your source text and call it per chunk.

Errors

Which errors you can get back depends on how you’re calling — anonymous and authenticated calls are validated differently. Don’t assume one path’s error behavior applies to the other.

Calling anonymously (no API key)

The pattern from Your first SDK call — all tools listed above, rate-limited per IP.

Status	Error code	Meaning
404	—	Unknown tool slug.
403	—	Bot check failed.
429	`guest_quota_exceeded`	You’ve hit the anonymous per-IP or global daily request limit.
429	`guest_cost_exceeded`	You’ve hit the anonymous per-IP or global daily cost limit (expensive tools use up this budget faster).
202	—	Success — `{ ticket_id, status: "QUEUED" }`. Poll for the result the same way as any other call.

Important: on this path, your inputs are not checked against the tables above before the call is accepted — a missing required field or an invalid value doesn’t get you a 400. The run itself will fail instead, which you’ll see when you poll for the result. Once you have an API key, switch to the authenticated path below, which validates upfront.

Calling with an API key or session token

The pattern from Choose your auth mode — any tool you have access to.

Status	Error code	Meaning
401	—	Missing, invalid, or expired credentials.
403	`app_disabled`	Your application has been disabled.
403	`org_suspended`	Your organization has been suspended.
403	`org_pending_deletion`	Your organization is scheduled for deletion.
403	—	This tool isn’t in your credentials’ allowed pipeline list.
400	—	Your `inputs` don’t match the tool’s requirements (missing required field, invalid value, or the total input is too large). This path does validate upfront, unlike the anonymous one.
429	`rate_limited`	You’re sending requests faster than your per-minute limit.
429	`quota_exceeded`	You’ve hit your monthly request quota.
429	`daily_cost_exceeded`	You’ve hit a daily cost cap — a velocity limit, distinct from running out of balance below.
402	`insufficient_credits`	Your organization’s credit balance is too low to cover this call. Top up and retry.
202	—	Success — `{ ticket_id, status: "QUEUED" }`. Poll for the result.

For how credentials and the 401/403/429 auth decisions work in more depth, see Choose your auth mode.