Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-server-brewfather What are the latest gravity readings for my Hazy IPA batch?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server for the Brewfather API. It lets an LLM read your batches, recipes, fermentation readings, and inventory, and make the routine writes that come up while brewing: advancing a batch's status, logging measured gravities and volumes, tweaking a recipe, and adjusting stock after brew day.
Brewfather has no official MCP server; this wraps the public v2 API directly.
Tool | What it does |
| Find batches by name substring and/or status → |
| Batch summary, measured values, and embedded recipe (stats + ingredient bill) |
| Most recent hydrometer/sensor readings, oldest→newest ( |
| Set status and/or |
| Find recipes by name substring → |
| Target stats (OG, FG, ABV, IBU, color, …) and ingredient bill |
| Change settings (batch size, boil time, efficiency, …) and add/change/remove ingredients |
| Fermentables, hops, miscs, or yeasts in stock |
| Set absolute stock, or add/subtract |
All values are metric (SG, liters, kg/g, °C) — the API accepts nothing else. Timestamps are returned as ISO-8601 UTC.
Brewfather computes recipe stats (OG, FG, ABV, IBU, color) in the app, not the API.
After update_recipe, the app shows correct stats as soon as you open the recipe,
but get_recipe returns the stored values, which the API never recalculates.
Stats can't be written through this server.
Related MCP server: Bauplan MCP Server
In Brewfather: Settings → API → Generate API Key. Pick scopes to match what you want the server to do (see Security posture). Note the User ID shown alongside the key.
cp .env.example .env
# edit .env with your user id / API key, then:
source .envuv sync # or: pip install -e .Claude Code:
claude mcp add brewfather --scope user \
-e BREWFATHER_USER_ID=your_user_id -e BREWFATHER_API_KEY=your_api_key \
-- uv --directory /path/to/mcp-server-brewfather run mcp-server-brewfatherClaude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"brewfather": {
"command": "uv",
"args": ["--directory", "/path/to/mcp-server-brewfather", "run", "mcp-server-brewfather"],
"env": {
"BREWFATHER_USER_ID": "your_user_id",
"BREWFATHER_API_KEY": "your_api_key"
}
}
}
}The API key's scopes are the trust boundary. For read-only use, grant only
batches.read, recipes.read, inventory.read. Add batches.write /
recipes.write / inventory.write to enable update_batch / update_recipe /
set_inventory. Never grant *.delete — no tool uses it.
No delete tools. Every write is checked against an allowlist of fields before it's sent, because the API silently accepts unknown fields.
Two dependencies only (mcp, httpx — the latter already required by mcp);
pinned via the committed uv.lock.
Credentials live in a gitignored .env / Claude config.
Brewfather allows 500 calls per hour per API key. List tools page 50 items per
call, so find_*/list_inventory cost one call per 50 items. A rate-limited call
surfaces as an error naming the Retry-After delay.
uv sync # install deps (incl. dev group)
uv run ruff check . # lint
uv run ruff format . # format
uv run pytest # unit tests (acceptance auto-skipped)
uv run pytest --run-acceptance # + live read-only API checks (needs BREWFATHER_* creds)CI (GitHub Actions) runs the PR-title check, ruff lint/format, and the unit tests
on every PR; the CI Success job is the aggregate gate. Acceptance tests are not
run in CI — they need live credentials and stay local/manual. They are read-only
and never modify your brewing data.
MIT — see LICENSE.
Find batches by name (case-insensitive substring) and/or status.
``status`` is one of Planning, Brewing, Fermenting, Conditioning, Completed,
Archived; empty means any. Returns compact dicts:
{id, name, batch_no, status, brewer, brew_date, recipe}. Use the id with
get_batch / get_readings / update_batch.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| status | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses substring matching behavior, the full status enum, that empty means unfiltered, and the exact shape of the returned records. It does not mention ordering, result limits/pagination, or explicitly confirm the operation is a non-mutating read, which are minor gaps for this scope.
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?
Three tight sentences, front-loaded with purpose, then filter semantics, then return shape and id-usage. Every sentence earns its place with no filler.
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 low-complexity, zero-required-param finder with an output schema present, the description covers purpose, filtering, and routing. Minor omissions (ordering, pagination/limits) remain, and the enumerated return fields duplicate the output schema, but nothing needed to call it correctly is missing.
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 description coverage is 0%, so the description must compensate, and it does: name is case-insensitive substring, status accepts the enumerated values Planning/Brewing/Fermenting/Conditioning/Completed/Archived, and empty string means any. Both parameters gain meaning that the bare schema lacks.
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?
States a specific verb (Find) and resource (batches) plus the exact matching semantics: case-insensitive substring on name and/or status filter. An agent can immediately tell this apart from get_batch (fetch one by id) or find_recipes (different resource) 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to take the returned id and use it with get_batch / get_readings / update_batch, which gives clear downstream chaining context, and clarifies that an empty status means 'any'. It stops short of stating when-not to use it (e.g. against listing-only paths), so it's clear but not fully exclusionary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find recipes by name (case-insensitive substring; empty returns all).
Returns compact dicts: {id, name, author, type, style, equipment}.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It discloses read/search semantics, case-insensitive substring matching, empty-input behavior, and the compact return shape, but it does not mention pagination, ordering, auth needs, or rate limits.
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?
The description is two short, front-loaded sentences with no filler. Search semantics come first, and the return format is stated compactly.
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 one-parameter finder with an output schema, the description is nearly complete: it explains matching behavior and summarizes returned fields. It omits sibling routing, but the core behavior needed to call the tool correctly is present.
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 description coverage is 0% and there is only one parameter, so the description must carry parameter semantics. It does so by explaining that name is a case-insensitive substring and that an empty value returns all recipes, fully compensating for the schema gap.
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 states a specific verb and resource: "Find recipes by name." It also defines the search scope with case-insensitive substring matching and empty-returns-all behavior, but it does not explicitly distinguish this tool from the sibling get_recipe or explain when to prefer one over the other.
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 description gives clear usage context: search by name is case-insensitive, and an empty string returns all recipes. It does not, however, name alternatives such as get_recipe or state explicit exclusions, so the agent must infer sibling routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one batch: summary, fermentation/bottling dates, estimated targets (OG, FG, IBU, color), all measured values, and the embedded recipe (target stats + ingredient bill). Units are metric (SG, L, °C).
| Name | Required | Description | Default |
|---|---|---|---|
| batch_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully discloses the return payload shape and that units are metric (SG, L, °C) – genuinely non-obvious context – but says nothing about permissions, missing-batch behavior, or any embedding/aggregation side effects.
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?
A single front-loaded sentence starting with the verb and resource, followed by a compact units note. The long parenthetical enumeration is information-dense rather than wasteful, so it stays efficient without being padded.
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?
Given no output schema and no annotations, the enumeration of returned fields (targets, measured values, embedded recipe) supplies the return-value information an agent would otherwise lack. The only real gap is batch_id semantics, which the description leaves entirely to the schema.
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 0% and the single required parameter batch_id has no schema description. The description refers only to 'one batch' and never clarifies batch_id's expected format, source (e.g. from find_batches), or whether it is a UUID or human-readable name, so it fails to compensate for the coverage gap.
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?
States a specific verb and resource ('Read one batch') and enumerates exactly what is returned (summary, dates, targets, measured values, embedded recipe). The singular 'one batch' implicitly contrasts with the sibling find_batches, but no sibling is named explicitly, so it falls short of a 5.
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?
Usage is only implied: the agent can infer this is the fetch-by-id counterpart to find_batches, but the description never states when to prefer it over find_batches, get_readings, or get_recipe. No prerequisites or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a batch's sensor readings (hydrometer, e.g. Tilt/iSpindel), newest last.
Returns {total, readings: [{time, sg, temp, ...}]} with only the most recent
``limit`` readings (0 = all — can be thousands over a fermentation).
Temperatures are °C.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| batch_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses the return shape ({total, readings: [...]}), ordering (newest last), the limit=0 special case, the scale warning (can be thousands over a fermentation), and temperature units (°C). It does not mention read-only/auth expectations, which is a minor gap.
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?
Three tight sentences, front-loaded with the action and the return contract, with the limit and unit caveats following. Every sentence adds information an agent needs; nothing is filler.
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?
No output schema or annotations exist, yet the description supplies the return shape, ordering, units, and limit semantics — enough to invoke and interpret the call correctly. Only the absence of batch_id semantics and any auth/permission note keeps it from being fully complete.
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 description coverage is 0%, so the description must compensate, and it does for the critical parameter: limit's default behavior, its special value 0 = all, and the potential magnitude. batch_id is left unexplained, but its meaning is self-evident from the tool's framing.
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?
States a specific verb (Read) plus resource (a batch's sensor readings), with the domain clarified via concrete examples (hydrometer, Tilt/iSpindel). No sibling tool covers readings, so the agent can distinguish it immediately from get_batch or find_batches.
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?
Usage is implied by the resource name — you call it to read a batch's sensor data — but the description gives no explicit when-to-use framing, no mention of how it relates to get_batch, and no exclusions or prerequisites. Adequate but leaves routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one recipe: summary, target stats (batchSize, og, fg, abv, ibu, color, …) and ingredient bill (fermentables, hops, miscs, yeasts). Units are metric. Stats are as last saved in the Brewfather app, so they can be stale after update_recipe.
| Name | Required | Description | Default |
|---|---|---|---|
| recipe_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden, and it does disclose meaningful traits: read-only nature is implied by 'Read', the metric unit convention is stated, and the staleness-after-update_recipe caveat is a genuine behavioral warning. It stops short of auth/permission behavior or error conditions.
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?
Front-loaded with the core action in the first clause, and each subsequent phrase adds return-shape or staleness detail rather than filler. The parenthetical field list is slightly dense but earns its place by telling the agent what 'stats' and 'bill' contain.
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?
With no output schema, the description rightly compensates by describing the return payload (summary, stats, ingredient bill) and units. For a single-parameter read tool this is nearly sufficient; only identifier sourcing and error behavior are absent.
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 description coverage is 0% for the single required recipe_id, and the description adds no format, source, or example for that identifier. 'Read one recipe' does establish that exactly one identifier is needed, but no semantics beyond what the parameter name already conveys.
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?
States a specific verb and resource ('Read one recipe') and immediately enumerates the returned payload: summary, target stats, and ingredient bill. The scope ('one') implicitly separates it from find_recipes, so an agent can route 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the staleness note hints the tool is best called after data settles, and update_recipe is named as the cause of stale data. There is no explicit statement of when to prefer this over find_recipes or when not to call it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List inventory items of one kind: fermentables, hops, miscs, or yeasts.
Filter by ``name`` (case-insensitive substring) and/or ``in_stock_only``
(inventory > 0). Returns {id, name, inventory, type, supplier, ...}; amounts
are in Brewfather's stored metric units.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | ||
| name | No | ||
| in_stock_only | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does add real behavioral detail: 'name' is a case-insensitive substring match, 'in_stock_only' means inventory > 0, and amounts are in Brewfather's stored metric units. It stops short of noting read-only status, pagination, ordering, or result limits.
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 short sentences, front-loaded with the primary action and the required 'kind' domain before the optional filters and return note. Every clause carries information an agent needs; nothing is padding.
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 3-parameter read tool with an output schema already present, the description covers the required enum, filter semantics, and unit convention, so return values need not be restated. Minor gaps remain around pagination/result limits and explicit read-only confirmation.
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 description coverage is 0%, so the description must compensate, and it does: it supplies the four valid 'kind' values (absent from the schema), the case-insensitive substring behavior and default for 'name', and the precise meaning of 'in_stock_only' (inventory > 0). All three parameters are fully disambiguated.
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?
States a specific verb and resource ('List inventory items') and enumerates the exact 'kind' domain (fermentables, hops, miscs, yeasts), which is the only place those values appear since the schema has no enum. An agent can distinguish it from the sibling 'set_inventory' (a write) by name and scope alone.
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 description explains how to narrow results ('Filter by name ... and/or in_stock_only'), which implies the usage context. However, it never states when to prefer this over alternatives such as 'set_inventory' for inventory changes, nor any exclusions or prerequisites, leaving routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change the stock of one inventory item.
Pass exactly one of ``amount`` (set absolute stock) or ``adjust`` (add, or
subtract with a negative number — e.g. after brew day). ``kind`` is
fermentables, hops, miscs, or yeasts. Returns {item_id, result}.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | ||
| adjust | No | ||
| amount | No | ||
| item_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden. It usefully discloses the mutual-exclusivity rule and that 'adjust' accepts negative values (adding vs subtracting), plus the return shape. However it is silent on error behavior, whether the change is reversible, and any permission or concurrency constraints for a stock-mutating operation.
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?
Front-loaded first sentence states the action, followed by tightly scoped parameter guidance and the return shape in three short blocks. No filler sentences.
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 mutation tool with no annotations and no output schema, the description covers the parameter contract well and even summarizes the return value. The remaining gap is behavioral: error cases and side effects of the change are not addressed.
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 description coverage is 0% and all four params are undocumented in the schema, so the description must compensate. It explains amount vs adjust semantics (absolute vs additive, negative allowed), enumerates the valid kind values (fermentables, hops, miscs, yeasts), and states the one-of requirement — only item_id is left to inference, which is low-cost.
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?
States a specific verb+resource in one line: 'Change the stock of one inventory item.' It is clearly distinct from the sibling list_inventory (a read), but it never names or contrasts against siblings explicitly.
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 description gives operational guidance ('pass exactly one of amount or adjust') but says nothing about when to reach for set_inventory versus update_batch or list_inventory, and no prerequisites or exclusions are stated. Usage is implied rather than directed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a batch's status and/or measured values.
``status``: Planning, Brewing, Fermenting, Conditioning, Completed, Archived.
``measurements`` keys (metric only — gravities SG, volumes liters, temps °C):
measuredMashPh, measuredBoilSize, measuredFirstWortGravity,
measuredPreBoilGravity, measuredPostBoilGravity, measuredKettleSize,
measuredOg, measuredFermenterTopUp, measuredBatchSize, measuredFg,
measuredBottlingSize, carbonationTemp. Returns {batch_id, result}.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | ||
| batch_id | Yes | ||
| measurements | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It usefully discloses the return shape ({batch_id, result}) and the units expected for measurements, but says nothing about whether omitted fields are preserved (partial vs full update), permission requirements, or error behavior for a mutation tool.
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?
Front-loaded with the core action, then two clearly-labelled blocks for status and measurements. The measurement list is long but every entry is necessary because the schema does not enumerate it.
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 mutation tool with no annotations and no output schema, the description covers parameters well and gives a return shape. It still leaves partial-update semantics, permissions, and error conditions unaddressed for what is a write operation.
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 0% and the schema types are generic (bare string for status, untyped number map for measurements), so the description's value is high: it supplies the full allowed status enum and the exact measurement key names with their metric units. This fully compensates for the schema gap.
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?
States a specific verb+resource ('Update a batch') and names exactly what can be changed (status and/or measured values). An agent can distinguish it from update_recipe or set_inventory, though the description never explicitly contrasts them.
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?
There is no statement of when to use this tool versus get_batch, find_batches, or update_recipe, and no prerequisites or exclusions. The enumeration of status values and measurement keys aids invocation but not tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit a recipe's settings and/or ingredient bill.
``fields`` keys (metric — liters, minutes, percent): name, author, notes,
batchSize, boilSize, boilTime, efficiency. Stats (og, fg, abv, ibu, color)
can't be set; Brewfather computes them from the ingredients.
``ingredients`` is a list of changes, each with ``kind`` (fermentables, hops,
miscs, yeasts) and:
- ``index`` + fields to change an item — index is its 0-based position in
get_recipe's list, e.g. {"kind": "hops", "index": 1, "amount": 50};
- ``index`` + ``"remove": true`` to delete it;
- with ``index``, pass ``current_name`` (the item's name as get_recipe showed
it) and the change is rejected if the item there has a different name;
- no index to add one; needs name and amount, e.g. {"kind": "hops",
"name": "Citra", "amount": 30, "alpha": 12, "use": "Boil", "time": 5}.
Ingredient fields: name, amount (kg for fermentables, g for hops), unit,
type, use, time, alpha, color, potential, attenuation, form, laboratory,
origin, supplier.
Returns {recipe_id, result, note}.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | ||
| recipe_id | Yes | ||
| ingredients | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and does well: it discloses that this is an edit/mutation, that stats cannot be set because Brewfather computes them, and that ingredient changes can modify, remove, or add items with a name-check safeguard. It also describes the return shape, but omits operational details such as authentication requirements, rate limits, or whether unspecified fields are left unchanged.
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?
The description is front-loaded with the core action and then organized into clear, topic-specific paragraphs and bullet points. Although lengthy, every section appears to earn its place by specifying field constraints, ingredient mutation patterns, and parameter examples for a complex update operation.
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 three-parameter mutation tool with no annotations and no output schema, the description is complete enough for correct invocation. It covers the required recipe_id implicitly, fully explains the optional fields and ingredients parameters, lists ingredient fields, provides examples, and states the return object shape.
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 description coverage is 0%, so the description must compensate, and it does thoroughly. It enumerates allowed fields keys, metric units, disallowed stats, ingredient operation syntax with index semantics, remove/current_name behavior, add requirements, units by ingredient kind, and a concrete example. This adds substantial meaning beyond the bare schema.
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 a specific verb and resource: 'Edit a recipe's settings and/or ingredient bill.' It is clear what the tool does and distinguishes the mutation intent from read-only siblings like get_recipe and find_recipes. However, it does not explicitly name or compare against alternatives, so it falls short of the top score for sibling differentiation.
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?
Usage is implied rather than stated: the agent can infer this is for editing a recipe, and the description explains detailed mechanical usage of fields and ingredients. But it never says when to choose this tool over siblings like update_batch or get_recipe, nor does it state explicit prerequisites such as needing to call get_recipe first to obtain indices and current_name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0find_batchesfind_recipesget_batchget_readingsget_recipelist_inventoryset_inventoryupdate_batchupdate_recipeScored across 9 tools
Each tool targets a distinct resource+action pair: find/get/update for batches, get for readings, find/get/update for recipes, list/set for inventory. The find-versus-get distinction (search by name/status vs. read one by id) is spelled out in descriptions, leaving little room for misselection.
All tools use consistent snake_case verb_noun form and the read/update pattern repeats cleanly across batches and recipes. Minor deviation: retrieval uses three different verbs (find_*, get_*, list_*) and mutation uses both update_* and set_*, which is defensible but slightly inconsistent.
Nine tools is well within a comfortable range and the surface is tightly scoped to the domain's three entities (batches, recipes, inventory). Every tool earns its place with no redundancy.
Coverage is read- and update-heavy: batches and recipes can be searched, read, and edited, but there are no create or delete operations for batches, recipes, or inventory items. This is a notable lifecycle gap for an agent trying to start new batches or add recipes, though the operational update path is solid.
Gateway between LLM agents and world data through eight tools and a bundled endpoint catalog.
Give your AI agents the tools to build, manage, and run automation workflows.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Provides capabilities that let LLM agents perform a range of infrastructure management tasks.
