AI Agent Tools

A reference for the built-in tools an Appivo AI Agent can call, what each one does, and how to configure it in an agent's chain definition.

An AI Agent in Appivo runs an AIChain — a named pipeline of one or more steps driven by an LLM, optionally armed with a set of tools. A tool is a capability the model can decide to invoke mid-turn: search an index, read a web page, generate an image, remember a fact, query a knowledge dataset, and so on. The LLM sees each tool's name, description, and parameter schema, and calls it with arguments it fills in; the platform executes the tool and feeds the result back into the conversation.

Tools are declared in the tools array of the chain JSON. Each entry has a type discriminator that selects the tool class, plus tool-specific configuration. This page lists every built-in tool, the type value(s) that select it, its purpose, and its configuration properties.

How tools are declared

Tools live in the tools array of the chain definition. The type field selects the tool; everything else is configuration:

{
  "name": "research-agent",
  "version": 1,
  "description": "Answers questions using the docs index and the web.",
  "tools": [
    { "type": "SEARCH", "index": "product-docs", "limit": 8 },
    { "type": "webSearch" },
    { "type": "webGet" }
  ],
  "steps": [
    { "name": "answer", "input": { "message": "$question" } }
  ]
}

Each type value is matched case-insensitively against the tool type enum, after a small set of friendly aliases are folded in (e.g. createImage → GENERATEIMAGE). Both the canonical enum name and the documented aliases work; see the quick reference for the exact set each tool accepts.

Which tool do I need?

Start from the outcome you want, not the tool list. Find the row that matches what the agent should do, then jump to its catalog entry for the configuration details.

One way to hold the whole catalog in your head: retrieval tools bring information in (Search, Web, Document, Knowledge), generation tools send rich artifacts out (Chart, Excel, Image, Audio, Video), memory tools persist context across conversations, and Script / Java / Agent let you extend or compose beyond the built-ins.

Properties every tool shares

Every tool inherits these base properties. Most are set automatically (the platform supplies a sensible default name, description, and parameter schema per tool), but you may override them in the JSON:

The arguments (parameter schema) and required (list of required parameter names) properties also exist on the base class but are only authored by hand for Script tools — built-in tools define their own parameter schema in code.

Configuration vs. call-time parameters

Two distinct things are easy to confuse:

• Configuration properties — set by you in the chain JSON. They are fixed for the life of the agent (which index to search, which image provider to use, the timeout).
• Call-time parameters — filled in by the LLM each time it invokes the tool (the search query, the image prompt, the fact to remember). You don't set these; they're listed here so you know what the model controls.

Each tool below documents both.

Minimal config cheat-sheet

Every tool's smallest valid declaration, ready to paste into the tools array. The Common knobs column lists the optional properties you'll reach for most often; the full set lives in the catalog.

Only four tools need any configuration to work: Search (index), Java (class), Agent (agent), and Script (name + script). Every other tool runs with just its type — all remaining properties have sensible defaults.

Tool catalog

Custom tools: Script, Java, Agent

These three aren't fixed capabilities — they're how you extend an agent with your own logic or compose agents together.

Script — inline JavaScript tool

Define an ad-hoc tool whose body is JavaScript you write directly in the chain. Selected when type is omitted (null) or "SCRIPT". This is the one tool where you author the full parameter schema yourself.

Configuration

A Script tool is only added to the chain if both name and script are present.

{
  "name": "celsius_to_fahrenheit",
  "description": "Convert a Celsius temperature to Fahrenheit.",
  "arguments": {
    "celsius": { "type": "number", "description": "Temperature in °C" }
  },
  "required": ["celsius"],
  "script": "return { fahrenheit: input.celsius * 9 / 5 + 32 };"
}

Java — reflective internal tool

Loads a Java class and exposes its annotated methods as tools via reflection (langchain4j ToolSpecifications). For platform/internal use.

{ "type": "JAVA", "class": "com.acme.MathTools" }

Agent — call another agent as a tool

Invoke another named AI Agent as a sub-tool, enabling hierarchical composition (a supervisor agent that delegates to specialists). The sub-agent's input parameters become the tool's call-time parameters automatically.

{ "type": "AGENT", "agent": "invoice-extractor",
  "description": "Extract structured fields from an invoice document." }

