Glazecalc

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

Beyond annotations, it discloses append-only semantics, preservation of existing rows, version retention, a 500-row cap, data-fidelity constraints, and the access-token requirement. These are specific behavioral and safety details that the annotations alone do not 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?

The purpose is front-loaded and the sentences mostly earn their place by covering scope, versioning, limits, data fidelity, and auth. However, the first sentence is dense with parentheticals and the fragment 'At most 500 rows a log' slightly weakens flow.

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 with no output schema, the description supplies enough: it explains what is added, how existing data is treated, limits, versioning behavior, and auth needs. The schema covers the conditional rev semantics, so nothing critical 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 coverage is 100%, so the schema already documents id, rev, and rows. The description reinforces id sourcing and row layout but does not add meaning for rev or otherwise go beyond the schema descriptions.

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: it adds rows to the end of a named firing log, with the id sourced from list_firings. It also clarifies that this is for readings dictated during a firing, distinguishing it from log creation or retrieval 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?

It gives clear context for use: you need an id from list_firings and columns from get_firing, and the rows are the readings during a firing. It does not explicitly say when to choose create_firing_log instead, or name other alternatives, so it misses full 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 this as a non-idempotent write that is not destructive. The description goes further by naming the destination (Materials page) and stating the auth requirement ('an access token that can read and change your records'), which the structured fields do not convey. It does not describe error or duplicate-name behavior.

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 the core action and effect, with no filler. Slightly padded by the auth sentence and the loss-on-ignition clause, which is already in the schema, but overall efficient.

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 five-parameter mutation with no output schema, the definition omits what the call returns (presumably the created material) and gives no duplicate-name or validation-failure behavior. The destination and auth context are covered, but the return surface is left unspecified.

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 60%; loi, analysis and language are already documented in the schema, while name and notes are not. The description restates the oxide-in-weight-percent format, adding little beyond the schema's own example, so it only partly compensates for the undocumented parameters.

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: it saves a material of the user's own into their Glazecalc account from an oxide analysis. The scope is narrow enough to separate it from add_to_shelf or add_notebook_entry, though it never names those 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?

Downstream context is given ('Recipes can then use it by name'), which implies when to reach for it, but there is no explicit guidance versus update_my_material or list_my_materials, and no note that repeat calls create duplicates. 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 readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the description's added value is the authorization requirement ('an access token that can read and change your records') and the destination of the write (the Notebook page). It does not say whether the write is reversible or what is returned, which keeps it below a 5.

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, purpose front-loaded, with the `about` variant explained second. The phrasing 'With about, it is a note about one of your recipes' is slightly clumsy and restates the schema's `about` description, 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 3-parameter append operation with no output schema, the description covers purpose, the record-linking case, and the auth requirement, which is enough to call it correctly. The main omission is any hint about what the response contains (e.g., the new entry's id or how to locate it later beyond list_notes).

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 67%, and the description compensates by naming `title` as optional and clarifying that `about` turns the entry into a note about a specific recipe, material, or firing log, retrieved later via list_notes. The `content` parameter's only added meaning is the example content types, which the schema already 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?

Specific verb+resource: adds an entry to the Glazecalc notebook, with concrete content examples (test result, observation, firing to try) and an explanation of the record-linking variant. It does not, however, distinguish itself from sibling creation tools like add_firing_rows, add_to_shelf, or add_my_material, so an agent must infer the boundary from names 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 gives examples of what belongs in an entry and explains that the `about` parameter is used when the note concerns a saved recipe/material/firing, which implies when to supply it. It never states when to use this tool instead of a sibling creation tool, and there are no exclusions or prerequisites beyond the auth note.

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 flag this as a non-readOnly, non-idempotent mutation; the description adds real value on top by disclosing reversibility ('the shelf as it was is kept: undo_shelf_change puts it back') and an auth requirement ('needs an access token that can read and change your records'). It omits the duplicate-add behavior implied by idempotentHint=false, but the key behavioral facts are covered.

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, purpose front-loaded, each sentence carrying distinct information (what it does, its role, reversibility, auth). Slightly dense phrasing in the first clause 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 single-param mutation with no output schema, the description covers purpose, downstream role, reversibility and auth, which is close to everything an agent needs. It doesn't state the return shape (e.g., what's confirmed after the add), the one remaining minor gap.

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 param is documented as 'The materials, by name.' The description still adds meaning by clarifying that names may be the library's names or the user's own materials, which helps an agent supply valid values rather than guess.

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 (marks materials as on hand) and resource (materials/shelf), and defines the fuzzy term 'on hand' by tying it to the sibling capability 'Match with what I have'. It also distinguishes itself from undo_shelf_change, so an agent can place it in the family without opening schemas.

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 for use (populating the shelf that match_with_what_i_have reads from) and points to undo_shelf_change as the reversing action. It stops short of an explicit when-not-to-use or a contrast against add_my_material, but the usage situation is unambiguous.

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 read-only, idempotent, closed-world behavior, so the description's job is to add analytical context — and it does: it discloses that results mirror the Glazecalc app and that Stull placements are illustrative rather than predictive, citing the cone 11 fixed-flux test basis and warning the crazed region is not a fit test. That is meaningful interpretive guidance an agent would otherwise get wrong.

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 is front-loaded in the first sentence and outputs are enumerated efficiently, but the second half is a sprawling three-clause sentence on Stull caveats that repeats the 'guide, not a promise' idea twice (regions move / not a test of fit). It could be trimmed by a third without losing instruction value.

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, so the description carries the burden of telling the agent what comes back, and it does so by enumerating every reported quantity including the Stull region labels (unfused, matte, semi-matte, bright, underfired). For a computationally complex tool this is close to complete, missing only response shape/structure detail.

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%, covering line structure, material naming, analysis fallback and language tags, so the schema does the heavy lifting. The description adds nothing about the parameters (no clarification of units, colorant exclusion, or language fallback behavior), so 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?

