Tools and limits · Documentation

When an AI tool connects, SAPUGO tells it which tools it may use. The list depends on the scopes you gave the application and on whether your organization has advanced AI tool access. A tool that isn't offered can't be called.

You don't need to learn these names to use a connection. The AI tool picks the right one from your request. They are listed here so you can see exactly what a scope opens up, and read the activity list with confidence.

Standard access#

These tools are available to every connection. All of them follow the application's access rules: hidden columns can't be read or written, and rows outside a view's filter can't be reached.

Tool	What it does	Scope
`list_dataviews`	Lists the views the application can read.	Read records and history
`get_dataview`	Shows a view's columns, their types and which are hidden.	Read records and history
`query_dataview`	Finds records with filters, sorting, search and paging.	Read records and history
`list_comments`	Reads the comments on a record.	Read records and history
`list_activity`	Reads the change history of a record.	Read records and history
`create_row`	Creates a record.	Create and change records
`update_row`	Changes a record.	Create and change records
`delete_row`	Deletes a record. It can be restored from the trash with advanced access.	Create and change records
`add_comment`	Adds a comment to a record.	Create and change records

Advanced access#

With advanced AI tool access, the same scopes open more tools, and the remaining scopes become available.

Scope	Tools
Read records and history	Tables and schemas, databases, the current user, totals over a view with `aggregate_dataview`, record layouts and buttons, business rules and their logs, navigation, dashboards and widgets, pages, document templates, users, groups and permissions, effective access rules, workflows and their runs, files on records, the trash, the status of a change request, and, for organizations that use forms, forms with their versions, links and submissions.
Create and change records	Create or update many records at once with `create_rows` and `update_rows`, restore a record or a trash item, attach files, create a document from a template, and edit page content.
Change the structure	Create, change and delete tables and columns, convert a column to another type, create and change views, record layouts and buttons, folders and apps, business rules, dashboards and widgets, pages, and document templates and their components. For organizations that use forms: build and change forms, and close a form or one of its links. Publishing a form and creating a link that opens it to other people always wait for a person to approve.
Create and change workflows	`create_workflow`, `update_workflow` and `delete_workflow`.
Run workflows and buttons	`trigger_workflow`, `run_entry_button` and `cancel_workflow_run`.
Decide approval requests	`list_pending_approvals` and `decide_approval`, for requests assigned to this application.
Use the assistant	`assistant`: a conversation with the SAPUGO assistant.

Not every tool is shown to the AI tool up front. To keep its working memory free, a connection lists the everyday tools and adds find_tools and call_tool. The tool searches the rest by what it wants to do, then runs the one it found. Every check applies exactly as if it had called the tool directly.

Use the assistant#

With Use the assistant, the AI tool can describe a job in plain words, such as "add a status column to orders and a workflow that emails the customer when it changes", and the SAPUGO assistant does the work, one conversation turn at a time. If the assistant needs an answer, it asks, and the tool answers in the next turn. The assistant works only within the application's scopes. If the application can't change anything, the assistant can only look.

Guides the tool can read#

Along with the tools, a connection offers short guides that the AI tool can read when it needs them.

Guide	Contents	Needs
`sapugo://guides/filters`	Filter methods for each column type, and how filter groups combine.	Read scope
`sapugo://guides/columns`	Column types, their options and value shapes.	Change the structure
`sapugo://guides/formulas`	How to write and check a formula column.	Change the structure
`sapugo://guides/workflows`	The workflow language, its steps and examples.	Create and change workflows

Limits#

Limit	Value
Reads per key	120 per minute
Writes and structure changes per key	30 per minute
Assistant turns per key	6 per minute
Records returned by one query	Up to 100. The default is 50.
Size of one result	About 100,000 characters. Larger results are cut and marked as truncated.
Records created or updated in one call without confirmation	50

Limits are counted per key, so one busy tool doesn't use up what another one needs. Your organization's overall request limit also applies. A tool that goes over a limit is told how many seconds to wait. Semantic search isn't available through a connection. Use filters and text search instead.

Repeating a call safely#

Tools that create things accept an optional idempotency_key, 8 to 128 letters, digits, dashes or underscores. If a call times out and the tool repeats it with the same key, it gets the first answer back, and nothing is created twice.

Messages you may see#

An AI tool shows these as short reasons. Most explain themselves, and the tool usually corrects itself.

Message	Meaning
`mcp_not_available`	Your plan doesn't include AI tool access.
`database_not_allowed`	The application isn't allowed to use that database.
`insufficient_scope`	The application doesn't have the scope this tool needs.
`insufficient_permission`	The application lacks the organization permission this step needs.
`confirmation_required`	The step can't be undone. The tool must repeat it with confirmation.
`pending_approval`	A person has to approve the step. The tool gets a `request_id` to check later.
`preparing_backup`	A backup is being taken first. The tool repeats the call shortly.
`rate_limited`	A limit was reached. The reply says how long to wait.
`invalid_api_key`	The key is wrong, revoked or expired, its application is disabled, or it is used from an address that isn't allowed.

Connect AI toolsCreate an application and connect your first tool.Control what a tool may doScopes, approvals and the activity list.