ShotPulled

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

Annotations already declare that this is a read-only, idempotent, non-destructive, closed-world operation. The description adds useful behavioral context by explaining that it computes age off roast and a resting/staling verdict, and that it resolves to the current bag unless a bag is specified.

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 a single front-loaded sentence with no filler. Every clause contributes either the computation performed, the verdict returned, or the bag-selection behavior.

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?

The tool is simple, an output schema exists, and annotations cover its safety profile, so the description does not need to explain return values or side effects. It is nearly complete, with only minor room to clarify the required bean_id parameter.

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 50%: bag_id is documented in the schema, but bean_id has no schema description. The description partially compensates by implying bean_id identifies the coffee and clarifying that bag_id defaults to the current bag, but it does not explicitly explain the required bean_id parameter or its role.

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 uses a specific verb and resource: it computes a bag's age in days off roast and its resting/staling verdict. It also distinguishes the default current-bag behavior from an explicitly named bag, so an agent can identify the tool's function without inspecting 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 clear operational context: use the coffee's current bag by default or target a named bag. It does not explicitly state when to prefer this tool over siblings, but no sibling provides an equivalent age/verdict computation, so the usage is sufficiently clear.

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

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

Annotations already declare destructiveHint=true, so the irreversibility itself is structured data — but the description adds real information beyond it: the bean's remaining weight is restored and is derived from logged doses. That side effect could not be inferred from annotations or schema. Minor gap: the idempotentHint=true annotation sits slightly awkwardly with a hard delete (a second call would target a missing row), and the description does not address repeat-call behavior.

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

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

Three short sentences, front-loaded with the action, then the non-obvious side effect, then the routing rule. Nothing is wasted and nothing important is buried.

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?

Output schema exists so return values need not be explained, and annotations cover the safety profile. Combined with the side-effect and alternative-tool guidance, an agent has everything needed to call this correctly and safely.

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

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

Schema description coverage is 100% and the single parameter is documented as 'ID of the shot to delete'. The description adds no format, sourcing, or lookup guidance (e.g. where to get shot_id) beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Delete a logged shot from history') and immediately separates it from the sibling that handles corrections ('prefer update_shot over delete-and-relog'). An agent can distinguish it from update_shot without opening either schema.

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

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

Gives an explicit when-to-use condition: only for removing a shot from history, not for fixing a mistake on a valid shot — in which case update_shot is named as the alternative. This is exactly the routing guidance the dimension asks for.

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

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

Annotations already cover read-only/idempotent/non-destructive, and the description adds real value on top: it names exactly what is not produced (no verdict, no recommendation-trail entry), clarifies which bean and which age snapshot are used in shot_id mode, and defines the sensory_tags override semantics including the empty-array case.

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 key fact (writes nothing), then the two modes in dependency order. Dense and mostly earned, though the single long parenthetical sentence could be split for scanability.

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?

An output schema exists, so return values need no explanation, yet the description still points at parity with diagnose_shot including bean_context. Mode selection, side-effect profile, and parameter grouping are all covered for a 10-parameter, all-optional 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 100%, so a 3 is the floor, but the description earns more: with zero required parameters declared, saying that the hypothetical mode needs the full metric set (bean_id, grinder_id, machine_id, grind_label, dose_g, yield_g, time_s, source) tells the agent which subset to supply. It adds no format or unit detail beyond the schema, which is fine given full coverage.

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 (sandbox-only diagnosis preview) and immediately names its sibling diagnose_shot as the output-equivalent, so the agent can triangulate its role without opening another schema. The two operating modes are named concretely.

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 explains the two invocation paths and their conditions: shot_id to dry-run a logged shot, or the full metric set for a hypothetical shot. It stops short of an explicit when-not statement (e.g. 'use diagnose_shot to actually record a verdict'), leaving that contrast implied by naming the 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real substance beyond them: bean resolution semantics, the echo of bean_context, and the fact that the engine ignores free-text notes. It does not discuss output shape or confidence limits, but the added context is well above the annotation baseline.

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

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

Three tight sentences, front-loaded with the core function and warnings, then scope, then the prerequisite. The rule codes (C6/G2/G6) are opaque without KB context and occupy space that could be plainer, but there is no filler.

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

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

An output schema exists, so return values need not be explained, and the description supplies the missing behavioral context: bean resolution, the sensory_tags requirement, and what warnings to expect. Adequate for a zero-required-param read tool, with only the sibling routing 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 coverage is 100% and the single parameter's default (last pulled shot) is documented in the schema itself. The description adds no independent detail about shot_id, so the baseline 3 applies.

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

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

