PerfuMate

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 safety profile is covered. The description adds genuinely new behavior: default working dilution in DPG (or neat) when no strength is given, and that unmatched names return suggestions. It does not address the non-idempotent hint, e.g. whether re-adding the same material duplicates it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, front-loaded with the usage trigger and then progressive detail on formats and defaults. Dense but nearly every clause carries operational information; only the bulk-list sentence runs slightly long.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a multi-mode, nested-object tool with no output schema and low schema description coverage, the description covers triggers, input variants, defaults, and a partial return behavior. Remaining gaps (duplicate handling, exact return shape, lowStockGrams) are modest rather than blocking.

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?

With only 33% schema description coverage, the description compensates by naming the real-world meaning of most fields (bottle strength, solvent, stock in grams, price per gram, supplier, lot, material by name or CAS) and explaining newMaterial's purpose. The text/file input modes are also spelled out (one material per line, or a table whose header row names columns). It omits lowStockGrams and never maps its vocabulary onto actual property names.

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 (adding catalog or user-created materials to the shelf) and enumerates the per-item attributes it accepts. It is clearly distinguishable from siblings like list_shelf, update_bottle, or search_materials 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?

"Use this when the user says they have bought or own materials and wants them on their shelf" gives a concrete trigger condition, and the newMaterial clause implicitly routes uncatalogued items. It never names an alternative tool (e.g. search_materials, list_shelf, update_bottle), so the contrast 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 and idempotentHint=false; the description usefully adds that the old working copy stays in the tree, clarifying the branch is non-destructive. It does not say what the new branch is called, whether it becomes the active working copy, or what the caller gets back.

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 trigger condition first and the key behavioral consequence second; no filler. It is efficient, though arguably under-informative rather than merely 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?

For a non-idempotent mutation with no output schema, the description covers the safety-relevant fact that the source stays intact, but omits the outcome (what the branch looks like, its naming, whether it is switched to) and the undocumented version parameter. Adequate but with clear gaps.

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 50%: the formula parameter is documented in the schema, but version has no description anywhere. The description's phrase "from a past version" weakly implies the version param identifies the source version, but it never states the expected format (id vs. name vs. label), which is a real gap for a required 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 gives a concrete verb+resource: starting a new line of work from a past version, i.e., branching. However it never distinguishes this from near-neighbors like open_version, restore_deleted, or duplicate_formula, so the agent must infer the difference.

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 this when the user wants to start a new line of work from a past version" is an explicit trigger condition, which is more than most definitions provide. It offers no exclusions or named alternatives, so the agent cannot tell when NOT to branch versus opening or restoring.

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 (readOnlyHint=true, idempotentHint=true, destructiveHint=false), yet the description still adds real context: it does not save or alter amounts, it returns a PerfuMate link, it evaluates IFRA Category 4 at a user-chosen concentration, and unmatched lines are listed but not counted. Missing only finer details such as exact return structure, which is largely fine given the read-only profile.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single dense paragraph, but it is front-loaded with the trigger and each sentence carries distinct information (trigger, verdicts, category, input format, edge cases, exclusions, return link, alternatives). Slightly long 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?

Covers the trigger, both input formats, the unit rule, unmatched-material behavior, the mutation disclaimer, and the returned link, which is enough for a tool with no output schema. The only minor gap is that the interplay/optionality of 'lines' versus 'formula' is implied rather than stated.

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 explaining the two mutually exclusive input shapes (verbatim pasted text versus structured lines) and the unit rule (all lines in grams or all in percent). It also frames concentrationPct semantically ('how much of the finished product it may be', 'the concentration the user chooses'), which the schema only partially conveys.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (check) and object (a perfume or accord formula) plus the exact verdicts returned: IFRA compliance, finished-product percentage, which line to reduce, and EU allergens to declare. It is unmistakably distinct from sibling tools like get_material and find_starting_formula.

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?

Opens with a precise trigger ('when the user has a perfume or accord formula, pasted or drafted earlier in this conversation, and wants to know whether it is IFRA compliant...'). It also routes to alternatives explicitly: 'For one material's limit use get_material; for a starting recipe use find_starting_formula.'

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 non-idempotent, so the safety profile is covered. The description adds genuinely new behavioral context: the 30-day restorability window and the fact that confirmName is only required when a protected item is present.

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?

Four short sentences, each earning its place, with the usage precondition front-loaded ahead of the parameter notes and the recovery caveat. No redundancy.

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 two-parameter tool with no output schema and full annotation coverage, the description covers when to call it, what confirmName needs, and the restore window. Only the provenance of the token could be stated more explicitly.

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 load, and it does: it explains confirmName's conditional requirement ('the formula's name as the user typed it') and ties token to the list produced by delete_items. The token's exact origin is only implied rather than spelled out, so not a 5.

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 (Deletes) and resource (exactly that list), and the title/description make the two-step relationship with delete_items explicit (step 2 of 2). An agent can distinguish this from the sibling delete_items 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?

'Use this only after the user has said yes to the list delete_items showed' gives an explicit precondition and names the alternative that produces the token. The when-to-use condition is unambiguous and cannot be inferred from the schema.

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 only say this is a non-read-only, non-idempotent, non-open-world write. The description goes well beyond: expects lines matched to catalog and user materials, is all-or-nothing ('if any line does not match, nothing is saved'), returns unmatched names with suggestions, and off-shelf-adds bottles the user does not own. That is exactly the behavioral context annotations cannot 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?

Dense but front-loaded: the primary trigger comes first, then the matching/atomicity caveat, then the off-shelf side effect, then the check_formula disambiguation. Sentences are long and clause-heavy, but no sentence is pure 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 9-parameter, zero-required, nested-schema mutation with no output schema, the description covers the essential call-shaping facts: input forms, failure semantics, unmatched-name feedback, and side effects. It omits the meaning of kind and several optional metadata parameters, which an agent may still have to infer.

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 low (33%), so the description has to carry more weight. It does explain the three line-input shapes (structured lines, pasted text, attached file) and the user-materials/newMaterial flow, but leaves kind, name, folder, description, batchGrams and targetConcentrationPct unexplained. Partial compensation only.

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?

Opens with a specific verb+resource: creating a new formula on the user's PerfuMate bench, empty or populated from lines the user supplies. It is instantly distinguishable from update_formula, edit_formula, duplicate_formula and check_formula 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?

