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)
`bag_id`	No	Which bag of the coffee the shot came from; defaults to its current (open) bag. Bag numbers are on list_beans' bags[]
`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.

Changed1 schema field changedSep 12, 2026

addedInput schema / properties / bag_id

Added value: +{
+  "description": "Which bag of the coffee the shot came from; defaults to its current (open) bag. Bag numbers are on list_beans' bags[]",
+  "type": [
+    "integer",
+    "null"
+  ]
+}

First observedSep 6, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations only declare the mutation/safety profile (readOnly=false, idempotent=false, destructive=false), so the description carries additional burden and delivers: how context defaults resolve, that a tag-less/rating-less shot is silently filed taste-pending, and that the diagnosis engine reads tags/metrics rather than flavor_notes. These are real system-state consequences an agent could not infer elsewhere.

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?

Single dense paragraph, front-loaded with the core purpose before the override/taste rules, and nearly every clause carries actionable content. It is long, but the length is justified by the tool's complexity and 32 parameters.

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?

Given an output schema exists (return values needn't be described) and annotations cover the safety profile, the description fills the key gaps an agent needs: context resolution, backdating, and the taste/tag filing rules. Remaining gaps (e.g., explicit auth/permission requirements) are minor.

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 32 params at 66% schema coverage, the description adds genuine semantics beyond the schema for the highest-stakes fields: bean_id override and the wrong-bag risk, pulled_at backdating, sensory_tags for diagnosis, and tasted=1. It does not explain the required dose_g/yield_g/time_s/finish_action, but those are self-evident and schema-documented.

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 (Log) and resource (espresso or alternative shot/brew attempt), which cleanly separates it from siblings update_shot, delete_shot, and list_shots. An agent can identify the operation without opening the 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 explicit when/when-not rules: use active context unless overriding via *_id, ALWAYS pass bean_id when the user names a coffee, backdate with pulled_at for earlier shots, and pass tasted=1 (no tags) for clean tastings. Each rule maps a user situation to a concrete invocation choice.

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?