Tool reference

Every built-in tool's inputs, valid values, and output shape — 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, and what each one outputs. For the exact HTTP request/response shape of each call path (anonymous vs. authenticated) and the full error tables, see Direct API integration.

The tools

All tools below are callable anonymously via POST /tools/:slug/run, the pattern in Your first SDK call, and are the same ones shown on the public Tools page. They’re also callable authenticated via POST /tickets — see Get your API key and Choose your auth mode.

These two are separate HTTP endpoints, not one endpoint gated by a header, and they return different output field names for the same tool — see Direct API integration for the full request/response shape of each.

Every tool has both a slug (what the public Tool Portal and POST /tools/:slug/run use) and a pipeline_id (what ai.run({ pipeline: ... }) and POST /tickets use). They’re the same string for every tool except translate, whose slug is translate but whose pipeline_id is translate-string — use the right one for the call you’re making.

Tool	slug	pipeline_id	Credits
Translate	`translate`	`translate-string`	1
Summarize	`summarize`	`summarize`	1
Rewrite	`rewrite`	`rewrite`	1
Grammar fix	`grammar-fix`	`grammar-fix`	1
Email generator	`email-generator`	`email-generator`	2
Knowledge base Q&A	`knowledge-base-qa`	`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.

None of these fit what you need? Raw prompt mode lets you send a custom system/user prompt instead of one of these fixed templates — it needs a separate grant on your credentials, so most integrations should start here and only reach for raw mode if nothing below covers the case.

“Valid values” is guidance, not server-side enforcement — even authenticated. For every select/enum-style field below (target_language, language, extract, action, tone, etc.), the authenticated POST /tickets path validates that the field is present (if required) and is the right type and size — it does not check that the value is one of the listed options. Send a value outside the list and it passes straight through to the LLM unchanged, on both the anonymous and authenticated paths. Only required/type/length are enforced.

translate

slug: translate · pipeline_id: translate-string

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 (authenticated /tickets shape): translation (the translated text), applied_terms (which glossary terms, if any, were applied). The anonymous Tool Portal path normalizes this to result.text instead — see Direct API integration for the two endpoints’ full request/response shapes.

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

summarize

slug: summarize · pipeline_id: 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

slug: rewrite · pipeline_id: 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

slug: grammar-fix · pipeline_id: 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

slug: email-generator · pipeline_id: 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

slug: knowledge-base-qa · pipeline_id: 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, and each has its own full table. See Direct API integration for the complete anonymous and authenticated error tables (status codes, error codes, and what each one means), and Choose your auth mode for how credential grants work in more depth.