States a specific verb and resource: evaluate shot metrics and return ranked hypotheses plus flip-flop/fatigue warnings. The scope clarification (resolves the shot's own bean, not the active profile) helps separate it from a preview-style diagnosis, but it never explicitly names diagnose_preview as the alternative.

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

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

Gives a concrete prerequisite: sensory feedback must be recorded as sensory_tags on the shot via log_shot/update_shot before calling, otherwise bad-tasting in-range shots come back 'balanced'. That is a clear use condition, though it stops short of stating when to prefer this over diagnose_preview.

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 that this is a read-only, idempotent, non-destructive, closed-world operation. The description adds useful behavioral context by disclosing the aggregate contents returned, including active context, recent shots, recommendations, and locked recipes, though it does not discuss freshness or 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 a single front-loaded sentence with no wasted words. The action and the returned content are presented immediately.

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

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

This is a zero-parameter, read-only aggregate tool with an output schema, so the description does not need to document parameters or return structure. It sufficiently states what the tool retrieves and what categories of data the agent should expect.

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 has zero parameters, so there are no parameter semantics for the description to explain. Per the baseline for zero-parameter tools, a 4 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 uses a specific verb (Retrieve) and a clear resource (current dialing state), then enumerates the bundled content: active context, recent shots, recommendations, and locked recipes. It distinguishes the tool from simple list tools by framing it as an aggregate current-state read, though it does not explicitly name sibling alternatives.

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

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

Usage is implied by the phrase 'current dialing state' and the listed outputs, suggesting the tool is for getting a consolidated dialing overview. However, the description gives no explicit when-to-use guidance, no prerequisites, and no comparison to siblings such as list_shots or suggest_next_step.

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, so the safety profile is fully covered. The description adds no extra behavioral context beyond the basic retrieval action, but it does not contradict the annotations either. Given the low bar enabled by rich annotations, a neutral score of 3 is appropriate.

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 a single, well-structured sentence that states the exact operation and target. There is no redundant or filler content, and the key information is front-loaded. It earns its place by being perfectly compact and informative at a basic level.

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

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

Given the tool's simplicity, an output schema exists to define the return value, and annotations cover the operational behavior, nothing critical is missing from the description. It could have added a hint about what 'knowledge base version' refers to, but for a zero-parameter read-only getter, the description is sufficiently 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 has zero parameters, so there is no parameter information to explain. Per the rubric, a 0-parameter tool gets a baseline of 4; the description does not need to compensate for any schema gaps because there are no parameters.

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

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

The description uses the specific verb 'Retrieve' and identifies the resource as 'the current version of the knowledge base,' making the tool's purpose immediately clear. It does not differentiate itself from siblings, but no sibling appears to handle the same operation, so the lack of explicit distinction is not a significant gap.

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 usage context is implied by the name and description: an agent would naturally use this to get the knowledge base version. However, the description gives no explicit guidance about when to prefer this over related tools like kb_changelog or get_stats, nor any conditions under which it should not be used.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world behavior. The description adds meaningful operational context: default scope, id provenance, unmatched-id reporting under 'missing', and that guide content is synthesized from maker documents.

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

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

Three front-loaded sentences with no filler; each sentence carries either mode selection, scope, id provenance, or edge-case behavior. Dense but appropriately sized for a retrieval tool with default and filtered modes.

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

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

With an output schema present, the description need not explain the return shape. It covers content type, default scope, id source, and unmatched-id handling, while annotations carry the safety profile, so nothing material is missing for correct invocation.

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%, but the description still adds substantial meaning beyond the schema: guide_ids should come from maintenance.tasks[].guide.id in list_grinders and list_machines, omitting the parameter fetches all guides for current equipment, and unmatched ids are reported under 'missing'.

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, enumerates the guide contents (tools, supplies, steps, warnings), and explains both invocation modes. It clearly distinguishes this retrieval tool from scheduling/due-list siblings by naming the sibling tools only as id sources.

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?

Explains the no-argument behavior (all guides for current grinders, machines, and fitted water filters) and the guide_ids behavior, including where ids come from. It does not explicitly compare against siblings such as list_maintenance_due or log_maintenance, nor does it state when not to use this tool.

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, and destructiveHint=false, so the safety profile is covered. The description adds minor behavioral context by promising 'detailed text' as the return content, but does not disclose error/not-found behavior. No contradiction exists.

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

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

A single sentence with no filler; the core operation, resource, and identifier are stated immediately. Every word earns its place.

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

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

For a simple, idempotent, read-only lookup with one fully documented parameter and an output schema, the description provides sufficient context. It does not explain what kinds of rules exist or where rule IDs originate, but those are not necessary for correct invocation.

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 single parameter rule_id is fully described in the input schema (100% coverage), including an example value 'CAT.DARK'. The description only reinforces that lookup is by rule ID, adding no significant meaning beyond the schema.

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

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

The description identifies a specific action ('Retrieve the detailed text'), a specific resource ('a specific rule from the knowledge base'), and the lookup key ('by its rule ID'). It is clear, though it does not explicitly distinguish itself from sibling getters such as get_dial_state or get_kb_version.

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

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

The description implies usage: when you have a rule ID and need the rule text. However, it provides no explicit guidance on when not to use this tool or which sibling tool to prefer for related lookups.

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=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that stats are 'compact flat', which hints at the output shape, but it does not disclose aggregation details, time range, or any other behavioral nuances beyond what annotations provide.

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

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

The description is a single, compact sentence that front-loads the essential information. Every word contributes: the action, the output type, and the supported scopes.

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

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

For a simple two-parameter read-only tool with an output schema and comprehensive annotations, the description is complete enough. The schema covers parameters, annotations cover behavior, and the output schema covers return structure, leaving no critical 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 the schema already documents both parameters fully. The description adds minimal parameter meaning beyond echoing the scope enum ('grinder', 'machine', 'bean') and the notion of usage stats, so a baseline score of 3 is appropriate.

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

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

The description clearly identifies the action ('Get'), the resource type ('usage stats'), and the supported scopes ('grinder, machine, or bean'). This distinguishes it from sibling getters like get_dial_state and get_rule, which target different kinds of information.

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

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

The description implies when to use the tool: when you need usage statistics for one of the three entity types. However, it does not explicitly contrast with alternatives or state when not to use it, such as when listing entities or retrieving state information.

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, and the description's 'Determine' is consistent with a safe computation. It adds that the result is a steps/clicks difference and direction, but does not reveal additional behavioral nuance such as label assumptions or failure 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?

A single sentence with no filler, and the key operation is front-loaded. The unexplained 'C3' parenthetical costs it a top score because it is cryptic rather than clarifying.

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 math utility with an output schema, the high-level purpose is enough for selection, but the agent must guess the labeling convention and why grinder_id is required. Combined with no usage routing, the definition is workable but not fully self-sufficient.

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

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

With 0% schema description coverage, the description must carry the meaning, but it only loosely connects from_label/to_label as 'setting labels' and never explains the label syntax or the grinder_id parameter. It also doesn't state the mapping between labels and steps/clicks, which is the core semantic the 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?

Clearly identifies a calculation: it determines the difference/direction in steps/clicks between two setting labels, so an agent knows what the tool computes. It does not explicitly distinguish itself from siblings like set_grinder_position, and the parenthetical 'C3' is unexplained.

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?

Provides no guidance on when to call this rather than a sibling such as set_grinder_position or suggest_next_step. It neither states prerequisites (e.g., a registered grinder) nor when the math should be used, so an agent must infer from context.

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

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

The description is consistent with the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false). It adds mild context by specifying the changelog content (updates and version differences), but it does not describe ordering, scope, or any additional behavioral detail. Given the annotations already cover safety, this is adequate but not rich.

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 clear sentence with no filler. The main action and content are front-loaded, and every word adds meaning.

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, parameterless read-only tool with rich annotations and an output schema present, the description is sufficient. An agent can correctly infer what the tool returns and that invoking it is safe and non-mutating.

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 has zero parameters, so there is no parameter semantics to explain. The baseline of 4 applies here. The schema coverage is 100% trivially, and the description does not need to compensate for undocumented parameters.

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

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

The description states a specific verb ('Retrieve') and resource ('changelog') and clarifies what it contains ('updates and version differences for the knowledge base'). It distinguishes from the sibling get_kb_version by indicating full version history rather than the current version.

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 intended use is reasonably clear from the description: retrieve knowledge-base changelog/history. However, it does not explicitly mention when to use this tool over get_kb_version or other knowledge-related tools, nor does it state any exclusions. The usage context 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?

