# Read effective tools for an agent

Launch state: **Live**. Agents can register at /auth.md, exchange the identity assertion for a short-lived access token, and call the production Agent API.

Contract status: **implemented**. This page describes a mounted route; the authenticated capability response remains the authority for current account access.

## Request

`GET /api/agent/v1/agents/{agentRef}/tools`

Operation ID: `getAgentEffectiveTools`

Send a short-lived access token obtained through [auth.md](https://neotask.ai/auth.md) for `https://neotask.ai/api/agent` in the `Authorization: Bearer` header. The token must include `neotask:catalog:read`.





## Response

Selected-run tools with blockers, setup operations, approval requirements and documentation links, plus the existing MCP permission fields. The JSON schema is `AgentEffectiveToolsResponse` in [OpenAPI](https://neotask.ai/openapi.yaml).

- The top-level tools array contains the complete selected preparation, including denied entries. Site checks current account, task, resource, profile, runner and source authority against the run capabilityDigest. A changed binding returns a conflict.
- Without runRef, complete is false and reason is run_selection_required. The providers and allowedToolNames fields retain their MCP permission meaning. They do not describe a prepared runtime.
- Each tool has availability, reason, setupOperationIds and documentationUrl. Setup operation IDs name the next supported account actions; the caller still needs their scopes and any human approval.
- For current cron preparations, actions distinguishes read access from mutation access. Mutations use the same billing and recovery decision as the native cron owner. On Free, eligible job mutations list the managed_memory_dreaming request exception; wake does not. The owner still checks the exact job on each call. A billing-read outage disables mutations without hiding read actions.
- approvalClass is request_specific because this read contains no invocation arguments. The approval field includes current settings and both source revisions. For a selected run, Site checks those policy rows against the admitted resource binding and rejects a concurrent policy change.
- approval.delegations lists eligible public approval-decision grants for this caller and selected agent. Each entry retains its operation, optional tool, argument digest, scope, expiry, generation and remaining uses. Reading the list consumes no use and authorizes no invocation. Native runner and workload MCP approval requests still require their human review routes.
- Legacy preparedRun receipts remain readable. If a run lacks the current prepared capability binding, its source-allowed tools report setup_required with prepared_capability_required.
- skills lists the selected run’s eligible instruction names before prompt display limits. The names share the prepared capability binding. An empty complete list means the run exposed no skills; skill_inventory_unavailable means the runner did not retain that inventory.
- Skill instructions grant no tool execution or provider access. Provider calls still need current credentials, capability checks and approval. File paths, instruction text and credential metadata are omitted.
- Provider credentials, server IDs, plugin IDs, lease identifiers and raw tool configuration are never returned.
- An unclaimed Agent Trial may read this view for its own standalone agents. The runRef view requires the claim and otherwise returns claim_required.

## Errors

| HTTP | Codes | Meaning | Next action |
|---:|---|---|---|
| 400 | `invalid_request` | A path or query value is malformed. | Correct only the documented input and retry. |
| 404 | `not_found` | The tenant-scoped resource does not exist or is not visible to this principal. | Do not try another tenant identifier. Re-read the tenant-scoped resource list. |
| 409 | `conflict` | The selected run or its prepared source binding is no longer current. | Read the current run state before retrying. |
| 403 | `scope_denied`, `tenant_inactive`, `model_not_allowed` | The credential, account, or requested model cannot perform the operation. | Use an allowed model, request the documented scope, or ask the user to restore account access. |
| 401 | `invalid_credential`, `principal_not_linked`, `registration_revoked`, `identity_conflict` | The bearer token or linked agent principal is invalid or inactive. | Register, refresh, or claim through the documented Auth.md flow, then retry with a new token. |
| 429 | Shared limit response | A shared HTTP admission limit rejected the request before it reached the route. | Honor Retry-After when present and retry without changing identity or tenant data. |
| 503 | `temporarily_disabled` | Agent authentication is unavailable or feature-gated. | Do not bypass authentication. Retry only after the returned guidance or launch state changes. |

## Related resources

- [Agent API index](https://neotask.ai/docs/llms.txt)
- [OpenAPI JSON](https://neotask.ai/openapi.json)
- [Arazzo quickstart](https://neotask.ai/arazzo.yaml)
- [Knowledge manifest](https://neotask.ai/agent-public-contracts/v1/knowledge-manifest.json)