Loafy: Sourdough Bread Baking

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

Annotations already declare this is a non-destructive, non-idempotent write, so the safety profile is covered. The description adds value beyond them by disclosing the return shape ('Returns it with its id and a link') and an account prerequisite. It does not mention error/duplicate behavior, which would be the natural next step for a non-idempotent create.

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 short sentences, front-loaded with purpose and followed by return info and the prerequisite — well ordered and free of filler. Slightly verbose but every sentence carries information.

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 exists, and the description fills that gap by naming the returned id and link; all three parameters are schema-documented and the auth prerequisite is stated. Complete enough for a simple create tool, with only minor omissions around failure cases.

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 100%, so name, notes, and weight_grams are already documented in the schema. The description reinforces the weight parameter's meaning ('its empty weight in grams') but adds no syntax, bounds, or format detail beyond what the schema provides. Baseline 3 applies.

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 ('Add a container to the baker's Loafy account') and explains the domain purpose ('so Loafy can take it off when dough is weighed in it'). The resource noun 'container' cleanly distinguishes it from add_starter, update_container, and list_my_containers without needing to name 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?

Usage is implied by the purpose statement, and the prerequisite 'Needs the baker's Loafy account' is a genuine contextual hint. However there is no explicit when-to-use guidance, no when-not, and no reference to alternatives like update_container for modifying an existing one.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Annotations already declare it is a non-destructive, non-idempotent write (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds real context beyond them: the auth/account requirement and, importantly, what is returned (the starter with its id and a link where photos are added) — valuable because there is no output schema.

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 compact sentences, front-loaded with the action and resource, and the prerequisite/return details are appended rather than buried. The return clause is slightly convoluted ("a link, where photos are added") but nothing is wasted.

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 simple single-object create tool with full schema coverage and annotations covering the safety profile, the description supplies the missing pieces: the account prerequisite and the shape of the response. Only explicit sibling routing and any failure/validation 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 100%, so the schema already documents name, notes, story and birthday (including the YYYY-MM-DD format and today-default). The description restates the same fields in prose without adding format, constraint or interaction details, so the baseline 3 applies.

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 ("Add") and resource ("sourdough starter") scoped to the baker's Loafy account, and enumerates the payload fields. It is clearly a creation tool, distinct from update_starter and list_my_starters by verb and noun, though it never explicitly names or routes to those siblings.

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: an agent can infer this is for creating a brand-new starter rather than modifying an existing one, but no when-to-use/when-not-to-use guidance or explicit alternative (e.g. update_starter) is given. The prerequisite note ("Needs the baker's Loafy account") is helpful but is a condition, not routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Annotations already declare readOnly/idempotent/non-destructive/non-open-world, so safety is covered. The description adds genuinely useful behavior the annotations cannot: the exact return contents (flour, water, starter, salt) and the fact that a loafy.ai link is included for adjustment and timers.

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, no filler, with the calculation purpose front-loaded and the return value stated second. Every clause carries information an agent would otherwise have to guess.

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 correctly steps in to describe the returned values and the external link, which is what an agent needs to chain this tool. The only small gap is that whole_grain_percent is a parameter never acknowledged in the description.

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 100% and the property descriptions are unusually rich (loaf_size_g explains flour-vs-dough-weight with a worked example). The description restates three of the four inputs and omits whole_grain_percent, so it adds little beyond the schema; baseline 3 applies.

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 (calculate) and a specific resource (sourdough bread recipe), plus the three driving inputs, so an agent knows exactly what comes out. It does not differentiate itself from the sibling calculate_pizza_dough or from plan_sourdough_bake, so it stops 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?

There is no when-to-use or when-not-to-use guidance and no named alternative, even though calculate_pizza_dough and plan_sourdough_bake are close siblings. Usage is only inferable from the verb 'Calculate', which is the same level of guidance as the mid-tier calibration example.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds genuinely new context: the exact outputs produced (flour, water, salt, leavening, toppings) and the fact that a loafy.ai recipe link accompanies them, which matters since no output schema exists.

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 dense sentence that front-loads the core action and inputs, then appends the return payload. No filler, no repetition of the title.

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 compensates by enumerating the returned values, and the 100%-covered schema handles the inputs. The only real gap is the absence of sibling routing guidance, which an agent would still need.

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 100%, and the schema documents every parameter including enum meanings, defaults, and the weight-follows-oven rule. The description only restates the input dimensions at a high level, adding no syntax or format detail beyond the 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?

Specific verb (calculate) + resource (pizza dough) with the exact inputs (pizzas, ball weight, hydration) and the two leavening modes named. An agent can distinguish it from the sibling calculate_bread_dough purely from the text.

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 implies its use case (scaling a pizza recipe by count and ball weight) but never states when to pick this over calculate_bread_dough or the sourdough planning tools. No exclusions or prerequisites are given, so routing is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial behaviour beyond that: the no-match fallback returns closest book passages, results are English-only, and unauthenticated use is rate-limited to 3 questions/day with a 15-minute lookup window counting as one. These are exactly the operational traits an agent cannot get from the annotations.

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?

Purpose and fallback behaviour are front-loaded, and the rate-limit and scope sentences carry non-obvious operational information rather than filler. The prose is dense and slightly long, but every sentence adds a distinct fact an agent would otherwise lack.

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 carries the return-value burden and does so: matching answers with the backing book chapter and a link, or closest book passages when nothing matches. Combined with the topical scope, language, and auth/rate-limit context, nothing essential for correct invocation 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 100%, so both `query` and `limit` (default 3, max 10) are fully documented in the schema. The description adds no syntax, format, or semantic detail about either parameter, so the baseline 3 applies.

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?

It states a specific verb and resource ('Search Loafy's library of answers to real questions from bakers'), names the author and grounding source, and describes the topical coverage (starters, fermentation, dough, flour, baking, storage). This clearly separates the answers library from raw book content, though it never explicitly names the sibling search_sourdough_book as the contrasting alternative.

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 English-only note, the fallback-to-book-passages behaviour, and the mention that 'calculators, guides and the book's table of contents need no account' hint at where this tool stops and siblings begin. However, there is no explicit 'use this instead of search_sourdough_book when...' routing or exclusion, leaving the agent to infer the boundary against three closely related book tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable payload context (per-chapter word lengths, chapter/section numbering) that the annotations do not convey, though it says nothing about pagination or format of the returned structure.

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 core purpose, then the routing hint, then the topical scope. Nothing is redundant and each sentence carries information.

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 carries the burden of describing the return value and does so (chapters, sections, numbers, word counts). For a zero-param, read-only browse tool, this is sufficient.

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?

The tool takes zero parameters, so the baseline is 4; there are no parameter semantics for the description to compensate for.

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 resource (the table of contents of a named book) and what it contains (chapters, sections, numbers, word lengths). An agent can distinguish it from read_sourdough_book and search_sourdough_book without opening either 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?

The sentence 'read_sourdough_book returns any of them in full' implicitly routes the agent: use this to browse/select, use read_sourdough_book to fetch full text. It names the alternative but does not state an explicit when-to-use condition or exclusion beyond that.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so safety is covered. The description adds genuine behavioral context by detailing exactly what is returned (title, position, timer-in-minutes, opening link) and flagging that the instructions/timer run on the page, which is valuable given no output schema.

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 tight sentences, front-loaded with the action and the return fields, then the pointer to the page. No filler; every clause 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 simple two-parameter read tool with no output schema, the description does the heavy lifting by enumerating the returned fields and clarifying where the actual instructions live. Only minor gaps remain (nothing on response shape/ordering beyond the fields listed), but it is complete enough to call correctly.

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 100%, so both parameters are already documented, including the 'first step returned' default. The description's 'by its id or its position' restates the schema's identifier-or-position semantics without adding format detail or edge cases beyond it, so the baseline 3 applies.

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 (look up) and resource (one step of a guided journey) and enumerates the fields returned (title, position, timer, link). This clearly separates it from siblings like list_sourdough_journeys or read_sourdough_book.

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 fetch-one-step framing and the note that instructions live on the page rather than here, which gently steers the agent away from expecting body text. However, it never states when to use this versus list_sourdough_journeys or start_sourdough_journey, and names no alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context beyond annotations: the fields returned (recipe figures, rating, problems, notes, id, link), the newest-first ordering, and the account requirement.

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 dense sentence carries the resource, ordering, returned fields and identity fields, with a short second sentence stating the account prerequisite. Front-loaded with the resource and free of filler, though the first sentence is long.

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 usefully enumerates the returned fields, ordering and account requirement. Combined with the fully documented parameters, an agent has what it needs to call the tool; only explicit alternative-routing guidance 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 100%, so both parameters (limit, bake_type) are fully documented in the schema, including the default and max for limit and the enum for bake_type. The description's 'newest first' merely echoes the schema's ordering note and adds no syntax or format detail beyond it, so the baseline 3 applies.

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 names a specific resource (the baker's own bakes from their Loafy bake journal) and its scope, which separates it from book/search siblings and from get/update_bake. The listing verb is only implied by 'bakes ... newest first' rather than stated, so it falls just short of a clean verb+resource phrasing.

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: the 'own bakes' scope and 'newest first' ordering signal this is the personal-journal retrieval tool rather than a search or a single-record fetch. However, no sibling is named and no explicit when/when-not guidance is given, so an agent must infer the routing itself.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world, non-destructive), so the bar is lowered; the description still adds value by disclosing the exact data returned (name, empty weight in grams, notes, id, link) and the account prerequisite. It does not, however, mention ordering, count limits, or what happens with zero containers.

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 core identity is front-loaded and only one sentence long, but it is comma-heavy and packs the return fields, a semantic aside about empty weight, and the auth requirement into a single run-on clause. It earns its length but could be split for readability.

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 usefully compensates by listing the returned fields and explaining what empty weight means, and it notes the account requirement. For a simple zero-parameter, read-only list tool this is nearly complete; only pagination/ordering behavior is left unstated.

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?

The tool takes no parameters, so the baseline is 4; the description correctly supplies no parameter information beyond the implicit account context. Nothing is missing that could be documented.

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 identifies the specific resource ('the baker's own containers in Loafy') and even enumerates the fields returned, so an agent can distinguish it from siblings like list_my_starters and list_my_bakes. The listing action itself is only implied by the name rather than stated with an explicit verb, keeping it just 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?

It states the prerequisite ('Needs the baker's Loafy account'), which is genuine usage context, but it never says when to call this versus the other list_* siblings or whether any filtering exists. Usage is inferred from the resource name rather than spelled out.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value beyond them by disclosing the authentication requirement (a Loafy account) and by previewing the returned content, though it says nothing about result size or pagination.

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 naming the resource and its contents, followed by one short prerequisite sentence. No filler, and the most important identifying information comes first.

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 carries the burden of describing return values, and it does so by listing the fields each starter carries plus id and link. Combined with the auth note, an agent has what it needs; only pagination/volume behavior is unaddressed.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The field inventory describes output rather than input, which is harmless here.

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 names a specific resource (the baker's own sourdough starters in Loafy) and enumerates the fields returned, which lets an agent distinguish it from list_my_bakes and list_my_containers. It never states the verb 'list' outright, but the name plus the content inventory make the operation unambiguous.

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 prerequisite 'Needs the baker's Loafy account' gives a usable condition for calling it, but there is no guidance on when to prefer this over sibling tools or on any exclusions/limits. Usage is implied rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds value beyond them by disclosing the return payload (slug, title, duration, difficulty, step count, link) in the absence of an output schema, plus that journeys are timed walkthroughs hosted on loafy.ai.

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 tight sentences with zero waste: the first defines the resource, the second describes the return shape. Front-loaded and appropriately sized for a zero-argument list tool.

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 compensates by enumerating the returned fields and clarifying the nature of the resources. For a parameterless read-only list tool, nothing an agent needs to invoke 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?

The tool takes zero parameters, so the baseline is 4. There is no parameter syntax the description could or should add, and nothing in the text misleads about inputs.

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 ('List Loafy's guided sourdough journeys') and clarifies scope as the catalog of guided walkthroughs rather than the user's own data, which cleanly separates it from siblings like list_my_bakes and list_my_starters.

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: an agent can infer you list journeys before calling start_sourdough_journey or get_sourdough_journey_step, but neither the alternative tools nor the condition for choosing this one is stated. No exclusions or when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Annotations already declare the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the bar is lower. The description adds genuinely useful context beyond them: it returns the new entry with a link, photos are attached via that link, and an account is required. It does not say what happens on repeated calls despite non-idempotency.

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, front-loaded with the action and resource, with the return format and account requirement appended. No filler, though the single dense colon-list sentence packs several ideas together.

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 16-parameter mutation tool with no output schema, the description usefully covers purpose, return value, photo-link workflow, and the auth prerequisite. It does not clarify that all parameters are optional or how blank/omitted fields behave, which is a minor gap given the tool's complexity.

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 100%, so all 16 parameters are documented in the schema and the baseline is 3. The description's phrase 'the recipe figures, how it went and what to try next time' loosely maps to the hydration/salt/starter/temperature groups, notes/rating, and next_time_notes, but adds no syntax or default detail beyond the 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 gives a specific verb and resource ('Add a bake to the baker's Loafy bake journal') and enumerates the content scope (what was baked and when, recipe figures, outcome, next steps). An agent can distinguish it from list_my_bakes or plan_sourdough_bake, though it never names the closest sibling (update_bake) to draw a hard boundary.

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 'Add a bake to the journal,' and one prerequisite is stated ('Needs the baker's Loafy account'). However, there is no explicit guidance on when to use this versus update_bake (editing an existing entry) or plan_sourdough_bake, leaving the agent to infer the boundary.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Annotations already establish this is a read-only, idempotent, non-destructive, closed-world computation, so the safety bar is low. The description still adds real value by disclosing the return shape (the times plus a link to the plan on loafy.ai) and the underlying rule set (The Sourdough Framework), which no structured field provides since there is no output schema.

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, front-loaded with the core purpose and the backward-planning method, then the return value. The first sentence is long but dense with genuine content rather than padding; nothing reads as 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 read-only planner with 4 well-documented parameters and no output schema, the description covers the process, the inputs' roles, and what comes back. It stops short of edge-case behavior (e.g. a ready_at in the past or the book's default assumptions when optional params are omitted), but that gap is minor.

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 100%, so the baseline is 3, but the description adds meaning beyond the field descriptions: it frames ready_at as the anchor that everything is computed backwards from, and states that kitchen temperature drives how much starter is used. These causal relations are not spelled out in the schema itself.

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 names a specific verb and resource ('Plan a sourdough bake') and pinpoints the exact computation: working backwards from oven-out time to feed, mix, shape, proof, preheat and bake. This is clearly distinct from siblings like calculate_bread_dough or log_bake, which handle ingredients or recording rather than scheduling.

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?

It gives a clear triggering condition — the baker knows when the bread should come out of the oven and wants the full schedule. However, it names no alternative tool (e.g. calculate_bread_dough for ingredient amounts) and states no 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.

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

Annotations already cover the read-only/idempotent/non-destructive profile, and the description adds substantial context on top: return contents (text, chapter, link, licence), the ~40,000-character pagination trigger, and the 3-questions-per-day limit with a 15-minute coalescing window for anonymous users. That rate-limit and auth disclosure is genuinely useful behavioral information not present in the structured fields.

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 sentences, front-loaded with purpose before return behavior and access constraints, and no sentence is filler. It is dense but each clause carries information an agent needs (identifier source, pagination, quota).

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 steps in to describe the return payload (text plus chapter, link and licence) and the pagination behavior of long chapters. Combined with the quota/auth constraints, an agent has everything needed to invoke this correctly and interpret the result.

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 100%, so the baseline is 3, but the description goes beyond the schema by explaining why `page` exists - chapters longer than ~40,000 characters come in pages - which the schema's one-line description does not convey. It adds meaning without contradicting the schema's type/bounds.

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) and resource (a chapter/section of The Sourdough Framework), and pins the identifier source to get_sourdough_book_contents, cleanly separating it from search_sourdough_book. An agent can tell what this does and where the `part` value comes from 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 routes the agent to get_sourdough_book_contents for chapter numbers and clarifies that the table of contents, guides and calculators need no account, which sets expectations about prerequisites. It never names search_sourdough_book as the alternative for lookup-by-topic, so the when-not-to-use side is only implied rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, and the description adds substantial context beyond them: the English-only matching behavior, the account gating, the exact quota (3 questions/day, with any lookup inside 15 minutes counting as one), and what a result contains. This is exactly the behavioral disclosure the annotations cannot 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?

Front-loaded with the core action and the key sibling distinction, and every sentence carries information (coverage topics, language, quota, account boundary). The first sentence is a long chain of clauses that could be split, which costs it the top score.

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 correctly explains the return shape (passages with chapter, link and source part), the result cap, the language of matching, and the access limits. An agent has everything needed to call it and interpret the response.

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 100%, so both parameters are already documented with examples and defaults. The description only restates the English-language constraint on the query and says nothing new about the limit parameter, so the baseline 3 applies.

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 (search) and resource (The Sourdough Framework), and explicitly distinguishes itself from the sibling read_sourdough_book by noting it returns passages while that tool returns full text. The scope (chapter, link, source part) and topic range are named, 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?

Names the complementary alternative (read_sourdough_book) and its relationship to this tool, plus explains that calculators/guides/table of contents need no account, which frames when this paid-limited search is worth using. It does not, however, distinguish itself from the sibling find_sourdough_answer, leaving one obvious routing question open.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds useful context that the journey is executed externally on loafy.ai with timed steps, but says nothing about auth requirements, whether a session is created server-side, or what happens on repeat calls.

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, front-loaded with the action and the returned artifact. The second sentence's 'each fold, proof and bake is timed for the baker' is mildly promotional rather than operational, but it is short and does convey that the journey is time-guided.

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?

There is no output schema, yet the description tells the agent what it gets back (a link that opens the journey at the first step), which is the main thing missing from structured fields. It is complete enough for a simple one-parameter tool, with only prerequisite/permission details 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 coverage is 100% and the single slug parameter is fully documented in the schema, including its source (list_sourdough_journeys) and an example value. The description adds no parameter detail beyond that, so the baseline 3 applies.

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 ('Start') and resource ('guided journeys') and adds the key outcome: a link that opens the journey at its first step. This distinguishes it from list_sourdough_journeys and get_sourdough_journey_step, though it doesn't explicitly name those siblings.

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 implies you pick 'one of' the journeys, and the schema points to list_sourdough_journeys for the slug, but the description itself gives no explicit when-to-use, prerequisites, or when-not-to-use guidance. Usage is inferable rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Annotations already declare destructiveHint=true and idempotentHint=true, yet the description adds real value: partial-update semantics (only supplied figures/notes change), the fact that supplied text overwrites old text, an explicit no-delete assurance, the returned value shape, and the account requirement. These go well beyond the annotation flags.

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-loads the verb and resource, then packs mutation semantics, replacement rule, safety note, return value and auth requirement into a few compact clauses. Slightly run-on with one colon-chained sentence but 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 17-parameter mutation tool with no output schema but full annotation coverage, the description covers the operation's scope, safety, and result. It could go further on why it is idempotent or what a returned "link" contains, but nothing essential 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 100%, so per-field semantics are already documented and the baseline is 3. The description adds the cross-parameter rule that omitted fields are preserved and text inputs replace existing text, which materially affects how an agent chooses to populate the 17 fields.

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 ("Change a bake in the baker's Loafy bake journal") and immediately disambiguates it from the create path by naming the sibling sources of the id (list_my_bakes, log_bake). An agent can distinguish it from log_bake/update_container 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?

Gives clear context: use it with an id from list_my_bakes or log_bake, and only the fields supplied change while the rest stays. It does not state explicit when-not conditions or name a competing sibling directly, so it stops short of a full routing rule.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Adds real behavior beyond the annotations: partial-update semantics ("only the name, weight or notes given change"), text replacement ("a text given replaces the old text"), and the guarantee that "No container is deleted." It also notes the auth context ("Needs the baker's Loafy account"). The overwrite/replace disclosure aligns with destructiveHint=true rather than contradicting it.

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?

One sentence, front-loaded with the action and id source, with no boilerplate. The clause "only the name, weight or notes given change" is slightly tangled in wording but carries needed semantics.

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 output schema, the description covers the essential concerns: target identification, partial-update behavior, overwrite semantics, no-deletion guarantee, and account requirement. Return shape is unspecified, which is a minor residual gap given no output schema exists.

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 100%, so the baseline is 3, but the description adds meaning the schema does not encode: that unspecified fields are left untouched and that supplied text overwrites the previous value. It also names the three mutable fields in prose, reinforcing the schema's parameter set.

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?

Names a specific verb+resource ("Change one of the baker's containers") and pins the target by id source (list_my_containers), distinguishing it from the sibling update_bake/update_starter tools that act on different resources.

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?

It tells the agent where the required id comes from (list_my_containers, echoed by add_container in the schema) and clarifies the tool is for modifying an existing container. It stops short of explicitly routing the agent to add_container when no container exists yet, so no exclusion is stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true and openWorldHint=false, so safety is partly covered. The description adds genuine context beyond them: omitted fields are left untouched, supplied text overwrites the previous value, and no starter is deleted. That 'No starter is deleted' note does not contradict destructiveHint=true, since the destructive behavior is the field-value replacement, which the description explicitly discloses.

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 compact sentence front-loads the verb and resource before the id source and the update semantics, so the key facts come first. The phrasing 'a text given replaces the old text' is slightly awkward and the closing auth note is tacked on, keeping it out of the top band.

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 5-parameter mutation tool with full schema coverage, no output schema and rich annotations, the description covers the essentials: identity of the target, partial-update semantics, non-deletion, and the account requirement. It omits error behavior for an unknown id and whether the updated starter is returned, which are minor gaps given the structured fields available.

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 100%, so the baseline is 3; the description earns above baseline by explaining the update contract that the per-field schema entries do not: only the fields actually supplied are changed and a supplied text replaces the old text. It doesn't add format details (e.g., the YYYY-MM-DD convention is left to the 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?

States a specific verb (change) and resource (starter), scoped to the baker's own starters, and tells the agent where the required id comes from (list_my_starters / add_starter). The clause 'only the name, birthday, notes or story given change' immediately separates it from add_starter and list_my_starters by defining the partial-update behavior.

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?

Gives a clear precondition ('by its id from list_my_starters') and an auth requirement ('Needs the baker's Loafy account'), which is enough context to invoke it correctly. It does not state when not to use it (e.g., versus add_starter for creating a new starter), so it stops short of a full when/when-not routing statement.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.