Annotations already declare this as a safe, read-only, idempotent operation. The description adds useful behavioral context beyond annotations by explaining that each coffee carries bags[], current_bag_id, and that top-level roast_date/state/grams_remaining/age fields belong to the current bag.

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

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

The description is front-loaded with the core purpose, then adds relevant data-model and ID clarifications. It is somewhat dense for a one-parameter list tool, but every sentence provides useful context rather than repeating structured 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?

Given the low complexity, full schema coverage, existing output schema, and annotations covering safety, the description is complete enough for correct invocation. It additionally resolves the potentially confusing distinction between coffee ids and bag ids.

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 status enum is fully documented in the schema, so the schema carries the parameter semantics. The description only restates that there is a status filter, without adding format or default behavior beyond the schema.

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

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

The description gives a specific verb and resource: listing coffees registered for the account, with a status filter. It clearly separates coffee rows from bag data, but it does not explicitly distinguish this tool from siblings such as register_coffee or update_bean.

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

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

Usage is implied by 'List the coffees registered for the account' with a status filter, so an agent can infer this is for browsing coffees. However, there is no explicit when-to-use guidance, no exclusions, and no named alternatives for cases such as creating or updating coffees.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so safety is covered. The description adds genuinely useful non-obvious behavior: the `id` is a per-account ordinal counting from 1, safe to display, and the handle other tools expect back. It explains the row contents, but not 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?

Purpose is front-loaded in the first clause, followed by the id contract and then the row shape. The class-code list (S/H/Y/A/T/N/U/E) is dense but each token is load-bearing for interpreting output, so it earns its space. Still one long sentence in the middle section.

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?

An output schema exists, so return values don't need full explanation, yet the description still clarifies the non-obvious id semantics and class-code vocabulary, which are the main interpretation hazards. It omits ordering and pagination, which is the 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 description coverage is 100%, so both `status` and `maintenance` are fully documented in the schema. The description restates 'status filter' and the maintenance block contents but adds little parameter-level detail beyond the schema, which is the baseline-3 case.

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 with scope: 'List grinders registered for the account, with status filter.' An agent knows exactly what it returns. It does not, however, distinguish itself from siblings like list_maintenance_due or get_maintenance_guides, which also surface maintenance information.

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

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

Usage is only implied by 'with status filter' and by the maintenance compaction choice. There is no explicit when-to-use or when-to-prefer-a-sibling guidance, no mention of list_maintenance_due for due-only queries, and no exclusions.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior, so the bar is lower. The description nonetheless adds genuinely useful behavioral context: the `id` is account-relative and counts from 1 (safe to display, and what other tools expect back), and `settings` is null when the model is unknown or has no selectors. Those are non-obvious traits an agent would otherwise have to discover by trial.

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

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

The core purpose and the ID semantics are front-loaded, and every sentence conveys information about the payload that the agent would need. The second and third sentences are dense and slightly overloaded, but no sentence is filler.

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

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

An output schema exists, so return values need not be explained, yet the description still covers the two traps: account-relative IDs and null settings. Combined with annotation coverage, an agent has enough to call this correctly; only the relationship to sibling listing tools is left unaddressed.

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

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

Schema description coverage is 100% and both parameters are enums fully documented in the schema, so the baseline is 3. The description mentions the status filter but adds no syntax or default information beyond the schema, and the `maintenance` parameter's compact/full distinction is left entirely to the schema.

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

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

The first sentence states a specific verb and resource: 'List machines registered for the account, with status filter.' That is unambiguous and distinguishable from register_machine and update_machine. It does not, however, explicitly separate itself from list_maintenance_due or list_grinders, which is what a 5 would require.

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

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

The description implies the listing and filtering use case via 'with status filter' and describes what the rows contain, but never says when to choose this tool over list_maintenance_due or when a full maintenance block is warranted. Usage must be inferred from the payload description rather than being 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 establish read-only, idempotent, non-destructive behavior, so the bar is lower. The description nonetheless adds real behavioral context beyond the annotations: only interval-based tasks are considered, and machine-counted, habit-driven, and maker-discouraged tasks never appear — a meaningful scoping rule an agent could not guess.

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

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

Purpose is front-loaded in the first sentence, followed by usage context and then item-level semantics. Three sentences with little waste, though the final sentence overlaps with what the output schema presumably documents.

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 safety fully covered by annotations, a single enum parameter, and an output schema, the description supplies the pieces the structured fields cannot: ordering, inclusion/exclusion rules, and the provenance of each interval (user, maker, or ShotPulled default). Complete enough for correct invocation.

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 enum parameter carries its own explanation (due = due/overdue and not muted; all = every task, muted last). The description never references the status parameter, so it adds no meaning beyond the schema; baseline 3 applies.

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

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

States a specific query over a specific resource — what maintenance is due across the user's current grinders and machines — plus output ordering (most urgent first). It is clearly distinguishable from sibling tools like set_maintenance_schedule, log_maintenance, and get_maintenance_guides, which write or reference guidance rather than report current status.

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

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

"Use it for 'is anything due?'" gives a concrete triggering question, and the exclusion rules clarify what the answer will and will not contain. However, it never names an alternative tool (e.g. get_maintenance_guides for how-to, log_maintenance for recording work), so the agent must infer when another sibling is the better call.

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 one genuinely useful behavioral fact — the `id` is an account-local sequential number safe to display and usable as a key elsewhere — but says nothing about ordering, pagination, or empty 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?

Two sentences, no filler, front-loaded with the core action. The second sentence is convoluted ("the number this account knows that record by, counting from 1") where "account-local sequential ID" would say it faster.

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?

An output schema exists, so return shape needn't be explained, and annotations cover safety. But with three of four parameters undocumented and no statement of filter-combination semantics or default behavior, the description does not close the gaps the structured data leaves.

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%: `status` is documented in the schema but bean_id, grinder_id, and machine_id have nothing. The phrase "filtered by equipment and status" implies those three IDs are equipment filters, but never says what each one selects or how multiple filters combine (AND vs OR).

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

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

States a specific verb and resource ("List recipes") plus the two filtering axes (equipment and status), which is enough to distinguish it from mutation siblings like lock_recipe or update_shot. It stops short of differentiating it from other list_* tools (list_shots, list_beans), which share the same shape.

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

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

