---
title: "Tools"
description: "Invantive MCP Server offers the following tools to an AI client such as Anthropic Claude."
language: en
source_language: en
translation_state: complete
canonical: https://documentation.invantive.eu/en/docs/invantive-mcp-server/tools
original: https://documentation.invantive.eu/en/docs/invantive-mcp-server/tools
updated: 2026-11-06T00:00:00Z
license: https://documentation.invantive.eu/en/
---

Invantive MCP Server offers the following tools to an AI client such as Anthropic Claude. The tools on a database only read: they change no data and run no SQL statement. Only `check_sql` accepts one, which it parses without running it. The status tools work on a status page of Invantive Cloud Status instead of a database; four of them change the status page.
- `describe_entities`: lists the entities that can be read from the database, with their name, label, type, data container and the order of magnitude of their number of rows. Available from release 26.0. See below.
- `describe_entity`: describes one entity in full, with its fields, primary key, unique keys, foreign keys and the speed to expect. Available from release 27.0. See below.
- `read_records`: reads rows from one entity, with a select, filter, sort and number of rows in the notation of the OData version 4 query interface. Available from release 26.0. See below.
- `analyze_records`: runs the same read as `read_records` and returns how it was executed instead of the rows. Available from release 28.0. See below.
- `current_cloud_user`: returns the profile of the signed-in user and of the organisation of that user, as held in Invantive Cloud. Available from release 26.0. See below.
- `check_sql`: checks the syntax of Invantive UniversalSQL and PSQL statements without running them. Available from release 28.0. See below.
- `status_get_summary`: returns the state of the status page at a glance. See below.
- `status_list_incidents`: lists the incidents of the status page, newest first. See below.
- `status_get_incident`: returns one incident with its components and updates. See below.
- `status_create_incident`: opens an incident on the status page. See below.
- `status_add_update`: posts an update on an incident, which can resolve it. See below.
- `status_set_component_state`: sets the state of one component. See below.
- `status_schedule_maintenance`: plans maintenance with a window. See below.

## Instructions to the Client
When an AI client connects, the server sends it instructions. They name the version of the server and the addresses at which the same database is available for other clients, with whether the user activated each address: Invantive MCP Server, the SQL Server protocol of Invantive UniversalSQL Server for SQL Server clients and ODBC, Bridge Online for Power BI and App Online for applications, both over OData version 4. They also give advice on reading efficiently, name the rate limits of the platforms and point to Invantive Data Hub.

The instructions state as well that Invantive Cloud can exchange data between the database and other platforms, by replicating, combining or integrating it. They list the commercial names of those platforms, such as Exact Online, Salesforce and AFAS Profit. The list holds the platforms for which Invantive Cloud has a driver. Test drivers, helpers, obsolete drivers and the own products of Invantive are left out. The list is available from release 27.0.

## Listing Entities
`describe_entities` lists the entities of the database that can be read, so that an AI client can choose one. It does not describe an entity in full: `describe_entity` does that for one entity. The tool takes two arguments, both optional:
- `entities`: the names of the entities to list. A name is matched without regard to case and must be written as an earlier answer returned it. A single name or a comma-separated list is accepted in place of an array.
- `nameOnly`: when true, every entity is reduced to its name, label, type and data container. Use it only when the answer was truncated. Default is false.

