Costory: Your Finops MCP

update_event

Destructive

Persist changes to an existing cost-chart annotation event already saved in Costory. This is a write (not a preview): it overwrites the event's name, date, description, tags, metadata, team scope, and/or the annotation chart in the database. It does not create a new event, does not send Slack/Teams/email, and does not archive or delete the event. Use list_events to find the event id first. All fields except eventId are optional — omit a field to keep the stored value. Metadata is merged into existing values; source is preserved on the event column and should not be supplied. Tags replace the full tag list. Name, date, description, tags, metadata, and scopeId need no widget.

scopeId (same id as list_teams) sets the event scope and leaves the chart unchanged. Omit it to keep the saved scope. null clears it. An id replaces it. If both scopeId and widget.scopeId are sent, scopeId wins.

widget replaces the annotation chart wholesale, or creates one if none exists. If you send widget, send the full chart on the first call, written from scratch exactly as for query: title, queries, and datePreset or from/to. Set chartType on every series (BAR, LINE, AREA, WATERFALL, or TABLE). Omitting it stores LINE and replaces the previous chart type. widget.scopeId alone is invalid. list_events returns chart id and title only, not the stored queries, so do not patch or echo the current chart. Omit widget to leave the chart unchanged. A full widget without widget.scopeId keeps the saved event scope unless top-level scopeId is set. widget.scopeId: null clears the event scope when top-level scopeId is omitted. If the event has multiple charts, pass widgetEventId. EXAMPLE: "Add a PR link to yesterday's deploy event" → { eventId: "clx9abc", metadata: { link: "https://github.com/acme/app/pull/99" } } EXAMPLE: "Fix the description on the migration event" → { eventId: "clx9abc", description: "Migrated prod cluster; temporary 2-day cost spike from dual-running nodes." } EXAMPLE: "Scope the migration event to the platform team" → { eventId: "clx9abc", scopeId: "" } EXAMPLE: "Clear the event scope" → { eventId: "clx9abc", scopeId: null }

Input Schema

Name	Required	Description
`date`	No	New event date (YYYY-MM-DD).
`name`	No	New event name.
`slug`	No	Organization slug. Omit to auto-detect from your account (fails if you belong to multiple orgs).
`tags`	No	Replace all tags on the event.
`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: STRONGLY RECOMMENDED; omit only for truly org-wide events 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.
`eventId`	Yes	Event ID from list_events or create_event.
`scopeId`	No	Event scope id from list_teams. Omit to keep the saved scope. null clears it. Does not change the chart. If widget.scopeId is also sent, this field wins.
`category`	No	Deprecated. If sent, merged into tags then discarded.
`metadata`	No	Metadata fields to merge into existing metadata (e.g. link, owner). Existing source is preserved.
`description`	No	New description.
`widgetEventId`	No	ID of the widgetEvent to update when the event has multiple annotation charts.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedSep 30, 2026

addedInput schema / properties / scopeId

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Event scope id from list_teams. Omit to keep the saved scope. null clears it. Does not change the chart. If widget.scopeId is also sent, this field wins."
+}

changedInput schema / properties / widget / description

Previous value: -"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: STRONGLY RECOMMENDED; omit only for truly org-wide events with no cost chart. On update: omit to leave existing annotation charts unchanged; pass widgetEventId when the event has multiple charts."New value: +"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: STRONGLY RECOMMENDED; omit only for truly org-wide events 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."

Changed4 schema fields changedSep 16, 2026

changedInput schema / properties / category / description

Previous value: -"New category."New value: +"Deprecated. If sent, merged into tags then discarded."

removedInput schema / properties / category / enum

Removed value: -[
-  "BUSINESS",
-  "TECHNICAL",
-  "PROVIDER"
-]

addedInput schema / properties / labels

Added value: +{
+  "description": "Deprecated alias for tags. Ignored when tags is sent.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

changedInput schema / properties / tags / description

Previous value: -"Replace all labels on the event."New value: +"Replace all tags on the event."

First observedAug 19, 2026

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare destructiveHint=true and readOnlyHint=false; the description goes far beyond that by disclosing overwrite semantics per field, merge-vs-replace behavior (metadata merged, tags replace the full list, source preserved), omission meaning 'keep stored value', and the wholesale-replacement nature of the widget. This is exactly the extra behavioral context a mutation tool needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and write-vs-preview caveat are front-loaded, and the worked examples make intent concrete. It is long, though justified by 12 parameters and nested objects, with some overlap between the top-level scopeId precedence sentence and the later widget/scopeId discussion that could be consolidated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex 12-parameter mutation tool with a nested widget object and no output schema, the description covers defaults, replacement vs merge semantics, precedence rules, and cross-tool lookups (list_events, list_teams). Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 100% (baseline 3), the description adds semantics the schema does not: scopeId precedence over widget.scopeId, null-clears vs id-replaces behavior, the full-replacement requirement for widget including mandatory chartType on every series, and the requirement to pass widgetEventId for multi-chart events. These rules materially change how an agent fills the fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Persist changes to an existing cost-chart annotation event'), and immediately disambiguates from siblings by declaring it is a write, not a preview, and does not create a new event (create_event), send notifications, or archive/delete (archive_object). An agent can route to it correctly without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names prerequisites ('Use list_events to find the event id first') and enumerates when-not conditions: it does not create events, does not notify Slack/Teams/email, and does not archive or delete. It also names list_teams as the source of scope ids, giving concrete routing context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Costory: Your Finops MCP tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?