Customizing tools

The Agent Toolkit ships with a built-in tool registry, but every real deployment shapes that registry differently. You’ll typically remove tools the user shouldn’t trigger, replace a default with one wired to your own backend, add entirely new domain tools, or start from a blank slate and hand-pick what to bring in.

This page covers all four patterns. They compose freely — a single createMapAgent call can remove some, replace others, and add yet more.

How the registry is resolved

The plugin merges three sources, in this order, to produce the final tool set the agent exposes to the model:

1. DEFAULT_TOOLS — the built-in registry (54 tools as of this version).
2. dataEntries — narrows the surface by data-entry kind. Setting byod: { enabled: false } removes every BYOD-related tool (addByodLayer, recallByod, updateByodDisplay) AND drops byod from analyseData / processData scope. See State / dataEntries .
3. Your tools option — the per-key overrides described on this page. Overrides win against everything above.

Remove a default tool

Pass false against the tool’s key to drop it from the registry. Use this when a tool is irrelevant for your use case (e.g. language switching in a single-language deployment) or actively harmful (e.g. executeMaplibreCode in an untrusted-prompt deployment).

1
const agent = createMapAgent(map, {
2
    model: openai('gpt-4o'),
3
    tools: {
4
        setLanguage: false,
5
        executeMaplibreCode: false,
6
    },
7
});

Removed tools are not visible to the classifier and cannot be called by the model. If another tool’s relatedTools or dependsOn references a removed tool, the reference is silently ignored — the descriptions stay correct because they’re written as hints, not contracts.

Replace a default tool

Pass a full ToolEntry under the same key as a built-in. Your version takes precedence; the built-in is never instantiated.

The most common use case is wiring a built-in to your own backend — for example, replacing getCurrentLocation so it reads from your fleet system rather than the browser’s geolocation API:

1
import { z } from 'zod';
2

3
const agent = createMapAgent(map, {
4
    model: openai('gpt-4o'),
5
    tools: {
6
        getCurrentLocation: {
7
            description: 'Returns the user position from the company fleet system.',
8
            inputSchema: z.object({}),
9
            execute: async () => {
10
                const position = await fleetApi.getDriverPosition();
11
                return { position };
12
            },
13
            classificationPrompt: 'Get the driver\'s current GPS position from the fleet system.',
14
            tags: ['location'],
15
        },
16
    },
17
});

Match the original’s input/output contract whenever possible — other tools and the system prompt may assume the built-in’s shape. Where you genuinely need a different shape, also update any callers (or your own systemPromptSuffix) so the model doesn’t pass the old fields.

Add a custom tool

Bring your own domain tools alongside the built-in stack. Custom tools receive the same state object, so they can hand results to the built-in display flow (place pins via state.places.addPlaceResult, route renders via state.routing, BYOD layers via state.byod.addEntry, etc.).

1
import { z } from 'zod';
2
import type { Place } from '@tomtom-org/maps-sdk/core';
3
import type { ToolEntry } from '@tomtom-org/maps-sdk-plugin-agent-toolkit';
4

5
const getFleetVehicle: ToolEntry = {
6
    description: 'Get the current map position of a fleet vehicle by ID and add it to the places history.',
7
    classificationPrompt: 'Locate or display a fleet vehicle on the map by its ID.',
8
    inputSchema: z.object({ vehicleId: z.string().describe('The fleet vehicle identifier') }),
9
    execute: async ({ vehicleId }, state) => {
10
        const position = await fleetApi.getPosition(vehicleId);
11
        const place: Place = {
12
            type: 'Feature',
13
            geometry: { type: 'Point', coordinates: position },
14
            properties: { name: `Vehicle ${vehicleId}` },
15
        };
16
        // Append to the places history; the model can then show it via updatePlacesDisplay,
17
        // route to it via setRoute, or recall it later through recallPlaces.
18
        const entryId = await state.places.addPlaceResult(place, `Vehicle ${vehicleId}`);
19
        return { vehicleId, entryId, position };
20
    },
21
    tags: ['location'],
22
    examplePrompts: ['Where is vehicle TT-001?', 'Show fleet vehicle on the map'],
23
};
24