The answer holds:
- `database`: the URL segment of the database.
- `detailLevel`: `summary`, or `namesOnly` when `nameOnly` applied.
- `entityCount` and `returnedEntityCount`: the number of entities that match the request and the number of entities in the answer.
- `truncated` and `truncationHint`: present when the answer holds fewer entities than match. The hint explains how to ask a narrower question, by naming the entities of interest in `entities`.
- `unknownEntities` and `unknownEntitiesHint`: present when `entities` holds a name which does not exist. The hint names the closest existing entities for at most the first five unknown names. `unknownEntitiesHint` is available from release 27.0.
- `dataContainers`: one object per data container, since partitioning belongs to the data container and not to the entity. It holds the `alias` which an entity name carries after the `@`, the `provider` which serves the data container and whether it `supportsPartitions`. A data container which supports partitions also holds `partitionLabelPlural`, `partitionCount`, `selectedPartitionCount` and `allPartitionsSelected`: the term the platform uses for several partitions, such as divisions on Exact Online, the number of partitions available, the number a call of `read_records` queries and whether that is all of them.
- `partitioningNote`: how partitioning relates to the entities of this database. Present when at least one data container supports partitions.
- `selectedPartitionCountTotal`: the number of selected partitions over all data containers.
- `entities`: one object per entity, ordered by data container and then by name, so that a truncated answer leaves out the same entities on every call.

An entity holds:
- `name`: the name to pass in the `entity` argument of `read_records` and `describe_entity`.
- `label`: the label the platform uses for the contents. Present only when it differs from `name`.
- `type`: the kind of object, such as `table`, `view` or `tablefunction`.
- `dataContainer`: the alias of the data container which holds the entity.
- `rowCountBand`: the order of magnitude of the number of rows, when the platform provides an estimate. The value is `empty`, `<=100`, `<=1k`, `<=10k`, `<=100k`, `<=1M` or `>1M`.
- `notReadable`: true when the entity cannot be read. Absent otherwise.

The members `rowCountBand` and `notReadable` are left out when `nameOnly` applied.

Up to and including release 26.0 every entity also held `description`, `keyField` and `partitionSpecific`, and a data container held the whole partitioning: the terms, the partition column and the selected partitions. From release 27.0 these are in the answer of `describe_entity`. That keeps the list short and fast on a database with over a thousand entities.

The size of the answer is limited to 60,000 characters by default. The setting `MaxDescribeEntitiesResponseChars` changes that limit. It is available from release 26.0. The setting `MaxEntityDescriptionChars` is not used from release 27.0, since the list holds no descriptions.

The following arguments list two entities of the database:

```json
{ "entities": [ "SalesInvoices", "Accounts" ] }
```

## Describing an Entity
`describe_entity` describes one entity in full. An AI client calls it with a name from `describe_entities`, before it reads the entity with `read_records`. It is available from release 27.0. The tool takes one argument:
- `entity`: the name of the entity, as `describe_entities` returns it. A name is matched without regard to case. Required.

A name which does not exist is refused with message code `itgenmcp665`. The hint names the closest existing entities.

The answer holds:
- `database`: the URL segment of the database.
- `name`, `label`, `labelSingular`, `type` and `dataContainer`: as in the list. `label` and `labelSingular` are present only when they differ from `name`.
- `description`: what the entity holds, written for a business user and in full. `documentation` is a further explanation, when the platform gives one.
- `partitionSpecific`: true when the contents depend on the selected partitions. Absent otherwise.
- `notReadable`: true when the entity cannot be read. Absent otherwise.
- `rowCountBand` and `estimatedRowCount`: the order of magnitude of the number of rows and the estimate itself, when the platform provides one. An estimate is not a count.
- `performance`: what to expect of the speed of reading the entity.
- `primaryKey`, `uniqueKeys` and `foreignKeys`: the keys and the relations to other entities.
- `dataContainerDetails` and `partitioningNote`: the data container which holds the entity and how partitioning relates to the entity.
- `fieldCount`, `returnedFieldCount`, `truncated` and `truncationHint`: the number of fields, the number in the answer and, when fields are left out, what to do about it.
- `fields`: the fields of the entity.

