Suits · 02
Tools
A Suit offers its agents only the tools that are on in it, and the Tools page sorts them by risk, so you can decide a group at a time.
Which tools start on
Every tool has its own switch in each Suit. When a Connection joins a Suit, all its tools start on, whatever the Suit's policy, even if its tools first load after it joins. Switch off the ones you don't want.
The new-tool policy
The top of a Suit's Tools page is its New-tool policy. It decides only how a tool that a server adds later starts; tools already in the Suit keep their switches. Choose one of three:
- Read-only on. New tools start on only if the server marks them read-only.
- All on. New tools start on, including ones that can change or delete data.
- All off. New tools start off until you switch them on.
A new Suit's policy is "All on". Your choice applies the moment you pick it: there's no Save, and nothing to confirm.
Tuxedo reads each Connection's tools again every day, and whenever you choose Refresh tools on the Connection. Each read finds the tools a server added.
Risk groups
Under the policy, each Connection's tools are sorted into groups by what their server declared, safest first:
- Read-only: the server says the tool doesn't change anything.
- Writes: the server says the tool isn't read-only, or says only that it isn't destructive.
- Destructive: the server says the tool may destroy data.
- Not declared: the server says neither.
Read-only wins: a tool its server marks both read-only and destructive goes in Read-only, because the MCP specification reads the destructive hint only for a tool that isn't read-only.
Writes isn't a promise. A tool lands there when its server says it isn't read-only but stops short of calling it destructive, so it can still delete things if its server didn't say. Not declared means the server said nothing either way: treat it as unknown.
A group with no tools isn't shown. A group whose tools are all off starts folded: choose its header to open it. A long group shows its first few tools, with a button to show the rest.
Hint badges
Under a tool's name you may see up to four badges, one for each hint its server declared true:
- Read-only: the tool doesn't change anything.
- Destructive: it may change or delete what's there, not only add to it.
- Idempotent: calling it again with the same arguments changes nothing more.
- Open-world: it may reach things outside its own system, as a web search does.
A hint the server declared false, or didn't state, shows no badge. A tool's details show all four, each as Yes, No or Not stated. Tuxedo never fills in a hint the server left out.
Hints are the server's own claims
Switch a whole group
Each group's header shows how many of its tools are on, whether that's All on, Some on or All off, and a switch. On a phone, it shows the count and the switch.
The switch is on only when every tool in the group is on. Flip it from Some on or All off and every tool in the group goes on; flip it from All on and they all go off.
Switch a Connection's tools
Each Connection has a card with its name, handle and account, and how many of all its tools are on. Its buttons act on all its tools at once:
- All on switches every tool on.
- All off switches every tool off.
A Connection that has no tools yet says so, with a link to refresh its tools.
Switch one tool
Switch a tool on or off on its row, or in its details.
Your switches are kept
Picking another policy doesn't change your switches, and neither does a server changing a tool's hints, or Tuxedo reading its tools again. A Connection's All on or All off with no search also forgets the switches of tools its server no longer lists, so one that comes back starts as the policy says.
Taking a Connection out of a Suit forgets its switches there; add it back and it starts afresh, with every tool on. Changing a custom server's URL forgets its tools' switches in every Suit, and all the new server's tools start on. Tailor a Suit covers choosing a Suit's Connections.
Search tools
The field beside the list shows only the tools that match what you type. A tool always matches when its name or title contains it, in capitals or not. The name is the one clients see, such as github__search_issues. Tuxedo can also search by what tools do: type what you want done, such as “file a bug report”, and it finds the tools for it, best match first, whatever they're called. Its placeholder then reads Search by name or what it does; when it reads Filter by name, only names and titles are matched. While you search:
- A line under the field says how many tools match. When searching by what tools do isn't available just then, such as after many searches in a minute, it says so, and only names and titles are matched.
- Connections with nothing that matches are left out, and named in one line under the list.
- The Connection's buttons read Matching on and Matching off. They and the group switches change only the tools the search shows, including those in folded groups, and those stay the same until you change the search. Change the search and switch before the new results show, and nothing is switched: the page says so, so you can check the list and try again.
- A group's count, and its All on, Some on or All off, cover only the matching tools. The Connection's count still covers all its tools.
To search by what tools do, Tuxedo sends the search, with the names, titles and the start of the descriptions of the Suit's tools, to TypeSafe, whose Jev model judges which ones match. A Connection's Tools page has the same search, over that Connection's tools.
Filter a Connection's tools
Above the list on a Connection's Tools page, In Suits shows all its tools, only those in Suits, or only those switched off for every Suit, with how many there are of each. A chip for each hint, Read-only, Destructive, Idempotent and Open-world, shows only the tools whose server declared it (Yes), declared the opposite (No) or didn't say (Not stated). The filters combine with each other and with the search, and stay in the page's address, so you can bookmark a filtered view. Clear filters shows every tool again and keeps the search.
Switch a tool off for every Suit
A Connection's Tools page lists every tool its server offers, each with a switch under In Suits. Every tool starts on. Switch one off there and it leaves every Suit that includes the Connection, whatever each Suit's own switch says: clients no longer list or call it.
- On a Suit's Tools page, it moves to a group of its own after its Connection's risk groups, named after the Connection, such as Off on GitHub, with no switch and a link to the Connection's tools. The risk groups' counts and All on or All off leave it out, and searching the Suit still finds it.
- Each Suit keeps its own switch for it. Switch it back on and each Suit has it on or off as before.
- It stays off when Tuxedo reads the server's tools again, even if the server stops listing it for a while. Changing a custom server's URL turns it back on, with the rest of the new server's tools.
A tool's details
Choose a tool's name to open its details beside the list. They show:
- its risk group, its Connection and account, the name clients call it by, and its title
- whether it's on in this Suit (for a Suit named Work, On in Work or Off in Work), with its switch
- its description, or "The server gave no description."
- Server's name (the tool's own name on its server), Connection, and the four hints
- Parameters: each one's name and type, and whether it's Required or Optional
- In your Suits: each of your Suits that includes the Connection, and On or Off
- Recent calls: up to 5 of its latest calls through any of your Suits that Activity still keeps
They end with "Tuxedo never stores a call's arguments or results." A Connection's own Tools page opens the same details, without the switch.
What agents see
An agent sees only the tools that are on. When its client lists a Suit's tools, the ones that are off aren't there. If it calls one anyway, Tuxedo answers exactly as it does for a tool the Suit doesn't have: Tool [handle__tool] not found.
So an agent can't tell a tool that's off from one that doesn't exist.
You can tell. While the tool is still off, Activity shows such a call as Refused · tool off, and its details offer Switch on in Work for a Suit named Work. See Activity.
A switch takes effect on the next call: switch a tool off, and Tuxedo refuses its next call. Tuxedo doesn't tell connected clients that the list changed, so a tool you switch on reaches a client the next time it lists the Suit's tools.