# Getting started

The mandatory path for agents that work with Adlass over MCP or the REST API.
MCP tool names come first, the REST equivalent (under `/api/v1/operations/`)
follows in parentheses.

## Steps

1. `get_context` (`GET context/`) once per session. It lists your Spaces, the
   connected integrations, the available guides and the steps to take before
   the first write.
2. `read_guide("getting_started")` (`GET guides/getting_started/`): this
   guide.
3. `read_guide(<domain>)` (`GET guides/<domain>/`) before the first write in a
   domain, for example `records`, `skills`, `scripts`, `workflows`. Every
   operation names its guide in `guide`.
4. `search_operations` (`GET ?q=&domain=&provider=`) to find the operation.
   Narrow with `domain` or `provider`; the result is capped, and
   `truncated: true` means you must narrow further.
5. `describe_operation` (`GET <key>/`) before the first invoke of every
   operation. Follow its input schema, `constraints`, `examples` and `guide`;
   the schema alone does not carry every rule.
6. `invoke` (`POST <key>/invoke/`) with the arguments.

## Rules

1. Prefer `*_many` operations over repeated single calls when you change
   several entities.
2. Every write operation needs an `idempotency_key`. Reuse the same key to
   retry the same write safely; use a new key only for a new action.
3. On `validation_error`, read the paths in `details`, fix exactly those
   arguments, and check `describe_operation` again before retrying.
4. On `truncated: true`, narrow the request (filters, pagination, fewer
   fields) as `result_hint` describes instead of repeating the same call.
5. Publishing operations such as `records.types.publish` and `skills.save`
   are allowed for agents.
6. Operations with `access` set to `human` or `human_approval` are reserved
   for people in the Adlass app. Do not call them; tell the user what to do
   there instead.
7. Use `report_feedback` (`POST feedback/`) when an operation is missing, a
   contract is unclear or an error leaves you without a way forward.