There is no explicit when-to-use guidance and no named alternative. The only usage signal is the implicit hint that the returned `id` is "what other tools expect back," which suggests chaining but never states the condition that selects this tool over a 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, destructiveHint=false, and openWorldHint=false, so the description does not need to restate safety. It adds valuable behavioral context by explaining that the id is a stable, user-facing number counting from 1 and is what other tools expect 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?

Two sentences, front-loaded with the purpose and then a useful clarification about the id field. Every sentence contributes without repetition or 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?

Given the simple one-parameter schema, rich annotations, and an existing output schema, the description is complete enough for correct invocation. It covers purpose and the non-obvious id semantics without needing to explain return values.

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%, including a fully documented status enum with default behavior, so the schema carries parameter semantics. The description adds no additional detail about the status parameter, making the baseline 3 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 states a specific verb and resource ("List registered scales") and scopes it to the account, clearly distinguishing it from register_scale, update_scale, and the other list_* siblings by resource.

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 conveys the basic purpose but gives no explicit guidance on when to choose list_scales over alternatives, no prerequisites, and no exclusions. The note about id semantics is useful but does not tell an agent when to invoke the tool.

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 safe, idempotent read, so the description correctly spends its words elsewhere: it discloses that taste_pending is a derived flag and defines precisely what makes it 1. It does not state default sort order or whether filtering combines with AND, which are meaningful behavioral details for a list tool.

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

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

Two sentences, front-loaded with capability and then the derived-field explanation. The taste_pending parenthetical is dense but every clause adds information an agent cannot get from the name alone; 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?

With an output schema present, the description needn't explain return values, and annotations cover the safety profile. What remains thin is ordering and filter-composition behavior, but the core call-correctly information is present.

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

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

Schema coverage is 67%, so the schema already carries most parameter meaning, including a taste_pending definition nearly identical to the description's. The description adds the actionable consequence (backfill via update_shot) but says nothing about how limit/offset behave at boundaries or how multiple filters compose. Baseline 3 fits.

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

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

States a specific verb and resource ("List shot history") plus the two capabilities that matter (pagination, filtering). It does not distinguish itself from neighbors like get_stats or diagnose_shot, but the resource is concrete enough that an agent can identify the tool's job.

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

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

Gives clear context for use (history retrieval with pagination/filtering) and explicitly names update_shot as the path for backfilling an owed tasting, which is real routing guidance. No exclusion rules tell the agent when to prefer get_stats or diagnose_shot instead, keeping it below a 5.

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

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

Annotations already establish that this is a safe, read-only, idempotent operation, so the bar is lower. The description adds useful return-value context: each row's id is account-scoped, starts at 1, is safe to expose, and is what other tools expect. It does not cover ordering or pagination, but adds meaningful behavioral detail 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?

Two tight sentences, front-loaded with purpose and followed by a relevant note about IDs. There is no wasted text.

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

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

For a simple list tool with full schema coverage, strong annotations, and an output schema, the description supplies what is needed and adds an important note about ID semantics. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, and the only parameter is an enum with a clear description and default. The tool description does not add further meaning about the status filter, so 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 states a clear verb and resource: 'List registered waters for the account.' It is easy to distinguish from register_water or update_water, but it does not explicitly differentiate itself from other list_* siblings.

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

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

It says what the tool does but gives no guidance on when to use it versus related tools such as list_recipes or the register/update water tools. There are no exclusions, prerequisites, or alternative-selection hints.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds the critical specifics beyond that: it overwrites only the recipe matching the same coffee/grinder/machine/program/drink-intent tuple, and preserves the existing recipe_id. That explains exactly what is destroyed and how identity is retained, which the annotations alone 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?

Two sentences, no filler, and the definition of the action is front-loaded before the overwrite rule. 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?

With an output schema present, the description needn't explain return values, and the annotations cover the safety profile. It covers the mutation effect well; only minor gaps remain, such as failure behavior or why drink_intent (straight/milk) is a required selector.

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 coverage the description must carry the load, and it does: it frames from_shot_id as the 'successful shot' source and names the composite key (coffee, grinder, machine, program, drink intent) that determines which record drink_intent selects. This meaningfully exceeds the bare enum/integer schema, though from_shot_id's exact semantics remain only implied.

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 (lock) and resource (recipe) and defines what locking means: promoting a successful shot to the reference dialing recipe for the equipment profile. This clearly separates it from list_recipes, update_shot, or log_shot.

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 phrase 'Lock a successful shot' implies you should have a successful shot to promote, which is implied usage context. However, it never states when-not to use it or points to any alternative (e.g., list_recipes or update_shot), leaving the routing 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?

Adds substantial behavior beyond annotations: a disassembly task opens a calibration epoch, prior locked recipes are reinterpreted through that epoch's offset, and omitting offset_value leaves the epoch visibly unmeasured rather than assumed zero. These are consequential side effects not derivable from readOnly=false/destructive=false.

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

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

Purpose and epoch consequence are front-loaded and almost every sentence carries information. A few asides ('which is the one moment anybody actually knows it') add flavor at some cost to terseness.

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 write tool with nested details and an output schema, the description covers the epoch mechanics, offset omission state, and evidence capture well. It does not address duplicate or repeated logging behavior, which matters given idempotentHint=false.

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

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

Schema coverage is already 100%, but the description still adds meaning: offset_value is defined as a signed clicks-to-add correction along the collar's direction, offset_source enumerates pull/counted/typed, and details is tied to the per-task details_fields published elsewhere.

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 and resource: 'Log a cleaning or maintenance job against a piece of equipment.' It also distinguishes itself from read-side siblings by pointing at list_grinders/list_machines for due state and from set_maintenance_offset by owning the offset recorded at log time.

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

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

Gives clear conditions: record the offset only if you counted clicks at reassembly; any vocabulary task may be logged even if the maker advises against it; read due state from list_grinders/list_machines. No explicit when-not guidance relative to list_maintenance_due or set_maintenance_offset, which leaves some sibling 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 carry the mutation and non-idempotency signals, so the description's job is lighter. It adds context that this records a recommendation rather than a definitive change and notes the G2 analysis purpose, but says nothing about repeated logging effects or return 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?

The description is one tight sentence with no filler, and the key action is front-loaded. The parenthetical G2 is opaque but does not add bloat.

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

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

For a six-parameter write tool with four required fields and no schema descriptions, this single sentence is too sparse. The purpose is clear, but the agent still lacks guidance on how to fill parameters, especially cited_rules and based_on_shot, and when this tool should be preferred over siblings.

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

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

