ShotPulled

Log a shot

log_shot

Log an espresso or alternative shot/brew attempt. Uses the active context (bean/grinder/machine/program) unless overridden via bean_id/grinder_id/machine_id/program_id — ALWAYS pass bean_id explicitly when the user names a specific coffee, so the shot cannot land on the wrong bag. Backdate with pulled_at when the shot happened earlier. When the user reports taste (bitter, sour, harsh, hollow…), include matching sensory_tags — the diagnosis engine reads tags and metrics, not free-text flavor_notes. When the user tasted the shot and reports it as GOOD/clean (no defects), pass tasted=1 with no sensory_tags — otherwise a tag-less, rating-less shot is filed taste-pending as if never tasted.

Input Schema

TableJSON Schema

Name	Required	Description
`tds`	No	Total Dissolved Solids percentage (e.g. 9.1 or 1.35)
`dose_g`	Yes
`rating`	No
`tasted`	No	1 = the shot was tasted at log time. The explicit way to record a CLEAN tasting: sensory tags all describe defects, so a good shot has none — without this flag (or a rating) it would be filed taste-pending. Tags or a rating also mark a shot as tasted; 0 (default) = taste later.
`time_s`	Yes
`bean_id`	No	Override: log against this bean instead of the active one (null = active)
`verdict`	No
`yield_g`	Yes
`water_id`	No	Optional references to waters formulation
`best_brew`	No	1 if marked as best brew, 0 otherwise
`favourite`	No	1 if favourite, 0 otherwise
`pulled_at`	No	When the shot was actually pulled (ISO 8601 or "YYYY-MM-DD HH:MM:SS"), for backdated entries. Defaults to now (null = now). When backdating, pass the returned shot_id to diagnose_shot explicitly — the default diagnosis target is the chronologically latest shot.
`beverage_g`	No	Yield mass excluding cup/vessel weight in grams
`grinder_id`	No	Override: grinder used, if not the active one (null = active)
`machine_id`	No	Override: machine used, if not the active one (null = active)
`program_id`	No	Override: machine program used, if not the active one (null = active)
`temp_taste`	No
`vessel_name`	No	Cup/vessel name
`bloom_time_s`	No	Pre-wetting or bloom duration in seconds
`drink_intent`	No
`flavor_notes`	No
`flow_profile`	No	Opaque flow profile data (JSON/TEXT)
`method_tools`	No	JSON representation of method tools used (e.g., paper filters, screen)
`observations`	No
`sensory_tags`	No
`finish_action`	Yes
`temperature_c`	No	Brew temperature in Celsius
`data_confidence`	No	measured = weighed/timed live; recalled = from memory; estimated = a best guess (e.g. missed the timer — "~25s")
`vessel_weight_g`	No	Cup/vessel weight in grams
`pressure_profile`	No	Pressure profile description or values
`first_drip_time_s`	No	Time to first drip in seconds

Output Schema

TableJSON Schema

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

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

Changed1 schema field changedAug 17, 2026

changedOutput schema / (root)

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

Changed13 schema fields changedJul 19, 2026

changedInput schema / properties / bean_id / description

Previous value: -"Override: log against this bean instead of the active one"New value: +"Override: log against this bean instead of the active one (null = active)"

changedInput schema / properties / bean_id / type

Previous value: -"integer"New value: +[
+  "integer",
+  "null"
+]

addedInput schema / properties / data_confidence / description

Added value: +"measured = weighed/timed live; recalled = from memory; estimated = a best guess (e.g. missed the timer — \"~25s\")"

changedInput schema / properties / data_confidence / enum

Previous value: -[
-  "measured",
-  "recalled"
-]New value: +[
+  "measured",
+  "recalled",
+  "estimated"
+]

changedInput schema / properties / grinder_id / description

Previous value: -"Override: grinder used, if not the active one"New value: +"Override: grinder used, if not the active one (null = active)"

changedInput schema / properties / grinder_id / type

Previous value: -"integer"New value: +[
+  "integer",
+  "null"
+]

changedInput schema / properties / machine_id / description

Previous value: -"Override: machine used, if not the active one"New value: +"Override: machine used, if not the active one (null = active)"

changedInput schema / properties / machine_id / type

Previous value: -"integer"New value: +[
+  "integer",
+  "null"
+]

changedInput schema / properties / program_id / description

Previous value: -"Override: machine program used, if not the active one"New value: +"Override: machine program used, if not the active one (null = active)"

changedInput schema / properties / program_id / type

Previous value: -"integer"New value: +[
+  "integer",
+  "null"
+]

changedInput schema / properties / pulled_at / description

