---
title: "Discover Capabilities"
method: POST
path: "/tools/discover"
tags: ["Tools"]
---

# Discover Capabilities

`POST /tools/discover`

Discover the tools that fit a set of use cases, translated to Agenta terms.

Wraps the provider's semantic search and reports each integration's connection
state for the calling project. Read-only; project scope comes from caller auth.
See ``docs/design/agent-workflows/projects/tool-discovery/design.md``.

## Request body

- CapabilitiesQuery — Request body for ``POST /tools/discover``. The response is the core ``CapabilitiesResult`` (see ``docs/design/agent-workflows/projects/tool-discovery/design.md``). Project scope comes from the caller's auth, not the body.
  - `use_cases` string[], required
  - `provider` string
  - `limit_alternatives` integer

## Response `200`

Successful Response

- CapabilitiesResult — The ``discover_tools`` response (Agenta-native).
  - `capabilities` Capability[]
    - `use_case` string, required
    - `integration` string, nullable
    - `tool` DiscoveredTool — A discovered tool, already shaped as a ``GatewayToolConfig`` plus the model-facing extras the setup agent needs. ``connection`` is filled only when the integration's state is ``ready``; otherwise the agent resolves it first.
      - `type` 'gateway'
      - `provider` string
      - `integration` string, required
      - `action` string, required
      - `connection` string, nullable
      - `input_schema` object, nullable
      - `description` string, nullable
      - `provider_action` string, required
    - `alternatives` DiscoveredAlternative[]
      - `integration` string, required
      - `action` string, required
      - `description` string, nullable
      - `provider_action` string, required
    - `connection` CapabilityConnection — The connection state for a capability's primary integration.
      - `state` 'ready' | 'needs_auth' | 'needs_input', required — The connection state of one integration, derived per the design's state machine. ``ready`` reuses an existing connection; the other two need a human.
      - `slug` string, nullable
    - `difficulty` string, nullable
    - `note` string, nullable
  - `connections` ConnectionRequirement[]
    - `integration` string, required
    - `state` 'ready' | 'needs_auth' | 'needs_input', required — The connection state of one integration, derived per the design's state machine. ``ready`` reuses an existing connection; the other two need a human.
    - `slug` string, nullable
    - `connect` ConnectAffordance — The Agenta create-connection call to run when a connection is missing. Speaks Agenta, not Composio: it points at ``POST /tools/connections/`` (which returns a ``redirect_url``), never at ``COMPOSIO_MANAGE_CONNECTIONS``.
      - `endpoint` string
      - `body` object, required
  - `guidance` CapabilityGuidance — Structured operating knowledge the setup agent composes into ``agents_md``. Composio slugs in the text are mapped to the same ``integration.action`` names used elsewhere, so nothing Composio leaks.
    - `plan_steps` string[]
    - `pitfalls` string[]
  - `ready` boolean
  - `notes` string[]

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/agenta-ai/apis/agenta-api.md) · [All operations](https://skmtc.net/agenta-ai/apis/agenta-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/agenta-ai/agenta-api/versions/ea6421d829f1/schema)