A custom tool is a capability defined by the thunk builder that the AI agent can invoke during a workflow run. The AI agent calls the tool by name, passes structured inputs, and acts on the return value.

From + Add New Tool you can create several types, including Custom AI Tool, Custom Code Tool, Document Template Tool, Spreadsheet Lookup Tool, Custom Database Tool, and Tool Wrapper. You can also build a new tool to match one entry of an interface — a file you upload, or one already used by a plug-in connection on this thunk. Thunk fills in that tool's name, description, and inputs from the interface and leaves you to implement it; those three then stay fixed. See Reuse thunk interfaces and plug-in connections. This article focuses on AI and Code tools. For filling Word or Google Doc templates, see Generate documents from templates. For looking up rows in a spreadsheet by the columns you choose, see How to build a Spreadsheet Lookup tool. For querying a connected SQL database, see How to build a Custom Database tool. For wrapping an existing tool with fixed arguments and inputs of your own, see How to build a Tool Wrapper. To reuse a recent result when an AI or code tool is called again with the same inputs, see Cache results of a custom AI or code tool. Not sure which type fits? See the comparison in AI Tools.

An AI agent can build these tools for you through the FDA MCP, including their inputs, outputs, batch settings and the tools an AI or code tool may call. See Build thunks with the FDA MCP.

A tool is not finished until it has tests. When you build a tool, give it test cases, each with at least one assertion on what it should return. See Automated tests for custom tools.

An AI tool executes a natural language instruction. A code tool executes a JavaScript function. Both are built on the same tool page. What differs is the logic in the Details section of the Implementation tab, described below.

Open Custom-built tools in the left nav and select a tool. On an MCP server thunk the page shows two lists. Exported tools are the ones published to external AI agents. Internal tools are helpers used inside the thunk, for example called by other tools. Manage export next to the Exported tools heading opens the screen where you choose which tools to publish.

A tool's page has these tabs:

Tool name is the snake_case identifier the AI agent uses to select the tool. The name should describe the decision, computation, or action the tool performs.

Description is the plain-language explanation of what the tool does and what it returns. The AI agent reads the description to determine when to call the tool. A precise description improves invocation accuracy. A vague description produces inconsistent behavior.

Logic/Intent describes, in plain language, what the tool should do and how. The AI that helps you build the tool uses it to design the inputs, outputs, and implementation. It is not the instruction or code the tool runs — that is on the Implementation tab.

The Enabled switch at the end of the tab decides whether the tool can be used inside this thunk: by its AI agents, its workflow steps, and its other tools. It does not decide whether the tool is published to external AI agents. That is set separately when you publish your thunk as an MCP server.

The Implementation tab is split into sections you can open and close independently: Inputs, Outputs, Details, Tools, and Behavior. Only Details starts open. Each closed section shows a short summary in its header — for example Inputs (2 fields) or Tools (2 connections enabled) — so you can see what is set without opening it. Not every tool type has every section: Tools appears only for code tools and document template tools, and some tool types have no Outputs.

Inputs and Outputs each have a Show raw JSON schema? switch, so you can see either one as a JSON schema instead of a list of fields.

Each input is defined as a named field with a description and a type. The AI agent reads the description of each input to determine what value to pass. Field names are case-sensitive and must match how they are referenced in the implementation.

A Conversation input lets a custom AI tool or a custom code tool read and message a conversation on the current work item. Use type Conversation, or a Reference that points at a Conversation property (the reference is the precise choice when a work item has more than one conversation). How the nested AI sees the transcript, how a code tool sends and waits, and examples of both are in How to build a tool that uses a conversation. While a custom AI or custom code tool is waiting for a reply, the calling step's activity log shows that tool's own log live — not only after the tool finishes.

A Reference input takes its type from a work item property, and follows that property if its type changes. Apart from the conversation case above, it sets only the type: the tool does not read the property's value from the work item. The AI agent that calls the tool passes the value, like any other input, so say in the input's description which property to pass. To have the platform pass the value itself — so the agent does not copy a large property into the tool call — map that field on the workflow step with Map I/O, or on a custom AI tool that calls this tool, onto that AI tool's own inputs. See Map a tool's inputs and outputs to the work item. A code tool sees only the inputs it is called with. If the agent leaves out a required input or passes the wrong type, the call fails before the tool runs, and the agent sees the error.