Previous value: -"When the shot was actually pulled (ISO 8601 or \"YYYY-MM-DD HH:MM:SS\"), for backdated entries. Defaults to now. When backdating, pass the returned shot_id to diagnose_shot explicitly — the default diagnosis target is the chronologically latest shot."New value: +"When the shot was actually pulled (ISO 8601 or \"YYYY-MM-DD HH:MM:SS\"), for backdated entries. Defaults to now (null = now). When backdating, pass the returned shot_id to diagnose_shot explicitly — the default diagnosis target is the chronologically latest shot."

changedInput schema / properties / pulled_at / type

Previous value: -"string"New value: +[
+  "string",
+  "null"
+]

addedInput schema / properties / tasted

Added value: +{
+  "description": "1 = the shot was tasted at log time. The explicit way to record a CLEAN tasting: sensory tags all describe defects, so a good shot has none — without this flag (or a rating) it would be filed taste-pending. Tags or a rating also mark a shot as tasted; 0 (default) = taste later.",
+  "enum": [
+    0,
+    1
+  ],
+  "type": "integer"
+}

Changed5 schema fields changedJul 14, 2026

addedInput schema / properties / bean_id

Added value: +{
+  "description": "Override: log against this bean instead of the active one",
+  "type": "integer"
+}

addedInput schema / properties / grinder_id

Added value: +{
+  "description": "Override: grinder used, if not the active one",
+  "type": "integer"
+}

addedInput schema / properties / machine_id

Added value: +{
+  "description": "Override: machine used, if not the active one",
+  "type": "integer"
+}

addedInput schema / properties / program_id

Added value: +{
+  "description": "Override: machine program used, if not the active one",
+  "type": "integer"
+}

addedInput schema / properties / pulled_at

Added value: +{
+  "description": "When the shot was actually pulled (ISO 8601 or \"YYYY-MM-DD HH:MM:SS\"), for backdated entries. Defaults to now. When backdating, pass the returned shot_id to diagnose_shot explicitly — the default diagnosis target is the chronologically latest shot.",
+  "type": "string"
+}

First observedJun 16, 2026

TDQS

A4.6/5.0

Behavior5/5

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

With all annotations set to false, the description carries the full behavioral disclosure burden, and it does so thoroughly. It reveals that the tool uses the active context unless overridden, that a shot can land on the wrong bean bag without an explicit bean_id, that the diagnosis engine reads tags and metrics rather than flavor_notes, and that a tag-less/rating-less shot is filed as taste-pending. These are meaningful behaviors beyond what the annotations or schema express.

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?

The description is dense but every sentence earns its place: purpose first, then active-context overrides, backdating, taste tagging, and the clean-shot indicator. It uses emphasis and examples effectively without filler or repetition.

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 31-parameter tool with nested objects and seven enums, the description covers the most consequential behaviors: active-context resolution, overrides, taste workflow, backdating, and a pointer to diagnose_shot. The large number of optional parameters is acceptable because the schema already documents 65% of them and the output schema exists, so the description does not need to explain every field.

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?

At 65% schema coverage, the description adds important semantics to high-risk parameters: bean_id (always pass when a specific coffee is named), pulled_at (backdating and the diagnose_shot implication), sensory_tags (read by the diagnosis engine), and tasted (the explicit marker for a clean shot). It does not enrich every optional parameter, but it targets the ones that most affect correctness.

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?

The description opens with a specific verb and resource: 'Log an espresso or alternative shot/brew attempt.' This clearly distinguishes the tool from sibling tools like update_shot, delete_shot, and diagnose_shot, so an agent knows exactly what action this call performs.

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?

The description gives concrete conditional guidance: pass bean_id explicitly when the user names a coffee, use pulled_at when backdating, add sensory_tags for taste reports, and set tasted=1 for clean shots. It even points to diagnose_shot for backdated entries. It does not explicitly list when to avoid this tool in favor of update_shot or delete_shot, but the creation context is otherwise clear.

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

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

B3.4/5.0

Disambiguation4/5

Most tools target a clearly distinct resource and action, and the list/register/update/set tool families are easy to tell apart. The closest pair is diagnose_preview and diagnose_shot, which are well-described but similar enough in name that an agent could select the wrong one.

Naming Consistency4/5

The overwhelming majority of tools follow a consistent verb_noun pattern (list_beans, register_grinder, update_shot, set_active). Minor exceptions like grinder_math and kb_changelog lack the imperative verb prefix, but they are readable and do not create real confusion.

Tool Count2/5

34 tools is above the 25+ threshold and feels heavy even though the domain is fairly rich. The many parallel list_* and register_* tools for beans, grinders, machines, scales, waters, programs, and recipes could plausibly be consolidated or trimmed without losing core capability.

Completeness3/5

The core shot lifecycle is well covered: log, update, delete, diagnose, and list shots, plus bean registration and maintenance tracking. However, most registered entities lack update/delete tools, and get_rule has no corresponding list_rules tool, leaving some obvious workflow gaps that agents must work around.

Resources

Need Help?