Retrieval & web

Search — SEARCH

Search a configured Appivo search index (vector and/or BM25 keyword) and return ranked documents. The agent's primary RAG retrieval tool.

Configuration

Call-time parameters: query (String, required).

{ "type": "SEARCH", "index": "support-kb",
  "limit": 8, "minScore": 0.6, "type": "both" }

Web Search — WEBSEARCH / webSearch

Search the public internet and return ranked results (title, URL, snippet). No configuration beyond the standard name/description.

Call-time parameters: query (required), optional startDate / endDate (ISO-8601 YYYY-MM-DD) to bound results by date.

{ "type": "webSearch" }

Web Get — WEBGET / webGet

Download and read a web page from a URL. By default it runs the content through the web scraper and extracts the main text (stripping boilerplate); set useSimpleFetch for a raw HTTP fetch.

Configuration

Call-time parameters: url (required), extract_text (Boolean, default true).

{ "type": "webGet", "useSimpleFetch": false }

Documents & summarization

Document Get — DOCUMENTGET / documentGet

Read the full contents of a stored document by ID or checksum, extracting text from PDFs, images, and other formats.

Configuration

Call-time parameters: id (required) — document ID or checksum.

{ "type": "documentGet" }

Summary — SUMMARY / summary

Produce a concise summary of a document, web page, image, audio, or video file. Large inputs are chunked and summarized with the configured LLM model.

Configuration

Call-time parameters: file-id (required).

{ "type": "summary", "model": "gpt-4o-mini",
  "targetSummaryWords": 200, "temperature": 0.2 }

Content generation

These tools create rich artifacts (charts, spreadsheets, images, audio, video) that the agent can return as embeddable resources.

Chart — CHART / createChart

Render a chart from structured data. No configuration beyond name/description; the chart type, data, and layout are supplied by the LLM at call time.

Call-time parameters: chartType (BAR, STACKED_BAR, LINE, AREA, PIE, SCATTER, BUBBLE), config ({title, width, height, xAxisTitle?, yAxisTitle?, showLegend}), and datasets ([{name, dataPoints:[{x, y, z?}]}]).

{ "type": "createChart" }

Excel — EXCEL / createExcel

Generate an Excel spreadsheet from structured data, with optional sum rows for numeric columns. No configuration beyond name/description.

Call-time parameters: columns ([{headerName, dataType, shouldSum}], required), rowData (array of row arrays, required), optional title and description.

{ "type": "createExcel" }

Generate Image — GENERATEIMAGE / generateImage / createImage

Generate an image from a text prompt. Supports OpenAI (DALL·E / gpt-image), Google Vertex AI Imagen, and OpenRouter (Flux, Stable Diffusion).

Configuration

Call-time parameters: prompt (required), optional size and quality overrides.

{ "type": "generateImage", "provider": "GOOGLE",
  "model": "imagen-4.0", "aspectRatio": "16:9" }

Generate Audio — GENERATEAUDIO / generateAudio / createAudio / textToSpeech / tts

Text-to-speech generation. Supports OpenAI TTS, Google Cloud TTS, and ElevenLabs.

Configuration

Call-time parameters: text (required), optional voice, speed, format overrides.

{ "type": "tts", "provider": "ELEVENLABS",
  "voice": "Rachel", "format": "mp3" }

Generate Video — GENERATEVIDEO / generateVideo / createVideo

Generate a video from a text prompt. Supports Google Veo, OpenAI Sora, and Replicate.

Configuration

Call-time parameters: prompt (required), optional duration, aspectRatio, resolution overrides.

{ "type": "generateVideo", "provider": "GOOGLE",
  "model": "veo-3.0-fast", "duration": 8, "resolution": "1080p" }

Code execution

Execute Code — EXECUTECODE / executeCode / codeExecution / codeInterpreter

Run JavaScript in a secure GraalVM sandbox with no access to host resources. Lets the agent do precise calculations, data transformations, and programmatic work it can't reliably do in plain text.

Configuration

Call-time parameters: code (required), optional description.

{ "type": "executeCode", "timeout": 15, "allowConsole": true }

Long-term memory

These tools connect the agent to the Appivo AI Memory platform. All four extend a shared base and accept one configuration property:

When omitted, the tools operate against the agent's default memory space for the current tenant and user. See the AI Memory guide for the memory model (atoms, spaces, entities, bi-temporal validity).

Create Memory — CREATE_MEMORY / createMemory / rememberFact / remember

Save a single, self-contained fact to long-term memory so it can be recalled later. Lets the agent commit durable information (preferences, decisions, constraints, identity facts) mid-conversation instead of waiting for post-conversation extraction.

Call-time parameters: text (required — one complete sentence), category (required — preference, goal, identity, fact, rule, or episode), importance (1–5, default 3), entities (optional [{name, type?, role?}]).

{ "type": "rememberFact" }

Recall by Topic — RECALL_BY_TOPIC

Recall memories semantically related to a free-text query, using vector search over memory atoms.

Call-time parameters: query (required), limit (default 10, max 50).

{ "type": "RECALL_BY_TOPIC", "memorySpaceId": "$spaceId" }

Recall by Entity — RECALL_BY_ENTITY

List every memory atom tagged with a specific entity (person, organization, place, object, concept, event, agreement), newest first, with bi-temporal validity windows.

Call-time parameters: entityIdOrName (required — UUID or canonical name), limit (default 10, max 50).

{ "type": "RECALL_BY_ENTITY" }

Recall Timeline — RECALL_TIMELINE

Recall what was true within a time window using bi-temporal versioning — including superseded atoms — to track what changed and when.

Call-time parameters: entityIdOrName or query (at least one required), optional from / to (ISO-8601 validFrom bounds, inclusive), limit (default 10, max 50).

{ "type": "RECALL_TIMELINE" }

Discriminator note: the three recall tools have no camelCase aliases — use the exact enum names (RECALL_BY_TOPIC, RECALL_BY_ENTITY, RECALL_TIMELINE). Create Memory does accept the friendly aliases listed above.

Knowledge datasets

A single tool queries structured knowledge datasets (entities, attributes, relationships) under access control, so an agent only sees data it's permitted to. It takes no special configuration beyond name/description — the dataset and scope are passed at call time.

The schema is embedded — the agent doesn't have to discover it. Any agent that carries the knowledge tool automatically gets the dataset schema injected into its system prompt: the entity types with their attributes and dedup keys, the relationship graph (relType: fromType -> toType, with the out/in direction convention), and each type's taxonomy facets. The model therefore already knows the exact entityType, attribute, relType, and direction names to use, and does not need a separate discovery step before querying.

Knowledge Query — KNOWLEDGE_QUERY / knowledgeQuery

Run a structured query against a knowledge dataset: select entities of a type, look one up by name, filter by attributes, traverse relationships (1–2 hops), and optionally aggregate. Results are always filtered to what the current user is permitted to read — you can't widen that from the tool config.

Call-time parameters: datasetId (required), spec (required — see below), folderIds (optional — scope visibility to specific folders/documents; the record-level ACL still applies).

spec shape (a JSON object; may be passed as a nested object or a JSON string):

Traversal is a filter by default (inner join). Only roots that have a surviving neighbor are returned — e.g. to answer "who worked in Marketing", select person and traverse the person→industry relationship filtered to the neighbor named Marketing. Set optional: true on a hop to keep every root and just attach whatever neighbors it has (left join). More than two hops is rejected.

Aggregates. count counts the matched roots. group_by / distinct run over the root's own attribute when over is omitted, or over the neighbors reached by the hop whose as equals over (use attr: "canonicalName" to group/dedup by the neighbor's name). A distinct (or group_by) aggregate is also how an agent discovers valid filter values — it returns an attribute's distinct values, access-filtered to the current user — e.g. {"entityType":"person","aggregate":{"op":"distinct","attr":"department"}}.

{ "type": "knowledgeQuery" }

Removed: the knowledgeVocabulary / KNOWLEDGE_VOCABULARY agent tool. Discovering distinct values is now done with knowledgeQuery's distinct / group_by aggregate (same access model), and taxonomy facets are part of the embedded schema described above. The developer JS API context.getKnowledge().vocabulary(...) is unaffected and still works from Actions — only the agent tool was retired. See the Knowledge guide.

Discriminator quick reference

The type value is matched case-insensitively against the enum after the aliases below are applied. The canonical column is always safe; aliases are conveniences.

