ShotPulled

Update a coffee

update_bean

Destructive

Update a coffee's own fields (roaster, origins, roast level, rest window, notes, rating…). Bag-shaped fields sent here (state, roast_date, bag_weight_g, grams_remaining, cost…) land on the coffee's CURRENT bag. Use update_bag when it has more than one. Changing dial_category changes what the engine advises (G5, C10), so say why in the optional note.

Input Schema

Name	Required	Description
`fields`	Yes
`reason`	No	Optional free-text note, appended as an ordinary line to the coffee's notes, or to the current bag's bag_notes when the call changed only bag fields. Omit it and nothing is written.
`bean_id`	Yes

Output Schema

Name	Required	Description	Default
`status`	Yes
`message`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedOct 22, 2026

changedInput schema / properties / fields / properties / best_by_date / description

Previous value: -"Calendar day in YYYY-MM-DD format — a day, not a timestamp"New value: +"Calendar day in YYYY-MM-DD format: a day, not a timestamp"

changedInput schema / properties / fields / properties / buy_date / description

Previous value: -"Calendar day in YYYY-MM-DD format — a day, not a timestamp"New value: +"Calendar day in YYYY-MM-DD format: a day, not a timestamp"

changedInput schema / properties / fields / properties / frozen_at / description

Previous value: -"Calendar day the bag went into the freezer, YYYY-MM-DD — a day, not a timestamp"New value: +"Calendar day the bag went into the freezer, YYYY-MM-DD: a day, not a timestamp"

changedInput schema / properties / fields / properties / notes / description

Previous value: -"The coffee's own description — roaster tasting notes, the dialing approach. Replaces the stored value; the optional reason is appended instead."New value: +"The coffee's own description: roaster tasting notes, the dialing approach. Replaces the stored value; the optional reason is appended instead."

changedInput schema / properties / fields / properties / opened_date / description

Previous value: -"Calendar day in YYYY-MM-DD format — a day, not a timestamp"New value: +"Calendar day in YYYY-MM-DD format: a day, not a timestamp"

changedInput schema / properties / fields / properties / roast_date / description

Previous value: -"Calendar day in YYYY-MM-DD format — a day, not a timestamp"New value: +"Calendar day in YYYY-MM-DD format: a day, not a timestamp"

changedInput schema / properties / fields / properties / unfrozen_at / description

Previous value: -"Calendar day the bag came out, YYYY-MM-DD — a day, not a timestamp"New value: +"Calendar day the bag came out, YYYY-MM-DD: a day, not a timestamp"

changedInput schema / properties / reason / description

Previous value: -"Optional free-text note, appended as an ordinary line to the coffee's notes — or to the current bag's bag_notes when the call changed only bag fields. Omit it and nothing is written."New value: +"Optional free-text note, appended as an ordinary line to the coffee's notes, or to the current bag's bag_notes when the call changed only bag fields. Omit it and nothing is written."

Changed7 schema fields changedSep 12, 2026

addedInput schema / properties / fields / properties / acidity

Added value: +{
+  "description": "Free text; roasters usually say low, medium or high",
+  "type": "string"
+}

addedInput schema / properties / fields / properties / arabica_pct

Added value: +{
+  "maximum": 100,
+  "minimum": 0,
+  "type": "number"
+}

addedInput schema / properties / fields / properties / body

Added value: +{
+  "description": "Free text; roasters usually say low, medium or high",
+  "type": "string"
+}

addedInput schema / properties / fields / properties / notes

Added value: +{
+  "description": "The coffee's own description — roaster tasting notes, the dialing approach. Replaces the stored value; the optional reason is appended instead.",
+  "maxLength": 4096,
+  "type": "string"
+}

addedInput schema / properties / fields / properties / origins / items / properties / elevation_max_m

Added value: +{
+  "description": "Upper end of an elevation range; elevation_m is the lower end",
+  "type": "number"
+}

addedInput schema / properties / fields / properties / sweetness

Added value: +{
+  "description": "Free text; roasters usually say low, medium or high",
+  "type": "string"
+}

changedInput schema / properties / reason / description

Previous value: -"Optional free-text note, appended to the bag notes as an ordinary line. Omit it and nothing is written."New value: +"Optional free-text note, appended as an ordinary line to the coffee's notes — or to the current bag's bag_notes when the call changed only bag fields. Omit it and nothing is written."

Changed9 schema fields changedAug 17, 2026

changedInput schema / properties / fields / properties / best_by_date / description

Previous value: -"Date in YYYY-MM-DD format"New value: +"Calendar day in YYYY-MM-DD format — a day, not a timestamp"