A field holds:
- `name`: the name as the `select`, `filter` and `orderby` arguments of `read_records` accept it.
- `label`: the label the platform uses. Present only when it differs from `name`.
- `dataType`: the OData version 4 primitive type, such as `String`, `Int32`, `Decimal`, `DateTimeOffset`, `Boolean` or `Guid`.
- `nullable`: whether the field can be empty.
- `maxLength`, `precision` and `scale`: the length of a text or binary field and the digits of a decimal field, when the platform states them.
- `primaryKey`: true when the field is part of the primary key. Absent otherwise.
- `description`: what the field holds, written for a business user.
- `filterOnPlatform`: true when the platform itself evaluates a filter on the field, so that only the matching rows are fetched. False when every row is fetched first and filtered afterwards, which is slow on a large entity.
- `sortOnPlatform`: true when the platform itself sorts on the field. Absent when that is not known.

The members `uniqueKeys` and `foreignKeys`, and the `guarantee` of a key, are available from release 28.0. Release 27.0 answers the primary key without a guarantee, since its engine holds no other key metadata.

A key holds `fields`, `guarantee` and, when the platform gives one, `name`. The guarantee is `enforced` when the platform itself keeps the key unique and `declared` when the driver or the model states it without the platform enforcing it. The fields of a key are named as the fields of the entity. A name which is no field of the entity is written as the platform names the column. A key which repeats the primary key is not listed in `uniqueKeys`.

A foreign key is a relation from fields of this entity to the key of another entity. It holds:
- `fields`: the fields of this entity which hold the reference.
- `referencedEntity` and `referencedFields`: the entity referred to, as `describe_entities` names it, and its fields, in the same order as `fields`.
- `referencedTable`: the name the platform gives the object referred to. Present only when that object is no entity of this database, in which case `referencedFields` holds the column names of the platform.
- `kind`: `key` when the fields refer to a key of the referenced entity, `textual` when the relation exists in words only and holds under a condition, and `candidate` when it follows from the names of the fields and holds in the data without the platform stating it.
- `guarantee`: `enforced` or `declared`, as for a key.
- `description`: says when a `textual` or `candidate` relation holds. A relation of these kinds does not hold for every row.
- `name`: the name of the foreign key on the platform, when it has one.

This server reads one entity per call and does not join. An AI client reads the related rows with a second call of `read_records`, filtering on the values of `fields`.

The performance holds the following members, when the driver of the platform states them:
- `accessLatencyMs`: the average time of one round trip to the platform in milliseconds.
- `fullScanRowsPerMinute`: the average number of rows per minute when the whole entity is read.
- `pointQueryRowsPerMinute`: the average number of rows per minute when rows are read by a filter on a key.
- `estimatedFullScanSeconds`: an estimate of the time to read every row of the entity, from `estimatedRowCount` and `fullScanRowsPerMinute`. It is present only when both are known.

The figures are static averages of the driver for the platform and not measurements of this database. The figure for writing is not returned, since the server only reads. A driver which states no figures leaves `performance` out.

The size of the answer is limited to 60,000 characters by default. The setting `MaxDescribeEntityResponseChars` changes that limit and `MaxSelectedPartitionsDescribed` the number of partitions listed in `dataContainerDetails`. Both are available from release 27.0 and 26.0 respectively. When the fields do not fit, the fields of the keys come first. The keys, the relations and the performance are never left out.

The following arguments describe one entity of the database:

```json
{ "entity": "SalesInvoices" }
```

## Reading Records
`read_records` reads rows from one entity. An AI client calls it once `describe_entities` has shown which entity holds the data and `describe_entity` has listed its fields. The tool takes the following arguments:
- `entity`: the name of the entity, as `describe_entities` returns it. Required.
- `select`: a comma-separated list of field names, as `describe_entity` returns them, in the `$select` notation of the OData version 4 query interface.
- `filter`: the condition the rows must meet, in the `$filter` notation, with the operators `eq`, `ne`, `gt`, `ge`, `lt`, `le`, `and`, `or` and `not`.
- `orderby`: a list of fields with a direction, in the `$orderby` notation, such as `AmountDC desc`.
- `first`: the maximum number of rows to read. When omitted, every row which matches the filter is read.

The read is translated into a `select` statement and executed under the authorisation of the signed-in user. The rows come back as structured content, one object per row with the selected fields. There is no cursor and no paging. An AI client passes `first` unless it wants the whole set, and narrows the answer with `filter` and `orderby`.