Gives a concrete trigger (the user wants a new formula, e.g. after building one together in this chat) and names the alternative explicitly: 'To only check a formula without saving it use check_formula.' That is an explicit when/when-not routing rule.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the mutation profile is known. The description adds genuinely useful context beyond that: the change is in-place, preserves the same dose, and is reversible via undo_last_change. It doesn't disclose failure modes or what happens to dependent lines.

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 that leads with the usage trigger and packs scope, dose preservation, in-place semantics and the undo path without waste.

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 two-parameter mutation with no output schema, the description covers the operation's effect and its reversal, which is what an agent needs to act. It omits edge-case behavior (e.g. what happens if the accord holds nested accords or the line is already decomposed).

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% for both parameters (line: name or id; formula: id from list_formulas or exact name), so the schema carries the semantics. The description adds no additional parameter-level detail, making the baseline 3 correct.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a precise verb+resource+effect: an accord line is replaced by the materials it holds, at the same dose, in place. This clearly separates it from siblings such as insert_accord, view_accord and resync_accord without needing to open 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 explicit trigger condition ('when the user wants an accord line replaced by the materials it holds') and points to undo_last_change as the reversal path. It does not state when not to use it (e.g. use view_accord for inspection), so a 5 is not warranted.

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?

Goes well past the annotations: it clarifies the counterintuitive non-destructive nature of a tool named delete_items, states that a confirmation token is returned with a 10-minute expiry, notes protections are surfaced, and warns the result must be shown to the user. The readOnly/idempotent annotations are consistent with and reinforced by this text.

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?

Four short sentences, each carrying distinct information: trigger, non-destructive behavior, required follow-up, and constraint. The step-1-of-2 framing is front-loaded where an agent will see it first.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description still conveys the key return artifact (a 10-minute confirmation token) and the two-step workflow. It does not describe the structure of the preview list the agent must show the user, which is the one remaining gap for a preview 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 0%, so the description must compensate. It partially does by naming the deletable kinds (which maps to the kind enum, though journal_note is omitted), but it says nothing about ref, formula, material, or dilutionPct semantics or the 50-item/1-item bounds.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (prepare a deletion) and enumerates the six entity types it applies to. It immediately distinguishes itself from confirm_delete by declaring 'it is step 1 of 2 and deletes NOTHING', so an agent can route between the two 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?

Explicit when-to-use ('when the user asks to delete a formula, version, material, bottle, batch or note'), an explicit next step ('only after they agree, call confirm_delete'), and an explicit exclusion ('Locked formulas cannot be deleted here'). Nothing about routing is left to inference.

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

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

Annotations declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the copy is independent, mirrors the working copy's bottles, and is auto-named '<name> copy' unless a name is supplied. It does not say what happens to later edits or where the copy lives, but this is solid added value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence, front-loaded with the use trigger, with no filler. It is slightly dense with nested qualifiers (working copy, bottles, naming fallback), but every 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?

For a two-parameter mutation tool with annotations present and no output schema, the description covers the trigger, the copy semantics, and the naming default. It leaves unstated whether the copy is a saved or draft artifact and what identifier comes back, but no output schema exists to carry that, so this is a minor residual 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 50%: 'formula' is documented (id or exact name) but 'name' is bare. The description compensates for the undocumented parameter by specifying the default naming convention ('<name> copy' unless named), which is exactly the missing semantic an agent needs.

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 ('duplicate a formula') and qualifies exactly what kind of duplicate it produces: an independent copy of the working copy with the same bottles. This distinguishes it from create_formula, branch_version, and save_version without the agent needing to open 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?

'Use this when the user wants a copy of a formula to try changes on' gives a clear triggering intent. It does not name siblings like branch_version or create_formula as alternatives, so routing remains partly inferential, but the use 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?

Annotations already declare the mutation/non-idempotent/non-destructive profile. The description adds substantial context beyond that: in-place editing of the working copy, no version creation, the behavior when a batch was made from the working copy, app update timing, and the percentage-solving rules for weighed targets.

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 primary use case and packs multiple high-value distinctions into dense but purposeful sentences. Every sentence (unit semantics, version behavior, percentage solving, line naming) earns its place for a tool with nine operations.

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, multi-operation mutation tool with no output schema, the description covers workflow, versioning, and percentage semantics well. It could go further by mapping which fields each operation requires (e.g., swap needs newMaterial, set_flag needs flag/line), which would reduce reliance on schema inference.

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 50%, so the description must compensate. It gives critical semantics for the unit field (g as weighed amount vs. % as final weighed share including solvent, not the pure aromatic relative/absolute percent), warns never to copy relativePct/absolutePct as grams, and tells the agent to use weighedPct from get_formula for percentage edits.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('change a formula on their bench') and enumerates supported line operations, so the agent understands the scope. It names alternatives like undo_last_change and save_version, but does not distinguish from the sibling update_formula, leaving a potential routing ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Use this when the user wants to change a formula on their bench' and lists the qualifying operations. It names undo_last_change for reversal and save_version for keeping a version, and directs the agent to read get_formula first—clear when/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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description still adds substantive behavior: matched results include percentages and grams, an IFRA Category 4 verdict with highest safe concentration and allergens to declare, a deep link, and ranked alternatives. It also discloses sourcing ('the ratios are the library's own; nothing is invented'), the no-match fallback (returns the list of available accords), and that nothing is saved.

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 usage trigger, then output, then fallback, then sibling routing — a sensible order. It is long and reads as one dense sentence-chain, but nearly every clause carries distinct, non-redundant information about behavior or exclusions.

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 return-value burden and does so fully: match, percentages, grams, IFRA verdict, highest safe concentration, allergens, link, alternatives, plus the no-match path. Combined with the annotations, an agent has everything needed to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3, but the description adds operational meaning the schema lacks: haveMaterials changes ranking (accords makeable with them rank first, missing ones listed) and concentrationPct drives the IFRA check. It also frames idea as the user's own words and batchGrams as the basis for amounts.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (find/matches), resource (starting formula from PerfuMate's reference accords library) and output (closest match with percentages, grams, IFRA check, link, alternatives). It is clearly distinguishable from siblings like create_formula, check_formula, and find_substitutes without opening their 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?

Explicit trigger ('when the user wants to build, create, compose or formulate a perfume... or asks what they could make with materials they list'), explicit alternative ('Re-check any edited version with check_formula'), and explicit exclusion ('Not for copying a named commercial perfume'). When-to-use, when-to-route-elsewhere, and when-not-to-use are all present.

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?

With annotations covering readOnly and idempotent, the description adds meaningful context: results are ranked 'best first' with a match percent and trade-offs, and it never offers IFRA-prohibited materials. It does not describe pagination or result limits, but for a read-only finder this is strong.

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 dense sentences with zero waste, front-loading the trigger and then the return format and mutation note. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Complete for a read-only lookup: trigger, return shape, ranking, constraint (no IFRA-prohibited), and the follow-up mutation tool are all covered. Minor gap: it doesn't say what happens if no substitutes are found, but that is a small omission.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both parameters are fully documented in the schema. The description does not add syntax or format details beyond saying it operates on 'one line' of a formula. Baseline 3 is appropriate when 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?

