Permissions

Safety classes

You are deciding which hints to put on your tools. The hints decide the class, and the class decides what the person using the agent is asked before your operation runs.

Three classes

Read only: Looks things up and changes nothing. Once the person allows a site’s read-only tools, these run without another question.
Mutating: Changes something, and the change is ordinary and easy to undo — adding a note, saving a draft. The permission questions call these non-consequential read/write tools.
Consequential: Changes something that matters or cannot be taken back — deleting, sending, paying, publishing. Confirmed one call at a time unless the person has allowed all of a site’s tools.

The tools palette shows each tool’s class as a badge, which is the quickest way to check your hints landed:

The Available tools palette, cropped. One group headed Notes, xataworks.ca: List Notes badged Read only, Add Note badged Mutating, Delete Note badged Consequential, and Notes House Style badged Skill. — The Notes example declares one tool of each class, and a skill.

The hints

readOnlyHint: true makes a tool read-only — unless it also says it is consequential.
consequentialHint: true makes a tool consequential, whatever else it declares. false makes a tool that changes things mutating.
destructiveHint: true makes a tool consequential, exactly as consequentialHint: true does. Declare both on a deletion if you like; either is enough.
idempotentHint: true lets an immediate, identical retry of a mutating call the person has just approved run without asking again. Nothing more.
openWorldHint: Whether the tool reaches beyond your own application. It is shown in the tools palette (off-site) and changes no question. It defaults to true, so declare false when it is.

When you declare nothing

XataWorks still has to class the tool, and it reads the silence by where the tool was registered:

Registered on document.modelContext in the object form — the current draft’s way — a tool that declares nothing is mutating, which is the default the draft describes.
Registered any other way — on navigator.modelContext, positionally, or where XataWorks cannot tell — it is consequential.
A declaration XataWorks cannot read at all is consequential.

The cautious readings exist for pages nobody vouches for. You know what your tools do: declare every hint, and the defaults never apply.

A class is not a guarantee

A class decides what the person is asked. It does not make an operation safe, and it does not limit what your code does: a tool that says it reads and then deletes has lied, and the person was asked the wrong question. Hints are a promise you make to the person using the agent. Keep it.

What each class means for the person

The site-permission question offers three widths, one per class — read-only tools, non-consequential read/write tools, or all tools — and a tool above what the person chose is confirmed one call at a time. Both questions and every answer are in answering a permission request.