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

TableJSON 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

TableJSON Schema

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

Schema Changelog

Changes observed during successful MCP inspections.

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/5.0

Behavior4/5

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

Annotations declare destructiveHint=true and idempotentHint=false, and the description adds the non-obvious behavioral consequence that changing dial_category alters the engine's advice (G5, C10) and that the routing of bag fields depends on bag count. It does not state that field updates replace stored values wholesale (that detail lives in the schema) nor discuss auth or reversibility.

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 the 'what' and followed by routing and side-effect warnings. No filler, though the parenthetical field lists are dense and the final sentence could be tighter.

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?

Covers the essential call-time decisions: which fields belong here, where bag fields go, and the visible side effect of dial_category. Return values are omitted but an output schema exists, so that is acceptable. Missing: confirmation of whether unspecified fields are untouched and whether this is a partial update, which matters on a destructive, non-idempotent tool.

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 33%, so the description must carry weight. It does: it explains which parameter keys are coffee-scoped versus bag-scoped and which are diverted to the current bag, plus a rationale for the optional reason note. It omits any interpretation of the reason append mechanic in field terms and the full field partition is left in the schema.

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

Purpose4/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 the coffee-scoped fields it accepts, which distinguishes it from update_bag. It stops short of a peerless 5 because the coffee/bag field split has to be inferred from examples rather than stated as a rule.

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

Usage Guidelines4/5

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

Gives a concrete routing rule: bag-shaped fields sent here land on the CURRENT bag, and 'use update_bag when it has more than one' bag. That is explicit when-to-use guidance, but the guidance for non-current bags is incomplete and no guidance is given for shared fields that exist on both entities.

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?