AI tool usage

The public API can be exposed to AI assistants as tools. Use the AI tool schema when a framework accepts JSON tool definitions, and use the OpenAPI schema when a framework imports OpenAPI directly.

Recommended agent policy

Give the assistant this policy before allowing write access:

You can read subscriptions without confirmation.
Before creating, updating, or deleting subscriptions, summarize the exact planned change and ask for confirmation.
Before deleting, repeat the subscription name and id.
Never send server-managed fields: id, createdAt, updatedAt. Use nextPaymentDate for the upcoming renewal.
If the API returns field, suggestedFix, allowedValues, or writableFields, revise the payload using those hints.

Tool selection

User intent	Tool
”Show my subscriptions”	`list_subscriptions`
”Find my Netflix subscription”	`list_subscriptions`, then match by name/category
”Show details for this id”	`get_subscription`
”Add ChatGPT Plus”	Confirm, then `create_subscription`
”Change Netflix to yearly”	`list_subscriptions`, confirm target/change, then `update_subscription`
”Delete the duplicate Netflix record”	`list_subscriptions`, confirm exact name/id, then `delete_subscription`

Risk levels

Risk	Operations	Agent behavior
Low	List and get	Can run directly when the user asks
Medium	Create and update	Confirm the planned write before calling
High	Delete	Confirm the exact record name and id before calling

The API does not currently have an inactive status field. If the user asks to cancel a subscription, clarify whether they mean deleting the local tracking record or cancelling the service outside this app.

Example flow

User:

Change Netflix to yearly billing.

Assistant:

Calls list_subscriptions.
Finds the Netflix record.
Asks:

I found Netflix (33333333-3333-4333-8333-333333333333), currently monthly. I will change period to yearly while keeping the upcoming renewal date. Confirm?

Calls update_subscription only after confirmation:

{
  "id": "33333333-3333-4333-8333-333333333333",
  "patch": {
    "period": "yearly"
  }
}

Error recovery

Errors use a stable shape:

{
  "error": {
    "code": "invalid_subscription",
    "message": "Invalid option",
    "field": "period",
    "suggestedFix": "Use one of the supported billing periods: monthly, yearly, custom.",
    "allowedValues": ["monthly", "yearly", "custom"]
  },
  "requestId": "request-..."
}

Use field and suggestedFix to correct the next request. For writes, ask for confirmation again if the corrected payload changes the effective action.

​AI tool usage

​Recommended agent policy

​Tool selection

​Risk levels

​Example flow

​Error recovery