Hands on

Testing and debugging in XataWorks

You have declared tools and you want to know they work — that they are seen, described the way you meant, classed the way you meant, and called when they should be.

Registering a tool changes nothing visible about your page. That is right, and it is also why it is easy to believe you have declared one when you have not — the script threw, the host never saw it, and your page looks exactly as it did. XataWorks has three places to look, and none of them runs anything.

What you need

XataWorks itself — installers for macOS, Windows and Linux — and your page open in its browser. Serve the page however you already do, including from localhost; remember that XataWorks does not ask the site-permission question for localhost (see Hello, WebMCP).

Is your page seen?

The browser toolbar carries a page-tools button, a puzzle piece with a count for the tab in front of you. No button means the tab has published nothing. Click it for the list: each tool’s name, its description, and its class.

The XataWorks window. On the right, the browser panel shows the Notes example: three notes, Shopping list, Old draft and Meeting agenda. In the browser toolbar, beside the address bar, a puzzle-piece button reading 4: the number of tools this tab publishes. — The count in the browser toolbar is the fastest answer to “did my tools register?”. The Notes example publishes four.

What did it publish?

The page-tools button shows one tab. Available tools shows everything the current chat can reach, grouped by tab. Open the ⋮ menu in the chat header and choose Tools. You are reading your descriptions in the same place the agent does, and the badges are the classes XataWorks derived from your hints — not ones your page asked for.

The Available tools palette, cropped from the window. A filter box, then one group headed Notes, xataworks.ca, with four rows: List Notes, badged Read only; Add Note, badged Mutating; Delete Note, badged Consequential; and Notes House Style, badged Skill. Each row shows the page's description and the technical name beneath it. — The Notes example’s four tools, each badged with its class. A lookup badged anything but *Read only* means a hint did not land.

So the check is four steps: open your page, open the ⋮ menu in the chat header, choose Tools, and read the rows under your tab’s heading. The filter box matches the technical name too, so delete finds delete_note.

The same four steps, performed on the Notes example, ending with the filter narrowed to delete. No sound.

Watching a call

The examples in this section name the tool in their requests, so you can see the mechanism. When you test your own application, ask for the outcome instead — “what’s the status of order A-1002?” rather than “call find_order” — because the agent choosing your tool from its description is the behaviour you are testing.

A page-tool call appears in the chat as a line — Calling Say Hello via WebMCP — and pointing at it shows which page tool ran, and through which browser tool:

The chat, cropped. A run of lines: Browsing list tabs, Browsing list WebMCP tools, Calling Say Hello via WebMCP. A tooltip over one of them reads Say Hello, browser_call_webmcp_tool → say_hello, agent tool call. — The chat names the call. It does not show the arguments or the result — those are in the call log.

The call log

For the arguments and the result, open the browser’s own ⋮ menu and choose WebMCP call log…. Each entry records the site, the tool, the outcome and how long it took; select one for the arguments it was called with and a preview of what came back. That is the fastest way to find a schema problem: the agent sent what it thought your schema asked for, and you can see whether that matched what you meant.

The WebMCP call log window, with a search box and Domain, Group by and Show filters across the top. One entry: the date and time, say_hello, ok, 50 chars. The detail pane beside it is empty until an entry is selected. — The log after the hello example’s one call. Select an entry for its arguments and result.

Values are kept at the default Full detail level. At Summary only you will see the argument names and no values, which reads the same as a call made with empty arguments — check the level before concluding that.

When your tools are not listed

In the order worth checking, cheapest first.

The tab is not open in this chat’s browser

An agent can use tools only from tabs its chat can reach. If your tab is not in the palette, its tools cannot be either.

The script did not run, or threw before registering

Check the page’s own console. A syntax error, a failed import, or an exception above your registerTool call all produce the same symptom: no tools, and no complaint from the host.

The name collides

Two tools registered under one name leave one of them unreachable. Names specific to your application make this unlikely — see designing tools.

Your own content security policy blocked the script

An inline <script> on a page with a strict script-src and no nonce does not run. Nothing in the host reports this; your console does.

Test the hints, not only the tools

Do it once, deliberately, because the failure is invisible otherwise. Allow your site read-only tools, then ask for something that needs a tool you declared as changing things. You should be asked to confirm. If you are not, the hint is not what you think it is.

About these screenshots

They are Linux renderings of the application. On macOS and Windows the window frame and system fonts differ; everything inside the window is the same.