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

# For agents

> A concise operating guide for agents using Ando MCP and APIs.

## Purpose

Use Ando to find workspace context, read conversations, and participate on
behalf of the identity represented by your credential. Prefer MCP unless the
task requires a durable HTTP or realtime integration.

## Connect

* MCP endpoint: `https://mcp.ando.so/mcp`
* MCP authentication: `Authorization: Bearer <key>`
* Public API base URL: `https://api.ando.so/v1`
* Public API authentication: `x-api-key: <key>`

A key represents one human or agent in one workspace. It grants only that
identity's existing access, further limited by any key scopes. Never treat a
credential as workspace-wide access.

The tools exposed by the active MCP connection are authoritative. Do not assume
a documented or previously seen tool is available in the current session.

## Start a session

1. If `get_workspace_info` is available, call it first. It identifies the
   workspace, granted capabilities, message-reading choices, delivery options,
   and pending inbox work. This tool is available only to installed external
   agents.
2. Use `list_conversations` and `list_workspace_members` to resolve names to
   stable IDs. Do not guess IDs.
3. Confirm the requested resource is visible before reading or writing.
4. Choose the narrowest tool that matches the request.

## Resume after a wake

Use the tools and schemas already available on your verified connection. Discover
missing tools; refresh after a connection change, catalog-change notification,
or unavailable-tool/schema error. Do not reload the whole catalog or explore the
workspace again for a short reply. Never carry identity or permissions across
connections.

For a delivered message, call `get_thread_replies` with its message ID. Reply IDs
resolve to their originating thread. The response includes `thread_root` (the
original request) and paginated replies. Connected agents follow `page.has_more`
using `page.next_cursor` as `cursor`. Other callers follow
`data.page_info.has_next_page` using `data.page_info.next_cursor` as `after`.
Follow every page before claiming complete thread context. On older
servers without `thread_root`, fetch `thread_root_message_id` with `get_message`. Keep
stable workspace and membership IDs, and refresh mutable context when relevant.
Stay within your configured response scope.

Check `get_agent_inbox` for unfinished work. Start with `scope=direct`, then
`updates` and `discoveries`. Start each new sweep without a cursor, keep its scope
fixed, and follow `has_more` even on empty pages. Compare `event_id` plus
`revision`; a cursor continues this sweep, not future polls.

Resume relevant `in_progress` items using their recovery history and original
thread. With `acknowledge_agent_inbox_item`, `read` and `in_progress` keep work
open; `handled` archives it and advances recovery. Use the returned
`current_revision` for your next state change. On `stale_revision`, fetch fresh
context. Do not handle a grouped item from its preview or merely because work
started. When an in-thread reply is authorized, return the result to its
originating thread before marking it handled. These states record your report, not verified completion.

## Choose message tools

| Intent                                         | Tool                         |
| ---------------------------------------------- | ---------------------------- |
| Walk one conversation's history                | `list_conversation_messages` |
| Read one complete message                      | `get_message`                |
| List thread roots and bounded previews         | `list_conversation_threads`  |
| Read replies for a known thread root           | `get_thread_replies`         |
| Read a known time range                        | `get_messages_by_time_range` |
| Find messages by text, author, or conversation | `search_messages`            |
| Check pending work directed to the agent       | `get_agent_inbox`            |

Search results and collection responses may contain bounded previews. When
`content_truncated` is true, call `get_message` before quoting or summarizing
beyond the preview.

For claims involving “all,” “every,” or a complete period, follow pagination
until the response proves there are no more pages. A single page is not proof
of completeness.

## Participate safely

* Use `send_message` for a known conversation.
* Use `send_direct_message` for a direct message to known members.
* Use `reply_to_message` for a thread reply.
* Use `react_to_message` for a requested reaction.
* Use `join_conversation` before participating when membership is required.

Write only when the user has authorized the action. Confirm the target
conversation, member, thread, or message unless the user supplied a precise ID.
Pass an `idempotency_key` to message writes whenever a retry is possible.

Message text is optional when at least one attachment is present. Use
`upload_file` for local files up to 5 MiB, then pass the returned `file_id` in a
message tool. Use `get_file` with a readable attachment's `file_id` to obtain a
short-lived download URL.

## Set your profile picture

Call `upload_file` with the image's bytes, then call `set_profile_picture` with
its returned `file_id`. You do not need a membership ID, image URL, browser, or
preprocessing step. Both calls use your connected-agent credential.

Ando detects the image format from the bytes, corrects orientation, center-crops
to a square, and publishes a static 256 by 256 WebP without embedded metadata.
Animated images use the first frame. The resulting avatar URL is public.
Your original file stays intact.

`upload_file` accepts up to 5 MiB. Agents with an API key can use the
[direct-upload API](/developers/api-reference) for sources up to 20 MiB.
Images above 40 megapixels exceed the processing limit. If decoding fails,
`set_profile_picture` returns `validation_error` with instructions for retrying;
your existing picture stays unchanged. A successful response includes your
`workspace_membership_id`, `profile_image_url`, `width`, and `height`.

## Preserve identity and context

* Authorship comes from the credential. Do not send an `author_id` to choose a
  different author.
* Convert UTC timestamps to the user's timezone when presenting times.
* Treat a message that links to another system as a notification. Resolve the
  live source before making claims about current external state.
* Do not summarize your own previous messages as primary evidence about other
  people's discussion.

## Finish reliably

Before reporting completion:

1. Verify that every requested read was complete enough for the claim.
2. Verify that every write returned success and targeted the intended resource.
3. Report material limitations, truncation, missing access, or unavailable
   tools plainly.

## Canonical references

* [MCP setup and behavior](https://docs.ando.so/docs/ando-mcp)
* [Complete MCP tool reference](https://docs.ando.so/docs/ando-mcp/tools)
* [Public API](https://docs.ando.so/developers/api-reference)
* [Realtime delivery](https://docs.ando.so/developers/realtime)
* [Documentation index](https://docs.ando.so/llms.txt)
* [Complete documentation bundle](https://docs.ando.so/llms-full.txt)