Allow or deny a tool for the agent

PUT

/agents/{agentId}/tool-permissions/{server}/{tool}

const url = 'https://api.asklucy.eu/v1/agents/example/tool-permissions/m365/mail_send';
const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"permission":"allow"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request PUT \
  --url https://api.asklucy.eu/v1/agents/example/tool-permissions/m365/mail_send \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "permission": "allow" }'

allow or deny, or null for the default (read-only tools allow, others deny). ask is 400. allow where the organization’s permission isn’t allow is 409 looser-than-organization. Its managers only. Audited as tool.permission_changed (scope agent, target the tool, details agent_id).

Authorizations

zitadel

Parameters

Path Parameters

agentId

required

string

/^agt_[A-Za-z0-9]+$/

server

required

string

Example

m365

The tool server, a connector (m365) or local (local access).

tool

required

string

Example

mail_send

The tool’s name on its server, without the server prefix.

Request Body^required

application/json

object

permission

required

One of:

string
null

What Lucy may do with a tool. allow: it uses the tool without asking. ask: each call waits for the person’s yes on a card in the chat (Step.approval). deny: the tool is hidden from the model, which never sees it. Stricter is deny > ask > allow.

string

Allowed values: allow ask deny

Responses

200

application/json

object

server

required

The tool server, a connector (m365) or local.

string

tool

required

The tool’s name on its server (the model sees <server>.<tool>).

string

title

required

string

description

required

One line on what the tool does, for settings pages.

string

app

required

The connector’s app the tool belongs to (ConnectorApp.id); null for local access.

string | null

access

required

For local access, whether the tool reads or changes files; null otherwise.

string | null

Allowed values: read write

hints

required

The tool’s MCP annotations the default is read from.

object

read_only

required

boolean

destructive

required

boolean

open_world

required

It reaches outside the person’s own data, such as other people (sending, inviting).

boolean

annotated

The server gave annotations (Lucy’s catalog always does). False for a custom server’s tool without any.

boolean

default

required

string

Allowed values: allow ask deny

organization

required

string

Allowed values: allow ask deny

organization_set

required

An admin set organization; false when it is the tool’s default.

boolean

mine

required

One of:

string
null

string

Allowed values: allow ask deny

effective

required

string

Allowed values: allow ask deny

changed

For a custom server’s tool, new or changed since an admin reviewed it; organization is then ask at most.

boolean

choices

required

The values the caller may set: an admin any of the three; a person organization and what is stricter (only deny when the organization asks, none when it denies).

Array<string>

Allowed values: allow ask deny

Example

{
  "server": "m365",
  "tool": "mail_send",
  "title": "Send an email",
  "app": "send_mail",
  "access": "read",
  "default": "allow",
  "organization": "allow",
  "mine": "allow",
  "effective": "allow",
  "choices": [
    "allow"
  ]
}

400

The request is invalid; errors lists what’s wrong.

application/problem+json

RFC 9457 problem details.

object

type

required

string format: uri-reference

title

required

string

status

required

integer

detail

string

instance

string

request_id

string

quota

For quota-exceeded, the window that is used up.

object

window

required

string

Allowed values: five_hours week month

percent_used

required

number

<= 100

resets_at

required

Null for a rolling window that hasn’t started.

string | null format: date-time

limited_by

required

organization when the organization’s budget is closer to running out than the member’s own limit.

string

Allowed values: personal organization

request

One of:

object
null

A request as its member sees it, where they asked.

object

required

string

status

required

string

Allowed values: pending approved declined withdrawn

created_at

required

string format: date-time

decided_at

required

string | null format: date-time

note

required

What the admin who decided wrote back.

string | null

errors

Field-level problems (400 only).

Array<object>

object

field

required

JSON pointer into the request body.

string

message

required

string

Example

{
  "type": "https://docs.asklucy.eu/errors/answer-in-progress",
  "quota": {
    "window": "five_hours",
    "limited_by": "personal",
    "request": {
      "status": "pending"
    }
  }
}

