> ## Documentation Index
> Fetch the complete documentation index at: https://docs.engini.io/llms.txt
> Use this file to discover all available pages before exploring further.

# For AI Agents

> How AI agents should discover, read, and operate Engini.

Engini is built to be operated by AI agents. This page is the entry point an agent (or its author) should read first.

## Discover these docs

* `https://docs.engini.io/llms.txt` - index of all pages
* `https://docs.engini.io/llms-full.txt` - the full docs in one file
* Append `.md` to any page URL for raw markdown
* **MCP docs server** - connect your MCP client to search these docs

## Operate the platform (REST)

1. Authenticate with `x-api-key` and verify with `GET /v1/auth/whoami` ([Authentication](/concepts/authentication)).
2. Discover: `GET /v1/applications?available=true`, then `GET /v1/tools?applicationSlug=...`.
3. Read the tool's contract before composing a call: `GET /v1/tools/{toolSlug}` returns `inputSchema`, `outputSchema`, and the `supportsFilters`/`supportsSort`/`supportsTopOffset` flags.
4. Execute: `POST /v1/tools/{toolSlug}/execute` with `{"fields": {...}}`. **Branch on `isSuccess`** - a `200` with `isSuccess: false` means the tool itself failed (`errorMessage` says why).
5. On errors, parse the [error envelope](/concepts/pagination-and-errors); on `429`, back off for `Retry-After` seconds.

Scope an agent's reach with a [toolset](/sdk/toolsets): it pins which connections are used and allow-lists the callable tools - pass its id as `?toolsetId=` on discovery and execution.

## Operate via the CLI

The CLI's [machine contract](/cli/machine-contract) is designed for agents:

* Stable exit codes (`3` = auth, `5` = a `need:*` gate, `124` = timeout).
* JSON automatically when piped; `--schema` for flag discovery; `--dry-run` for previews.
* `engini connect <app>` never blocks: each gate prints `{need, ..., resume}` where `resume` is the exact next command - ask your user for the missing value, run `resume`, repeat.
* Large results become handles; drill in with `engini tools result <handle> --select <path>` instead of re-fetching.

## LLM tool-calling (SDK)

The SDKs convert Engini tool schemas into OpenAI/Anthropic tool-calling formats and run the execution loop - see [LLM providers](/sdk/llm-providers) and [Toolsets](/sdk/toolsets):

```python theme={null}
toolset = client.toolset(connections={"salesforce": conn_id})
tools = toolset.tools()                      # vendor-shaped schemas
results = toolset.handle_tool_calls(reply)   # execute the model's calls
```