update_beanUpdate coffee bag fields. Changing dial_category changes what the engine advises (G5, C10), so say why in the optional note.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | Yes | ||
| reason | No | Optional free-text note, appended to the bag notes as an ordinary line. Omit it and nothing is written. | |
| bean_id | Yes |
| Name | Required | Description | Default |
|---|---|---|---|
| status | Yes | ||
| message | Yes |
Changes observed during successful MCP inspections. Dates show when Glama detected each change.
Input schema / properties / fields / properties / best_by_date / descriptionPrevious value: -"Date in YYYY-MM-DD format"New value: +"Calendar day in YYYY-MM-DD format — a day, not a timestamp"Input schema / properties / fields / properties / buy_date / descriptionPrevious value: -"Date in YYYY-MM-DD format"New value: +"Calendar day in YYYY-MM-DD format — a day, not a timestamp"Input schema / properties / fields / properties / frozen_at / descriptionPrevious 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"Input schema / properties / fields / properties / opened_date / descriptionAdded value: +"Calendar day in YYYY-MM-DD format — a day, not a timestamp"Input schema / properties / fields / properties / roast_date / descriptionPrevious value: -"Date in YYYY-MM-DD format"New value: +"Calendar day in YYYY-MM-DD format — a day, not a timestamp"Input schema / properties / fields / properties / unfrozen_at / descriptionPrevious 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"Input schema / properties / reason / descriptionPrevious value: -"A clear justification why this category/roast level is updated."New value: +"Optional free-text note, appended to the bag notes as an ordinary line. Omit it and nothing is written."Input schema / requiredPrevious value: -[
- "bean_id",
- "fields",
- "reason"
-]New value: +[
+ "bean_id",
+ "fields"
+]Output schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "properties": {
+ "message": {
+ "type": "string"
+ },
+ "status": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "status",
+ "message"
+ ],
+ "type": "object"
+}Input schema / properties / fields / properties / grams_remainingAdded value: +{
+ "description": "Override the computed grams left in the bag (weigh the bag, set what is actually there). Translated into weight_adjustment_g so bag_weight_g keeps recording the true bag size. 0 marks the bag finished; a positive value on a finished bag un-finishes it.",
+ "type": "number"
+}Input schema / properties / fields / properties / dial_category / descriptionAdded 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."Input schema / properties / fields / properties / dial_category / enumPrevious value: -[
- "nordic-light",
- "ultra-light",
- "processed",
- "dark",
- "aged"
-]New value: +[
+ "nordic-light",
+ "ultra-light",
+ "classic",
+ "processed",
+ "dark",
+ "aged"
+]Input schema / properties / fields / properties / weight_adjustment_gAdded value: +{
+ "description": "Grams consumed or lost OUTSIDE logged shots (spillage, unlogged brews). grams_remaining = bag_weight_g − logged doses − this. To force remaining to a known value X, set this to bag_weight_g − logged doses − X. Negative adds weight back.",
+ "type": "number"
+}Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already communicate mutability, idempotency, and non-destructiveness. The description adds a genuinely non-obvious side effect: changing dial_category alters what the engine advises (G5, C10), and it recommends explaining the change in the optional note. This goes beyond what annotations and schema alone provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The general update action is front-loaded, and the important dial_category caveat immediately follows. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with this many updatable fields, the combination of description, nested schema, annotations, and output schema is sufficient. The only notable gap is lack of explicit alternative routing, which is already reflected in the usage_guidelines score, so it is not double-penalized here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33% at the top level, but nested fields are individually described in the schema. The description adds meaningful coupling between dial_category and the reason parameter, explaining a consequence not present in the schema. It does not discuss bean_id or the fields wrapper, but those are structurally evident.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Update coffee bag fields' — a specific verb and resource — and the title reinforces the scope. It does not explicitly name sibling tools to distinguish from, but 'coffee bag fields' clearly separates it from siblings like update_shot and register_coffee.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The action itself is stated directly, but there is no guidance on when to use this tool versus alternatives such as register_coffee, set_active, or update_shot. The dial_category note is a useful within-tool instruction, not an alternative-routing or when-not-to-use rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
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.
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.
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.
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.