Names a specific verb and resource and enumerates what the analysis produces (unity/Seger formula, oxide groups, silica:alumina ratio, fired analysis, LOI, calculated thermal expansion) plus the Stull output. It does not explicitly distinguish itself from siblings like check_limits or compare_recipes, 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?

The Stull paragraph implies this is an interpretive/educational analysis ('a guide to the surface, not a promise') and lists conditions under which the Stull regions are unreliable (cone other than ~11, boron, other fluxes). There is still no explicit statement of when to choose this tool over check_limits, solve_target or compare_recipes.

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 safe-read profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: it discloses the exact payload of each tile (shares, unity formula figures, silica:alumina, expansion, Stull position, cautions, coneFit verdict), the 21-tile ceiling, and the limits-not-checked-above-cone-12/coneFit-only-06-to-10 caveats. The 'calculation from published figures, not a test result' disclaimer is useful framing the annotations cannot supply.

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 both blend modes are front-loaded in the first sentence, and every later clause carries information (inputs, outputs, caveats). The long mid-sentence enumeration of returned figures is dense and would read better as a list, but nothing is redundant.

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 takes on the burden of describing returns and does so thoroughly, plus the safety and firing-range caveats. The only shortfall is that it doesn't explain how firing/limitSet/language interact with the verdict fields, though the schema already documents those parameters.

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; the description still adds meaning by tying a/b/c to their geometric corners (first tile/top of triangle, last tile/bottom left), explaining that steps counts tiles for a line but rows for a triangle, and flagging the steps=2 comparison behavior and the no-colorants constraint on the recipe arrays.

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: it works out the test tiles of a line blend between recipes a and b, or a triaxial blend when c is given. The 2–11 / 2–6 step bounds and the Glazecalc Blends page reference make the scope unambiguous and distinguish it from compare_recipes and vary_material.

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 shapes usage within the tool well (leave c out for a line, give it for a triangle; give base materials only, no colorants) and notes that two recipes with steps 2 yields an oxide-by-oxide comparison, hinting at compare_recipes. However, it never names an alternative tool or states when to prefer one, so an agent must infer the 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 establish this as a safe read-only, idempotent, closed-world operation, and the description still adds substantial behavioral detail: what limitsNote reports, the exact coneFit verdicts ('cooler', 'hotter', 'fits', 'skipped') and their conditions, the weak 'soft' strength for cone 6 vs 10, that 'fits' is not a pass, and that Stull regions shift with cone/flux. The closing caveat that these are published-figure cautions, not a test or food-safety guarantee, is exactly the kind of expectation-setting an agent needs.

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?

It is one dense paragraph with long parenthetical asides and trailing ellipses ('rising expansion...'), and the cone-12-and-up no-limits fact is asserted twice. Most sentences do carry real information, but the lack of front-loading and grouping by parameter/return field makes it harder to scan than it needs to be.

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 complex tool with nested objects and no output schema, the description does substantial work by naming the returned concepts (limitsNote, coneFit with verdicts, strength, stull) and their interpretation. It stops short of a full return-value description, so an agent still infers the overall response shape, but nothing essential for calling 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 100%, so every parameter, including the nested firing object and limitSet defaulting, is already documented in the schema. The description reinforces consequences (leaving firing out, no limits from cone 12 up, limitSet falling back to account preferences) but adds little syntax or semantics not present in the schema. Baseline 3 applies when the schema does the heavy lifting.

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 opening clause gives a specific verb and resource: 'Checks a glaze recipe for what is past a recommended limit for its firing', and it enumerates the limit categories (boron, alkali, alumina, clay, expansion). It also distinguishes itself from analyze_recipe by noting stull is reported 'as analyze_recipe gives it'. The core purpose is clear, though the surrounding clauses about coneFit and Stull caveats dilute the focus.

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 rich applicability context: which cone bands are checked, that 'top' band limits are not checked, that coneFit returns 'skipped' for lead/lithium/raku and cones 01-3, and that limitSet choices come from account settings. What it never frames explicitly is a routing rule against siblings (e.g. when to call check_limits versus analyze_recipe), so the guidance is contextual rather than directive.

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 safety profile, and the description goes well beyond them: limits are not checked from cone 12 up, the cone check judges only cone 06 to 10, saved-recipe ids require being signed in, unsupported languages fall back to English, labels are echoed back, and the result is a calculation rather than a fired test. Those are exactly the behavioral caveats an agent needs before trusting or relaying the output.

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 is front-loaded in the first clause, which is good, but the description then becomes one enormous sentence enumerating return fields down to the 0.3 x10^-6 per °C expansion threshold. Since an output schema exists, much of that enumeration is redundant and makes the definition hard to scan; the closing note about firing tiles is characterful but adds length without operational value.

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 an output schema present and 100% parameter coverage, the definition still supplies the things structured fields cannot: input-mode exclusivity, signed-in requirements, limit-checking and cone-verdict boundaries, and the calculation-versus-test caveat. A reader has everything needed to call it correctly; only a brief note on result size or cost would be 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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: a and aRecipeId are alternatives for the same side ("one or the other for each side"), and limitSet is defined by reference to how check_limits takes it. These are useful disambiguations rather than restatements.

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 opening sentence gives a specific verb and resource (compares two glaze recipes side by side) and immediately enumerates the comparison axes: unity formula, flux ratio, silica:alumina, expansion, Stull placement, cautions, coneFit. It also explicitly distinguishes itself from the sibling blend_recipes, so an agent can separate it from analyze_recipe or check_limits without opening any 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?