25
const agent = createMapAgent(map, {
26
    model: openai('gpt-4o'),
27
    tools: { getFleetVehicle },
28
});

The custom tool participates in intent classification automatically — as long as it has a classificationPrompt. The classifier reads the description and the prompt to decide whether to activate it for a given turn.

If your tool depends on a per-turn scope (e.g. it touches different data kinds depending on what the user asked), use a ToolEntryBuilder instead — see Scope-aware data tools / Add a scopable custom tool .

Errors are part of the contract

Every tool execute must catch its own failures and return a structured error shape — typically { error: string }. Throwing escapes the AI SDK boundary and surfaces as an opaque step failure that the model can’t reason about. Name the missing entity and the next valid action in the error string:

1
execute: async ({ vehicleId }, state) => {
2
    try {
3
        const position = await fleetApi.getPosition(vehicleId);
4
        // …
5
    } catch (error) {
6
        return { error: `Fleet vehicle "${vehicleId}" not found. Call listFleetVehicles to see available IDs.` };
7
    }
8
}

See ENGINEERING-GUIDELINES.md §4 for the full error-shape contract.

Start from a blank slate

Set includeDefaultTools: false to begin with no built-in tools. Useful when building a narrowly scoped agent that should not stray into general map control. Re-add specific defaults by referencing DEFAULT_TOOLS:

1
import { createMapAgent, DEFAULT_TOOLS } from '@tomtom-org/maps-sdk-plugin-agent-toolkit';
2

3
const agent = createMapAgent(map, {
4
    model: openai('gpt-4o'),
5
    includeDefaultTools: false,
6
    tools: {
7
        getFleetVehicle,                              // your custom tool
8
        locatePlace: DEFAULT_TOOLS.locatePlace,       // selectively re-add a built-in
9
        flyTo: DEFAULT_TOOLS.flyTo,
10
    },
11
});

When includeDefaultTools: false, the dataEntries narrowing layer becomes mostly irrelevant — no built-in tools means no kind-tied tools to drop. You’d still set dataEntries if any of the data tools you re-added (analyseData, processData) need per-kind narrowing.

Putting it all together

A real deployment usually mixes all four patterns:

1
const agent = createMapAgent(map, {
2
    model: openai('gpt-4o'),
3

4
    // Narrow the data surface — drops every byod-related default tool.
5
    dataEntries: {
6
        byod: { enabled: false },
7
        routes: { entryMode: 'single' },
8
    },
9

10
    // Per-key overrides on top of what dataEntries left.
11
    tools: {
12
        // Remove what doesn't fit the deployment
13
        setLanguage: false,
14
        executeMaplibreCode: false,
15

16
        // Replace with a backend-backed version
17
        getCurrentLocation: fleetCurrentLocationTool,
18

19
        // Add new domain tools
20
        getFleetVehicle,
21
        getDispatchJobs,
22
    },
23
});

Verifying your registry

Use onClassify to confirm the right tools survive the resolution pipeline and that custom tools are getting picked up by the classifier:

1
const agent = createMapAgent(map, {
2
    model: openai('gpt-4o'),
3
    tools: { getFleetVehicle },
4
    onClassify: (result) => {
5
        console.log('Tools selected for this turn:', result?.activeToolNames);
6
    },
7
});

If a custom tool isn’t activating when expected, the typical fixes are tightening its classificationPrompt (too vague → activated for every turn; too narrow → never activated), or adding examplePrompts so the classifier has concrete training signal.

Related

• Tool registry — the full list of built-in tools and what each one does.
• Scope-aware data tools — building custom tools whose schema changes per turn.
• Bring your own data — when your “data” is a GeoJSON layer rather than a new tool.
• State — extending agent state alongside a custom tool.