Tools

Tools give your agent a way to explicitly initiate actions/interactions with Wysp.

Depending on your model’s strengths and context window pressure, you can choose integrate just a single Wysp hypertool alone, or to augment it with Wysp’s granular tools.

Hypertool

The hypertool is a single tool provided by wysp that accepts arbitrary natural language input and can exercise all of Wysp’s features. This is the recommended way to integrate Wysp, as it protects your context window from bloat.

Context Window

Granular Tools

Some of Wysp’s “UI Relevant” features are exposed as individual tools. These are roughly equivalent to the familiar controls you would find in a traditional maps UI.

They are useful if:

• the impulse to call a tool can come from multiple sources within your stack (LLM agent, UI interaction, secondary models, etc.)
• your base model struggles to correctly route the right inputs into the hypertool

Context Window

Tool Definitions

After initializing a connection to the websocket, you receive the state.bootstrap message. The toolDefinitions field contains the definitions (in MCP Tool format) for all tools provided by Wysp.

Note

The contents of toolsDefinitions can differ between user regions and model snapshots, so do interpret it at runtime (don’t hardcode it)

The hypertool is always available, and thus always present in the list.

bootstrap.toolDefinitions

{
  "toolDefinitions": [
    {
      "name": "add_destination",
      "description": "Add a destination to the trip",
      "argsSchema": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "Search query for Maps api for the destination to add"
          },
          "required": ["query"]
        },
        "guidance": {
          "indications": [
            "the user asks specifically for a stop to be added to their route"
          ],
          "contraindications": [
            "the user asks about a place in a general or hypothetical way"
          ]
        }
      }
    }
  ]
}

Tool Availabilities

Not all tools are available/applicable at all times. At various stages throughout the lifetime of the socket you will receive updates to the state.toolAvailabilities value, which lists a subset of the names from toolDefinitions, indicating which tools are currently available.

state.toolAvailabilities

{
  "toolAvailabilities": ["hypertool", "start_navigation", "..."]
}

Inclusion in context window

With the tool definitions and availabilities, you have everything needed to integrate Wysp’s tools into your agent’s context window.

If minimizing context window usage is the priority, include only the definitions of the currently available tools, and update the context anytime the availabilities change.

If maximizing cache usage is the priority, always include all the tools definitions near the top or your context window, and use the availability list lower in the context window to steer the agent away from currently unavailable tools.