create_event
Create a new event to annotate a cost change. Use this when the user wants to document why costs changed — e.g. a deployment, migration, pricing update, or business decision. Events are displayed on cost charts as annotations so the team can correlate cost movements with real-world changes. An optional "widget" definition creates a visual annotation tied to the relevant cost movement; omit it for an informational event without a chart. Optionally attach tags (string labels such as "migration" or "scaling") to the event — call list_tags to discover existing tag values in the org before inventing new ones. Optionally attach metadata key-value pairs (e.g. link to a PR, owner, external reference) — source is a column set by the server and should not be sent inside metadata. widget.scopeId is stored on the event (same id as list_teams). Omit it for no scope. null is the same as omit on create.
EXAMPLE: "Log the Kubernetes migration we did last Tuesday" → { name: "Kubernetes cluster migration", date: "2026-03-18", description: "Migrated from k8s v1.27 to v1.30, caused temporary node scaling cost spike", tags: ["migration"], metadata: { link: "https://github.com/acme/infra/pull/42", owner: "platform-team" }, widget: { title: "K8s node cost", queries: [{ type: "cost", name: "a", metricId: "cost", currency: "USD", filterCel: "cos_service_name in ["AmazonEC2"]" }], from: "2026-03-10", to: "2026-03-25", aggBy: "Day" } }
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"name": "<name>",
"date": "<date>",
"description": "<description>",
"context": "<context>"
},
"name": "create_event"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Event date (YYYY-MM-DD) | |
| name | Yes | Event name (min 5 characters) | |
| slug | No | Organization slug. Omit to auto-detect from your account (fails if you belong to multiple orgs). | |
| tags | No | Tags to attach to the event (e.g. 'migration', 'scaling'). Use list_tags to discover existing tag values. | |
| labels | No | Deprecated alias for tags. Ignored when tags is sent. | |
| widget | No | Annotation chart for the event. Same shape as the `query` tool (`queries`, `datePreset` or `from`/`to`, `aggBy`, `compare`, `limit`, `scopeId`) plus `title` and optional `description`. Providing a widget creates a visual annotation so the team can see which cost movement the event documents. On create: provide this unless the event is truly org-wide with no cost chart. On update: omit to leave the chart unchanged. If sent, widget is a full replacement (title, queries, and datePreset or from/to required; scopeId alone is invalid). Pass widgetEventId when the event has multiple charts. | |
| context | Yes | A few words on why you are calling this tool, for the server developer's analytics. Describe people and things by role, such as "a customer". Do not quote the user or include names, emails, or other personal details. | |
| category | No | Deprecated. If sent, merged into tags then discarded. | |
| metadata | No | Optional key-value metadata (e.g. link, owner, event). source is always set to api. | |
| llm_model | No | The model identifier you are running as, for example "claude-opus-4-8" or "gpt-5.2". Pass "unknown" if you are not certain. Recorded for the server developer's analytics. | |
| description | Yes | What happened and why it affects costs | |
| conversation_id | No | The conversation_id this server returned earlier in this conversation, unchanged, including after later user messages. Omit it if you have none. Recorded for the server developer's analytics. |