ShotPulled

Register a coffee

register_coffee

Register a coffee that is NOT yet in list_beans, together with its first bag, and make it the active coffee. 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
`bag_id`	Yes
`status`	Yes
`bean_id`	Yes
`message`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

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"
+]

First observedSep 6, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower; the description still adds non-annotation behavior: the side effect of making the new coffee the active one, the duplicate precondition, and the returned identifiers. It does not say what happens on a duplicate name or whether anything is overwritten, which is the remaining gap.

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?

Three sentences, front-loaded with the action and precondition, then the domain model that justifies the dual entity, then the alternative and return values. No filler; every clause carries routing or modeling information an agent needs.

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 45-parameter creation tool the description covers the hardest part — the coffee/bag split and the sibling routing — and an output schema exists so return values need not be re-explained. What is missing is duplicate/conflict behavior and coverage of the many non-obvious optional fields, but the essential calling information is present.

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

Parameters3/5

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

Schema description coverage is 44% and there are 45 parameters, so the schema cannot carry this alone. The description usefully partitions fields into the coffee's attributes versus the bag's purchase attributes, which is genuine meaning beyond field names, but it gives no formats, ranges, or guidance for the large set of undocumented parameters (ean, qr_code, co2e_kg, arabica_pct, decaffeinated, dial_category, etc.).

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 ('register a coffee ... together with its first bag') and explicitly distinguishes the coffee entity from the bag entity with field groupings. It also names the sibling it is not (register_bag) and the precondition state (not yet in list_beans), so an agent can tell it apart from update_bean/merge_beans without opening a 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?

Gives an explicit when-to-use ('a coffee that is NOT yet in list_beans') and an explicit alternative with the reason to choose it ('for another bag of a coffee already on file call register_bag instead — it keeps the recipes and notes'). This is a real routing rule, not just implied context.

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?