Tool

An LLM tool built as a row action – a compound pipeline that can move rows between tables, call an API endpoint, send email, and more – taking arguments inferred from the pipeline’s own steps and returning author-selected result columns back to the model.

Ingredient Family: llmQueryToolIngredients

Outline Display: Allow LLM to run a row action ({{toolName}}): {{toolDescription}}{{parameters:
Declared arguments: {{parameters}}}}
Action: {{rowAction}}
Returns to the model: {{outputMapping}}
Requires approval: {{requiresApproval}}
MCP hints: read-only {{readOnlyHint}}, destructive {{destructiveHint}}, idempotent {{idempotentHint}}, open-world {{openWorldHint}}{{advisory:
Not enforced by the server: {{advisory}}}}

Details

The tool’s arguments are the steps’ own free references: every name a step mentions (a formula’s [Name], a SQL query’s [Name] parameter) that neither an earlier step nor the table it is reading provides is an argument the LLM must supply, and its type is the type the step uses it at – or string, the default where the step only computes with it. String is a default and not a type every formula accepts: arithmetic over such an argument ([Amount] + 1 reaching an int) does not compile, so give an argument the steps only compute with a parameterType of its own. An inferred argument is required unless every step that reads it takes it at an option type, in which case the model may leave it out. So parameters: is optional, and an entry there annotates an argument rather than creating one: a description the model reads, an allowedValues enumeration, a pattern, a maxLength. allowedValues and maxLength are enforced and not merely advertised: a call whose value is outside the enumeration or over the cap is refused as bad arguments before any step runs, so an enumeration needs no Require restating it. pattern is advertised in the schema only. A declared parameter nothing reads – no step formula, no output mapping entry – gets a checker warning: the model would send a value the pipeline drops, so wire it in or remove it. Declare one with an option type (option string) to let the model leave it out. A name used at two incompatible types is an error, not a guess – declare it with the type you mean. The supplied values form the initial row handed to the row action. The action can build up more data (Load column from query/formula, Call API endpoint) and perform operations (Add row to table, Delete matching rows, Send email) before finishing. You then choose which columns of the post-action row are returned to the model via the output mapping – or leave outputMapping unset to return every column the action produced (never the arguments), each under its own name; an explicit empty mapping returns nothing. Only row-action ingredients that declare their produced columns to the compiler (the Load-column and Call-API-endpoint family) contribute columns the output mapping can read; the page content the action would otherwise render is discarded, since a chat tool has no page to render it on. That covers in-app page links too: a Redirect’s URL formula compiles and resolves here as it does anywhere else, but the redirect it would perform is thrown away with the rest of the rendered content, so the model sees only the output mapping. Note what this tool does NOT enforce, because the action’s ingredients run as configured: whatever the action’s own steps were configured to allow is what the model gets. The Send email and Send Gmail steps carry recipient allowlist and outbound-content knobs of their own, and they apply no matter how the action is reached – but only if the author set them. A completed call is audited under its tool name, and each step that sends, writes or refuses adds its own line, on failure as well as success. Those step lines carry fixed details (the addresses mailed, “add row”, the rule a Require states) rather than this tool’s name, so read them alongside the RunAction line that names the caller. An action can also stop and say why: a Require whose condition is false refuses the call, and steps like Load column from query and Send email report a malfunction when what they need is not there. Either way the remaining steps do not run, the call returns an error carrying the message and a kind of refusal or malfunction, and the model can read it and try something else. The transaction commits, so the audit lines and the chat turn survive the failure. Only a genuine Ur/Web error still aborts the turn and rolls its audit lines back with it. Because the LLM supplies every argument value and none of the above is enforced, an unstated requiresApproval gates this tool wherever its steps amount to anything but a read – which, for a pipeline holding an unannotated API call or an Ask an LLM step, is the usual case. Say readOnlyHint: true for an action that only reads, or requiresApproval: false for one whose writes stay inside the database.

Local scope

Names introduced within this component’s knobs:

• NULL – empty table populated by ingredients
• paramTable – empty table populated by ingredients
• argTable – empty table populated by ingredients
• scopeTable – empty table populated by ingredients
• outputTable – empty table populated by ingredients

Settings

Required

• toolDescription : constant value (type: text; required, non-nullable)
  A description of what this action does and when to use it, to help the LLM decide when to call it

Optional

• toolName : constant value (type: text; required, non-nullable)
  The name the LLM uses to call this tool; also names the action for the model. Defaults to the entry’s own name:, or, when neither is set, to a name derived from the pipeline’s sole API call, send, or draft step; set it only to say something different

• toolTitle : constant value (type: text; optional)
  The human-readable name an MCP client shows for this tool (MCP’s title), never read by a model. Omitted, it is derived from the wire name: search_open_orders becomes “Search Open Orders”. Two tools in one module cannot share a title, derived or authored.

• advisory : constant value (type: text; optional)
  A rule the server does NOT enforce, sent to the model as guidance under an explicit ‘not enforced’ header; use only when no deterministic form (Require, parameter constraints, allowedRecipients…) exists. The checker warns and the dashboard shows it as not guaranteed.

• parameters : ingredient slot of llmParamIngredients(paramTable) (many)
  Annotations for the arguments this tool takes: a description, an allowed-value list, a pattern, a length cap. The allowed-value list and the length cap are enforced on every call. An argument the steps use needs no entry here; an entry with a name the steps never mention adds an argument, and warns until a step or the output mapping reads it.

• rowAction : ingredient slot of rowActionsIngredients(scopeTable) (many)
  The action to run, using the supplied arguments as its initial row

• outputMapping : ingredient slot of mappingIngredientsList(scopeTable, outputTable, NULL) (many)
  Which columns of the post-action row to return to the LLM, and under what names. Left out entirely, every column the action produced is returned under its own name; an explicit empty list returns nothing

• requiresApproval : constant value (type: bool; required, non-nullable)
  Require the user to approve each invocation of this tool before it runs. Only honored inside a Chat concept, where the agent pauses mid-turn and shows Approve/Reject buttons; rejecting tells the LLM the call was denied and ends the turn. Setting it true on a tool used by any other agent (e.g. a row-action AskAnLLM triggered by a button) is rejected by the NectryCore typechecker – except under MCP Server, which only warns. When unset, the tool is gated exactly when its steps make it anything but read-only – the same reading its MCP category comes from, so a tool that annotates itself read-only is not gated – and only where a pause is honored: an unattended surface never invents a gate it cannot keep.

• readOnlyHint : constant value (type: bool; required, non-nullable)
  MCP readOnlyHint tool annotation, emitted in the MCP server’s tools/list: this tool modifies nothing in its environment. Omit it and the tool is advertised as read-only exactly when its own steps only read.

• destructiveHint : constant value (type: bool; required, non-nullable)
  MCP destructiveHint tool annotation, emitted in the MCP server’s tools/list: the tool’s modification may be irreversible (a delete, an outbound send). Only meaningful when the tool is not read-only. Omit it and the tool is advertised as destructive exactly when its own steps are.

• idempotentHint : constant value (type: bool; required, non-nullable)
  MCP idempotentHint tool annotation, emitted in the MCP server’s tools/list: repeating a call with the same arguments has no additional effect. Only meaningful when the tool is not read-only.

• openWorldHint : constant value (type: bool; required, non-nullable)
  MCP openWorldHint tool annotation, emitted in the MCP server’s tools/list: the tool reaches an open universe of external entities (the web, arbitrary recipients) rather than a closed domain such as a single CRM instance. Omit it and the tool is advertised as open-world exactly when one of its own steps calls an API, sends, or is a step of a kind the risk view does not recognize.