ShotPulled

Register a coffee

register_coffee

Register a coffee that is NOT yet in list_beans, together with its first bag. It does not switch a coffee in use: it becomes active only when no coffee is in use (none active, or the active one archived or with every bag finished); otherwise call set_active with its bean_id when the user starts brewing it. The active field of the reply says which. The coffee is the roaster's product (roaster, origins, variety, process, roast level, roasting type, cupping score, aromatics, roaster notes, rest window); the bag is this purchase (roast date, weight, price, state). For another bag of a coffee already on file call register_bag instead: it keeps the recipes and notes. Returns bean_id and the first bag's bag_id.

Input Schema

Name	Required	Description
`ean`	No
`url`	No
`body`	No	Free text; roasters usually say low, medium or high
`cost`	No
`name`	Yes
`notes`	No	The coffee's own description: the roaster's tasting notes, the dialing approach that worked. Per bag notes go in bag_notes.
`state`	No
`origin`	No
`rating`	No
`acidity`	No	Free text; roasters usually say low, medium or high
`co2e_kg`	No
`origins`	No	List of bean origin details
`qr_code`	No
`roaster`	No
`storage`	No
`variety`	No
`archived`	No	1 if archived, 0 otherwise
`bean_mix`	No	E.g. blend details
`buy_date`	No	Calendar day in YYYY-MM-DD format: a day, not a timestamp
`currency`	No
`finished`	No	1 if finished, 0 otherwise
`aromatics`	No
`bag_notes`	No
`favourite`	No	1 if favourite, 0 otherwise
`frozen_at`	No	Calendar day the bag went into the freezer, YYYY-MM-DD: a day, not a timestamp
`sweetness`	No	Free text; roasters usually say low, medium or high
`product_id`	No	Set by the apps. Leave out.
`roast_date`	Yes	Calendar day in YYYY-MM-DD format: a day, not a timestamp
`arabica_pct`	No	Percent arabica, 100 for a pure arabica; the rest robusta
`attachments`	No	JSON or comma-separated list of attachments
`frozen_note`	No
`opened_date`	No	Calendar day in YYYY-MM-DD format: a day, not a timestamp
`roast_level`	Yes
`roast_range`	No
`unfrozen_at`	No	Calendar day the bag came out, YYYY-MM-DD: a day, not a timestamp
`bag_weight_g`	No	Bag weight in grams
`best_by_date`	No	Calendar day in YYYY-MM-DD format: a day, not a timestamp
`process_type`	Yes
`roast_custom`	No
`decaffeinated`	No	1 if decaf, 0 if regular
`dial_category`	No	Dialing behavior class: classic = medium/traditional espresso roasts (chocolate/nut, balanced); dark = genuinely dark/roasty; the light categories cover Nordic and ultra-light styles.
`roasting_type`	No
`cupping_points`	No
`frozen_storage`	No
`lot_revision_id`	No	Set by the apps. Leave out.
`catalog_coffee_id`	No	Set by the apps. Leave out.
`rest_window_days_max`	No
`rest_window_days_min`	No

Output Schema

Name	Required	Description	Default
`active`	Yes
`bag_id`	Yes
`status`	Yes
`bean_id`	Yes
`message`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed10 schema fields changedOct 22, 2026

changedInput schema / 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 / 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"

addedInput schema / properties / catalog_coffee_id

Added value: +{
+  "description": "Set by the apps. Leave out.",
+  "type": "string"
+}

changedInput schema / 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"

addedInput schema / properties / lot_revision_id

Added value: +{
+  "description": "Set by the apps. Leave out.",
+  "type": "string"
+}

changedInput schema / properties / notes / description

Previous value: -"The coffee's own description — the roaster's tasting notes, the dialing approach that worked. Per bag notes go in bag_notes."New value: +"The coffee's own description: the roaster's tasting notes, the dialing approach that worked. Per bag notes go in bag_notes."

changedInput schema / 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"

addedInput schema / properties / product_id

Added value: +{
+  "description": "Set by the apps. Leave out.",
+  "type": "string"
+}

changedInput schema / 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 / 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"

Changed2 schema fields changedSep 27, 2026

addedOutput schema / properties / active
```
Added value: +{
+  "type": "boolean"
+}
```

changedOutput schema / required

Previous value: -[
-  "status",
-  "bean_id",
-  "bag_id",
-  "message"
-]New value: +[
+  "status",
+  "bean_id",
+  "bag_id",
+  "active",
+  "message"
+]

Changed8 schema fields changedSep 12, 2026

addedInput schema / properties / acidity

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

addedInput schema / properties / arabica_pct

Added value: +{
+  "description": "Percent arabica, 100 for a pure arabica; the rest robusta",
+  "maximum": 100,
+  "minimum": 0,
+  "type": "number"
+}

addedInput schema / properties / body

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

addedInput schema / properties / notes

Added value: +{
+  "description": "The coffee's own description — the roaster's tasting notes, the dialing approach that worked. Per bag notes go in bag_notes.",
+  "maxLength": 4096,
+  "type": "string"
+}

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

Added value: +{
+  "description": "Upper end of an elevation range, e.g. 1980 for \"1800–1980 m\"; elevation_m is the lower end",
+  "type": "number"
+}

addedInput schema / properties / sweetness

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

addedOutput schema / properties / bag_id
```
Added value: +{
+  "type": "integer"
+}
```

changedOutput schema / required

Previous value: -[
-  "status",
-  "bean_id",
-  "message"
-]New value: +[
+  "status",
+  "bean_id",
+  "bag_id",
+  "message"
+]

Changed7 schema fields changedAug 17, 2026

changedInput schema / 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 / 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 / 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 / opened_date / description

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

changedInput schema / 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 / 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"

changedOutput schema / (root)

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

Changed2 schema fields changedJul 14, 2026

addedInput schema / 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 / dial_category / enum

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

First observedJun 16, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Goes well beyond the annotations by disclosing the activation side effect chain: the new coffee does not become active unless no coffee is in use (none active, active archived, or all bags finished), and the reply's `active` field reports which happened. Annotations only say non-readonly, non-idempotent, non-destructive; the active-state logic is the non-obvious behaviour an agent must know.

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?

Front-loads the decisive constraint (NOT yet in list_beans) and the alternative routing. The parenthetical field enumerations are long but justified because they are what separates bean from bag fields; the text is dense with little filler.

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?

For a 48-parameter creation tool, it covers the essentials an agent needs before calling: uniqueness requirement, the bean/bag split, the activation consequence, and the returned ids (bean_id, bag_id) even though an output schema exists. It leaves unclear how duplicates are detected (e.g. via ean) and what validation failures look like, which is a modest gap.

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?

Adds real meaning over the 48%-covered schema by partitioning the 48 parameters into coffee-level fields (roaster, origins, variety, process, roast level, roasting type, cupping score, aromatics, notes, rest window) versus bag-level fields (roast date, weight, price, state), which the schema does not do. Many parameters (ean, url, qr_code, currency, storage, attachments) remain unmentioned, so it stops short of full compensation.

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+resource plus a hard precondition: register a coffee NOT yet in list_beans, together with its first bag. It also names the sibling it is not (register_bag) and the neighbour it does not replace (set_active), so an agent can distinguish it from siblings without opening any 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?

Explicit when-to-use ('NOT yet in list_beans'), when-not ('For another bag of a coffee already on file call register_bag instead'), and what to do afterward ('call set_active with its bean_id when the user starts brewing it'). Exclusions and alternatives are spelled out rather than implied.

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?