changedInput schema / properties / fields / properties / buy_date / description

Previous value: -"Date in YYYY-MM-DD format"New value: +"Calendar day in YYYY-MM-DD format — a day, not a timestamp"

changedInput schema / properties / fields / properties / frozen_at / description

Previous value: -"Datetime in YYYY-MM-DD HH:MM:SS format"New value: +"Calendar day the bag went into the freezer, YYYY-MM-DD — a day, not a timestamp"

addedInput schema / properties / fields / properties / opened_date / description
```
Added value: +"Calendar day in YYYY-MM-DD format — a day, not a timestamp"
```

changedInput schema / properties / fields / properties / roast_date / description

Previous value: -"Date in YYYY-MM-DD format"New value: +"Calendar day in YYYY-MM-DD format — a day, not a timestamp"

changedInput schema / properties / fields / properties / unfrozen_at / description

Previous value: -"Datetime in YYYY-MM-DD HH:MM:SS format"New value: +"Calendar day the bag came out, YYYY-MM-DD — a day, not a timestamp"

changedInput schema / properties / reason / description

Previous value: -"A clear justification why this category/roast level is updated."New value: +"Optional free-text note, appended to the bag notes as an ordinary line. Omit it and nothing is written."

changedInput schema / required

Previous value: -[
-  "bean_id",
-  "fields",
-  "reason"
-]New value: +[
+  "bean_id",
+  "fields"
+]

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "properties": {
+    "message": {
+      "type": "string"
+    },
+    "status": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "status",
+    "message"
+  ],
+  "type": "object"
+}

Changed1 schema field changedJul 19, 2026

addedInput schema / properties / fields / properties / grams_remaining

Added value: +{
+  "description": "Override the computed grams left in the bag (weigh the bag, set what is actually there). Translated into weight_adjustment_g so bag_weight_g keeps recording the true bag size. 0 marks the bag finished; a positive value on a finished bag un-finishes it.",
+  "type": "number"
+}

Changed3 schema fields changedJul 14, 2026

addedInput schema / properties / fields / properties / dial_category / description

Added value: +"Dialing behavior class: classic = medium/traditional espresso roasts (chocolate/nut, balanced); dark = genuinely dark/roasty; the light categories cover Nordic and ultra-light styles."

changedInput schema / properties / fields / properties / dial_category / enum

Previous value: -[
-  "nordic-light",
-  "ultra-light",
-  "processed",
-  "dark",
-  "aged"
-]New value: +[
+  "nordic-light",
+  "ultra-light",
+  "classic",
+  "processed",
+  "dark",
+  "aged"
+]

addedInput schema / properties / fields / properties / weight_adjustment_g

Added value: +{
+  "description": "Grams consumed or lost OUTSIDE logged shots (spillage, unlogged brews). grams_remaining = bag_weight_g − logged doses − this. To force remaining to a known value X, set this to bag_weight_g − logged doses − X. Negative adds weight back.",
+  "type": "number"
+}

First observedJun 16, 2026

TDQS

A4.3/5.0

Behavior3/5

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

Annotations already declare this a non-idempotent, destructive, closed-world mutation, so the safety profile is covered. The description still earns credit for disclosing a non-obvious cross-resource side effect: bag-shaped fields passed here mutate the coffee's CURRENT bag rather than the coffee. It does not explain partial-update semantics (whether omitted fields are preserved), merge behavior, or failure modes.

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?

Three sentences, front-loaded with scope, then the routing rule, then the caution — nothing redundant. The '(G5, C10)' code references are opaque to an outside reader and cost a little clarity, and the parenthetical field lists are dense.

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

Completeness4/5

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

With an output schema present, return values need no explanation, and the annotations cover the destructive/non-idempotent profile. What remains thin is update semantics: whether this is a partial patch, how nested `origins` arrays are treated, and what happens when both coffee and bag fields are sent together.

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

Parameters4/5

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

Schema coverage is only 33%, and the flat `fields` bag mixes coffee-level and bag-level keys with no structural distinction in the schema itself. The description supplies exactly that missing semantics by naming which fields land on the bag versus the coffee, and it explains the purpose of the `reason` note. It falls short of fully compensating because the field lists are truncated ('…') and replace-vs-append semantics for individual fields are only partially addressed.

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 ('Update a coffee's own fields') and enumerates representative fields so the scope is concrete. It immediately contrasts with the sibling update_bag, so an agent can pick between the two without opening either 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 routes the agent: 'Use update_bag when it has more than one' bag. It also flags the dial_category change as having downstream consequences on engine advice and asks for a rationale note, which is real decision guidance rather than restatement.

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

All ShotPulled 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?