Tool capabilities

Atoti Intelligence Essentials

This is part of the Atoti Intelligence Essentials offer.

Every AI tool Atoti registers declares a capability that states the class of action it performs. Two properties decide whether a capability is active on a given deployment, without any change to the tool itself. One is a per-capability override. The other is a fallback for anything not listed. Two more properties together gate a small set of tools beyond their capability: a master switch, and a list naming which tools that switch applies to. The sections below cover each property and how they combine. The policy applies to the tools Atoti registers itself. These include discovery, validation, MDX query, the Auto-Explain run, find, and remove tools, chat history, and connected-servers tools. Every built-in Atoti AI tool available today is annotated read, except createCalculatedMember, deleteCalculatedMember, and updateCalculatedMember, which declare write. Two capability names carry meaning today, read and write.

Configuration reference

Property	What it controls	Default
`atoti.ai.tools.default-mode`	The fallback mode applied to a capability with no explicit entry in `atoti.ai.tools.capabilities`	`deny`
`atoti.ai.tools.capabilities`	A map from capability name to mode, `allow` or `deny`	`{read: allow}`
`atoti.ai.tools.extra-tools`	The list of tool names enabled under the experimental extra-tools mechanism, on top of their capability	`[]` (empty list)
`atoti.ai.tools.experimental`	The master switch for the whole extra-tools mechanism	`false`

How to configure the default mode

atoti.ai.tools.default-mode, available from Atoti Intelligence 6.2.2, sets the mode applied to a capability that has no explicit entry in atoti.ai.tools.capabilities. Accepted values are allow and deny, case-insensitive. The default is deny.

atoti:
  ai:
    tools:
      default-mode: deny

The default capabilities map already lists read explicitly, so raising default-mode to allow does not change read. It changes the fallback for write, and for any future capability that ships without an explicit entry. It never changes atoti.ai.tools.extra-tools or atoti.ai.tools.experimental. Both properties are separate, with their own defaults, and are not part of the capabilities map.

How to configure capabilities per tool

atoti.ai.tools.capabilities, available from Atoti Intelligence 6.2.2, maps a capability name to a mode, allow or deny. The default map is {read: allow}. read is explicitly allowed out of the box, and any unlisted capability, currently write, falls back to default-mode.

atoti:
  ai:
    tools:
      capabilities:
        write: allow

The snippet above allows write tools without changing default-mode or the existing read entry. Declaring one entry in capabilities does not remove the others. The entry is added to the default map instead of replacing it. An entry in capabilities always wins over default-mode, in both directions. Setting write: deny keeps write tools disabled even if default-mode is raised to allow. Setting write: allow enables write tools even while default-mode stays deny.

Capability names are plain strings. read and write are used by tools today. Each name is a key in the atoti.ai.tools.capabilities map. An environment variable reaches that map lower cased, with each underscore turned into a dot. A name with an uppercase letter or a hyphen could not be set from the environment, so capability names stay lower case and unpunctuated.

How to configure extra tools

atoti.ai.tools.extra-tools is experimental. Its name is the signal: the property itself, the list of tool names it accepts, and the behavior of each tool it gates may change or be removed in any release, including a patch. None of it is covered by the usual compatibility guarantees.

Two properties together gate a small set of tools beyond their capability. atoti.ai.tools.experimental, available from Atoti Intelligence 6.2.2, is a boolean switch for the whole extra-tools mechanism. Accepted values are true and false. The default is false. atoti.ai.tools.extra-tools, available from Atoti Intelligence 6.2.2, lists the tools to enable by name. An entry is the tool’s own name, exactly as the tool is named, for example createCalculatedMember. The default is an empty list. Entries are list values, not map keys, so they keep the tool’s own camel case. Both properties sit beside atoti.ai.tools.capabilities rather than inside it. atoti.ai.tools.default-mode never reaches either one: raising default-mode to allow does not turn any extra tool on.

Which tools can be named in extra-tools?

Tool name	Capability	What it does
`createCalculatedMember`	`write`	Creates a persisted calculated member on a cube from an MDX expression. The member is saved and available to every future query and widget until removed.
`deleteCalculatedMember`	`write`	Permanently removes a persisted calculated member from a cube. The member stops being available to every future query and every widget. Its parameters are the cube name and the member’s fully qualified MDX unique name. It fails if the member or the cube does not exist, or if the calling user cannot see that member. It also fails if another calculated member or KPI still depends on it. The error names the dependents, which must be removed first.
`retrieveOneCalculatedMember`	`read`	Returns the full definition of one calculated member on a cube: its MDX expression, caption, folder, and format string. Covers both the members saved on the Content Server and the members declared in the application’s cube configuration. Its parameters are the cube name and the member’s exact unique MDX name. It fails if the member or the cube does not exist, or if the calling user is not allowed to see that member.
`updateCalculatedMember`	`write`	Updates a persisted calculated member of a cube in place, keeping its unique name and the users it is shared with. Its parameters are the cube name, the member’s fully qualified MDX unique name, and the optional new MDX expression, caption, folder, and format string. Only the fields passed are changed, the others keep their current value. A field cannot be cleared this way, and the unique name cannot be changed: delete the member and create a new one for that. It fails if there is no persisted calculated member under that name on that cube, including when the member is only declared in the application’s cube configuration, or if the calling user cannot see it. Unlike `deleteCalculatedMember`, it is not blocked when another calculated member or KPI depends on the member.