Schema description coverage is 0%, and the description only hints at a 'dialing change,' which loosely covers lever and direction. It does not explain confidence, cited_rules, or based_on_shot, and does not compensate for the schema's lack of parameter 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?

The description states a specific verb—log—and a distinct object, a recommended dialing change, which separates it from sibling log tools like log_shot and log_maintenance. It does not explicitly name an alternative, so it stops short of full differentiation.

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

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

The description gives a purpose ('to allow contradiction/oscillation checking') but no explicit when-to-use or when-not-to-use guidance. It does not point to any alternative tools or exclusions, leaving the agent to infer when logging is appropriate.

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 annotations (write, non-idempotent, non-destructive) it discloses two non-obvious behaviors: shots with no tags/rating are filed as taste-pending, and the diagnosis engine reads sensory_tags rather than flavor_notes. It does not mention the backdating interaction with diagnose_shot's default target (that hint lives in the schema), so a small gap remains.

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 purpose and active-context semantics, then ordered by decision importance (bean override → backdating → tasting). Dense but nearly every clause carries an actionable rule; the closing sentence is long and could be split, but nothing is filler.

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

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

For a 33-parameter mutation tool with an output schema, the description covers the risky/ambiguous decisions well, but the four required fields (dose_g, yield_g, time_s, finish_action) have no description in either schema or text, and the many optional fields get no framing. Adequate but not complete for this surface area.

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%, so the description must add meaning for high-stakes params – it does for bean_id (wrong-bag risk), pulled_at (backdating semantics) and the sensory_tags/tasted/flavor_notes relationship (tags are defect-oriented, so a clean shot has none). Many optional params (verdict, drink_intent, observations, the metric fields) are left to the schema alone.

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?

"Log an espresso or alternative shot/brew attempt" states a specific verb and resource, and the body makes the scope concrete (active-context stamping, overrides, tasting state). It is clearly distinguishable from siblings like update_shot (edits an existing shot), diagnose_shot (analysis) and log_recommendation.

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 conditional rules are given for the three decisions that matter: pass bean_id when the user names a coffee, use pulled_at for backdating, and pass tasted=1 with no tags for a clean shot. It also names the alternative handling (rating or tags) and the consequence of doing neither.

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?

Far exceeds what the annotations convey: annotations only flag destructive=true and idempotent=false, while the description explains exactly what moves (bags, shots, recipes, recommendations), the conditional behaviors (origins only if target has none, newer lock wins and older is deleted), that the source is archived not deleted, and that the operation is irreversible.

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?

Leads with the trigger, then the consequences, then the safety warning — all within four sentences with no filler. The dense lock-conflict clause is the only heavy sentence, but it is information the agent cannot get elsewhere.

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?

A destructive mutation with an output schema needs the description to cover data migration, edge cases and irreversibility; it does all three. Return values are covered by the output schema, so nothing material 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 schema already labels from_bean_id as the duplicate to be archived and into_bean_id as the survivor, so the description is not the sole source. It still adds directional reinforcement and points the agent at list_beans to resolve the numbers before calling.

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 ('fold one coffee into another') plus the exact condition that motivates it ('when the same coffee was registered twice'). This clearly distinguishes merge_beans from update_bean and the register_* siblings.

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

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

Gives an explicit trigger condition (duplicate registration) and a required pre-flight step: confirm both numbers with the user and look them up via list_beans. It does not name the non-duplicate alternative (update_bean) for cases where the coffees are genuinely distinct, so the when-not case 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 declare a non-readonly, non-idempotent, non-destructive create, and the description adds real behavioral context beyond that: what is inherited (recipes, notes, history) versus what is new (roast date, weight, price, state), plus the bag_id return and that bag numbers are a separate series from bean numbers. It stops short of covering failure modes or duplicate handling, but the inheritance/no-active-change details are the valuable part.

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, front-loaded with the core action before the inheritance rule, the return-value caveat, and the alternative. Nothing repeats the name or the schema, and every sentence carries information an agent needs.

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 create tool with annotations and an output schema, the description covers the essential gap areas: which entity is being extended, what is conserved, the id semantics of the return, and the sibling to use instead. Remaining detail (formats, defaults, optional fields) is delegated correctly to the schema.

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

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

Schema coverage is 69% and the schema already documents the dates, state default, bag_notes scoping and product_id guidance, so the baseline is a 3. The description does add a useful partition by naming the 'purchase facts (roast date, weight, price, state)' that are new per bag, but it leaves the remaining undocumented fields (ean, cost, storage, currency) untouched.

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 ('Register another bag of a coffee that is already in list_beans') and pins the scope to a repeat purchase of the same roaster's product. It explicitly distinguishes itself from register_coffee, so an agent can choose without opening either schema.

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

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

Gives both the when ('coffee already in list_beans... bought again') and the when-not with a named alternative ('For a coffee that is not in list_beans yet, call register_coffee instead'). It also rules out a side effect an agent might assume ('Does not change the active coffee').

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 beyond the annotations by disclosing the activation side effect chain: the new coffee does not become active unless no coffee is in use (none active, active archived, or all bags finished), and the reply's `active` field reports which happened. Annotations only say non-readonly, non-idempotent, non-destructive; the active-state logic is the non-obvious behaviour an agent must know.

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 decisive constraint (NOT yet in list_beans) and the alternative routing. The parenthetical field enumerations are long but justified because they are what separates bean from bag fields; the text is dense with little 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 48-parameter creation tool, it covers the essentials an agent needs before calling: uniqueness requirement, the bean/bag split, the activation consequence, and the returned ids (bean_id, bag_id) even though an output schema exists. It leaves unclear how duplicates are detected (e.g. via ean) and what validation failures look like, which is a modest 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?

Adds real meaning over the 48%-covered schema by partitioning the 48 parameters into coffee-level fields (roaster, origins, variety, process, roast level, roasting type, cupping score, aromatics, notes, rest window) versus bag-level fields (roast date, weight, price, state), which the schema does not do. Many parameters (ean, url, qr_code, currency, storage, attachments) remain unmentioned, so it stops short of full compensation.

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 plus a hard precondition: register a coffee NOT yet in list_beans, together with its first bag. It also names the sibling it is not (register_bag) and the neighbour it does not replace (set_active), so an agent can distinguish it from siblings 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?

