TomTom Maps for JavaScript
    Preparing search index...

    Type Alias ToolEntry<S, Scope>

    A tool definition, the universal format for both built-in and third-party tools. It combines execution (inputSchema + execute) with classifier metadata.

    type ToolEntry<S extends ToolState = ToolState, Scope = unknown> = {
        alwaysActive?: boolean;
        classificationPrompt?: string;
        dependsOn?: string[];
        description: string;
        endsTurnOnCall?: boolean;
        examplePrompts?: string[];
        examples?: string[];
        execute: (
            input: any,
            state: S,
            options?: ToolExecuteOptions,
        ) => Promise<any>;
        inputSchema: z.ZodType;
        outputSchema?: z.ZodType;
        relatedTools?: string[];
        scopePrompt?: string;
        scopeSchema?: z.ZodType<Scope>;
        tags?: string[];
    }

    Type Parameters

    • S extends ToolState = ToolState

      The ToolState shape this tool requires. Default: base ToolState.

    • Scope = unknown

      Optional per-tool scope shape. When set via scopeSchema, the classifier may emit a value of this shape per turn so the tool's description and inputSchema can be rebuilt narrower for that step. Tools without scope leave this at the default unknown. scopeSchema is then absent and no rebuild ever runs for the tool.

    Index
    alwaysActive? classificationPrompt? dependsOn? description endsTurnOnCall? examplePrompts? examples? execute inputSchema outputSchema? relatedTools? scopePrompt? scopeSchema? tags?
    alwaysActive?: boolean

    Whether this tool stays active on every step regardless of the classifier's selection. Its name is unioned into the per-turn activeTools set, so the model can always reach it. Use it sparingly, for tools that may be needed to set up any request (e.g. asking the user to clarify intent). It has no effect on the fail-open path (when classification is skipped, every tool is active).

    classificationPrompt?: string

    Compact one-liner for the intent classifier prompt.

    dependsOn?: string[]

    Tool names that must run before this one.

    description: string

    Description of the tool's purpose.

    endsTurnOnCall?: boolean

    Whether to halt the agent loop on the SAME step that calls this tool, with no trailing step. Use for tools whose turn must be a single silent tool call (e.g. clarifyIntent rendering a form). Leave unset to let the model take one more step after the tool returns, for example to present the tool's result as text before the loop stops naturally on a no-tool-call step. A tool that semantically awaits the user conveys that through its own result (e.g. clarifyIntent's status: 'awaiting_user_response'), not this flag.

    examplePrompts?: string[]

    Natural language prompts (e.g. 'Where is the Louvre?').

    examples?: string[]

    Usage examples (e.g. 'geocode("Amsterdam")'), passed on in the metadata a custom classifier receives.

    execute: (input: any, state: S, options?: ToolExecuteOptions) => Promise<any>

    Function that executes the tool. It receives the parsed input and the agent's state.

    If this calls a @tomtom-org/maps-sdk/services function directly, wrap its params with withAgentToolkitHeaders (tools/shared/agent-headers.ts) before passing them in, for example const requestParams = withAgentToolkitHeaders({ position }); await reverseGeocode(requestParams);. This tags the request so TomTom's traffic analytics attribute it to agent-toolkit. The guard test in tools/shared/tests/agent-headers.test.ts picks up an untagged call.

    inputSchema: z.ZodType

    Zod schema defining the tool's input parameters.

    outputSchema?: z.ZodType

    Optional Zod schema describing the tool's structured output.

    relatedTools?: string[]

    Tool names that are often used together with this tool.

    scopePrompt?: string

    Compact one-line hint for the classifier explaining when and how to scope this tool (e.g. "Emit { kinds: ['places'] } when only places entries are relevant"). Appended to the tool's classifier-prompt entry.

    scopeSchema?: z.ZodType<Scope>

    Optional per-tool scope schema. When set, the classifier may emit a scope value (validated against this schema), and prepareStep then rebuilds this tool's description + inputSchema by re-invoking its ToolEntryBuilder with the parsed scope. Tools without a builder cannot be scoped, so scopeSchema is only meaningful on builder-produced entries.

    tags?: string[]

    Category tags (e.g. 'location', 'routing').

    Settings
    Member Visibility

    On This Page
    Properties