ShotPulled

Update a coffee

update_bean

Idempotent

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

Behavior4/5

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

Annotations already declare the safety profile (writable, idempotent, non-destructive), so the description wisely spends its words on behavior those annotations can't convey: the current-bag routing rule and the fact that changing dial_category alters engine advice (G5, C10). It stops short of covering what happens when multiple bags exist and a bag field still arrives.

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

Conciseness5/5

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

Front-loaded with the core action, then the routing rule, then the dial_category caveat — three dense sentences with no filler. Each clause carries distinct, actionable information.

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?

An output schema exists, so return values need no explanation, and annotations cover idempotency and safety. The description handles the tricky routing and the side-effect of dial_category, but for a tool with a large nested `fields` object it could be clearer about what 'CURRENT bag' means when bags proliferate.

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 description coverage is only 33%, so the description must carry weight, and it does: it splits the 40-plus flat fields into bean-level vs bag-level (state, roast_date, bag_weight_g, grams_remaining, cost) — a categorization the schema itself never states. It adds the dial_category/engine linkage as well, though it can't fully compensate for every undocumented field.

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 the field families it governs (roaster, origins, roast level, rest window, notes, rating). It also names the sibling it is NOT, distinguishing it cleanly from update_bag.

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: bag-shaped fields sent here land on the CURRENT bag, and 'use update_bag when it has more than one' gives the exact condition for choosing the alternative. Nothing about when-to-use is left to inference.

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?