Explicit when-to-use ('NOT yet in list_beans'), when-not ('For another bag of a coffee already on file call register_bag instead'), and what to do afterward ('call set_active with its bean_id when the user starts brewing it'). Exclusions and alternatives are spelled out rather than 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 declare non-readOnly, non-idempotent, non-destructive, but the description adds the crucial side effect the annotations cannot express: activation is conditional on no active/archived grinder, and the reply's `active` field tells which. That is genuine behavioral disclosure beyond structured data.

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

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

Three tight sentences with the core action front-loaded and the conditional-activation rule immediately after. No filler, though the final sentence about the `active` field is slightly compressed in wording.

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?

An output schema exists so return values need not be detailed, yet the description still points to the `active` reply field, which is the one output an agent must act on. Combined with the activation rule, an agent has enough to call it correctly; only the post-creation edit path is offloaded to 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 79%, so the schema already documents nearly all 14 parameters including the setting_scheme and catalog_id semantics. The description adds only the aggregate concept of a 'dial settings scheme' and does not clarify any individual parameter 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?

States a specific verb and resource ('Register a manual or electric grinder with its dial settings scheme'), which immediately separates it from update_grinder and set_active in the sibling list. The scope (creating a new grinder record vs. mutating state) is unambiguous.

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

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

Explicitly names the alternative for switching: 'otherwise call set_active with its grinder_id to switch to it,' and the condition under which this tool activates the grinder. It does not mention update_grinder for later edits, so it stops one step short of full routing guidance.

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

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

Annotations declare a non-read-only, non-destructive, non-idempotent write, but say nothing about the side effect of activation state; the description adds that meaningful behavior and points at the reply's `active` field to confirm it. It does not cover duplicate-name handling or validation failures, which is the remaining gap for a creation tool.

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

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

Three tight sentences with zero filler; the activation condition, which is the only non-obvious consequence of the call, is front-loaded right after the purpose statement.

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 14-parameter, 2-required creation tool with an output schema, the description covers the one behavior an agent cannot infer from structured data: the conditional activation. Return values are covered by the output schema, so the remaining uncovered params (notes, boiler_type, basket_size_grams) are a minor omission rather than a blocking one.

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

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

Schema description coverage is 71% and is unusually rich (catalog_id, hardness_dh, prep_style all carry their own semantics and warnings), so the baseline is a 3. The description itself adds no parameter-level meaning beyond what the schema already states, relying entirely on the structured fields.

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

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

Names a specific verb (register) and resource (espresso or alternative preparation machine), and immediately scopes it against the neighbouring alternatives by naming set_active for the switch case. An agent can distinguish it from update_machine and register_grinder 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?

States the exact condition under which the new machine becomes active (none active, or the active one archived) and the explicit alternative when that condition fails: call set_active with its machine_id. This is the when/when-not/alternative triad in two sentences.

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 openWorldHint=false, so the mutation profile is known. The description usefully adds what actually gets destroyed: an existing program_number is overwritten while previously logged shots keep pointing at it, which is valuable context beyond the annotations.

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

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

Three tight sentences, front-loaded with the core action and then the type semantics and overwrite consequence. Every sentence carries information, though it could be slightly terser.

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?

Output schema exists so return values need not be explained, and the description covers the two program types and overwrite behavior well. The omission of volume_source semantics and any error/permission notes keeps it from being fully complete for a 7-parameter 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 71%, and the description reinforces the key pairing (program_type "volumetric" → target_volume_g, "timed" → target_time_s), adding the relational logic the schema states per-field. However it says nothing about volume_source, description, or machine_id, so it only partially compensates for the coverage gap.

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

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

States a specific verb and resource ("Register a programmed shot button on a machine") and immediately defines what a program is and how it terminates a shot. This clearly distinguishes it from sibling registration tools like register_machine or register_grinder, which target different resources.

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

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

The description distinguishes the two program modes (volumetric vs timed) and the fields each requires, which implies usage, but it never says when to call this versus update_machine or register_machine, nor any prerequisites. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the description only needs to add context beyond that, and it adds almost none. It does not say what happens on a duplicate name, whether the call fails or merges, or what the response contains. The phrase about weighing dose and yield is a definition, not 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?

A single front-loaded sentence with no waste, but it is undersized for a 15-parameter creation tool; the brevity is under-specification rather than economy. Nothing in the sentence is wasted, yet it does not use its position to route the agent anywhere.

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 15-param create tool with a rich sibling set, the description omits duplicate handling, the update_scale alternative, and any note about which fields matter most (despite the schema hinting at fit under a group head). An output schema and annotations exist, so return values need not be explained, but the calling context is 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 100% and the 15 parameters are richly documented inline, including enum meanings and null conventions, so the schema does the heavy lifting. The description adds no parameter meaning at all. Baseline 3 applies.

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

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

Names a specific verb and resource (register a scale) and glosses the resource as the weighing instrument for dose and yield, which distinguishes it from register_grinder/register_machine. It does not explicitly separate it from update_scale, but the create-vs-update distinction is carried by the verb 'register'.

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

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

There is no when-to-use guidance at all: no mention of using update_scale for an existing scale, no pointer to list_scales to check for duplicates, and no prerequisites. The only signal is the implicit 'register = new record' reading of the verb.

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 signal that this is not a read-only operation, but the description adds no behavioral detail beyond that, such as whether duplicate names overwrite, whether registration requires approval, or any side effects. It does not contradict the annotations.

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

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

The description is a single sentence with no filler, front-loading the core action and resource. It is appropriately sized for the simplicity of the 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 registration tool, the description combined with full schema coverage, annotations, and an output schema provides enough context for an agent to select and invoke the tool. It is slightly incomplete only because it omits usage guidance relative to sibling tools, but that is covered under usage_guidelines.

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 input schema has 100% property description coverage, so the schema carries the parameter documentation burden. The description adds no additional parameter meaning beyond what is already in 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 uses the specific verb 'Register' with the resource 'water formulation', which matches the title and clearly identifies the tool's purpose. It also distinguishes this tool from sibling register_* tools by naming water as the entity, and custom/commercial scope adds useful clarity.

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

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

The description gives no guidance on when to use this tool over alternatives such as list_waters or update_* tools. No exclusions, prerequisites, or comparison with sibling tools are provided; usage context is only implied by the name and title.

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 idempotentHint=true and destructiveHint=false, so the safety profile is partly covered. The description adds useful behavioral context beyond them: partial updates leave fields unchanged (matching the null parameters) and the reply's `active` field reports what actually got activated, which is genuine non-obvious behavior.

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

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