It states the two accepted input modes per side (raw lines via a/b, or saved recipe ids from list_recipes when signed in) and explicitly positions itself as the same computation as blend_recipes "under a name that is easy to find", which is real routing guidance. It also constrains scope (base materials only, no colorants). What it lacks is an explicit when-not-to-use, e.g. pointing at check_limits or analyze_recipe for single-recipe or limits-only work.

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 read-only, idempotent, non-destructive behavior, so the bar is lower. The description goes beyond them by disclosing data-coverage limits: which charts exist, their source and firing-rate assumptions, and that Orton publishes nothing above cone 14, so high cones return no figure. That tells the agent when the tool will come up empty, which is real behavioral value, though nothing is said about result formatting.

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 first and last sentences are well placed and front-load the essential operation, but the middle is a dense provenance block about chart editions and firing rates that is hard to parse and pushes the invocation hint to the end. The detail is arguably useful given no output schema, yet it is not structured or scannable.

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 four-parameter conversion tool with 0% schema coverage and no output schema, the description covers chart semantics and cone ranges reasonably well and hints at nearest-cone matching. It is still incomplete on temperature-parameter behavior, cone string format, and what the returned conversion actually contains.

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 carry the parameter burden. It does explain the `chart` enum values (Orton vs SK, JIS R 8101) and the cone ranges per chart, and it hints that a cone or a temperature is supplied. However, `celsius` and `fahrenheit` are never mentioned, nor is their mutual exclusivity or the cone string format, leaving half the parameters undocumented.

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 opening sentence gives a specific verb and resource pair: converts between pyrometric cones and temperature, and between °C and °F. That is unambiguous and clearly distinct from the material/recipe siblings. It stops short of explicitly naming an alternative tool, but the domain is obvious enough that no sibling could be confused with it.

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 only operational guidance is the closing 'Give a cone, or a temperature to find the nearest cones,' which hints at input modes but never states when to choose this tool, when not to, or which chart value to pick. No prerequisites or exclusions are given, so the agent must infer everything about selection.

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 description's main added value is the authorization requirement ('access token that can read and change your records') and the no-fabrication rule. What it does not disclose is the result of a successful call — no id or confirmation of what was created — which matters because add_firing_rows is the natural next step.

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 action and resource, then the field inventory, then the sibling routing, then the guardrail — a sensible ordering. It runs as one dense paragraph and the field list slightly repeats the schema, but almost every clause carries usable instruction.

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 6-parameter write tool with no output schema, the description covers inputs, auth, and the follow-up path, but says nothing about what the call returns (e.g., a log id needed to call add_firing_rows or link_firing). That omission leaves a real gap for an agent chaining to siblings.

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 every parameter is already documented in the schema (including date format, column-order rows, and empty-string convention). The description's paraphrase adds no format or syntax detail beyond that; the phrase 'as the person dictated them' reinforces intent but isn't new semantics.

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 ('Saves a new firing log ... the Firing page') and enumerates exactly which fields constitute the log (title, day, kiln, columns, rows). It also explicitly separates itself from the sibling add_firing_rows, which handles later readings, so an agent can route correctly 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?

Gives a clear creation-time condition and names the alternative tool for the follow-up case ('Add later readings with add_firing_rows'). It also adds an explicit boundary: 'Save only what the person said and agreed to; never fill in an amount, temperature or analysis they did not give.'

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 write profile (readOnlyHint=false, destructiveHint=false), so the description is freed to add what they cannot: it states the auth requirement ('an access token that can read and change your records') and discloses that the call returns the computed unity formula. It omits that non-idempotent saves will create duplicate recipes on retry, which is the one behavioral 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?

Front-loads the core action and outcome, then adds the guardrail and auth note last. Four sentences with little waste, though the repeated 'as the recipe page does / as the recipe page chooses it' phrasing is slightly redundant 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?

With no output schema, the description usefully says the answer carries the unity formula, and it states the auth requirement for a mutation tool. Remaining minor gaps (duplicate-creation on retry, what the answer contains beyond the formula) are small against a 7-parameter tool whose schema is fully described.

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 every field, including the library-name-vs-own-analysis distinction and the firing band cones. The description restates the parameter set at a high level ('base materials and amounts... optional colorants, notes, firing band and food-surface mark') without adding syntax or format meaning, 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 and resource ('Saves a new glaze recipe in your Glazecalc account') and scopes what the recipe is built from (base materials and amounts, optional colorants/notes/firing/food-surface). The word 'new' cleanly separates it from the sibling update_recipe, so an agent can pick it 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?

Gives an explicit usage constraint: 'Save only a recipe the person asked to save,' which rules out speculative writes. It does not name update_recipe as the alternative for existing recipes or state any prerequisite beyond the token, so it falls short of full when/when-not 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 declare this a safe, idempotent, non-destructive read, so the description's added value is telling the agent what actually comes back: column definitions (time, temperature, cone), data rows, and notes. That is genuinely useful given there is no output schema. It does not cover failure behavior for a bad or missing id, which keeps it from a 5.

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 short sentence with zero filler, and the resource identity is front-loaded before the content enumeration. It is a fragment with no explicit verb and slightly awkward punctuation, which is the only reason it is not a 5.

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-required-parameter read with full annotations and no output schema, the description supplies the return shape and the resource scope, which is most of what an agent needs. Only error/empty-result behavior for an invalid id is left 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?