Prefer a Reference whenever an input carries the value of a work item property, and especially when the property has a structured type: a fixed list of values, a number, a date, a list or an object. The input then accepts exactly what the property accepts. For example, an expense tool whose category input is a Reference to an Expense Category property with the values Meals, Lodging and Ground transport refuses "Groceries" before the code runs, so the code never has to handle a category it doesn't know. When you add a value to the property, the tool accepts it too, with no second list to keep in step. Use a plain type only when no property holds the value.

The same goes for a Text property with a format, such as a length limit or a regular expression that the value must match (an order id like #W5061109 set as ^#W\d{7}$). A Reference input to that property, or a Text input that sets the regular expression itself, refuses a value in the wrong format. Before refusing a value that does not match the regular expression, Thunk.AI tries a few safe fixes: it removes spaces around the value, removes one pair of quotes around it, and adds the fixed text the format starts or ends with if the value is missing it. So W5061109 becomes #W5061109, and the tool receives the fixed value. A value that already matches is never changed. If no fix works, the call fails before the tool runs, and the agent sees which input was wrong, the value it sent and the format it needs, so it can correct the value and call again. Your code does not have to repair the format itself.

The same holds for an identifier the agent copies from one call to the next, such as an order number or customer id. Give it a property with a length limit, and make every input that carries it, in every tool, a Reference to that property. A value that lost or gained characters on the way is then refused before the tool runs, instead of reaching the wrong record. See "Values the AI agent copies" in Schematized State.

An input or output can also be a Structure Type, so a tool can take or return a whole structured record — a contact, an address, a list of line items — in one field instead of several loose ones. Define the shape once in the Type Library and the tool shares it with the columns and other tools that use it. See Structure Types and the Type Library.

Format constraints belong in the input description. If a date field expects DD/MM/YYYY, that constraint should appear in the description. If a field accepts only a fixed set of values, those values should be listed. If a field may be null and null has a specific meaning, that should be stated.

Outputs declares what the tool returns, as named fields with a description and a type, the same way as inputs. Declared outputs tell callers what to expect. When your thunk is published as an MCP server, outputs declared as named fields are part of what it publishes for the tool, and a thunk that reaches this tool through a plug-in connection relies on them. A tool built to match an interface may add output fields to those the interface declares, but it must still return every one of them.

An AI tool needs at least one output field (see AI-based Tools Implementation). An AI Classifier's outputs are its judgments, so each must be Yes/No or a choice from a fixed list of values. A Document Template or Spreadsheet Lookup tool's output is set by its type.

The Details section contains the logic for the tool. The form it takes depends on the tool type and is described in the sections below.

A code tool can call other tools. Turn on the connections it may use in the Tools section; its header shows how many are on. A custom AI tool's nested tools live under AI Instructions on the same page, including Map I/O onto that AI tool's own inputs and outputs. See Map a tool's inputs and outputs to the work item. A custom code tool does not map I/O.

The Behavior section applies to all tool types:

An amber warning icon next to a tool's name means one of the tool's schemas is not strict. You see it in the Custom-built tools list and in the thunk's tool lists. The tool's Implementation tab shows the same warning as a banner above the Inputs section. Hover over the icon to see which schema it is about: the input schema (what the AI agent passes to the tool), the output schema (what an AI tool must fill in when it finishes), or both.

A strict schema pins down exactly what the AI may pass: every object is closed to extra fields, and every field is listed as required. When a schema is not strict, the AI is held to it less tightly. It can leave fields out or add fields of its own, which makes the tool's calls and results less reliable. The tool still runs; the warning is about reliability, not an error.

Click the icon, or View details in the banner, to open the details. For each schema that is not strict, the dialog lists what does not pass. Then fix it in one of these ways:

Some warnings cannot be cleared from the tool:

If the dialog says the schema is not valid JSON, the AI cannot call the tool at all. Open the raw JSON schema and correct it.

A warning sign in the Tests column is a different signal: the last test run had inconclusive results. See Automated tests for custom tools.

The tool name, tool description, and input descriptions are read by the AI agent at runtime. Poorly written metadata produces incorrect or inconsistent invocations regardless of how well the implementation is written.

Tool names use snake_case. The name should express what the tool does, not how it does it.

Names that describe the question the tool answers or the computation it performs work well. Generic names that do not distinguish the tool from others in the same thunk do not.

The tool description should state what the tool does and what it returns, in one or two sentences. The AI agent uses this description to decide whether to call the tool at a given point in the workflow.

Descriptions that spell out the tool's purpose and what it returns let the AI know what to expect when calling it. Vague descriptions that could apply to many tools produce inconsistent behavior.

Each input description should state what the field contains and any constraints on its value. Three categories of constraint matter most:

Input names use PascalCase by convention when they correspond to fields in the thunk's data schema. This makes it easier to trace which schema field each input maps to.

The AI agent decides to call the tool based on the tool name and description. It constructs the input object by reading each input's description and populating it from available data. It then receives the return value and uses it in subsequent steps.

An AI tool implements its logic as a natural language instruction. The AI agent reads the instruction and produces a result. AI tools are appropriate when the task requires language understanding, judgment, or interpretation that cannot be expressed as fixed rules.

In addition to Inputs, an AI tool requires an Outputs section. Outputs are defined the same way as inputs: each output is a named field with a description and a type. The AI agent reads the output definitions to understand what values it is expected to produce. A well-written output description tells the agent both what the field contains and the format it should be in. Without defined outputs, the agent has no schema to produce values against.

The instruction can refer to inputs by name. The tool's AI agent receives the input values as a JSON object alongside the instruction, together with the input definitions; a name in the instruction is not replaced with its value. The instruction is prose that describes what to evaluate, what to produce, and how to handle edge cases.

When the input is unstructured or the outcome requires interpretation, the logic cannot be expressed as code. produce_structured_document in the Benchmark Invoice Processor sample illustrates this. It extracts structured fields from an invoice.

Tool name:produce_structured_document

Inputs:

Outputs:

The thunk reads each named output field from the agent's response and makes it available to subsequent steps.

The instruction defines not just what to extract but how to behave when the document is incomplete or inconsistent.

A code tool is appropriate when the logic is rule-driven and the outcome is fully determined by the inputs. Use code when the decision can be expressed as conditions, comparisons, or calculations, and when the same inputs should always produce the same output. If the task requires reading unstructured text, exercising judgment, or interpreting ambiguous content, use an AI tool instead.

For the JavaScript format, available globals (getTypedInput(), tools, thunk.dates, openFile, and others), and how to return a result, see How custom code tools work.

A common shape is a single async function:

The function is declared async; its name does not matter. You can also write only the function body, which is the preferred form: see How custom code tools work. The input parameter is an object whose keys correspond to the input names defined in the Inputs section. No external imports are available. Standard JavaScript and modern syntax are supported, including optional chaining, destructuring, and template literals.

Input fields can be null even when they are expected to have values. Guard against null inputs using optional chaining (?.) or fallback expressions (|| ""). Normalize string inputs with .trim() before comparison to avoid mismatches caused by whitespace. Guard clauses at the top of the function exit early when preconditions are not met, keeping the main logic path uncluttered.

People often describe what they want by comparing it with the alternatives: "the cheapest one", "the largest size", "the same color as the others", "my most recent order". A tool that only filters a list (returns everything in stock in size M) leaves the comparison to the AI agent, which then tells the person that something is the cheapest without having worked it out.

Give the agent a tool that runs the whole query and returns the answer:

The tool returns the chosen item and the values it compared, so the agent can tell the person why. A code tool is the natural fit: the same query always gives the same answer. Pair it with a direction that every number, comparison and action the agent states to the person comes from a tool result; see How to Write Effective AI Instructions.

When you review a thunk, look for superlatives in its directions and tool descriptions ("the cheapest", "the latest", "the best match") and check that a tool computes each one.

A common pattern in scheduled workflows is a tool that decides whether a workflow instance should wait for the next scheduled run or conclude. The tool checks whether the item has reached a terminal status and returns a value the AI agent uses to route the workflow.

Tool name:is_continued_tracking_required

Inputs:

'YES' signals that tracking should continue; 'NO' signals that the workflow instance can conclude.

The tool can be extended to return a structured object when downstream steps require additional data.

Tool name:is_continued_tracking_required

Inputs:

Two new inputs provide the dates needed to compute how long the item was open. On conclusion, the AI agent uses FinalStatus and DaysOpen to update the record before the workflow concludes.

When the item is still active, the function returns early with continueTracking: true. When the item has reached a terminal status, it computes DaysOpen and returns the outcome as a structured object. The AI agent reads the object fields by name and uses them independently.

The rules for batch_tools fields whose schema descriptions only
summarize them.

Response parsers (api and db tools). A responseParser is an
optional JavaScript snippet run in an isolated sandbox as the body of an
async function. Call getResponse() for the raw response text — an api
tool's HTTP body, a db tool's CSV result; there is no response
variable. input holds the tool's input arguments, log(str) appends to
an execution log returned with the result, and
​await fetch_str(url, options) performs one extra HTTP request and
returns its body text (a non-2xx status throws; private addresses are
blocked). The snippet must return a string and has a 5-second timeout.
String literals in the snippet must not contain raw newline characters —
build a newline with String.fromCharCode(10).

Output declarations (outputSchema / outputProperties). Declare
what a code, api, db, ai or classifier tool returns with one of
the two, not both: outputSchema is JSON Schema (an object of named
fields, or a bare value such as {"type":"string"}), and
​outputProperties is the batch_properties field shape, stored and
returned as outputSchema (set constraints.required on a field the
tool always returns; otherwise it may be null). Omitting both on an
update keeps the stored output; {} or [] clears it. A code tool's
return value is checked against the declaration, an ai tool's nested
agent must conclude with it, and a classifier needs at least one Yes/No
or text-enum field. A tool pinned to an interface may add output fields
but never remove or retype one the stored output declares.

Result caching (cachePolicy, clear_cache). On an ai or code tool, cachePolicy turns on reuse of identical lookups (cacheable) and how long to keep them (defaultTtlSeconds, 1–604800 seconds; 86400 is one day). Only enable this when the tool reads data and does not change anything — a reused result does not run the tool or call nested tools. Changing the instruction or code does not forget stored results; clear_cache (same name, no other fields) makes the next identical lookup run again and does not change cacheable or the duration. See Cache results of a custom AI or code tool.

Partial updates (intent, description, title, codeEdits, guidanceEdits, cachePolicy, addSchemaField, removeSchemaField). An update can change one part of a tool without sending the rest. Do not mix a partial update with tool. intent, description, and title replace those stored strings on any custom tool; omit a field to keep it. For a code tool, codeEdits is a list of find and replace texts applied in order to the saved code; each find must appear exactly once. guidanceEdits is the same kind of list applied to an ai tool's saved userGuidance (ai tools only). cachePolicy on the update (not inside tool) sets cacheable and/or defaultTtlSeconds and keeps the stored values you omit. addSchemaField / removeSchemaField add or remove one top-level field (name, and for add a JSON Schema schema) on the input or output (side; omit side for input) of any tool that authors its schema — not documentTemplate or spreadsheetLookup. Send addSchemaField or removeSchemaField, not both, and do not mix codeEdits with the other patch fields. A tool pinned to a Workflow Plan step cannot change a schema field this way — change the step, or detach the tool first. This does not forget cached results; use clear_cache for that.

Nested tool access (toolConfig). On an ai or code tool,
​toolConfig takes the enable/disable library and tool operations a
step's toolConfig uses (enable_library, disable_library,
​enable_tool, disable_tool) and controls which AI Tool Libraries and
tools the implementation may call — the ai tool's nested agent, the
​code tool's tools.* calls. It does not take set_io_bindings (Map
I/O is a workflow-step setting; see Map a tool's inputs and outputs to
the work item)
or set_binding_column. A tool inherits the thunk's enabled libraries
unless it disables them, an enable_* operation also opts the thunk in,
and the operations apply on top of the stored config. Read the effective
result from the tool summary's toolConfig (includeImpl /
​includeToolImpl). Plug-in binding inputs are set with bindingCases,
not here.

Step pinning (stepTarget). stepTarget pins a tool to one Workflow
Plan step (by id and/or title) and copies that step's current input and
output bindings onto the tool as ordinary schemas. Later updates may
change those schemas; the step's settings warn when they no longer match.
It does not set the step's implementation — use batch_steps
​implementationTool for that. Sending null detaches the tool, and
​stepTarget cannot be combined with signature.

Document templates. Every documentTemplate add or update fetches
the template variables from the document into the input schema's data
(structure from the template; descriptions and narrowed types from what
you send), so after editing the template document, resend the tool as an
​update to refresh them. Google Drive and OneDrive/SharePoint URLs need
Google Drive or Microsoft 365 enabled on the thunk; a .docx stored on
the thunk through upload_files or create_upload_link needs no extra
connection, and arbitrary internet URLs are not supported. The template
document itself must already exist.