Three sentences, front-loaded with the core action, then provenance, then the non-obvious activation caveat. Dense and mostly waste-free, though the final sentence is slightly long for what it conveys.

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

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

With an output schema present, return-value docs aren't needed, and the description still hints at the reply's `active` field. Combined with full schema coverage and annotations, an agent has what it needs; only the absence of explicit alternative routing keeps it from a 5.

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 each parameter already documents 'null = leave unchanged' and 'Never guess one'. The description only adds the provenance of the numbers (list_beans/list_grinders/list_machines), which largely duplicates the schema, 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 ('switch the active') and resource (bean, grinder, machine) for this account, and explicitly sets it apart from the register_* siblings by noting that registration only activates when nothing of that kind is in use. An agent can tell this is the explicit activation setter, not a create/update tool.

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

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

Gives clear context for when to call it: to start using something new (after registering) as well as to switch back to an existing item. It also points to the list_* tools that supply valid numbers, but doesn't enumerate alternatives such as update_bean or set_grinder_position for other forms of change.

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 indicate a non-read-only, non-destructive, idempotent operation. The description adds the useful behavioral nuance that the operation can both archive and restore, implying reversibility, but it does not disclose side effects, permissions, or what happens to equipment once archived.

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 a single, front-loaded sentence: action first, then the complete resource scope. Every word carries information, with no redundant filler.

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

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

For a simple three-parameter tool with fully documented schema fields, enum constraints, safety annotations, and an output schema, the description provides sufficient context for correct invocation. Remaining details such as return format are already handled elsewhere.

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 each parameter already has a clear description, including enum values for kind and archived. The description only restates the equipment kinds from the schema and adds no new parameter-level meaning.

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 uses precise verbs ('Archive or restore') and explicitly names all supported resource kinds ('grinder, machine, water, or scale'), matching the kind enum exactly. This makes the tool's purpose immediately distinguishable from siblings like set_active or register_*.

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 provides clear usage context: use this tool when you need to archive or restore one of the listed equipment types. It does not name alternatives or explicit when-not scenarios, but the action is unique among the sibling tools, so no routing conflict exists.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description adds real value by explaining what 'destructive' means here — the stored position is replaced and no history is retained — plus the side effect of a measured source on verification freshness. It stops short of describing permissions or the response shape.

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

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

Three short sentences, front-loaded with the core action, then the consequence of the source value, then the overwrite behavior. No filler, every sentence carries information.

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

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

An output schema exists so return values need no explanation, and the description covers the destructive overwrite semantics and the key source side effect. It is nearly complete for a 3-parameter mutation tool, with only minor gaps around permissions and freshness semantics.

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%, with source and setting_label documented in the schema. The description adds meaning to source="measured" by tying it to verification freshness, which the schema does not state, but it says nothing about grinder_id and only partially compensates for the coverage gap.

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

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

The description states a specific verb and resource — setting the grinder collar position — which separates it from the generic update_grinder sibling. It does not explicitly name or contrast with alternatives, but the scope is unambiguous.

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

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

There is no explicit 'use when / don't use when' guidance or named alternative, but the note that source="measured" resets verification freshness implies when a verified entry is warranted versus a guess. Usage is inferable rather than stated.

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

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

It provides significant behavioral detail beyond the structured fields by defining the logical meaning of 0 (unchanged), the semantic implication of omitting offset_value (clearing measurement), and the relational context (offsets composing for a locked recipe). These details add substantial clarity.

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 prose is highly technical yet perfectly structured. Every sentence contributes vital, specific information (e.g., 'Zero is a legitimate measurement,' 'takes an ENTRY') and the flow is logical and dense.

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?

The description provides a comprehensive context for a highly technical tool. By explaining concepts like 'calibration epoch' and the dependency on the entry ID, it ensures the AI agent has the full necessary context for correct invocation.

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 100% schema description coverage, the baseline is 3. The description elevates this by explaining the 'signed direction' of the offset and the context of the 'entry,' adding crucial meaning that transcends the formal type definitions.

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 is highly specific, stating that it records how a maintenance job moved the reference and attaches this data to the entry that opened a calibration epoch. This clearly defines the tool's domain within the overall system architecture.

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?

While it clarifies that the offset belongs to an 'ENTRY, not a piece of equipment,' which provides crucial scope guidance, it does not explicitly suggest alternatives like 'log_maintenance,' making it an implied usage scenario rather than a direct comparison.

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?

Despite annotations already declaring mutation and idempotency, the description adds substantial behavioral context: partial-update semantics ('Only the keys you send in fields change'), null-as-reset behavior for both every and muted_until, what enabled:false does without forgetting the interval, and how changed_at resolves queued-edit conflicts with applied:false. This is exactly the kind of detail 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?

Three sentences, front-loaded with the core action and then the partial-update rule and usage trigger. Dense but nearly every clause carries operational meaning; the final read-back sentence is slightly tangential but still 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 complex nested-parameter mutation with an output schema and annotations, the description covers when to use it, how partial updates behave, reset semantics, and where to read task state. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 80%, and the nested schema already documents the null-reset semantics for every and muted_until, enabled:false, and changed_at conflict handling. The description largely restates those same semantics rather than adding new meaning, so the baseline 3 applies.

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

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