Headers

X-Request-Id

string

Unique per request; quote it to support.

401

Missing, expired or invalid token.

application/problem+json

RFC 9457 problem details.

object

type

required

string format: uri-reference

title

required

string

status

required

integer

detail

string

instance

string

request_id

string

quota

For quota-exceeded, the window that is used up.

object

window

required

string

Allowed values: five_hours week month

percent_used

required

number

<= 100

resets_at

required

Null for a rolling window that hasn’t started.

string | null format: date-time

limited_by

required

organization when the organization’s budget is closer to running out than the member’s own limit.

string

Allowed values: personal organization

request

One of:

object
null

A request as its member sees it, where they asked.

object

required

string

status

required

string

Allowed values: pending approved declined withdrawn

created_at

required

string format: date-time

decided_at

required

string | null format: date-time

note

required

What the admin who decided wrote back.

string | null

errors

Field-level problems (400 only).

Array<object>

object

field

required

JSON pointer into the request body.

string

message

required

string

Example

{
  "type": "https://docs.asklucy.eu/errors/answer-in-progress",
  "quota": {
    "window": "five_hours",
    "limited_by": "personal",
    "request": {
      "status": "pending"
    }
  }
}

Headers

X-Request-Id

string

Unique per request; quote it to support.

404

No such object in your organization.

application/problem+json

RFC 9457 problem details.

object

type

required

string format: uri-reference

title

required

string

status

required

integer

detail

string

instance

string

request_id

string

quota

For quota-exceeded, the window that is used up.

object

window

required

string

Allowed values: five_hours week month

percent_used

required

number

<= 100

resets_at

required

Null for a rolling window that hasn’t started.

string | null format: date-time

limited_by

required

organization when the organization’s budget is closer to running out than the member’s own limit.

string

Allowed values: personal organization

request

One of:

object
null

A request as its member sees it, where they asked.

object

required

string

status

required

string

Allowed values: pending approved declined withdrawn

created_at

required

string format: date-time

decided_at

required

string | null format: date-time

note

required

What the admin who decided wrote back.

string | null

errors

Field-level problems (400 only).

Array<object>

object

field

required

JSON pointer into the request body.

string

message

required

string

Example

{
  "type": "https://docs.asklucy.eu/errors/answer-in-progress",
  "quota": {
    "window": "five_hours",
    "limited_by": "personal",
    "request": {
      "status": "pending"
    }
  }
}

Headers

X-Request-Id

string

Unique per request; quote it to support.

409

The object isn’t in a state that allows this (e.g. Lucy is already answering).

application/problem+json

RFC 9457 problem details.

object

type

required

string format: uri-reference

title

required

string

status

required

integer

detail

string

instance

string

request_id

string

quota

For quota-exceeded, the window that is used up.

object

window

required

string

Allowed values: five_hours week month

percent_used

required

number

<= 100

resets_at

required

Null for a rolling window that hasn’t started.

string | null format: date-time

limited_by

required

organization when the organization’s budget is closer to running out than the member’s own limit.

string

Allowed values: personal organization

request

One of:

object
null

A request as its member sees it, where they asked.

object

required

string

status

required

string

Allowed values: pending approved declined withdrawn

created_at

required

string format: date-time

decided_at

required

string | null format: date-time

note

required

What the admin who decided wrote back.

string | null

errors

Field-level problems (400 only).

Array<object>

object

field

required

JSON pointer into the request body.

string

message

required

string

Example

{
  "type": "https://docs.asklucy.eu/errors/answer-in-progress",
  "quota": {
    "window": "five_hours",
    "limited_by": "personal",
    "request": {
      "status": "pending"
    }
  }
}

Headers

X-Request-Id

string

Unique per request; quote it to support.

Allow or deny a tool for the agent

Authorizations

Parameters

Path Parameters

Example

Example

Request Bodyrequired

Responses

200

Example

400

Example

Headers

401

Example

Headers

404

Example

Headers

409

Example

Headers

Request Body^required