A field or literal which the OData parser does not know is refused with message code `itgenmcp640`. When the refusal is about a field, the hint names the fields of the entity which come closest. Dates and numbers are written without quotes.

The following arguments read the five largest open invoices of an entity:

```json
{ "entity": "SalesInvoices"
, "select": "InvoiceNumber,AmountDC"
, "filter": "Status eq 20"
, "orderby": [ "AmountDC desc" ]
, "first": 5
}
```

## Analysing a Read
`analyze_records` takes the arguments of `read_records`: `entity`, which is required, and `select`, `filter`, `orderby` and `first`. The read is translated into the same `select` statement, executed under the same authorisation and recorded in the same way. Its rows are read and counted, but not returned. The answer holds:
- `sqlStatement`: the `select` statement that was executed.
- `rowsReturned` and `rowsRead`: the rows the statement returned and the rows it read from all tables.
- `counters`: what the statement counted, summed over all steps, such as `PairsEvaluated` or `RowsSorted`; only the counters which are not zero.
- `steps`: one object per step of the execution, such as the read of a table, a join or a sort, with the same members as a line of the `/steps` file of [[Invantive Data Hub/Command Line Options|Invantive Data Hub]]: the kind and description of the step, the rows in and out, the duration, processor time and allocation including the steps below, the same figures without the steps below as [[Invantive UniversalSQL/Grammar/Statement Types/Explain Statement (explainStatement)|explain analyze]] measures them, how a join matched its rows, the number of rows a table declares, and the counters of the step itself. The members of a step are written as on that line, starting with a capital, such as `ExclusiveCpuMs`.

An AI client calls it when a read is slow or reads more rows than it returns, for instance to see whether a filter was handed to the data container, which join algorithm was chosen, or which step allocated the memory. Measuring every step costs a reading of the processor time per row per step, which only this tool pays.

The following arguments analyse the read of the five largest open invoices of an entity, with the same arguments `read_records` would take:

```json
{ "entity": "SalesInvoices"
, "select": "InvoiceNumber,AmountDC"
, "filter": "Status eq 20"
, "orderby": [ "AmountDC desc" ]
, "first": 5
}
```

## Reading the Current User
`current_cloud_user` returns the profile of the signed-in user and of the organisation of that user, as held in Invantive Cloud. An AI client calls it when the answer depends on who asks or on which organisation the data belongs to. The tool takes no arguments and reads nothing from the database.

The answer holds the following members of the user:
- `Uid`, `Iwid` and `CognitoUserId`: the identifiers of the user, of the web user and in the identity provider.
- `Name`, `GivenName` and `FamilyName`: the full name, the first name and the last name.
- `Gender`: `M` for male, `F` for female and `U` for unknown.
- `JobTitle`: the job title.
- `EmailAddress`, `PhoneNumber` and `MobileNumber`: how to reach the user.
- `LanguageCode`: the language in ISO 639-1 format. The default language of the service is used when the user has none.
- `CreatedUtc` and `ModifiedUtc`: when the user was created and last modified.
- `LogInStartUtc` and `LogInEndUtc`: the period in which the user can log on.
- `UserIconUrl` and `UserIcon`: the thumbnail of the user as an address and in binary form.

The answer holds the following members of the organisation of the user:
- `PartyName`: the name of the organisation. The name in the profile of the user is used first, and the name held by the organisation itself when the profile has none. The fallback is available from release 27.0.
- `PartyAddressLine1`, `PartyAddressLine2`, `PartyAddressLine3`, `PartyPostalCode`, `PartyCity` and `PartyCountry`: the address. The country of the organisation is used first, and the country in the profile of the user when the organisation holds none. The fallback is available from release 27.0.
- `PartyEmailAddress`, `PartyPhone` and `PartyWebSite`: how to reach the organisation.
- `PartyLegalStructure`: the legal structure, such as `NL-BV`.
- `PartyCoCNumber`, `PartyVatNumber`, `PartyIban` and `PartyBic`: the Chamber of Commerce number, the VAT number, the IBAN and the BIC.

