Saltar al contenido principal

Managing Tools

A Tool is a backend capability the assistant can invoke autonomously: an HTTP lookup, a server-side calculation, a draft generator, an integration with an existing internal API. Tools complement what the live DOM can do.

Where a Control names a single DOM element and a Form names a multi-field workflow, a Tool names a capability that lives outside the page. The agent calls it during reasoning and uses the result to compose its answer or its Action Plan.

Tools are deliberately shaped to mirror Web MCP's registerTool({ name, description, parameters }). If the host app eventually adopts Web MCP directly, your authored Tools migrate to the standard with minimal rewriting. Today, Appilot's Tool registry is the bridge.

When to author a Tool​

The decision rule, from Authoring for the agent. Author when any of:

  1. Server-side computation or lookup the user benefits from (translate a code, validate a key, compute a summary, generate a draft).
  2. Integration with an existing API (/services/leistung-search?q=…) the agent should be able to call without you scripting the HTTP request inline.
  3. Stateful operation (create a draft on the server, schedule a job) where calling once is preferred over guiding a multi-click form.
  4. A capability the host app will eventually expose via WebMCP (today's Tool is the migration shim).

Do not author when:

  • The data is static. → Author a Knowledge entry instead.
  • The action is purely DOM-side (click a button, fill a form). → Author a Control or a Form.
  • The capability requires an auth token the agent does not hold, or is a long-running async job the agent cannot await.

How Tools differ from the other entities​

EntityWhat it namesWhat the agent does with itRuns against
KnowledgeA fact, rule, or workflow narrativeReads it during context build, cites it in responsesPre-loaded text
ControlA single DOM elementClicks, types, selectsLive page
FormAn ordered group of DOM fieldsFills the form following the materialised planLive page
ToolA backend capabilityInvokes it; uses the result to answer or planYour server (or WebMCP host)

A user-facing question like "What's the official name of LeiKa code 99006008?" answered by a static answer would belong in Knowledge. Answered by lookup_leistung(query: "99006008") it belongs in a Tool.

Anatomy of a Tool​

FieldPurpose
Tool nameStable snake_case identifier (lookup_leistung, validate_leika_key, generate_draft): lowercase letters, digits and underscores, starting with a letter. The editor suggests it from the Title, checks the format as you type, and guards renaming once a tool exists (every reference must follow). Referenced from Knowledge entries via the {{tool:tool_name}} token.
TitleHuman-readable name, used by the agent when narrating "I'll look this up via Search the Leistungskatalog".
DescriptionWhat this Tool does and when the agent should call it. This is the most important field: the agent decides to invoke a Tool based on this description matching the user's intent.
ParametersA typed record { name → { type, description, required } }. The agent populates parameters from the user's question.
View (optional)Scope the Tool to one View so it is only offered when that View is active. Leave empty for app-global Tools.
title_i18n / description_i18n / parameters_i18nOptional per-locale overrides. Use when the description should differ between languages (e.g. a region-specific term users will type in DE vs ES).

Tool rows with a runtime_spec are declared to the model as native function tools. The model calls the tool by its semantic id, and Appilot executes it through the configured runtime adapter. Rows without a runtime_spec stay visible for authoring but are not offered to the model.

Authoring a Tool​

Step 1: Decide the contract​

Before opening the Backoffice, write down on paper:

  • What does it do? ("Looks up a Leistung in the central catalogue.")
  • When should the agent call it? ("When the user is creating an Onlinedienst and needs to bind it to a Leistung.")
  • What parameters does it need? ("query: string, required. region_filter: string, optional.")
  • What does it return? (Shape of the response payload. Used by the agent when composing the answer.)

If you can't answer these in two sentences each, the Tool is not ready to author.

Step 2: Open the Tools tab​

Navigate to Apps → [Your App] → [Domain] → Tools.

Step 3: Click "Create tool"​

Step 4: Fill the basics​

  • Tool name: snake_case, lowercase with underscores (lookup_leistung).
  • Title: concise, user-facing if the agent ever narrates it ("Search the Leistungskatalog").
  • Description: one or two sentences. Lead with the verb. Include the when the agent should call it.
  • View: only set if this Tool is contextual to one View. Most are app-global.

Step 5: Declare parameters​

Parameters are a JSON record. Each entry has type, description, required:

{
  "query": {
    "type": "string",
    "required": true,
    "description": "Service name or LeiKa key. Free-text the user typed."
  },
  "region_filter": {
    "type": "string",
    "required": false,
    "description": "Optional ARS prefix to narrow results to one region."
  }
}

Tips:

  • Use plain types (string, number, boolean, array). Avoid deeply nested objects.
  • Write parameter descriptions for the agent, not for humans: "Free-text the user typed" tells the agent what to put there.
  • Mark only truly required parameters as required: true. Anything else stays optional.

Step 6: Save​

The Tool is now in the registry. Knowledge entries can reference it via {{tool:lookup_leistung}} tokens. The agent uses the description to decide when to invoke it.

Referencing a Tool from Knowledge​

In a Knowledge entry's description:

When the user is creating an Onlinedienst, they must bind it to a Leistung
from the central catalogue. Use `{{tool:lookup_leistung}}` to search by
service name or LeiKa key; the result includes the canonical id and version.

The agent sees the Tool's signature in the provider tool catalog, populates the parameters from the user's message, calls the Tool, and uses the result to compose its answer or propose guided steps.

The full token syntax (including {{control:...}} and {{form:...}}) is documented in Knowledge management.

Web MCP alignment​

The Tool entity maps one-to-one to a Web MCP tool declaration. When a host app adopts Web MCP and calls navigator.modelContext.registerTool({ name, description, parameters }), that declaration replaces the Appilot Tool with no migration work in your Knowledge. The inline {{tool:semantic_id}} token continues to resolve.

In other words: your Tool catalogue today is a portable description of what your app can do, written in a vocabulary the web will eventually speak natively. Authoring Tools is forward-compatible.

Common patterns​

Read-only lookup​

semantic_id:  lookup_leistung
title:        Search the Leistungskatalog
description:  Look up a service by name or LeiKa key.
              Returns id, official name, applicable regions, current version.
              Call when the user is creating an Onlinedienst and needs to
              bind it to a Leistung.
parameters:
  query:         { type: string, required: true, description: Free-text user typed }
  region_filter: { type: string, required: false, description: Optional ARS prefix }

Validator​

semantic_id:  validate-leika-key
title:        Validate a LeiKa key
description:  Check whether a LeiKa key exists and is current.
              Returns { valid: boolean, reason?: string }.
              Call when the user has entered a LeiKa key and wants
              confirmation before saving.
parameters:
  key: { type: string, required: true, description: The LeiKa key }

Server-side draft generator​

semantic_id:  generate-onlinedienst-draft
title:        Generate an Onlinedienst draft
description:  Generate a draft Onlinedienst from a Leistung. Uses the
              central template and substitutes the four mandatory
              parameters. Returns the draft id.
              Call when the user asks "draft this for me" after they have
              bound the Leistung.
parameters:
  leistung_id: { type: string, required: true, description: Result of lookup_leistung }
  region:      { type: string, required: false, description: ARS prefix of the responsible authority }

Common mistakes​

Authoring a Tool for static data​

Anti-pattern: get-mandatory-parameters returning the fixed list of four required parameters.

That's a fact, not a capability. Author a Knowledge entry titled "Pflichtparameter" and let the agent read it directly. Tools that just return constants bloat the catalogue and don't earn their keep.

Authoring a Tool for DOM clicks​

Anti-pattern: click-save-button registered as a Tool.

Use a Control instead. Tools are for capabilities outside the page.

Vague descriptions​

Anti-pattern:

description: Does Leistung stuff.

The agent decides whether to call a Tool based on this string. Make it precise. Include the verb, the inputs, the outputs, and when the agent should call it.

Overlapping Tools​

Anti-pattern: search_leistung and lookup_leistung_v2 both exist with similar descriptions.

The agent will struggle to pick one. Consolidate. If two capabilities really differ, make the difference explicit in the description ("v2: includes regional metadata; prefer over v1 when ARS is known").

Troubleshooting​

SymptomLikely causeFix
The agent never invokes my ToolDescription doesn't match user intent, or the Tool is scoped to a View the user isn't onRefine description; broaden View scope or set to app-global.
The agent tries to invoke a Tool that doesn't existA Knowledge entry references {{tool:X}} but Tool X is not authoredEither author Tool X or remove the token from the Knowledge entry. The Backoffice warns on save.
The agent passes the wrong parametersParameter descriptions are unclear from the agent's perspectiveRewrite parameter descriptions to tell the agent what to put there.
Multiple Tools match a single user questionOverlapping descriptionsDifferentiate descriptions; consolidate where the difference is too small to be useful.