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

TableJSON 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
`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
`rest_window_days_max`	No
`rest_window_days_min`	No

Output Schema

TableJSON 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.

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?

Annotations declare non-readonly, non-destructive, non-idempotent, closed-world, but the description adds the crucial side-effect model: it does NOT switch the active coffee, becomes active only under stated conditions, and the reply's `active` field signals which happened. That's real behavioral disclosure beyond the annotations.

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 core scope and sibling routing before the field taxonomy, and every sentence carries information. It is dense and slightly long, but for a 45-param registration tool the length is largely earned.

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 routing decision, active-state semantics, entity split, sibling alternative, and return identifiers (bean_id, bag_id), so an agent can call it correctly; the output schema carries the rest. The only gap is the long tail of optional coffee/bag attributes not addressed.

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?

With 45 params at 44% schema coverage, the description compensates by grouping fields into coffee-level (roaster, origins, variety, process, roast level, roasting type, cupping score, aromatics, notes, rest window) versus bag-level (roast date, weight, price, state) — a semantic split the flat schema does not convey. It still leaves many optional params (ean, url, qr_code, arabica_pct, etc.) unexplained.

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+scope ('register a coffee that is NOT yet in list_beans, together with its first bag') and explicitly separates the coffee (roaster's product) from the bag (this purchase). This lets an agent distinguish it from register_bag and update_bean without opening schemas.

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 states when not to use it ('NOT yet in list_beans'), names the alternative for the existing-coffee case (register_bag, which keeps recipes/notes), and gives the routing rule to set_active 'when the user starts brewing it'. Covers when, when-not and alternative in one pass.

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?