Capability Discovery

Capabilities define what your agents can do. Before submitting an intent, use the Capability Discovery API to find what's available in your organization's configuration and understand the exact parameters each capability expects.

Capability anatomy

Every capability is identified by a three-part tuple:

domain.action.entity

Part	Description	Example
`domain`	The business domain or service category	`document-signing`
`action`	The operation being performed	`create`
`entity`	The thing being operated on	`contract`

Examples: document-signing.create.contract, project-management.create.ticket, messaging.send.message

Your agents use this vocabulary exclusively. The underlying provider — whether that's DocuSign, PandaDoc, or any other system — is abstracted away.

List all capabilities

Retrieve all capabilities available to your organization:

GET /agent/v1/capabilities
Authorization: Bearer YOUR_API_KEY

Response:

{
  "capabilities": [
    {
      "domain": "document-signing",
      "action": "create",
      "entity": "contract",
      "version": "1.0.0",
      "description": "Create a new contract and send it to one or more signers",
      "riskMetadata": {
        "reversibility": 0.4,
        "visibility": "external"
      }
    },
    {
      "domain": "project-management",
      "action": "create",
      "entity": "ticket",
      "version": "1.0.0",
      "description": "Create a new task or issue in your project management system",
      "riskMetadata": {
        "reversibility": 0.9,
        "visibility": "internal"
      }
    },
    {
      "domain": "messaging",
      "action": "send",
      "entity": "message",
      "version": "1.0.0",
      "description": "Send a message to a channel or direct recipient",
      "riskMetadata": {
        "reversibility": 0.0,
        "visibility": "external"
      }
    }
  ]
}

Only capabilities that are both defined in the platform catalog and configured with an active provider binding for your organization appear in this list.

Get a single capability schema

Retrieve the full parameter schema for a specific capability:

GET /agent/v1/capabilities/{domain}/{action}/{entity}
Authorization: Bearer YOUR_API_KEY

Example:

GET /agent/v1/capabilities/document-signing/create/contract

Response:

{
  "domain": "document-signing",
  "action": "create",
  "entity": "contract",
  "version": "1.0.0",
  "description": "Create a new contract and send it to one or more signers",
  "parameters": {
    "type": "object",
    "required": ["signerName", "signerEmail", "templateId"],
    "properties": {
      "signerName": {
        "type": "string",
        "description": "Full name of the primary signer"
      },
      "signerEmail": {
        "type": "string",
        "format": "email",
        "description": "Email address of the primary signer"
      },
      "templateId": {
        "type": "string",
        "description": "ID of the template to use for this contract"
      },
      "subject": {
        "type": "string",
        "description": "Subject line for the signing request email",
        "default": "Please sign this document"
      },
      "message": {
        "type": "string",
        "description": "Optional personal message to include in the signing request"
      },
      "expiresInDays": {
        "type": "integer",
        "minimum": 1,
        "maximum": 90,
        "description": "Number of days before the signing request expires"
      }
    }
  },
  "returns": {
    "type": "object",
    "properties": {
      "contractId": {
        "type": "string",
        "description": "Provider-assigned contract identifier"
      },
      "signingUrl": {
        "type": "string",
        "description": "Direct URL for the signer to access the document"
      },
      "status": {
        "type": "string",
        "enum": ["sent", "delivered", "viewed"],
        "description": "Initial status of the signing request"
      }
    }
  },
  "riskMetadata": {
    "reversibility": 0.4,
    "visibility": "external",
    "description": "Sending a contract notifies the signer externally; the envelope can be voided but the notification cannot be unsent"
  }
}

Parameter schema

The parameters object is a JSON Schema definition. Formael validates your intent's parameters against this schema before policy evaluation. Required fields must be present; optional fields have description and sometimes default values.

Risk metadata

The riskMetadata object tells you how the platform's risk axis will initially score this capability:

Field	Values	What it affects
`reversibility`	0.0–1.0	Higher means harder to undo — raises the risk score
`visibility`	`internal` / `external`	External actions affect parties outside your org — raises the risk score

These are defaults. Your organization's policies and the specific parameter values provided by the agent influence the final risk score per execution.

Building agent prompts with capability schemas

A common pattern is to include the capability schema in your agent's system prompt or context window so it knows exactly what parameters to provide:

# Fetch the schema once and include it in the agent's context
capability = client.capabilities.get("document-signing", "create", "contract")
schema_context = f"""
You can create contracts using the following parameters:
Required: signerName (string), signerEmail (email), templateId (string)
Optional: subject (string), message (string), expiresInDays (1-90)
"""

Because the schema is machine-readable JSON Schema, it can also be passed directly to function-calling models as a tool definition.

Capability versioning

Capabilities are versioned. The version field in the response tells you which schema version your organization is running. When a capability schema changes in a backward-incompatible way, a new version is released — your existing intents targeting the previous version continue to work until you migrate.

Version upgrades are announced in the changelog and managed in your organization's capability configuration.