The members `PartyCurrencyCode`, `PartyState`, `PartyGlnNumber`, `PartyRsinNumber`, `PartySiretNumber`, `PartyPaypalIdentifier` and `PartyWageTaxNumber` are part of the answer, but the service does not fill them. Invantive Cloud holds no value for them.

## Checking the Syntax of SQL
`check_sql` parses one or more Invantive UniversalSQL and PSQL statements, separated by `;`, without running them and without reading the database. An AI client calls it on a statement it wrote for Invantive Data Hub, Invantive Query Tool or a script, before the statement costs a budget or changes data. Names of tables and columns are not checked, since that needs the database. Available from release 28.0.

The tool takes one argument, `sql`, with at most 1,000,000 characters. The answer holds:
- `Valid`: `true` when the statements follow the grammar.
- `MessageCode`, `Message` and `Hint`: the syntax error, its message with an excerpt and carets, and what to do. The codes are explained in [[Syntax Errors]].
- `Url`: the address of the section of the message code in [[Syntax Errors]].
- `Position`: `Line` and `Column`, counted from 1 with a tab as one column, `Offset`, counted from 0 in the text, and `Length`, the number of characters marked.
- `Syntax`: `Kind` such as `missing` or `premature-end`, `Expected` with what is valid at the position as a list of untranslated items such as `FROM`, `,`, `name` or `expression`, and `Context` with the part of the statement such as `whereClause`.

A syntax error is the answer of the tool and not a failure of it: the result is not marked as an error.

## Tools on Invantive Cloud Status
The status tools let an AI client read and maintain a status page of Invantive Cloud Status, for instance to answer whether a service is down or to report an outage. They are offered only on a server where the settings `StatusPage:Server` and `StatusPage:ApiToken` are set: the address of the status server, such as `https://statuspage.invantive.eu`, and an API token of one tenant, created under "Settings" and "API tokens". `StatusPage:TimeoutSec` sets the number of seconds a call may take, with a default of 20. The tools are not released yet.

The tools work on the pages of the tenant of the token. A token of scope read is enough for the three tools that read. The four tools that change the status page need a token of scope write; with a token of scope read the status server refuses them. A change is visible to readers at once and can notify subscribers, so the AI client is told to confirm the text with the user before calling.

The states of a component are `operational`, `degraded_performance`, `partial_outage`, `major_outage` and `under_maintenance`. The phases of an incident are `investigating`, `identified`, `monitoring` and `resolved`.

`status_get_summary` takes no arguments. The answer holds:
- `overallState`: the most severe state over the components that count for the overall state.
- `componentCount`: the number of components.
- `componentsNotOperational`: per component that is not operational its `component` code, `name`, `state` and the moment `since` which it holds that state.
- `openIncidents`: per incident that is not resolved its `publicId`, `title`, `phase`, `impact` and `startedAt`.
- `maintenance`: the maintenance in progress or planned within seven days, with `publicId`, `title`, `phase`, `windowStart` and `windowEnd`.

`status_list_incidents` takes two optional arguments:
- `openOnly`: when true, only incidents that are not resolved. Default is false.
- `first`: the number of the newest incidents to return, from 1 to 100. Default is 20.

The answer holds `incidents`, with the same members per incident as `openIncidents` of `status_get_summary`.

`status_get_incident` takes the `publicId` of an incident, such as `2026-0187`. The answer is the incident as the management API of the status server returns it, with its affected components and their state, its timeline of updates with their phase and its version.

`status_create_incident` takes:
- `title`: the title readers see. Required.
- `message`: the first update, for customers.
- `impact`: one of `none`, `minor`, `major` or `critical`. Default is `minor`.
- `phase`: the phase of the first update. Default is `investigating`.
- `template`: the code of an incident template, which fills what is not given.
- `components`: the affected components, each with its `component` code and the `state` it gets while the incident is open.

