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

# Work recommendations

> Read actor suggestions and inspect current work through the API, CLI, and MCP.

`GET /api/orgs/{id}/work-recommendations` accepts optional `actor_id`
(member UUID, defaults to the caller), `project_id`, `limit` (1–5, default 5),
and `cursor`. Machines can read only their own recommendations. A human can
inspect self, a manageable agent, or another human with shared write access.
All issue and strategy evidence uses the intersection of caller and target
permissions. Missing and forbidden targets both return `404`.

The read evaluates the complete bounded authorized project scope before global
ranking. It scans at most 1,000 source issues, 250 scope rows, 200 queries,
25,000 related physical rows, and 4,000 execution or assignment rows per
category. Any exceeded ceiling returns `422 WORK_RECOMMENDATIONS_EVIDENCE_LIMIT`
with no partial ranking. Current work is displayed separately, capped at 20
with `current_work_truncated`. Occupation checks remain complete.

Any `assigned`, `running`, `waiting`, or `needs_human` execution for the target
suppresses all new-work suggestions across the organization, including work
outside the project filter and projectless work. Occupation uses immutable
execution actor identity and current issue ownership. Hidden occupation yields
only the generic `availability_not_established` caveat, with no hidden work
identity, title, state, count, or timestamp. Authorized waiting and attention
work has inspection actions. Failure inspection uses newest created-at/UUID
display chronology across actors; it does not establish retry supersession or
permission to dispatch. Succeeded and cancelled executions are terminal.

`available_for_recommendation` permits eligible read suggestions in this snapshot.
It never reserves an agent, claims runtime capacity, or authorizes execution.
Revalidate with the canonical assignment and execution APIs before any write.
A managed inactive agent returns only its authorized identity and lifecycle,
`availability: inactive`, empty work, no cursor, `can_assign: false`, and
`scope.project_id: null`. Former effective scope and work stay concealed.

Actor cursors are signed, bound to caller, organization, actor kind, target,
and project filter, and expire after 15 minutes. Each page rechecks current
permissions and a fingerprint of ranking and execution evidence. Drift returns
`409 WORK_RECOMMENDATIONS_CURSOR_STALE`; restart without a cursor. Invalid
scope or signatures return `400 WORK_RECOMMENDATIONS_INPUT_INVALID`.

`GET /api/orgs/{id}/work-recommendations/actors?project_id=<UUID>` returns the
bounded permitted enabled human/agent selector projection. It contains only
`self_id` and `actors` with `id`, `display_name`, and `type`.

Use `atoll work recommendations [--actor UUID] [--project UUID] --json`,
`atoll work actors --project UUID --json`, or
`atoll work project-recommendations --project UUID --json` for the existing
project-wide ranking. Full and public MCP expose `atoll_get_work_recommendations`
with `view: recommendations` (default), `actors`, or `project`. The selected
MCP `profile_ref` stays the authenticated caller; selecting a target never
changes that caller. These surfaces return the same server order and reasons.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.