This is the complete list of extra tools today. Naming any other tool in extra-tools has no effect.

How to enable the extra tools

createCalculatedMember declares the write capability. Enabling it takes three settings together: allowing write, turning on experimental, and naming the tool in extra-tools. deleteCalculatedMember and updateCalculatedMember, both available from Atoti Intelligence 6.2.2, also declare write and are enabled the same way. retrieveOneCalculatedMember, available from Atoti Intelligence 6.2.2, goes through the same three gates with read in place of write; read is allowed by default, so it needs only experimental: true and its name in extra-tools.

atoti:
  ai:
    tools:
      capabilities:
        write: allow
      experimental: true
      extra-tools:
        - createCalculatedMember
        - deleteCalculatedMember
        - retrieveOneCalculatedMember
        - updateCalculatedMember

The equivalent environment variables for the experimental switch and the tool list are ATOTI_AI_TOOLS_EXPERIMENTAL and ATOTI_AI_TOOLS_EXTRA_TOOLS. Several tool names are comma-separated:

ATOTI_AI_TOOLS_EXPERIMENTAL=true
ATOTI_AI_TOOLS_EXTRA_TOOLS=createCalculatedMember,deleteCalculatedMember,retrieveOneCalculatedMember,updateCalculatedMember

Naming no extra tool is a deliberate choice, and never an error: the default empty list simply offers nothing extra. Naming a tool whose other gates stay shut is a configuration mistake. Atoti refuses to start rather than silently withholding a tool that was explicitly asked for. The following table shows every combination for a write extra tool, using createCalculatedMember as the example. The same four outcomes apply identically to deleteCalculatedMember and updateCalculatedMember.

`extra-tools`	`experimental`	`capabilities.write`	Outcome
empty (default)	any	`allow`	Starts normally, tool not offered
`[createCalculatedMember]`	`false` (default)	any	Startup fails, error names `atoti.ai.tools.experimental`
`[createCalculatedMember]`	`true`	`deny` (default)	Startup fails, error names `atoti.ai.tools.capabilities.write`
`[createCalculatedMember]`	`true`	`allow`	Tool available

Setting capabilities.write: allow on its own no longer fails startup, and does not by itself enable createCalculatedMember, deleteCalculatedMember, or updateCalculatedMember. It only takes effect once the tool is also named in extra-tools and experimental is true.

What is the default behavior out of the box?

With no configuration, read tools are allowed and write tools are denied. Every built-in Atoti AI tool available today is annotated read, except createCalculatedMember, deleteCalculatedMember, and updateCalculatedMember, which declare write. With extra-tools empty and experimental false by default, none of createCalculatedMember, deleteCalculatedMember, retrieveOneCalculatedMember, or updateCalculatedMember is offered, regardless of the read or write setting. This changes nothing about the tools available before this feature. It matters once a write tool ships, or once createCalculatedMember, deleteCalculatedMember, retrieveOneCalculatedMember, or updateCalculatedMember needs to be enabled.

How to allow write tools

To allow write tools without changing any other capability, set only the capabilities entry:

atoti:
  ai:
    tools:
      capabilities:
        write: allow

How to change the fallback for unlisted capabilities

To flip the fallback applied to every unlisted capability, set default-mode to allow:

atoti:
  ai:
    tools:
      default-mode: allow

This also allows write, since it has no explicit entry in the default capabilities map. To keep write denied while raising the fallback for future capabilities, add an explicit write: deny entry alongside it. Raising default-mode does not by itself enable a write extra tool such as createCalculatedMember, deleteCalculatedMember, or updateCalculatedMember. Each tool also requires experimental: true and its own name in extra-tools; see How to enable the extra tools.

Retries and timeouts bounds how long and how often a prompt calls tools.

Introduction to Atoti Intelligence

Releases and Upgrades

User Guide

Developer Guide

Atoti Intelligence Essentials

Configuration reference

How to configure the default mode

How to configure capabilities per tool

How to configure extra tools

Which tools can be named in extra-tools?

How to enable the extra tools

What is the default behavior out of the box?

How to allow write tools

How to change the fallback for unlisted capabilities

​Atoti Intelligence Essentials

​Configuration reference

​How to configure the default mode

​How to configure capabilities per tool

​How to configure extra tools

​Which tools can be named in extra-tools?

​How to enable the extra tools

​What is the default behavior out of the box?

​How to allow write tools

​How to change the fallback for unlisted capabilities

​Related reading

Atoti Intelligence Essentials

Configuration reference

How to configure the default mode

How to configure capabilities per tool

How to configure extra tools

Which tools can be named in extra-tools?

How to enable the extra tools

What is the default behavior out of the box?

How to allow write tools

How to change the fallback for unlisted capabilities

Related reading