`status_add_update` takes:
- `publicId`: the public id of the incident. Required.
- `message`: the text of the update, for customers. Required.
- `phase`: the phase of the update. Required. The phase `resolved` closes the incident and returns its components to operational.
- `internalNote`: a note for operators only, which is never published or sent.

`status_set_component_state` takes:
- `component`: the code of the component, as `status_get_summary` returns it. Required.
- `state`: the new state. Required.
- `hold`: when true, the probes do not change the state until an operator releases it. Default is true.

`status_schedule_maintenance` takes:
- `title`: the title readers see. Required.
- `message`: what happens and what readers notice. Required.
- `windowStart` and `windowEnd`: the start and end of the window as an ISO 8601 date and time with offset, such as `2026-11-08T06:00:00+01:00`. Required.
- `components`: the codes of the affected components.
- `autoStart`: start the maintenance at the start of the window. Default is true.
- `autoComplete`: complete the maintenance at the end of the window. Default is true.
- `muteProbes`: mute the probes of the affected components during the window. Default is true.

The tools that change the status page return the incident, the component or the maintenance as the status server returns it after the change.

## Tracing the Size of an Answer
Invantive MCP Server writes the size of every answer to the trace in characters. The size is the quantity of the trace line with message code `itgenmcp664`, which is written at the debug level. It adds up the structured content and the text blocks of the answer, and the message names the tool, the database and both parts. The line is written for an answer which succeeded and for one which failed, since the AI client reads both in its context. The envelope of the JSON-RPC message is not counted. Available from release 27.0.

## When a Tool Fails
A tool which fails answers with `isError` set and the details in the structured content, so that the AI client can tell the user what to do. The answer holds:
- `Message` and `MessageCode`: what went wrong, and the code to quote when asking for help.
- `KindRequest`: the hint, which is the next step for the AI client or the user. Every answer has one. When no specific hint is known, it says whether to send the request again, to correct it or to tell the user.
- `NaturalKey`: what the message is about, such as the database or the entity asked for.
- `IsRecoverable`: true when sending the same request again later can succeed and false when it cannot. It is left out when nothing indicates either.
- `RetryAfterSec`: the number of seconds the service advised to wait before the same request is sent again, from a lock-out or from the `Retry-After` header of the platform. It is present only when `IsRecoverable` is true and a wait was advised; no wait is made up. When the wait is longer than 60 seconds, the hint tells the AI client to leave the wait to the user. Available from release 27.0.
- `Actor`: who has to act first. `ai` when the AI client can correct the request or wait and send it again, `user` when a person has to decide or act outside the conversation, such as on a licence, an IP address or a log-on, and `forums` when nobody can solve it in the conversation, so that the reference and message code are looked up or reported at the forums. A wait of more than 60 seconds is for the user. Available from release 27.0.
- `HelpUrl`: the address of the forum topic or help page about the message code, when one is known. Available from release 27.0.
- `Uid`: the reference of the failure, to quote to support.

A request for an entity or a field which does not exist names the closest existing names in the hint. `describe_entities` does the same for the names in its `entities` argument, in `unknownEntitiesHint`. Both are available from release 27.0.

A request from an IP address which is not authorised for the database is refused with message code `itgenmcp326`. The message names the address and the hint names the database to which it must be added.

A status tool which fails answers in the same way. When the status server refuses the call, `MessageCode` holds the message code of the status server, or `itgenmst001` when the answer holds none. A refusal for lack of scope write tells the user to ask for a token of scope write. `itgenmst002` means that the status tools are not configured on the server, and `itgenmst003` that the status server cannot be reached.

## Release Notes

- [Invantive MCP Server](/en/release-notes/products/invantive-mcp-server)
  - [26.0 to 27.0](/en/release-notes/products/invantive-mcp-server?step=26.0-to-27.0)