Common pitfalls & tips

A short list of things that trip people up.

• Give the step enough cycles. A tool call plus a final answer is at least two model turns, so a step that uses tools needs maxCycles ≥ 2 — and more if you expect several tool calls in a row. The worked examples below use 6–8.
• timeout is only honored by some tools. A JSON timeout is read for Script, Execute Code, Generate Image, Generate Audio, and Generate Video only — every other tool ignores it and uses the 60s default. Execute Code defaults to 30s and the media generators default higher (image 120, audio 120, video 300); raise those for heavy work.
• Search returning too little? minScore defaults to 0.7, which is fairly strict — lower it (e.g. 0.6) or raise limit if relevant hits are being filtered out.
• Keep tool names unique. name must be unique within the chain. If you add two tools of the same type, override name on at least one of them.
• memorySpaceId: literal vs. variable. Pass a literal ID to pin the space, or "$paramName" to bind it to a step input at runtime. If both are somehow set, the literal wins. Omit it to use the tenant/user default space.
• Mind the alias gaps. The three recall tools have no camelCase aliases — use the exact enum names (RECALL_BY_TOPIC, RECALL_BY_ENTITY, RECALL_TIMELINE). And a Script tool is only registered when both name and script are present.
• Scoping is automatic. Knowledge and memory tools only ever see data the current tenant and user are permitted to see — you can't widen that from the tool config.
• Script parameters arrive on input. Inside a Script body, read each call-time parameter as input.<name> (e.g. input.celsius), matching the schema you declared in arguments.

Worked examples

Support assistant — retrieval, memory, and a chart

A support agent that searches the knowledge base, can read a linked web page, remembers customer preferences it learns, and can draw a chart of ticket trends:

{
  "name": "support-assistant",
  "version": 1,
  "description": "Answers support questions and remembers customer context.",
  "input": {
    "message": { "type": "string" },
    "spaceId": { "type": "string" }
  },
  "tools": [
    { "type": "SEARCH", "index": "support-kb", "limit": 8, "minScore": 0.6 },
    { "type": "webGet" },
    { "type": "rememberFact", "memorySpaceId": "$spaceId" },
    { "type": "RECALL_BY_TOPIC", "memorySpaceId": "$spaceId" },
    { "type": "createChart" }
  ],
  "steps": [
    {
      "name": "respond",
      "maxCycles": 6,
      "input": { "message": "$message" }
    }
  ]
}

Report builder — compute, then render artifacts

An agent that crunches raw figures with code, then returns a chart, a spreadsheet, and a short written summary — pure generation, no retrieval:

{
  "name": "report-builder",
  "version": 1,
  "description": "Turns raw figures into a chart, a spreadsheet, and a summary.",
  "tools": [
    { "type": "executeCode", "timeout": 20 },
    { "type": "createChart" },
    { "type": "createExcel" },
    { "type": "summary", "targetSummaryWords": 150 }
  ],
  "steps": [
    { "name": "build", "maxCycles": 8, "input": { "message": "$message" } }
  ]
}

Knowledge analyst — exact answers with memory

An agent that issues structured queries for exact relational answers over a knowledge dataset, and remembers what the user cares about for next time. It already knows the dataset schema (that's injected into its system prompt), and discovers concrete filter values with a distinct aggregate when it needs them:

{
  "name": "knowledge-analyst",
  "version": 1,
  "description": "Answers exact, relational questions over a knowledge dataset.",
  "input": {
    "message": { "type": "string" },
    "spaceId": { "type": "string" }
  },
  "tools": [
    { "type": "knowledgeQuery" },
    { "type": "rememberFact", "memorySpaceId": "$spaceId" },
    { "type": "RECALL_BY_ENTITY", "memorySpaceId": "$spaceId" }
  ],
  "steps": [
    { "name": "analyze", "maxCycles": 6, "input": { "message": "$message" } }
  ]
}

In every case the LLM decides which tools to call and in what order at runtime; the platform executes each call, enforces tenant/user scoping and access control, and feeds results back until the step completes.

Related guides

• AI Agents — pre-built agents, custom agents, and RAG implementation
• AI Memory — conversations, distilled facts, and prompt-ready working context
• Knowledge — structured entity extraction for exact, exhaustive, and relational questions