States a specific verb (find substitutes) and resource (a line's material), and clarifies that it returns single bottles and 2-3 bottle blends from the user's shelf. This differentiates it from siblings like search_materials and use_substitute.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use: 'when the user lacks a material in a formula, or asks what they could use instead.' It also names the alternative tool for applying a chosen substitute ('use_substitute swaps one in'), leaving no ambiguity.

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, so safety is covered. The description goes beyond them by disclosing what the read returns and that past versions can be retrieved by number or id, which is genuinely useful behavior for an agent with no output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, densely packed and front-loaded with the primary trigger before the optional extras. Slightly list-heavy, but every clause maps to a real capability rather than 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 carries the burden of describing return content, and it does so thoroughly, while also covering all four parameters and the versioning behavior. Only a brief note on error behavior or large-formula handling is absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 75%: formula, version, and ifraConcentrationPct are documented in the schema, but checkIfra has no schema description. The description fills that gap by explaining the IFRA Category 4 and EU allergen check it triggers, adding meaning the schema alone lacks.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific trigger and resource ('see one of their formulas') and then enumerates exactly what the response contains (lines with material, bottle strength, amount, percentages, flags, notes, totals, cost, note pyramid). It is easily distinguished from list_formulas, view_accord, and get_material because it returns a single formula's full detail.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a clear when-to-use trigger ('when the user wants to see one of their formulas') and a concrete secondary trigger for the optional check ('is my formula IFRA compliant'). It does not name alternative sibling tools such as list_formulas or view_accord, so the routing is implied rather than explicit.

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 (which already cover readOnly/idempotent/non-destructive), the description discloses the full return payload, the fuzzy-match fallback ('without an exact match it returns the closest catalog names'), and an important semantic caveat that the limit is a regulatory ceiling, not a recommended dose. That is meaningful behavioral context the structured fields do not carry.

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 use case, then return contents, caveat, and the sibling alternative in a logical order, with no filler sentences. It is a dense single paragraph that could be broken up for scanability, which keeps it just short of 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?

There is no output schema, so the description correctly compensates by listing what is returned, and it covers the mismatch/fallback case plus the IFRA limit interpretation. For a single-parameter read tool with rich annotations, 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 coverage is 100% and the single 'name' parameter already documents that canonical names, synonyms and CAS numbers are accepted, so the schema does the heavy lifting. The description adds only a small amount beyond that, namely that inexact input degrades to nearest catalog names rather than failing. Baseline 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 (show/return) and resource (one perfumery material) and enumerates the exact user questions it answers: odour, usage, strength/longevity, IFRA limit. It explicitly distinguishes itself from check_formula, so an agent can separate it from siblings like search_materials 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?

It gives an explicit when-to-use trigger ('when the user asks what one perfumery material smells like... how much of it IFRA allows') and names the alternative tool plus the condition that selects it ('To check a whole formula use check_formula'). Nothing about routing is left to inference.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so safety is covered. The description adds meaningful value beyond that: it discloses that results come from PerfuMate's own scent model (not raw data), mirrors the app's scent profile sheet, includes a confidence value on the wear line, and samples the drydown at fixed hours (0/1/4/8/24). That is useful behavioral context, though the label is essentially a read-only lookup.

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 a single front-loaded sentence that opens with the trigger condition before enumerating the output, which is the right ordering. It is dense with output detail but every clause earns its place; only the sheer length of the colon-list keeps it from 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?

There is no output schema, so the description carries the return-value burden and does so thoroughly (families, sub-notes, drydown, wear line plus confidence, genre, pyramid, how accords are counted). Combined with annotations that fully cover the safety profile, an agent has enough to call it correctly; only minor gaps like pagination/format shape remain.

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 schema already documents the single 'formula' parameter (id from list_formulas or exact name). The description adds no additional parameter semantics, so the baseline 3 for well-covered schemas 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 (a formula's scent profile) and a specific action (retrieve/derive it from PerfuMate's scent model), and it enumerates exactly what the profile contains — families, sub-notes, drydown timeline, wear line, genre, note pyramid. This clearly distinguishes it from siblings like get_formula (the formula itself) and check_formula, letting an agent 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?

It gives an explicit trigger: 'Use this when the user asks what a formula of theirs will smell like, how it evolves or how long it lasts.' That is clear contextual guidance covering the main use cases. It stops short of naming a specific alternative tool or when NOT to use it, so it falls just below the top bar.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world reads, so the safety profile is covered. The description adds real value beyond that by disclosing the returned payload (notes, bottles with recent stock movements, formulas referencing the material) — especially useful since no output schema exists — though it says nothing about permissions or missing-material 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?

One sentence, front-loaded with the trigger condition and followed by the payload contents. Every clause earns its place with no filler or redundancy.

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 context, and it covers the main components (notes, stock movements, dependent formulas). It is adequate for a simple one-param read tool, with only minor gaps such as error/absence behavior.

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 'material' param is fully documented in the schema (name, CAS, or id from list_shelf). The description adds no format or syntax detail beyond that, 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 identifies the specific resource (one material the user owns) and enumerates its content: notes, bottles with recent stock movements, and formulas using it. The phrase 'they own' implicitly distinguishes it from sibling get_material, but it never names that sibling or explicitly contrasts scopes, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Use this when the user asks about one material they own' is an explicit trigger condition that an agent can route on. However, it names no alternatives (e.g. list_shelf for browsing, get_material for catalog lookups) and gives no exclusions, so the guidance is clear but incomplete.

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 (which only declare it is a non-idempotent, non-destructive write), the description discloses the key behavioral effect: the accord is a virtual material carrying the flattened composition so IFRA, allergens, cost, and scent profile can see inside it, placed at the accord's own aromatic strength. It omits reversibility and auth/permission requirements, but the semantic payoff is substantial.

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 trigger condition is front-loaded ('Use this when...') and the single dense sentence earns its clauses by explaining the accord's virtual-material behavior. The trailing 'Optionally at an amount in grams' is a slightly awkward fragment but carries real 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 three-parameter mutation tool with no output schema, the description conveys what the operation produces and why it matters (downstream IFRA/allergen/cost/profile visibility). It lacks guidance on failure modes, duplicate handling, or whether the source formula must already exist, but it is otherwise complete enough to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67%; 'source' and 'formula' are documented in the schema, while 'grams' has no schema description. The description only notes the amount is optional and in grams, adding little syntax or default detail, so it does not fully compensate for the undocumented parameter. A 3 is the appropriate baseline.

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: using a saved formula as a single ingredient inside another, mirroring the app's native accords. It is far more than a restatement of the title, though it does not explicitly name or differentiate itself from close siblings like decompose_accord, view_accord, or resync_accord.

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 triggering context ('Use this when the user wants to use one of their saved formulas as a single ingredient inside another'), which tells the agent exactly when to reach for this tool. It stops short of naming alternatives or exclusions, so the agent must infer that decompose_accord is the inverse operation.

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=false, idempotent=false and destructive=false, so the mutation profile is covered structurally. The description adds that entries can be corrected, hinting at overwriting an existing note while claiming non-destructiveness, but it never states whether correction replaces or appends, nor any permission requirement.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence that states the use case before the fallback mode, with no filler. It is arguably under-specified rather than over-verbose, but structurally it is clean.

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 non-idempotent write tool with four undocumented parameters and no output schema, the description omits essentials: how the batch is identified, what 'correct' does to the prior text, whether date is free-form, and what is returned. An agent can guess the happy path but not the edit path.

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?

With 0% schema description coverage across 4 parameters, the description carries the full explanatory burden and largely fails it. 'Dated line' loosely implies the date parameter and 'correct one' hints at noteId, but text and batch (the required and scope-defining parameters) are never explained, and no formats or constraints are given.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a concrete verb+resource: adding a dated line to a batch's maceration journal, with a secondary mode of correcting an existing entry. It is clearly differentiable in kind from generic siblings, but it never names or contrasts with write_note or log_batch, which an agent must disambiguate among.

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 a when-to-use trigger ('when the user wants to add a dated line... or correct one'), which is real guidance. However, it offers no when-not and no alternatives, leaving the journal_note vs write_note vs log_batch routing decision entirely to inference.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds only what the result contains (maceration journal, days resting), which is useful but not behavioral disclosure beyond 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 compact sentence that front-loads the trigger and states the scope. No waste, though the phrasing is slightly awkward in connecting the two scope cases.

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 read-only list tool with full annotation and schema coverage, this is adequate. It omits pagination, sort order, and return shape, which an agent might need to call it and interpret results correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single formula parameter is fully documented with id-or-name semantics. The description implies optional formula scoping ('all or one formula's') but adds no syntax or format detail beyond the schema, 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?

The description names a specific verb (list) and resource (batches) and ties it to the user's intent about batches made. It implies the scope (all batches or one formula's) but does not explicitly contrast with siblings like get_formula or log_batch.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a clear triggering condition ('when the user asks about batches they have made') and covers both the all-formulas and single-formula cases. It stops short of stating alternatives or exclusions, but for a simple read tool the guidance is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: a 30-day retention window and the fact that only restorable items appear. It says nothing about ordering, result limits, or what the returned list looks like.

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 no filler; the triggering condition comes first. It is arguably too terse to carry the parameter information the schema omits, but as a piece of prose it earns its place without waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a low-complexity, single-optional-param read tool with no output schema, the description covers timing, scope, and the restore-relevant subset, which is close to sufficient. The unaddressed kind filter and the absence of any sense of the returned list's extent leave a real gap for an agent trying to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and there is one meaningful parameter (kind) that the description never mentions — an agent reading only the description would not know the results can or should be filtered by item type. The enum values are self-explanatory in the schema, but the description does no work to compensate for the coverage gap or to explain behavior when kind is omitted.

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 ('see what they deleted') and scopes it ('last 30 days', 'can still restore'), which reads naturally as a recently-deleted listing. It does not name the sibling it is distinct from (restore_deleted, confirm_delete), but the read-vs-act distinction is inferable from 'see'.

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 opens with 'Use this when the user wants to see what they deleted in the last 30 days and can still restore,' which is an explicit triggering condition and implicitly defines the window in which the tool is meaningful. There is no when-not guidance and no alternative tool named for adjacent intents like restoring or permanently deleting.

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 readOnly/idempotent/non-destructive/closed-world, so the description's job is to add return-behavior context, which it does: sort order (pinned first, then most recently edited), folder grouping, and that locked formulas expose only their name. It omits pagination/result limits, keeping 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?

Front-loads the usage guidance in the first clause, then two short sentences for listing behavior. Efficient, though the first sentence is dense with multiple conditions packed into one breath.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description carries the return-value burden and does so reasonably (ordering, folders, locked-name-only visibility). It leaves the 'kind' filter and any pagination behavior unaddressed, so it is nearly but not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 25% (just 'folder'), so the description should compensate. It maps loosely to three params via 'name, folder or favourite', but never explains the 'kind' enum (perfume vs accord) or the semantics of 'query', leaving the compensation incomplete.

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 ('Lists the formulas on the user's PerfuMate bench') and distinguishes it from siblings by noting it returns the ids the other tools use, implying the get_formula/update_formula relationship. An agent can tell this apart from the many other list_* tools from the text 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?

Gives explicit when-to-use triggers ('when the user asks what formulas they have', 'wants to find one by name, folder or favourite') and a sequencing rule ('before you read or change a formula'). It does not name a competing tool to avoid, so it stops short of full alternative 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 readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds real behavior beyond that: the list form returns titles and previews, while passing an id returns a full notebook — useful disclosure about output granularity.

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 efficiently front-loaded sentence that leads with the trigger and then enumerates the two modes. No filler, though the single-sentence form forces the packed 'id' semantics to be inferred.

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 two-parameter, optionally-filtered list tool with no output schema, the description covers the read purpose and partial return shape, but the unexplained 'query' parameter and absence of pagination or filtering behavior leave a noticeable 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 0%, so the description carries the full burden. It explains the 'id' parameter implicitly (full notebook by id) but says nothing about the 'query' parameter, leaving half the inputs undocumented in both places.

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 concrete verb (read) and resource (PerfuMate notebooks), and describes two distinct modes: listing titles/previews versus fetching one notebook in full by id. It distinguishes itself from the write/journal siblings by being the read path, though it doesn't name them 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?

"Use this when the user asks to read their PerfuMate notebooks" gives a clear trigger condition, but there is no exclusion guidance or mention of alternatives such as write_note or journal_note when the intent is to modify rather than read.

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 safety is covered. The description adds value annotations don't carry: the result is a shelf listing where each material nests its bottles and a 'running low' flag. It still says nothing about pagination or ordering.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no filler, and the usage triggers are front-loaded. The payload enumeration is packed into one dense clause but every listed field is informative rather than padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-required-parameter read tool with no output schema, the description usefully enumerates the return fields, which covers the missing output schema. However the undocumented 'query' parameter remains an unresolved gap, so an agent still cannot call the tool fully correctly from the definition alone.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and neither parameter is described anywhere. 'lowOnly' is only obliquely hinted at by 'what is in stock or running low', and the 'query' parameter is entirely unexplained — an agent cannot tell whether it is free-text search, a material name, or a filter. With 0% coverage the description needed to compensate and largely does not.

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 on the user's shelf) and even enumerates the returned facets: bottles, strength, solvent, stock, price, supplier, lot, running low. That is far beyond a tautology. It never names a sibling (get_shelf_material, search_materials) to sharpen the boundary, 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?

Gives concrete triggering conditions: the user asks what they own, what is in stock or running low, or the agent needs a first step before suggesting makes. That is real usage context. It does not state when NOT to use it or name an alternative (e.g., get_shelf_material for a single item), so it is short of 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 readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile carries no burden. The description adds the content shape (lists, items with list and category, low-stock materials), which is useful, but says nothing about ordering, completeness, or size of 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?

The trigger is front-loaded and the whole definition is two short clauses with no filler. The parenthetical '(with list and category)' is dense but earns its place by describing returned fields.

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 full annotation coverage, one fully-documented optional parameter, and no output schema, this covers what an agent needs: the trigger, the contents, and the optional filter. Only the unresolved overlap with 'shopping_list' keeps it from being fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single 'list' parameter, so the baseline is 3. The description reinforces the optional single-list semantics ('Optionally one list only') but adds no format, id-vs-name, or fallback detail beyond what the schema already states.

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 concrete verb and resource: it returns the Shopping cart's lists, their items (annotated with list and category), and materials running low. That is far more specific than the bare name. However, it never distinguishes itself from the near-identically named sibling 'shopping_list', leaving an agent to guess which of the two to call.

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 names an explicit trigger condition — 'when the user asks what they need to buy' — which is a genuine usage rule. The optional single-list scoping is also flagged. What's missing is any when-not or alternative routing, particularly against the confusingly similar 'shopping_list' sibling.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds useful payload context (what the version tree contains, which is the working copy, which have batches), but says nothing about pagination, ordering, or empty-result behavior. Adds some value over annotations, not rich behavioral depth.

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 the trigger front-loaded and every clause carrying content (notes, parents, working copy, batches). No filler, no restatement of the name or 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?

No output schema exists, so the description correctly carries the burden of explaining what comes back, and it does so concretely. Combined with annotations that fully cover the read-only/idempotent safety profile, an agent has enough to call this correctly; only ordering/pagination details are absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single parameter is fully documented in the schema, including the id-vs-exact-name convention and pointer to list_formulas. The description adds no parameter-level detail, 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?

Specific verb (list) plus resource (versions of a formula) plus a precise enumeration of the payload (version tree, notes, parents, working copy, batches). This is clearly distinguishable from siblings like open_version, branch_version, and save_version, which act on a single version rather than enumerating them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit trigger condition: 'Use this when the user asks about a formula's history.' That is a real when-to-use statement, not just implied. It does not, however, name alternatives (e.g. get_formula for a single-version snapshot) or state when not to use it.

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 a non-readonly, non-idempotent, non-destructive write. The description adds genuinely new behavior beyond that: the optional stock deduction side effect, the weaker-strength option, and that it can run against the working copy or a version. It still omits permission requirements and what success looks like.

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 well-formed sentence with the usage trigger front-loaded and no filler. It is dense but every clause corresponds to a distinct capability, so nothing reads as padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter mutation tool with no output schema, the description covers the intent and the notable side effect but stops short of the full picture: no return/confirmation behavior, no auth or validation notes, and no explicit routing to list_batches for verification.

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 only 25%, so the description must carry the load. It conceptually covers most parameters (totalGrams, madeAt, notes, concentrationPct, deductStock, version) in prose, but never maps them to parameter names, leaves 'code' vs 'label' ambiguous, and gives no formats or bounds.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (log/record) and resource (a batch of a formula), and enumerates the payload it records (weight, date, label, notes, strength, stock deduction). It's clearly distinguishable from the read-side sibling list_batches, though it never names that sibling.

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?

Opens with an explicit trigger: 'Use this when the user has made a batch of a formula and wants it recorded.' That's a clear when-to-use condition, but there is no when-not guidance and no alternative named (e.g., list_batches for reviewing, or update_formula for edits).

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 tell the agent this is a non-idempotent write that is not destructive. The description adds one genuinely useful behavioral fact - the material is drawn from the source bottle's stock - but says nothing about whether the source stock is actually decremented, what happens on repeat calls, or what is returned.

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 tight sentence that leads with the triggering condition, with no padding or redundancy. It is well-formed, though it could have spent its length budget on parameter meaning instead.

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 mutation with zero schema coverage and no output schema, the description is far too thin. An agent can infer the intent but cannot confidently fill the required targetPct/grams pair or the source-vs-dilution fields from what is written here.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across 7 parameters, so the description carries the full burden and largely fails it. It only gestures at 'source bottle's stock' and never explains targetPct, grams, solvent, material, fromDilutionPct, or the deductFromSource flag, leaving most inputs ambiguous.

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 action (recording a dilution) and the source (a bottle the user owns, with material taken from that bottle's stock), so the intent is clear. It stops short of distinguishing this from the sibling scale_to_concentration, which plausibly overlaps, so it doesn't reach a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a concrete trigger: use when the user has made, or wants to record, a dilution from a bottle they own. That is real usage guidance rather than a restatement of the name, but it names no alternatives or exclusions against the many sibling tool names.

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 read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds useful context beyond them: the returned plan values ("unlimited"/"ai_studio") and the pre-sync state where the bench has not yet synced from the app.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler. The usage trigger is front-loaded and the return content follows, so an agent gets the decision rule first and the payload description second.

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 must carry the return-value burden, and it does so reasonably by naming the plan values and the three counts plus the unsynced-bench case. Exact field names or format are not given, but for a simple no-param read tool this is close to 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-param tool is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource (the linked PerfuMate account) and what is returned (plan and counts of formulas, shelf materials, notebooks). No sibling tool covers account data, so the agent can identify it unambiguously.

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 this when the user asks about their PerfuMate account or how big their bench is" gives an explicit trigger condition. No alternative or exclusion is needed since no sibling overlaps this scope, but it stops short of enumerating edge cases.

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 mark it as a non-read-only, non-idempotent, non-destructive mutation. The description adds a meaningful refusal condition not captured by annotations, which is valuable behavioral context. It doesn't say what editing entails or how the version is restored.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the main use case followed by the refusal caveat. 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 two-param mutation with no output schema, the missing documentation of the 'version' parameter and of what 'open/edit' means operationally (does it switch context? return a draft?) leaves gaps, though the annotations cover the safety profile.

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 50%. The formula parameter is documented in-schema (id or exact name), but the version parameter is entirely undocumented in both schema and description. The description adds no parameter meaning beyond what the schema 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 action: transitioning into a past version for in-place editing without cloning. The 'in place vs. clone' contrast distinguishes it from branch_version/duplicate_formula, though it doesn't name them 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?

It gives a clear when-to-use condition ('user wants to go back and edit a past version directly') and an exclusion ('refused for a version a batch was made from'). Alternatives like branch_version aren't named.

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?

With readOnlyHint=false and destructiveHint=false annotations, the description adds crucial context: without apply it only shows the plan; with apply: true it rewrites the working copy in place, and undo_last_change can revert it. This goes beyond annotations by disclosing the preview/edit distinction and reversibility, though it doesn't mention permissions or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is reasonably concise, front-loading the usage scenario, then explaining dry-run vs. apply behavior and recovery. It could be slightly tighter but every sentence contributes to understanding the tool's dual mode.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no output schema, two parameters, and partial schema coverage, the description provides enough context: what the tool does, when to use it, what the plan shows, and how apply and undo work. It doesn't elaborate on the output of the plan or error conditions, but covers the essential decision points.

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 50%, with only 'formula' documented in the schema. The description compensates by explaining the apply parameter's semantics: absent/false shows the plan, true applies the rewrite in place, and undo_last_change reverts. This adds meaning beyond the schema for the undocumented 'apply' 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?

States a specific verb (rebuild/formula) and resource (formula using shelf materials), and clearly distinguishes it from siblings like find_substitutes or use_substitute by describing the full-formula replacement plan and the app's 'Replace with materials I own' feature.

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 names the trigger: 'Use this when the user asks what they can make with the materials they own, or wants a formula rebuilt using only their shelf,' and contrasts the dry-run vs. apply behavior. It also names undo_last_change as the recovery path, giving when-to-use and when-not-to-apply guidance.

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

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

Annotations already declare readOnly=false, idempotent=false, destructive=false. The description adds genuinely new behavior: all formulas in the folder move with it, and an empty name unfiles them. It does not say whether the rename is reversible or needs ownership, so it stops short of full disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence, front-loaded with the usage trigger, followed by the key side effect in a parenthetical. Zero filler; every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 2-param mutation tool with no output schema and solid annotations, the description covers purpose, trigger, and the cascade/unfiling behavior. Minor omissions (reversibility, permissions) remain but nothing essential to a correct call 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 0%, so the description must carry the two params. It explains the empty-name semantics of the target name ('unfiles them'), which is real added meaning for `to`, but never names or maps `from`/`to` or notes the 80-char limit, leaving a gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (rename a formula folder) and the scope of the operation. The resource 'folder' clearly separates it from the sibling rename_version, so an agent can route on the noun 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?

"Use this when the user wants to rename a formula folder" gives an explicit trigger condition. It does not name alternatives or exclusions (e.g. vs. rename_version or restructuring folders), so the routing guidance is clear but not exhaustive.

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, and idempotentHint=false, and the description adds nothing on top of that. Notably, idempotentHint=false is counterintuitive for a rename operation and the description never clarifies whether the note is replaced or appended, or what happens on a number collision.

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 no filler, and the trigger condition leads. It is efficient, though it is so short that the 'Use this when...' framing consumes most of the space without carrying much content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no output schema and 25% schema coverage, the description should carry more: it omits the identifying parameters, permission requirements, note-null semantics, and the odd non-idempotent behavior flagged by annotations.

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 only 25% — just the formula parameter is documented in the schema. The description names 'note' and 'number' but never explains that formula + version identify the target, that number is bounded 1-100000, or that passing note=null clears it.

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 action (change) applied to specific fields of a specific resource (a version's note or number), so an agent can tell what the tool does. It does not, however, distinguish itself from nearby siblings such as update_formula, save_version, or rename_folder.

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 a trigger condition ('when the user wants to change a version's note or the number it carries'), which is more than nothing. It gives no exclusions, prerequisites, or alternatives (e.g., when to renumber vs. create a new version), so usage is only 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 the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the modifier-suppression burden is lifted. The description adds the valuable 30-day retention constraint, but says nothing about what happens to already-active items, whether a 50-item batch is all-or-nothing, or what restore of a 'version' means.

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 no filler; the trigger condition comes first. It is efficient, though one more clause on the required item shape would have been cheap and useful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with annotations but no output schema, the description provides the recovery window but omits how to supply the items, the batch limit, and the outcome of a partial or failed restore. Adequate to select the tool, thin on how to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the description never mentions the sole parameter. It does not tell the agent that each item requires both 'kind' and 'id', that the batch caps at 50, or that 'kind' must be one of eight enumerated types. The schema's enum partially self-documents, but the description compensates for none of the gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a clear action (restore) and a scoped resource (items from Recently deleted, within 30 days), so the agent knows exactly what happens. It does not differentiate from siblings such as list_deleted or delete_items, which an agent could reasonably confuse with this area of functionality.

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 leads with an explicit trigger condition: 'Use this when the user wants something back from Recently deleted.' The 30-day window adds a further qualifier for when this applies. It stops short of naming alternatives (e.g. use list_deleted first to find IDs) or stating when not to use it.

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 it is a non-read-only, non-destructive write; the description adds the useful behavior that existing composition/families/price are overwritten from the current source. However it does not say whether manual edits are lost, whether the change is reversible, or note that idempotentHint is false, so transparency is incomplete for a data-overwriting operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One tightly front-loaded sentence that puts the usage condition first and the effect second, with no filler. The trailing 'as the app's Re-sync does' is slightly redundant but does anchor the behavior to a known UI action.

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 two-parameter mutation with no output schema, the description covers trigger and effect but omits outcome-relevant details such as what happens on failure, whether manual overrides survive, and reversibility. Adequate but with clear gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters (line, formula) are already documented with id/name formats. The description loosely corroborates 'source formula' and 'accord line' but adds no new syntax or constraint detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb (re-reads/re-sync) and resource (the accord line), and states exactly what fields are refreshed: composition, families, and price. That distinguishes it from siblings like view_accord (no mutation) and update_formula (manual edit), though it doesn't name a sibling 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?

It gives an explicit trigger condition: use when the source formula has changed and the user wants the accord line to follow. This is real when-to-use guidance, but it names no alternative tool or a when-not condition (e.g. versus edit_formula).

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=false, idempotent=false and destructive=false, so the safety profile is covered. The description adds real behavioral context beyond that: the saved state becomes a version in a tree and the user continues working on a fresh copy, which tells the agent the original is preserved. It omits naming behavior and what happens on repeat saves with the same name.

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, front-loaded with the use condition and followed by the outcome. No filler, nothing 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 must carry the return/effect story, and it does state that a fresh copy is created. However it is silent on how the version is named (the unexplained 'note' parameter) and on behavior for duplicate names, leaving meaningful gaps for a mutation 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 coverage is 50%: the schema itself documents 'formula' (id from list_formulas or exact name), while 'note' (max 120 chars) is undocumented in both schema and description. The description adds no parameter meaning at all — notably it never explains how the version gets its name — so it does not compensate for the gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource — keeping the current state of a formula as a named version in its evolution tree — plus the resulting side effect (editing continues on a fresh copy). It is clear what the tool does, but it never distinguishes itself from close siblings like branch_version or rename_version, which an agent must disambiguate on its own.

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 this when the user wants to keep the current state... and carry on editing" is an explicit use trigger tied to user intent, which is stronger than most definitions. It offers no when-not conditions and names no alternative (e.g. branch_version), so it stops short of 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 cover the safety profile (not read-only, not destructive, not idempotent), so the bar is lower. The description adds real behavioral value: it explains the scaling math, the automatic addition of perfumer's ethanol from the catalog when none is present, the strength cap, and that changes happen 'in place' — which corroborates the non-idempotent, in-place mutation hints.

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 usage trigger and stays compact, with no wasted sentences. The trailing fragments ('Capped at the concentrate's own strength. In place.') are terse but each carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description must carry behavior, and it does so well for a mutation tool — mechanism, ethanol sourcing, and cap are all covered. The remaining gap is parameter semantics (units/meaning of totalGrams and concentrationPct), which is minor given the overall coverage.

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 only 33% (only 'formula' is documented). The description gives semantic context for concentration and finished weight, mapping loosely to concentrationPct and totalGrams, but adds no units, ranges, or format detail to compensate for the undocumented parameters. Baseline 3 for a partial-coverage schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (change a formula's concentration or finished weight) and grounds it in the app's Scale sheet, with a concrete example (EDP to EDT). It is clearly distinguishable from siblings like update_formula or edit_formula.

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?

Opens with an explicit trigger ('Use this when the user wants to change...') and two distinct cases (concentration or finished weight). It stops short of naming when-not to use it or naming alternative tools, so no exclusions are given.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's added value is the result behavior: cap of 10 results, the fields returned, and the ranking rule that IFRA-prohibited or EU-banned materials are flagged and ranked lower. This is meaningful behavioral context beyond the annotations. It stops short of covering zero-result or pagination behavior, so a 4 rather than 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-loaded with the trigger condition, then result behavior, then routing alternatives and exclusions. Every sentence earns its place — no filler, no restating of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description carries the burden of describing returns, and it does so thoroughly: material types, returned fields, result cap, ranking rule, and page link. Combined with the sibling routing and exclusions, an agent has everything needed to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 50%: the required 'query' param is documented in the schema itself, but 'limit' has no description anywhere. The description implies result-count capping ('up to 10') but never explains the limit parameter or its default/min/max interaction. It adds little semantic detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (search/find) and resource (perfumery materials) with the dimensions searched: scent, family, name, CAS number. It explicitly distinguishes itself from get_material (single-material detail) and check_formula (whole-formula check), 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?

Opens with an explicit 'Use this when...' trigger, gives concrete examples ('musks, woods or citrus', 'catalog name of a material they typed loosely'), names the two alternatives with their selecting conditions, and adds an exclusion ('Not for finished perfumes or shopping advice'). When/when-not/alternatives are all present.

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 declare this is a non-readonly, non-idempotent, non-destructive mutation, so the safety profile is covered without description help. The description adds only the sentinel behavior '0 turns it off' for one field; it never says whether unspecified preferences are preserved (partial update), whether confirmation is needed, or that changes persist immediately. Adequate but thin on behavior beyond 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 sentence with no filler, front-loaded with the usage trigger and then the two affected settings. Slight verbosity in the 'Use this when the user wants to' framing, but nothing 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 mutation tool with no output schema and 0% schema description coverage, the description covers both fields at a high level but omits partial-update semantics (both params optional), whether values are validated or rejected, and any confirmation/persistence note. Reasonably complete for a two-option settings setter, but key mutation behavior is left implicit.

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 load. It usefully documents the unit for lowStockDefaultGrams ('grams') and the sentinel value ('0 turns it off'), but adds nothing about currencySymbol format/length or the fact that both parameters are optional and can be sent independently. It covers the meaning of one parameter well and leaves the other and optionality gaps unaddressed.

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 (change) and the exact resources affected (currency symbol, default low-stock warning in grams), which clearly separates it from the read-only sibling my_account. It stops short of explicitly naming that sibling or any other alternative, so it is clear but not maximally 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?

It states a clear trigger condition: 'Use this when the user wants to change the account's currency symbol or its default low-stock warning.' There is no guidance on when not to use it, no prerequisites (e.g., ownership/permissions), and no named alternative for viewing preferences, so it lands at clear context without 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 already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that by explaining list-creation semantics ('the default list unless one is named; a new name makes that list'), a side effect not derivable from the schema, though it never says removal is irreversible or that calls are non-idempotent.

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 trigger condition first and the operations enumerated after; there is no filler. The nested parenthetical about default vs named lists slightly interrupts the scan but earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-parameter destructive mutation with no output schema, the description covers the main actions and list scoping but omits whether at least one action is required, whether actions can be combined in a call, and what happens when a named item is not found. Adequate, but gaps remain for a tool with no required parameters and no structured return contract.

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?

With only 33% schema description coverage, the description carries the load and does so for add, done, undone, remove and list, translating terse names into intent ('tick items as received or back to needed'). It leaves the category parameter and the interaction between multiple action arrays unexplained, so compensation is good but not complete.

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?

Concrete verbs (add, tick/untick, remove) against a specific resource (a named or default Shopping cart list), so an agent can immediately tell this is the cart-mutation tool. It does not name any sibling (e.g. list_shopping for reads, add_to_shelf for shelf items), so differentiation from related tools relies on the agent's own knowledge of the toolset.

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 opening 'Use this when the user wants to...' gives an explicit triggering condition and enumerates the three user intents (add, mark received/needed, remove) that route here. There is no explicit 'when not to use' or named alternative, which keeps it just short of full 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?

Adds real operational context beyond the annotations: omitting changeId is preview-only and mutates nothing, a concurrent edit aborts the whole restore, newer app work is not overwritten, and there is a 20-changes-per-formula / 30-day window. However, it explicitly claims 'a completed undo is idempotent and never steps farther back,' which directly conflicts with the declared idempotentHint=false and could lead an agent to retry more aggressively than the annotation sanctions.

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 trigger sentence and densely packed with decision-relevant facts; every clause carries weight. It is written as a long run-on with several ideas chained by semicolons, which slightly hurts scannability but not substance.

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 2-parameter tool with no output schema, it covers the key decision points: preview vs apply, retry/idempotency policy, retention window, and concurrency behavior. The one omission is the shape of the preview result when changeId is absent, but that gap is minor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds value the schema does not: it tells the agent where changeId comes from ('from a write result or this tool's preview') and the exact behavioral consequence of omitting it. That is meaningful semantics layered on top of the field documentation.

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 (undo) and resource (last change), and pins the scope tightly: 'take back the last change made from the chat, to one formula or the last of any, from any chat.' No sibling tool performs undo, and the preview-vs-apply distinction makes the intent 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?

Leads with an explicit trigger ('Use this when the user wants to take back the last change'), then gives when-not rules ('Only preview/select another ID when the user asks for another step') and the retry condition. The agent knows exactly when to call it and when to omit changeId versus supply one.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the safety burden is largely covered. The description adds some behavioral context by noting stock changes flow 'through the stock ledger' and that shelf/default status can be toggled. It does not disclose how unspecified fields behave on a partial update or any permission requirements, so it adds only moderate value.

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 a single front-loaded sentence opening with the usage trigger, and each clause maps to a real parameter or action, so little is wasted. The density of the enumeration makes it harder to scan than a structured list, but it is appropriately sized for a 14-parameter tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex tool with 14 parameters, zero required, low schema coverage and no output schema, the description covers what can be changed but omits how partial updates behave (whether omitted fields are left unchanged) and how the many optional parameters interact. The annotations carry the safety profile, but the operational semantics remain thin.

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 low (29%) with 14 parameters, so the description is expected to compensate. It does map most parameters to user intents (price per gram, supplier, lot, low-stock warning, strength, solvent, notes, shelf, default), but adds little meaning beyond the field names and never clarifies ambiguous ones like the dual meaning of dilutionPct or makeDefault vs onShelf. Marginal value over the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb (update) and resource (bottle) and enumerates the concrete fields and actions in scope — stock recording, price per gram, supplier, lot, low-stock warning, strength, solvent, notes, shelf status, preferred bottle. An agent can tell it is a multi-field bottle editor. It does not, however, explicitly contrast itself with siblings like update_material or add_to_shelf, so differentiation is only implied by the bottle-specific field 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?

It opens with an explicit trigger: 'Use this when the user wants to record stock... or change...'. This clearly states the context in which the tool applies. It stops short of stating when NOT to use it or naming an alternative tool, so it is a clear-context-but-no-exclusions case.

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, and idempotentHint=false, so the safety profile is covered and the description adds an enumeration of touchable fields. But it says nothing about the critical mutation behavior: whether unspecified fields are preserved or whether omitting a field clears it. With annotations carrying the safety burden, a 3 is fair.

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 that opens with the use condition and then enumerates the fields, with no filler. It is dense but every clause carries distinct field 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 an 11-parameter mutation tool with no output schema, the description covers which fields exist but omits the partial-update semantics that an agent needs to call it safely. Nothing explains what happens to fields the caller does not send, 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 only 9%, so the description is doing real work by mapping 10 of the 11 parameters to plain-language concepts ("bench notes" → personalNotes, "favourite star" → favorite, "pin" → pinned, "bottle size" → bottleSizeMl). It does not address the required formula argument beyond what the schema already documents, nor the kind enum values, so it stops short of a 5.

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 specific updatable attributes (name, description, kind, folder, favourite, pin, concentration, IFRA category, bottle size), so the agent knows this is a metadata-mutation tool. However, it never distinguishes itself from the sibling edit_formula, which by name appears to do something similar, leaving ambiguity about which to pick.

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 this when the user wants to rename a formula or change its description..." gives clear intent-based triggers that map to user phrasing. There are no exclusions, though, and the natural alternative (edit_formula) is not mentioned, which would have made the guidance complete.

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 disclose the write profile (readOnly=false, destructive=false, idempotent=false). The description adds the real permission nuance that name/CAS are editable only for the user's own materials, which is useful. However, it never says whether constituent/family updates replace or merge existing values, and non-idempotent repeats are unaddressed.

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 usage trigger first and the field enumeration after; no filler or preamble. The long field list is dense but each item is informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 16-parameter mutation tool with no output schema and very low schema description coverage, the definition is only partially complete. It leaves merge/replace behavior, tier/natural/dropsPerGram handling, and confirmation requirements unexplained, though the field list and permission note cover the essentials.

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 only 13%, so the description carries weight, and it does name most fields (odour, families, note, impact, blotter hours, shelf life, synonyms, flash point, constituents, name, CAS). But it adds little beyond the schema property names and omits tier, natural, dropsPerGram, and any value/format semantics; the 'notes' vs 'note' distinction is ambiguous.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('change a material on their bench') and enumerates the mutable fields, so the agent knows exactly what can be edited. It does not explicitly contrast itself with siblings like get_material or search_materials, but the write framing is unmistakable.

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 'Use this when the user wants to change a material' clause gives a clear triggering condition, and the closing clause constrains name/CAS edits to the user's own materials. No explicit when-not or named alternatives, so it stops short of the top score.

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 declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, covering the safety/mutation profile. The description adds useful behavior beyond that: the edit is in place, it uses the app's own amounts, and it preserves dilution/smell and merges into an existing line. It does not address reversibility or what happens to the replaced material.

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 a single sentence, which is structurally economical, but it is a dense run-on laden with poetic filler ('the same smell carried through each bottle's dilution') that does not earn its place. The usage trigger is front-loaded, but the rest reads as atmosphere rather than specification.

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 mutation tool with annotations and no output schema, the description covers the trigger and some effect semantics (in-place, merge, amounts), which is adequate. It is still vague on the precise result of the swap and on whether the prior line content is discarded.

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 all three parameters (line, formula, members) are already documented in the schema. The description only echoes 'pass its member names,' adding no syntax or format detail beyond what the schema provides; baseline 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 does convey the operation ('replaces the line with it... pass its member names') and ties it to a specific sibling, find_substitutes. But the flowery phrasing ('the same smell carried through each bottle's dilution, merged into a line that already holds that bottle') obscures the exact effect, leaving the core purpose only half-graspable.

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 a clear triggering condition: 'Use this when the user picks one of find_substitutes' suggestions,' which routes the agent from the discovery tool to this mutation tool. No when-not condition or other alternative is offered, but the context is explicit.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: the data is 'read live from its source formula' (freshness/derivation) and it also reports whether the accord 'can be decomposed'.

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 trigger first and the payload second; every clause carries information. It is dense with stacked clauses, which slightly reduces readability but wastes nothing.

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 must carry the return-value burden, and it largely does: material list, dose, per-material share, live source, decomposability flag. Missing only details like ordering or empty-accord behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters (formula, line) are already documented as id-or-name and material-name-or-line-id. The description adds no syntax, format, or disambiguation beyond that, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('show') and resource ('what an accord holds') and enumerates the exact payload: materials at the dose used, each with its share, read live from the source formula, plus decomposability. This distinguishes it from siblings like decompose_accord, get_formula, and check_formula without opening their 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?

'Use this when the user asks what is inside an accord line of a formula' gives a clear triggering condition. It does not, however, explicitly contrast with decompose_accord or insert_accord, leaving the boundary to inference.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the agent knows this is a non-idempotent write that is not destructive. The description is consistent with that ('create or change') but adds nothing beyond it: no statement of what happens to existing content, whether a missing id creates a new notebook, or whether appends are safe to repeat.

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 trigger condition first and the affected fields after. No filler, though the clause list is slightly compressed into one run-on string.

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, no-output-schema mutation tool, the description covers the trigger and the editable fields but leaves the create-vs-update switch (the role of 'id'), the append behavior, and failure conditions unexplained. Adequate as a starting point, 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 description coverage is 0% across five parameters, so the description must carry the load. It does enumerate four of them (title, body, appended text, pin), which is genuine added meaning, but it omits 'id' entirely — the parameter that determines whether this creates or mutates — and never clarifies body-vs-append semantics or the length limits.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a clear verb+resource: create or change a notebook, with the mutable fields enumerated. It does not differentiate itself from the sibling journal_note or list_notes, and the name/title mismatch (write_note vs 'notebook') leaves some ambiguity about whether notes and notebooks are the same object.

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 an explicit trigger — 'use this when the user wants to create a notebook or change one' — which is more than most definitions offer. However it names no alternatives (journal_note, list_notes) and gives no when-not guidance or prerequisites, so the routing decision is still left partly to inference.

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