Customizing tools

VERSION 0.16.0 PUBLIC PREVIEW

You can remove tools users shouldn’t trigger from the built-in registry, replace a default with one wired to your backend, add domain tools, or start from a blank slate and hand-pick built-ins. The four patterns combine in one createMapAgent call.

How the registry is resolved

Three sources, in this order, make the tool set the agent exposes:

DEFAULT_TOOLS - The 56 built-in tools, unless you set includeDefaultTools: false.
dataEntries - A disabled kind drops its tools, as listed in TOOLS_BY_DATA_ENTRY_KIND, and leaves the data tools’ inputs. byod: { enabled: false } removes addByodSource, setByodLayers and updateByodDisplay.
Your tools option - Per-key overrides. They win over both, so a tool you pass under a dropped name comes back.

Remove a default tool

To drop a tool, pass false under its key. Do this when a tool is irrelevant to your use case, such as language switching in a single-language deployment, or harmful, such as executeMaplibreCode where prompts are untrusted.

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

The classifier doesn’t see removed tools, and the model can’t call them.

Replace a default tool

Pass a full ToolEntry under a built-in’s key, and the toolkit never instantiates the built-in. Usually you wire a built-in to your backend. Here, getCurrentLocation reads the fleet system instead of 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
});

Keep the original’s input and output shape where you can, because other tool descriptions and the system prompt may assume it. If yours differs, say so in its description or your systemPromptSuffix, so the model doesn’t pass the old fields.

Add a custom tool

Custom tools receive the same state as the built-ins, so they can hand results to the built-in display flow. Add places with state.places.addPlaceResult and your GeoJSON with state.byod.addEntry.

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
            id: `vehicle-${vehicleId}`,
14
            geometry: { type: 'Point', coordinates: position },
15
            properties: {
16
                type: 'POI',
17
                address: { freeformAddress: '' },
18
                poi: { name: `Vehicle ${vehicleId}`, categories: [], localizedCategories: [] },
19
            },
20
        };
21
        // Append to the places history; the model can then show it via updatePlacesDisplay,
22
        // route to it via setRoute, or recall it later through recallState.
23
        const entryId = await state.places.addPlaceResult(place, `Vehicle ${vehicleId}`);
24
        return { vehicleId, entryId, position };
25
    },
26
    tags: ['location'],
27
    examplePrompts: ['Where is vehicle TT-001?', 'Show fleet vehicle on the map'],
28
};
29

30
const agent = createMapAgent(map, {
31
    model: openai('gpt-4o'),
32
    tools: { getFleetVehicle },
33
});

The tool takes part in intent classification through its classificationPrompt. The classifier reads that line, not the description. A tool whose schema should change with what the user asked is a scopable custom tool.

Resolve a place in a custom tool

A custom tool that needs one place by name can run the same lookup as the built-in locatePlace tool:

locatePlace(query, queryAs, bias?, execOptions?) - Returns the best-matching Place, or null. queryAs is 'poi' to search points of interest by name, or 'place' to geocode an address or an area. Pass the execute options as execOptions, so a cancelled turn cancels the request.
getViewportBias(state.baseMap) - Returns the map centre as [longitude, latitude], to favour results the user is looking at. Below zoom MIN_VIEWPORT_BIAS_ZOOM (6), it returns undefined, because the view is too wide to tell where the user means.

1
import { getViewportBias, locatePlace, type ToolEntry } from '@tomtom-org/maps-sdk-plugin-agent-toolkit';
2
import { z } from 'zod';
3

4
const findStore: ToolEntry = {
5
    description: 'Find one of our stores by name, near the map view when zoomed in, and add it to the places history.',
6
    classificationPrompt: 'Locate a named store of ours.',
7
    inputSchema: z.object({ storeName: z.string() }),
8
    execute: async ({ storeName }, state, options) => {
9
        try {
10
            const position = getViewportBias(state.baseMap);
11
            const place = await locatePlace(storeName, 'poi', position && { position }, options);
12
            if (!place) return { status: 'not_found' };
13
            return { entryId: await state.places.addPlaceResult(place, storeName) };
14
        } catch (error) {
15
            return { error: `Store lookup failed: ${error instanceof Error ? error.message : String(error)}` };
16
        }
17
    },
18
};

A failed or cancelled lookup rejects, so execute catches it and returns an error shape, as the next section explains.

Errors are part of the contract

Every execute catches its own failures and returns an error shape, typically { error: string }. A throw surfaces as an opaque step failure the model can’t reason about. Name the missing entity and the next valid action:

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
}

When the model must branch on the failure (retry, call something else, give up), return a discriminated status ({ status: 'not_found' | 'unauthorized' | … }) instead of prose.
Tell input errors from external ones. An unknown id means calling something else first. A service 5xx is safe to retry once. Vague error strings are the main cause of retry loops.
A cancelled turn is not a failure, so catch SDKAbortError separately.
When a TomTom service or the map fails, the default tools return { error, code }. code is the SDKErrorCode, and the error text ends by saying whether retrying helps.

Start from a blank slate

For a narrowly scoped agent that should not stray into general map control, set includeDefaultTools: false and re-add the built-ins you want from DEFAULT_TOOLS. tools takes any tool definition, an entry or a builder:

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,  // re-add built-ins
9
        flyTo: DEFAULT_TOOLS.flyTo,
10
        analyseData: DEFAULT_TOOLS.analyseData,
11
    },
12
});

dataEntries still narrows the data tools you re-add, such as analyseData. The site selection agent example builds its agent this way.

Putting it all together

A real deployment usually combines 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 resolution and the classifier picks up your custom tools:

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 doesn’t activate when expected, rework its classificationPrompt. A prompt that’s too vague fires every turn, and one that’s too narrow never does. alwaysActive: true offers the tool on every step regardless.

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.
Securing your agent — giving custom tools narrow schemas, and keeping side effects off the model’s word.