There is exactly one parameter (id) and schema description coverage is 100%, with the schema already explaining that the id comes from a list. The description adds no further syntax, format, or sourcing detail, 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 ('one firing log from your account') and enumerates its contents (columns such as time, temperature, cone; rows; notes), which clearly separates it from the plural sibling list_firings. It stops short of explicitly naming that sibling or restating the retrieval verb, so it is clear but not fully differentiated.

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: 'one firing log' plus the schema note that the id comes 'from a list' suggests the list_firings-then-get_firing flow, but the description itself states no when-to-use condition, prerequisites, or alternative. Adequate minimum-viable guidance for a simple singular getter.

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 safety is covered. The description adds the returned content domains, which is genuinely useful given there is no output schema, but it says nothing about behavior on unknown names, aliases, or discontinued items beyond listing them as 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?

A single compact sentence that front-loads the core idea ('One material') and then lists contents without filler. The trailing list is dense but every item is informative given the absence of an output schema.

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 is the only source of return-value information and it covers the main fields well. It is slightly incomplete on error/not-found handling and sibling routing, but adequate for a simple idempotent lookup.

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 single parameter is documented in-schema as 'Its name or alias.' The description adds no parameter semantics beyond that (it doesn't clarify alias matching or input normalization), so the baseline of 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 makes clear that this retrieves a single material's record and enumerates the content domains (oxides, LOI, discontinued status/replacement, vendors, hazards, data sheet source). It conveys verb+resource well, but never distinguishes itself from siblings like search_materials or match_from_materials, 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 explicit when-to-use statement and no mention of alternatives; the agent must infer that this is for fetching one known material by name vs. searching. No prerequisites or not-found behavior are described.

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 read-only, idempotent, non-destructive, closed-world. The description adds two facts beyond them: currency is returned as a unit "never the prices" (clarifying data granularity) and that confirmChanges is website-only, an approval-flow constraint the agent cannot act on. The safety profile itself is left to 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?

A single long sentence, but it is front-loaded with the resource and then lists return contents in order of relevance. Every clause carries information; the density is justified by the number of settings, though a list format would read better.

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 full burden for return values, and it enumerates every field returned, including the enumerated confirmChanges values (off, removals, all). Nothing needed to call or interpret this zero-argument read 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 and there is nothing for the description to document or misdescribe.

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 the specific resource (the caller's Glazecalc settings) and enumerates exactly which settings it returns: region, temperature scale, cones, language, weight unit, lead suggestion policy, recipe limit set, currency, and confirmChanges. No sibling tool returns user settings, so an agent can select it unambiguously from the list.

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?

"Settings that matter when talking about glazes" scopes when the tool is relevant, and "it can be changed only there" signals a when-not: don't attempt to modify confirmChanges through tools. It stops short of naming explicit alternatives or preconditions, so not a 5.

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 a safe read-only, idempotent operation, but the description adds substantial behavior: fresh unity-formula computation, limit-set selection rules, cone-12-and-up skipping with limitsNote, and detailed coneFit verdict semantics and limitations. No contradiction with 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?

The purpose is front-loaded, but the first sentence is extremely long and heavily nested with parentheticals, making it hard to scan. Most details earn their place because there is no output schema, but the structure could be much clearer.

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 full return-value burden and does so thoroughly: it enumerates recipe fields, firing details, limit-checking behavior, coneFit outcomes, and important caveats such as the cone-12 limit gap and 'guide, not a test' status.

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 id, firing, cone/chart/temperature, and language are already fully documented. The description adds the behavioral effect of the firing parameter on limit checks and coneFit, but does not add parameter syntax or value meaning 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?

Names a specific retrieval action and resource: one recipe from the user's account. The enumerated contents make clear what kind of data is returned, though it does not explicitly differentiate itself from siblings such as list_recipes or analyze_recipe.

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 explicit when-to-use, when-not-to-use, or alternative-tool guidance. The only hint that an id should come from a list appears in the schema, not in the description.

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, and a closed world, so the safety profile is fully covered. The description adds the useful fact that this shelf is the exact set consumed by Match with what I have, but says nothing about return shape or ordering. That context is worth a 3, not more.

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 sentence with no filler, and the core resource ('materials marked as on hand') is front-loaded. The trailing parenthetical is slightly indirect but still informative rather than redundant.

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 zero-parameter read tool with no output schema and fully covering annotations, the description supplies enough to call it confidently: what set is returned and how it relates to the matching workflow. Only a brief note on what the entries contain would improve it.

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 at all (empty schema, 0 required), so there is nothing for the description to disambiguate. Baseline 4 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 identifies the resource precisely ('the materials you marked as on hand in Glazecalc') and names the related consumer ('Match with what I have'), which lets an agent separate it from siblings like get_material or list_my_materials. It never states an explicit retrieval verb ('returns/lists'), so it falls short of the 5 bar, but the subject matter is 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 parenthetical link to 'Match with what I have' implies the tool is the source view behind that matching flow, which gives contextual usage. However, it never states when to reach for get_shelf versus list_my_materials, get_material, or match_with_what_i_have, and offers no exclusions.

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 cover the safety profile (destructiveHint=true, idempotentHint=false), and the description adds real value on top: partial-update semantics on re-link, a hard cap of 100 links per recipe, and an auth requirement ('access token that can read and change your records'). It does not explain what the destructiveHint actually destroys, nor what a successful call returns, which keeps it off a 5.

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 action in the first clause, then layers behaviour, limits, and constraints. It is dense but every sentence carries information; the 'as the recipe page does' analogy is the only slightly expendable phrase.

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 five parameters, no output schema, and annotations present, the description covers the operation, the upsert rule, the cap, the auth prerequisite, and content-integrity constraints. Only the return shape and the exact effect of the destructive flag are left unstated, which is a minor gap at this 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 the schema already documents recipeId, firingId, result, cone, and atmosphere in detail. The description reinforces the useful conditional semantics (cone and atmosphere only when they differ from the log, result in the person's words at 500 chars), but adds nothing the schema does not already say. Baseline 3.

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 (links a recipe to a firing log) and names exactly what it sets (result, cone, atmosphere), plus the 'as the recipe page does' analogy for the same operation elsewhere in the product. It is clearly distinct from the neighbouring create_firing_log, add_firing_rows, and get_firing tools.

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 explicit when-not behaviour: 'Taking a link off is done on the website', and clarifies upsert semantics ('Linked already, it changes only what is given'). It also gives a strong data-entry rule about not inventing amounts or temperatures. It never routes the agent among sibling tools for the related task of creating or populating a firing log, so 4 rather than 5.

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 genuine context beyond that: results are scoped to the caller's own account and returned newest-first. It says nothing about page size defaults or how to detect the end of the list.

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, zero waste, with the account scope and sort order front-loaded. It is efficient, though the extreme brevity contributes to the gaps flagged in other dimensions.

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 should ideally hint at what a firing log entry contains, and pagination behavior (next page via offset) is left entirely to the schema. It is adequate for a simple list call with zero required parameters, but not 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 coverage is only 67% – limit and offset are documented, but 'search' has no description anywhere. The description adds no parameter meaning at all, so it fails to compensate for the undocumented parameter. Only the schema's own text carries the load.

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 clear verb (lists) and resource (firing logs) plus scope ('saved in your Glazecalc account') and ordering ('newest first'). It is distinguishable from get_firing by the plural/list framing, though it never names that sibling to sharpen the distinction.

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?

No guidance on when to use this versus get_firing for a single log, nor any mention of paging workflow despite offset existing in the schema. Usage is only implied by the verb 'lists'.

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 and a closed world, so the safety profile is fully covered. The description adds only that results include 'their oxides', a genuine content disclosure, but says nothing about ordering, paging behavior, or empty-result handling.

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 with the scope qualifier placed immediately after the verb. Every clause earns its place and nothing is 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?

For a read-only list tool with rich annotations and no output schema, the description covers what is returned (materials plus oxides) and whose data it is. It omits default ordering and paging semantics, which is a minor gap rather than a blocking one.

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 67%: limit and offset carry inline descriptions, but search is completely undocumented in the schema, and the description mentions no parameters at all. Since coverage is not below 50%, the schema does most of the lifting, but the description misses an easy chance to compensate for the undocumented search filter.

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 (Lists) and resource (materials saved in your own Glazecalc account) and adds the scope boundary 'not the shared library', which separates it from search_materials/get_material. It does not name the alternative tool explicitly, but the scope contrast is enough for an agent to route correctly.

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 through the phrase 'your own Glazecalc account (not the shared library)', which tells the agent this is for personal saved materials rather than library search. There is no explicit when-not guidance or named sibling alternative, so it stays at the implied level.

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 and openWorldHint=false, so the safety profile is fully covered. The description adds useful behavior beyond that — result ordering ('newest first') and the filter semantics — but says nothing about pagination behavior, result size, or empty-result handling.

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 efficient sentence with the core resource and ordering front-loaded and the optional filter appended. No wasted words, though the sentence fragment style slightly weakens the lead.

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 list tool with no output schema and four optional parameters, the description covers ordering and the primary filter but leaves the 'search' parameter entirely undocumented in both schema and description, and gives no sense of the returned shape or pagination limits.

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 75%, so most parameters are already documented by the schema. The description adds real meaning to 'about' by spelling out what a record id can be (recipe, material or firing log id), but it contributes nothing for limit, offset, and especially the undocumented 'search' parameter.

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 the resource (notes in the Glazecalc notebook), the ordering (newest first), and the scope of the optional filter (a recipe, material or firing log id). It is clearly a read/list operation and is distinguishable from the write sibling add_notebook_entry, though it is phrased as a noun fragment rather than an explicit verb.

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 tool's nature (a listing tool with an optional 'about' filter) but there is no explicit when-to-use or when-not-to-use guidance, and no alternative sibling is named for cases like searching or retrieving a single entry. Adequate but with clear gaps.

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), so the description only needs to add what they don't. It does: results are ordered newest first, and it discloses a domain-specific behavior — recipes without a stated firing are treated as having none and won't match firing filters. Return/pagination behavior is not described.

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 what is listed before the filter and ordering details. The second sentence (stated-firing semantics) earns its place, but the first is dense and clause-heavy, making it slightly harder to parse than it needs to be.

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 7 optional parameters, no output schema, and no required params, the description covers filtering and ordering but not the returned record shape (only noting each result lists its stated firing) or how limit/offset paginate. Adequate for calling the tool, but the lack of an output schema leaves return-value expectations under-specified.

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 86%, but the description adds real meaning the schema lacks: the search parameter (which has no schema description at all) matches a recipe's title or a material, and it frames cone/atmosphere/process as matching 'stated' firing metadata. This is more than restating the schema, though it doesn't expand on scale/pagination params already 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?

States a specific verb (lists) and resource (glaze recipes in your Glazecalc account) with scope details: newest first, and the three filter axes (search text, stated firing/cone, atmosphere/process). This clearly separates it from singular siblings like get_recipe and from list_my_materials/list_firings/list_notes.

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 concrete motivating query ("which of my glazes fire at cone 10 reduction?") that shows when to reach for this tool and how the filters combine. It stops short of naming alternatives (e.g., get_recipe for a single recipe) or stating when not to use it, so it is clear context rather than full 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, yet the description adds substantial behavior: it explains the oxide-by-oxide closeness thresholds, the raw-clay 20% cap, and the solver score fields (report.miss, report.best, report.capped). It also cautions that suggestions should be tested before use. It stops short of naming rate limits or failure modes, so not a 5.

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 is front-loaded in the first clause, followed by output semantics and a closing caveat, which is a sensible order. The middle explanation of report.closeness thresholds is dense and wordy, but every sentence carries information, especially given there is no output schema.

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 does the heavy lifting by explaining the return fields and the capping behavior, and it flags the must-test caveat, so an agent can invoke and interpret results correctly. The one gap is the absence of explicit routing guidance versus the sibling tools.

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 all five parameters, establishing a baseline of 3. The description does link allowMore to report.capped (cross-field meaning not in the schema) and echoes the 'have' constraint, but leaves mustUse and language untouched, so the added value is marginal.

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 ('Remakes a glaze recipe') plus the defining constraint ('from only the materials listed in "have"'), which cleanly separates it from siblings like blend_recipes and suggest_substitutes. The reference to the Glazecalc 'Match with what I have' action anchors the concept precisely.

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, and 'Test any suggestion before using it' gives a caution, but there is no explicit when-to-use versus alternatives such as blend_recipes or suggest_substitutes, and no stated prerequisites. An agent must infer context from the description alone.

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, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds that it keeps the unity formula as near as materials allow and that report.closeness indicates oxide-by-oxide proximity, which is useful behavioral context. But it does not describe permissions, rate limits, or full return 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?

Front-loads the main action in the first sentence, but the parenthetical '(Match with what I have)' redundantly repeats the title, and the second sentence mixes output explanation with advice. Slightly wordy and could be tightened, though not severely bloated.

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 moderate complexity (4 params, nested lines array, no output schema), the description explains the main action and one output field (report.closeness). However, it omits other likely return fields and does not clarify the relationship between lines and recipeId. An agent gets enough to start but would benefit from more output detail.

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 four parameters are documented in the schema. The description only hints at the recipe sources (your recipe or one you give) and shelf materials, adding no syntax, format, or interaction details beyond what the schema provides. Baseline 3 is appropriate when the schema carries the parameter semantics.

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 (remakes) and resource (recipe) with clear scope: from only shelf materials, preserving unity formula. Distinguishes itself from match_from_materials by focusing on your shelf and referencing the closeness report. An agent can immediately understand the core function.

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?

Implies usage when you want to remake a recipe using only shelf materials, and adds the guideline 'Test any suggestion before using it.' However, it does not explicitly state when to choose this over siblings like match_from_materials, suggest_substitutes, or blend_recipes, nor does it provide exclusions or prerequisites.

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 substantial context beyond them: 30-day recoverability, no permanent deletion, a 100-per-hour per-token cap, refusal while the Trash is full, and the required read/write token scope. These are exactly the operational facts an agent needs before invoking a destructive mutation.

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 action and target resources, then the reversibility window, rate limits, and auth requirement — every sentence carries information. Slightly dense as a single block, but there is 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 destructive three-parameter mutation with no output schema, the description covers reversibility, throttling, failure conditions, auth scope, and a safety constraint on scope of removal. Nothing an agent needs 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 100%, with 'rev' fully explained as an optimistic-concurrency guard and 'kind' carrying an enum plus a note mapping. The description adds no parameter-level detail beyond restating the resource kinds, so the schema does the heavy lifting and 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 ('Moves ... to the Trash') plus the exact resource set (recipes, materials, notebook entries, firing logs), and clarifies the website-equivalent semantics. An agent can distinguish this from remove_from_shelf or update_recipe 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?

It gives a scope constraint ('Remove only what the person asked to remove') and explains the operation is reversible, which shapes when to call it. However, it never explicitly routes the agent away from alternatives such as remove_from_shelf (which detaches rather than trashes) or names the condition that selects this tool over them.

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?

The annotations already mark the operation as destructive and non-idempotent; the description adds crucial context that the underlying materials remain and that the shelf change can be undone via undo_shelf_change. It also discloses the access-token requirement, which goes beyond the structured 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?

The description is three short, front-loaded sentences with no wasted language. It conveys the action, its effect on materials, reversibility, and auth requirement efficiently.

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 single-parameter tool with no output schema and clear destructive annotations, the description covers the essential behavior: what is removed, what is not removed, how to revert, and the permission requirement. Nothing needed to select and 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?

Schema description coverage is 100%, and the parameter is already documented as an array of material names. The description reiterates that materials are referenced by name, but adds no additional syntax, constraints, or examples 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 states a specific verb and resource: taking materials off the shelf of materials on hand. It clearly distinguishes this from shelf-listing or adding actions by naming the shelf relationship and the undo path.

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 makes clear this is for removing named materials from the current shelf and points to undo_shelf_change when the change should be reversed. It does not explicitly compare against add_to_shelf or move_to_trash, but the removal context is unambiguous.

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?

Beyond the read-only and idempotent annotations, the description discloses that results include title, anchor, excerpt, website address, and resource URI, and that resources/read returns the full resource. It also describes language fallback behavior and citation expectations, which are important operational details not present in 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?

The description is dense but front-loaded, moving from purpose to return format to special instructions. The parenthetical list of guide topics is long but useful for routing, though the overall sentence structure could be slightly tighter.

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 supplies the missing return-value details, including excerpts and resource URIs. It also covers language fallback, citation, and the special video-linking restriction, making it complete for this search tool.

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 explains each parameter, including the language fallback and guide enum. The description adds little parameter-specific meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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 ('Searches Glazecalc's plain-language guides for potters') and lists the guide scope, including the specific domains it covers. This clearly distinguishes it from sibling tools such as search_materials or analyze_recipe.

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 explicitly says to use the tool for glaze defects, safety, firing, and terms, and gives a concrete citation instruction. It also states a special rule for John Britt's videos. It does not name an alternative tool for non-guide searches, but the usage context is clear.

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 and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior: colorants are only searched when explicitly requested ("if asked"), and matching spans aliases and makers, not just literal names.

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 tightly written sentences with no filler. The scope (what is searchable) is front-loaded and the routing purpose follows immediately.

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 read-only search with no output schema and 80% schema coverage, the description covers scope, matching keys and the conditional colorant behavior. Return shape and pagination/limit behavior are not described, but with no output schema declared that omission 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 description coverage is 80%, so the baseline is 3. The description earns above baseline by clarifying that matching extends to aliases and makers (beyond the schema's "Words in the name") and by tying the optional colorant scope to an explicit request, which maps to includeColorants.

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 (Finds) plus the resource (ceramic raw materials) and enumerates the concrete material types (feldspars, clays, frits, fluxes) and matching keys (name, alias, maker). This is clearly a lookup/search tool, distinguishable from the sibling get_material, which retrieves a single material by an already-known name.

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?

"Use it to find the exact name the other tools take" gives an explicit entry-point role relative to siblings like get_material, analyze_recipe and match_from_materials. It stops short of naming a when-not case or a specific alternative tool, so it is clear context without full routing rules.

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 the description adds substantial context beyond them: the closeness tolerance model (0.02 or 5% of large amounts, off/far thresholds), the verdict/summary/unreachable outputs, and the raw-clay 20% cap. This is rich behavioral disclosure that helps an agent predict results.

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?

Content is front-loaded with the core action and nearly every sentence earns its place, packing tolerance, cap, and validation guidance efficiently. It is a dense run-on paragraph, however, making the output-field and cap details harder to scan than a structured layout would be.

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 7-parameter solver with no output schema, the description fills the gap by describing the result fields (closeness, verdict, summary, unreachable, capped) and the clay-cap logic. An agent has enough to call it correctly and interpret the answer.

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; the description goes further by explaining the unity vs analysis distinction for target.kind and tying allowMore to report.capped. It reinforces schema meaning rather than merely repeating it, though it doesn't detail firing/language options already 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 opens with a specific verb+resource ('Makes a glaze recipe, in percent') and states the governing objective ('whose unity formula comes as near a target as they allow'), which an agent can map to the solve_target name. It doesn't explicitly differentiate from close siblings like match_with_what_i_have or match_from_materials, so it falls short of 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 supplies concrete calling conditions — give materials by library name or use onHand (with a token or connected app), and 'Test any recipe before using it' nudges toward validation siblings. It lacks an explicit 'use this instead of match_with_what_i_have when...' exclusion, so it stops at 4.

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 safety needs no restating. The description instead discloses the estimation fallback chain, the 5% exclusion rule for unestimable materials (bentonite, stains, mixed borates), the no-estimate outcome when that share is exceeded, and that nothing else is assumed. That is genuine behavioral disclosure beyond the annotations; only the return shape remains unstated, which is the main gap given 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?

The content is relevant and the opening is front-loaded with the primary capability, but the middle collapses into a dense semicolon-and-parenthesis chain covering density heuristics and Appen's glass factors. Those details are useful yet buried, and the single-paragraph block gives the agent no structural handles. Some trimming and ordering by mode would materially improve 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 six-parameter, no-output-schema calculation tool, the description covers the derivation logic, the mutually exclusive input modes, the override precedence, and the edge cases where estimation fails. An agent can decide which inputs to supply and predict roughly what comes back. 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 coverage is already 100%, so the baseline is 3, but the description adds real meaning on top: drySg wins over the estimated value, lines are used only to estimate dry materials' SG, and gramsPer100ml is the raw measurement alternative to sg. It also explains the estimation basis (mineral density, 2.6 for commercial feldspars and clays, Appen's factors for frits), which the schema does not. This is meaningful added semantics beyond the field descriptions.

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 opening states a concrete verb and resource: derive a glaze slurry's specific gravity from grams per 100 mL, or take the SG, then compute water to add or pour off, plus Brongniart's-formula dry glaze per litre. The domain is unmistakably distinct from siblings like analyze_recipe or solve_target. It loses a point only because the run-on phrasing forces the agent to parse three capabilities out of a single sprawling sentence rather than a clean enumeration.

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 does give conditional input guidance — 'The water to add needs nothing else', dry weights need drySg or lines — which effectively tells the agent which mode it is in. However, it never names an alternative sibling or states when to prefer this over solve_target or analyze_recipe, and there are no explicit exclusions. Usage is implied through input dependencies 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 carry read-only/non-destructive safety. The description adds real behavioral context: unity-formula preservation, the closeness report field, cap behavior on raw clay, and that suggestions are region-constrained. It doesn't describe response shape beyond report.closeness, keeping it a 4.

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 front-loaded sentences that lead with what it does. Slightly dense with cross-references ('as the Glazecalc app does', 'as match_from_materials does'), but each clause 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, so the description must describe returns; it names report.closeness and report.capped, covering the key outputs. Reasonably complete for a 5-param tool, though the full return shape is only partially sketched.

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 parameters are fully documented in the schema and baseline is 3. The description reinforces allowMore via report.capped naming and implies the region/lead constraints, but adds little syntax or semantics 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+resource: finds discontinued/scarce materials in a recipe and the modern replacements, plus suggests amounts preserving the unity formula. Explicitly distinguishes itself from match_from_materials by noting report.closeness parallels that tool.

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?

'Test any suggestion before using it' gives a verification step, and the match_from_materials comparison implies when closeness matters. But there's no explicit statement of when to prefer this over analyze_recipe or match_from_materials, so usage remains implied.

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, idempotentHint=false and readOnlyHint=false, but the description adds genuinely new behavior: it needs an access token with both read and change permissions, and the undo is strictly single-step against the last change regardless of whether the website, a token, or an assistant made it. That permission requirement and the one-step boundary are not derivable 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?

Three short sentences, each carrying distinct load (what it does, the one-step limit, the auth requirement), with the core purpose front-loaded. Nothing is redundant or 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?

For a no-param mutation with no output schema and full annotation coverage, the description supplies scope, the single-step constraint, and the permission requirement. The only minor gap is what a successful call returns or how the agent confirms the undo took effect.

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 of 4 applies; there is no parameter semantics for the description to add or omit.

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 (puts back/undo) and resource (the shelf), and scopes it to the last change only. An agent can distinguish it from add_to_shelf, remove_from_shelf, and get_shelf without opening any 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 states the operating window: 'One step back only: a second call finds nothing to undo until the shelf changes again,' which tells the agent when the call is valid and when it will no-op. It does not name a sibling alternative (e.g., get_shelf to inspect state first), so it stops just short of full when/when-not 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?

Beyond the annotations, it discloses important behavior: only supplied fields change, saved recipes retain their own copy, a previous version is kept for undo, and the token must be able to read and change records. These details substantially clarify the mutation semantics and authorization needs.

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, then adds only helpful behavioral constraints: partial updates, recipe independence, version history, and auth scope. It is compact and every sentence contributes useful 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?

For a destructive mutation with nested oxide analysis and no output schema, the description covers the essential risks and update behavior well. It could be more complete by mentioning response behavior or explicitly connecting the rev parameter to concurrency, though the schema already documents rev.

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 description adds meaning for the main mutable fields by listing name, oxide analysis in weight percent, loss on ignition, and notes, and it states that only given fields change. However, it does not explain the rev concurrency parameter or the language parameter, leaving part of the 57% schema coverage to compensate.

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: it changes one of the user's own materials, identified by an id from list_my_materials. It also names the mutable fields (name, oxide analysis, LOI, notes), making the operation clearly distinguishable from add_my_material or recipe tools.

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 a clear usage context: use it to change an existing material owned by the user, with the id obtained from list_my_materials. It does not explicitly name when not to use it versus siblings such as add_my_material or update_recipe, but the context is sufficiently clear.

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?

Beyond the annotations it discloses that the prior recipe is retained as an earlier version and can be undone on the website, that supplying lines re-derives the unity formula, that the update is partial by default, and that a read-and-write access token is required. These are exactly the mutation, reversibility and auth facts an agent needs and that the annotations alone do not convey.

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 then behavior then auth; every clause carries information. A few clauses (the parenthetical about the unity formula, the firing band phrasing) are dense, but nothing is redundant with 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?

For an 8-parameter destructive mutation with no output schema, the definition covers reversibility, auth scope, partial update and recomputation. It does not describe the shape of the response (the language parameter implies prose in the answer but the return value is never characterized), which is the main remaining gap.

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 75% and already documents rev, lines/analysis, firing and language in detail. The description still adds real meaning: partial-update semantics across all optional fields and the fact that changing materials recomputes the unity formula, which the schema does not state.

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?

"Changes one of your saved recipes" pairs a specific verb with a specific resource, then enumerates the mutable fields (title, base materials and amounts, notes, firing band, food-surface mark) and names the source of the id (list_recipes). This clearly separates it from create_recipe and update_my_material 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?

"Only what is given changes" and the pointer to list_recipes for the id give clear context for invoking it, and the recompute note signals a side effect of supplying lines. It stops short of naming alternatives or exclusions (e.g., update_my_material vs this tool), so no explicit routing to siblings.

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?

The description adds substantial behavior beyond the annotations: it is a calculation from published figures rather than a test result, cautions are guides not food-safety guarantees, limits are not checked above cone 12, and cone checks judge only cone 06 to 10. These details are consistent with the read-only, idempotent, non-destructive 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?

The purpose and mode distinction are front-loaded, but the description is dense and spends significant space enumerating per-tile and trend output fields even though an output schema exists. It is informative but not tightly concise.

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 the tool's complexity, nested schema, and output schema, the description is complete: it explains the progression concept, mode behavior, output content, limit and firing caveats, and the calculation-versus-test distinction.

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 input schema already documents all parameters thoroughly. The description reinforces concepts like mode "replace" using `instead` and the default from value, but it adds little parameter meaning beyond what the schema already provides.

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: it shows what one material does to a glaze by varying its amount through a base recipe. The progression-test framing is clear, but it does not explicitly distinguish this tool from siblings such as analyze_recipe, compare_recipes, or solve_target.

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 clear usage conditions: mode "add" versus "replace", base materials only and no colorants, and leaving out firing when unknown. It does not, however, explicitly say when to choose this tool over sibling analysis or comparison tools.

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