Names a specific verb and resource (set the user's own schedule for one maintenance task on one grinder/machine) and enumerates the three modes: own interval, switch off, or mute. It is clearly distinguished from siblings like log_maintenance and set_maintenance_offset, which handle logging and offsets rather than a full schedule.

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

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

Gives an explicit trigger ('when the user states how often they do a task or asks to be left alone about one') and an explicit prohibition ('never to invent an interval'). It also points to list_grinders and list_machines for reading back state, but does not explicitly contrast with set_maintenance_offset, so it falls just short of naming alternatives.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds only that exactly one step is returned; it says nothing about what happens when no step is available, whether state must exist first, or how fresh the suggestion is.

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. It is efficient, though the terseness contributes to the missing context.

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?

An output schema exists so return values need not be described. However, for a tool whose whole purpose is ambiguity-prone ('next step'), the bean_id semantics and the precondition for getting a suggestion are missing, leaving the definition only barely sufficient.

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

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

One required parameter with 0% schema description coverage, and the description never explains what bean_id identifies or that it comes from list_beans/register_bean. The description does nothing to compensate for the undocumented 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?

Names a specific verb ('Retrieve') and resource ('the single next experiment step from the reasoning engine'), which is enough to distinguish it from the CRUD/registration siblings. What an 'experiment step' actually is in this coffee-tooling domain is left implicit, so it stops short of full clarity.

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

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

There is no statement of when to call this versus diagnose_shot, get_dial_state, get_rule or the other read-oriented siblings. An agent must guess that this is the recommendation/advice endpoint rather than a lookup.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered elsewhere. The description does convey that this mutates bag status (open/seal/freeze/thaw/finish), which is useful context, but it says nothing about whether omitted fields are preserved, whether changes are reversible, or what the response confirms.

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 plus a single routing sentence, with the primary purpose front-loaded and the sibling disambiguation last. Every sentence carries distinct 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?

Output schema and annotations carry the return shape and safety profile, and the description covers purpose, identifier sourcing, and sibling routing. A mutation tool with a 19-field nested object would ideally state whether the fields object is a partial patch (unmentioned fields preserved) and confirm the destructive semantics, which is the main missing piece.

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 rich field-level descriptions already explain grams_remaining and weight_adjustment_g. The description adds the mapping from plain-language fields (roast date, weight, grams left, price) to the fields object, but says nothing about ean, qr_code, storage, bag_notes, or the optional reason 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 (change), resource (bag-level facts on one bag of a coffee), and enumerates the concrete operations (open, seal, freeze, thaw, finish, correct roast date/weight/grams left/price). It explicitly distinguishes itself from the sibling update_bean, which handles coffee-level attributes.

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?

Tells the agent where bag identifiers come from (bags[] on list_beans or current_bag_id) and names the alternative tool (update_bean) for coffee-level edits. The only minor gap is that it does not spell out that state transitions happen by setting state = open/frozen/etc., but the operation verbs imply 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 this a non-idempotent, destructive, closed-world mutation, so the safety profile is covered. The description still earns credit for disclosing a non-obvious cross-resource side effect: bag-shaped fields passed here mutate the coffee's CURRENT bag rather than the coffee. It does not explain partial-update semantics (whether omitted fields are preserved), merge behavior, or failure modes.

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

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

Three sentences, front-loaded with scope, then the routing rule, then the caution — nothing redundant. The '(G5, C10)' code references are opaque to an outside reader and cost a little clarity, and the parenthetical field lists are dense.

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

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

With an output schema present, return values need no explanation, and the annotations cover the destructive/non-idempotent profile. What remains thin is update semantics: whether this is a partial patch, how nested `origins` arrays are treated, and what happens when both coffee and bag fields are sent together.

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

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

Schema coverage is only 33%, and the flat `fields` bag mixes coffee-level and bag-level keys with no structural distinction in the schema itself. The description supplies exactly that missing semantics by naming which fields land on the bag versus the coffee, and it explains the purpose of the `reason` note. It falls short of fully compensating because the field lists are truncated ('…') and replace-vs-append semantics for individual fields are only partially addressed.

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 ('Update a coffee's own fields') and enumerates representative fields so the scope is concrete. It immediately contrasts with the sibling update_bag, so an agent can pick 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?

Explicitly routes the agent: 'Use update_bag when it has more than one' bag. It also flags the dial_category change as having downstream consequences on engine advice and asks for a rationale note, which is real decision guidance rather than restatement.

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?

Far exceeds the annotations: it explains that only sent keys change, that null (or empty string for text) clears, that required fields can be changed but not cleared, that saving writes maintenance history, opens an unmeasured calibration epoch for locked recipes, marks or clears the collar's current setting, converts measured offsets when a click changes worth, and that direction_convention flips all prior finer/coarser statements without moving a number. This is exactly the destructive/consequential context the destructiveHint flag 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?

Front-loads purpose and the clearing rule, then layers consequences. Dense and mostly earning its length, though the final sentence about direction_convention is long and the middle section packs several distinct behaviors into one sentence, which slightly hurts scannability.

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, non-idempotent nested-object mutation, it covers write semantics, clearing rules, side effects, dry-run behavior, and escalation to a sibling. An output schema exists and the dry_run parameter already enumerates returned fields, so return values need no further explanation.

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

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

Schema coverage is 75%, and the description adds genuine semantics the schema does not: partial-update/patch behavior, null-vs-empty-string clearing rules per type, the ability to omit fields when only reason is sent, and the shared meaning of setting_scheme/nominal_step/components_spec as the lens through which recorded grind labels are read. It does not individually explain every field, but the highest-risk ones are covered.

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 and resource ("Correct a registered grinder") and enumerates the mutable aspects (name, burrs, collar scheme, nominal step, layout, range, notes). It is clearly a mutation of an existing record, implicitly distinguished from register_grinder, but it never names 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?

Gives concrete operational guidance: call with dry_run first when changing setting_scheme/nominal_step/components_spec, and tell the user before saving. It also routes to set_maintenance_offset for resolving an opened calibration epoch. What's missing is an explicit boundary against register_grinder or update_machine for adjacent 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 give destructiveHint=true without explaining scope, and the description fills that gap precisely: partial-update semantics ('Only the keys you send in fields change'), the null-vs-empty-string clearing rule and its exception for numbers and closed lists, and the fact that required fields can be changed but not cleared. It also discloses a cross-system side effect not visible anywhere else — prep_style determines whether shots are diagnosed at all.

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?

Highly front-loaded: purpose, then update/clearing semantics, then exceptions, then sibling routing. The parenthetical field list and the dense closing sentence are efficient but pack several rules into single run-on clauses, which costs a little readability.

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

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

For a nested-object mutation with an output schema, the description covers what an agent actually needs: how partial updates work, how to clear values, what cannot be cleared, what is out of scope, and the domain consequence of prep_style. Return values are correctly left to the output schema.

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

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

With 67% schema coverage the schema already documents most fields, but the description adds rules the schema does not: the null/empty-string clearing asymmetry, the distinction between changing versus clearing required fields, and the consequence of prep_style on diagnosis. It does not, however, restate which fields are required or optional, leaving that to the schema.

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

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

Opens with a specific verb+resource ('Correct a registered machine') and enumerates the exact editable surface (name, control type, prep type/style, basket, boiler, accessories, notes) plus the secondary purpose of recording selector positions. It explicitly carves out what belongs to siblings: 'Programs are edited with register_program, the built-in grinder link is not editable here, and archiving is set_equipment_archived.'

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

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

Names three alternatives and the boundary condition for each (register_program for programs, set_equipment_archived for archiving, grinder link out of scope). It also states the degenerate call shape ('fields may be omitted when only reason is sent'), removing the main invocation ambiguity.

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