ShotPulled

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

Annotations already declare the tool read-only, idempotent, and non-destructive, and the description's 'Compute' wording is consistent with those. The description adds the output semantics (days off roast and verdict), but does not disclose behavior around unknown bean IDs or data availability; with annotations carrying the safety profile, 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?

The description is a single focused sentence that front-loads the action and states the key output. There is no redundant or filler content.

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

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

For a simple tool with one self-explanatory parameter, read-only/idempotent annotations, and an output schema, the description is sufficiently complete. It states what is computed without needing to detail return fields or side effects.

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

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

Schema description coverage is 0%, so the description needed to compensate by explaining bean_id, but it does not mention the parameter at all. The meaning is only inferable from the parameter name and the tool's purpose, which provides minimal but not adequate semantic guidance.

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 ('Compute') and resource ('coffee age') and clarifies the output as days off roast plus a resting/staling verdict. This makes the tool's function unambiguous and distinguishes it from the sibling tools, none of which compute age.

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 implied: call this tool when you need the age of a coffee bean in days off roast and a resting/staling verdict. However, the description does not explicitly state when not to use it or mention any alternative sibling, so guidance is only implicit.

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the bar is lower. The description still adds genuinely new behavioral info: the cascade side effect 'Restores the bean's remaining weight (which is derived from logged doses)' and the irreversibility warning 'Hard delete — there is no undo.' No contradiction with idempotentHint, since re-deleting an already-removed shot would simply no-op or fail.

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, each earning its place: purpose, side effect, and alternative routing. The hard-delete warning is front-loaded before the update_shot guidance, and there is zero fluff, repetition, or restatement of the title.

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

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

The behavioral core is covered: purpose, weight-restoration side effect, irreversibility, and the preferred alternative. The output schema exists so return-value detail is not required. A minor gap is behavior for a non-existent or already-deleted shot_id, but idempotentHint and the output schema mitigate that. For a one-parameter tool, this is complete enough.

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% — the schema itself documents shot_id as 'ID of the shot to delete.' The description adds no parameter-level detail beyond that (no validation rules, no edge-case handling), so the baseline of 3 applies per the coverage rule.

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 ('Delete') with a precise object ('a logged shot from history'), clearly scoping the operation to shot history entries. It distinguishes itself from update_shot by implication, and the title is reinforced rather than merely restated.

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 agents away from destructive misuse: 'To fix a mistake on an otherwise-valid shot, prefer update_shot over delete-and-relog.' This names the exact alternative and the condition that should select it, giving clear when-to-use vs when-not-to-use 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?

The description goes well beyond the annotations by disclosing exact non-obvious behaviors: no verdict is produced, no recommendation-trail entry is written, sensory_tags can override stored tags, and the shot's own bean and pulled_at age are used. This is rich behavioral context beyond the readOnly and idempotent hints.

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

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

The description is well-structured, front-loaded with the most important fact ('Sandbox-only diagnosis, writes nothing'), and every sentence adds information. The two modes are presented clearly without unnecessary verbosity.

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

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

For a tool with 10 parameters, no required fields, a full output schema, and safety annotations, the description covers everything needed to invoke it correctly: both modes, ignored params, side effects, and the relationship to diagnose_shot. No critical operational detail is missing.

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

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

The schema already covers all parameters at 100%, so the baseline is 3. The description adds value by grouping parameters into two meaningful modes, clarifying that shot_id ignores the metric params, and explaining the sensory_tags override semantics. This is helpful but not strictly necessary given the schema descriptions.

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

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

The description names a specific operation ('Sandbox-only diagnosis'), explicitly states it writes nothing, and differentiates it from the sibling diagnose_shot by noting the identical output shape but no verdict or recommendation-trail entry. The two call modes are clearly described, so an agent can tell exactly what this tool does.

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

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

The description gives clear context for when to use the tool: preview a logged shot via shot_id or a hypothetical shot via the full metric set. It implies this is the safe, side-effect-free alternative to diagnose_shot, but it does not explicitly say 'use diagnose_shot when you want actual diagnosis/writes,' so the exclusion is not fully 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 and idempotentHint, but the description adds substantial non-obvious behavior: the shot's own bean is resolved using pulled_at rather than the active profile, it is echoed as bean_context, and the engine ignores free-text notes while relying only on metrics and sensory_tags. The warning about in-range tasteless shots returning 'balanced' is especially valuable.

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 dense sentences each earn their place: the first front-loads the operation and outputs, the second explains bean resolution safety, and the third gives the critical data prerequisite and failure mode. There is no filler or repetition.

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

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

For a tool with one optional parameter and an output schema, the description fully covers the purpose, input default, bean-resolution behavior, data prerequisites, and a key failure mode. Nothing essential is missing for an agent to call this tool correctly.

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

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

The only parameter, shot_id, is fully documented in the schema including its default behavior. The description adds no new syntactic or semantic detail about the parameter beyond contextualizing older shots, so the baseline of 3 is appropriate given full schema 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?

The description uses a specific verb ('Evaluate shot metrics') and names concrete outputs: ranked hypotheses, flip-flop warnings, and fatigue warnings. It is clearly distinct from the many data-management siblings, though it does not explicitly contrast itself with diagnose_preview.

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 provides a clear prerequisite: taste feedback must be recorded as sensory_tags via log_shot or update_shot before diagnosing, with a concrete consequence if ignored. It also explains that diagnosing older or differently-filed shots is safe. It does not state explicit when-not-to-use cases or name alternative tools, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description needs less safety context. The description adds the scope of the read (dialing state, active context, recent shots, etc.) but no additional behavioral traits such as rate limits or state-dependent 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 a single sentence that leads with the action and resource, then compactly lists the output categories. Every word adds information, with no filler or redundancy.

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

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

For a zero-parameter read-only tool with full annotations and an output schema, the description is sufficiently complete. It identifies what is returned without needing to duplicate schema details or disclose side effects that annotations already cover.

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 and schema coverage is trivially 100%, so there is nothing for the description to explain. The baseline for zero parameters is 4, and no additional parameter detail is needed.

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 names a unique resource ('current dialing state'), then enumerates concrete result contents. This clearly distinguishes it from sibling tools like list_shots or get_stats, which cover separate concerns.

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 versus the many sibling tools. It does not mention alternatives, exclusions, or prerequisites, leaving the agent to infer usage from the name alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, 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 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?

The annotations already establish read-only, idempotent, non-destructive behavior, so the description adds value by explaining the id contract: rows are numbered from 1 per account, safe to display, and expected as identifiers by other tools. This is useful behavioral context that structured annotations do not convey.

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

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

Two compact sentences, with the core purpose front-loaded and the important id semantics in the second sentence. There is no filler or repetition of schema content.

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

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

For a simple, single-parameter list operation with full schema coverage and an output schema, the description covers the essential non-obvious context: account-scoped records, status filtering, and the id numbering/sharing contract with other tools. Nothing needed for correct invocation is missing.

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

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

Schema coverage is 100% for the single optional status parameter, including enum values and default. The description's mention of 'status filter' is consistent but adds no meaning beyond what the schema already documents, so the high-coverage baseline of 3 applies.

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

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

The description identifies a specific action (List), a resource (coffee beans), a scope (registered for the account), and a filtering capability (status), making it clear what this tool does. The resource is distinct from sibling list tools such as list_shots or list_grinders, so an agent can tell it apart.

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, exclusions, or comparison with alternative tools. The account-scoped listing is stated, but the agent is not told when to prefer this over related list tools, and the default-to-current status is only available in the schema rather than the description.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior, so the description correctly avoids repeating those. It adds useful context by explaining that the id is an account-relative ordinal, safe to display, and is what other tools expect back. No contradiction with annotations.

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

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

Two tightly written sentences with no wasted words. The core listing behavior is front-loaded, and the id semantics earn their place because they affect how an agent should use results.

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 one optional, fully documented parameter, an output schema, and strong annotations, the description is complete. It covers the only non-obvious detail an agent needs: the meaning and reusability of the returned id.

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 fully documents the single status parameter, including its enum values and default. The description only mentions a status filter generally and adds no parameter-level meaning beyond the schema. Baseline 3 is appropriate given 100% schema 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 and resource: lists grinders registered for the account. The status-filter mention and per-account id semantics further distinguish it from other list_* siblings. It is clear and not tautological.

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 it — when the agent needs grinder records for the account — but it does not explicitly state when to prefer it over similar sibling tools or exclude alternatives. Resource clarity covers most of the need, but no exclusions or alternative routing are provided.

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 description is not burdened with safety disclosure. It adds useful context beyond annotations by explaining that IDs are account-local, counted from 1, safe to display, and expected by other tools.

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

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

Two sentences with no filler. The first sentence states the primary purpose and filter; the second adds the important ID semantics that an agent needs before passing IDs 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?

This is a simple read-only listing tool with one optional parameter, a complete schema, comprehensive annotations, and an output schema. The description together with those artifacts provides everything an agent needs to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the schema fully documents the single optional status parameter and its enum values. The description references 'status filter' but does not need to repeat the schema's detail; baseline 3 applies.

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

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

The description names a specific verb ('List'), a specific resource ('machines registered for the account'), and an optional status filter. It is clearly distinguishable from sibling tools like register_machine and list_grinders by entity and action.

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 establishes clear context: this tool lists machines for the current account, and the returned IDs are what other tools expect. It does not explicitly name alternatives or when-not-to-use conditions, but the use case is clear enough without them.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses an important behavioral trait: returned IDs are account-relative counters starting at 1, so they are safe to display and are the values other tools expect. This prevents common misuses such as treating IDs as global references. No statement contradicts 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?

Two sentences carry the full semantic load with no filler. The main function is front-loaded, and the critical ID caveat is placed in a short second sentence where it cannot be missed.

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

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

For a read-only list tool with an output schema and no required parameters, the description covers function, filter dimensions, and the non-obvious ID contract. The annotations already establish the safety profile, so nothing essential is left for an agent to guess.

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 schema description coverage at only 25%, the description must compensate for the undocumented bean_id, grinder_id, and machine_id parameters. It does so only partially by grouping them under 'equipment' and noting optional status filtering; it does not explain each parameter's meaning or how filters combine, though the parameter names are self-explanatory.

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

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

The description opens with 'List recipes' — a specific verb and resource — and immediately narrows scope to 'all or filtered by equipment and status,' which separates it from the other list_* siblings that target different record types. The title says 'locked recipes,' but the description's broader phrasing still identifies the exact operation without ambiguity.

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

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

It clearly frames the tool as a list/filter operation and notes that the returned `id` is 'what other tools expect back,' telling an agent to use this tool when it needs recipe IDs for later calls. It does not spell out exclusions or when-not-to-use alternatives, but the entity-specific list_* siblings make that inference straightforward.

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 genuinely useful behavioral context beyond those annotations: the id is an account-relative count starting from 1, safe to display, and is the identifier expected by other tools. No contradictory behavior is described.

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

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

The description is two concise sentences with no filler. The main purpose is front-loaded, and the second sentence adds a specific, high-value detail about the returned id. Every clause earns its place.

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

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

For a simple list tool with one optional, well-documented parameter, an output schema, and strong annotations, this description is complete. It tells the agent what the tool does, what the id means, and how the result should be used. There are no meaningful gaps for an agent to call it correctly.

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

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

Schema description coverage is 100%, and the only parameter, status, already has a clear enum and description in the schema. The tool description does not add any extra parameter-level meaning, but it does not need to because the schema fully documents the filter and its default.

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

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

The description opens with a specific verb and resource: 'List registered scales for the account.' It also clarifies the meaning of the returned id, which is exactly what an agent needs to understand what this tool produces. This separates it clearly from non-list sibling tools and gives the action a distinct, concrete outcome.

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

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

The description explains that the returned id is 'safe to show' and 'what other tools expect back,' which tells the agent when to use this tool: when it needs a scale identifier to pass into other account-specific operations. It does not explicitly name an alternative or exclusion condition, but the usage context is clear enough for a simple listing 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 establish the safe, read-only, idempotent profile, and the description adds valuable behavioral detail beyond them: the taste_pending flag is derived, expresses a precise condition (no sensory tags, no rating, no tasted flip), and points to the update path. No contradiction with annotations.

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

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

Two sentences, with the core action front-loaded and the important derived-flag semantics in the second. Every clause earns its place; there is no filler or needless restatement of schema fields.

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

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

For a read-only list tool with rich input and output schemas, the description is complete: it covers the operation, pagination/filtering capability, the one non-obvious semantic (taste_pending), and the cross-tool backfill path. The schemas provide the remaining mechanical details.

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 carries most parameter meaning. The description adds specific semantic context for the taste_pending filter by explaining the flag is derived and that owed tastings can be backfilled via update_shot, going slightly beyond the enum text. Pagination and filter support are named generically, but limit/offset are already well documented 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 opens with a specific verb and resource — 'List shot history' — and immediately adds scope with pagination and filtering support. The resource ('shots') clearly distinguishes it from sibling list tools such as list_beans and list_grinders, and the description is not a mere restatement of the title.

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 context is implied rather than explicit: the description suggests list_shots is the place to find shots with owed tastings and that update_shot is the follow-up to backfill them. It does not state when not to use the tool or name alternatives for other listing needs, so the agent must infer the boundary from sibling names.

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

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

Annotations already cover safety (readOnlyHint), idempotency, and non-destructiveness. The description adds valuable behavioral context by explaining the id semantics: ids count from 1, are safe to display, and are what other tools expect. This goes beyond the schema and 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 sentences with no wasted words. The main action and scope are front-loaded, and the additional id semantics sentence earns its place by providing crucial cross-tool 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?

Given the simple optional parameter, full schema coverage, rich annotations, and an output schema, the description is complete. It additionally covers the non-obvious id convention that agents need for downstream tool calls.

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 sole parameter, status, is fully documented in the schema with its enum values and default behavior, so the description does not need to repeat it. The description adds no extra parameter-level meaning, but with 100% schema coverage the baseline of 3 is appropriate.

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

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

The description clearly states a specific action and resource: 'List registered waters for the account.' This is distinct from the sibling register_water and list_* tools by resource type, though it does not explicitly name a sibling to differentiate from.

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

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

The description makes it clear that this is the tool for listing registered waters, and the account scoping is stated. However, it does not provide explicit guidance on when to use this over list_recipes or other listing siblings, nor does it mention exclusions. 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 indicate this is a non-read-only, non-destructive, idempotent operation. The description adds useful context that the tool sets a persistent reference recipe for the current equipment profile, but it does not disclose side effects such as whether a previous locked recipe is overwritten. 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, front-loaded sentence with no filler or redundant wording. Every word contributes to the core action and outcome.

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 has two required parameters and zero schema descriptions, so the description carries a heavy burden. It leaves `drink_intent` unexplained, does not clarify how the equipment profile is resolved, and omits any mention of overwriting behavior. While annotations and output schema help, the description alone is not complete enough for confident 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 0%, so the description must compensate, but it does not explain `from_shot_id` or `drink_intent`. It indirectly suggests `from_shot_id` should reference a successful shot, but `drink_intent` (straight vs. milk) is entirely unexplained, leaving the agent without enough meaning to populate the parameter correctly.

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

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

The description opens with a specific verb ('Lock') and names the object ('a successful shot') and the outcome ('reference dialing recipe for this equipment profile'). It clearly conveys what the tool does and is distinguishable from siblings like log_shot or update_shot, though it does not explicitly name the distinction.

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

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

The phrase 'a successful shot' implies the tool should be used after a shot has been dialed in successfully, which is a useful prerequisite. However, the description does not explicitly state when to use this tool versus alternatives, nor does it mention when not to use it.

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

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

Annotations only indicate the tool is not read-only, not destructive, and not idempotent. The description adds substantive behavioral context: disassembly opens a calibration epoch, recipes locked before it are read through that epoch's offset, and the offset is only knowable at reassembly. This goes well beyond the sparse annotations, though it could also state the resulting side effects on already-locked recipes more explicitly.

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 dense sentences with no filler: purpose, calibration-epoch behavior, and a pointer to the task catalog. Each sentence earns its place, and the most important domain nuance (when to record the offset) is explained efficiently.

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

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

Covers the tool's purpose, its key behavioral consequence (calibration epoch), and where to discover task options. Combined with a fully described schema and an output schema, an agent has enough to call it correctly. The main gap is not mentioning set_maintenance_offset as the alternative when only the offset needs updating without logging a whole maintenance job.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds real conceptual meaning to offset_value and offset_source by explaining the calibration epoch and why the reassembly moment is the only reliable time to count clicks, which is not fully captured in the schema. It does not need to list individual parameters since the schema documents them thoroughly.

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 clear resource ('a cleaning or maintenance job against a piece of equipment'). It immediately distinguishes itself from the sibling read-only catalog tools by telling the agent to get available tasks from list_grinders, and from shot/recommendation logging siblings by the equipment-maintenance focus.

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

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

Explicitly instructs the agent to read tasks, intervals, and due state from list_grinders, pointing to the correct sibling for lookup. It gives a concrete condition for when to record the offset (if clicks were counted at reassembly) but does not name or contrast set_maintenance_offset as an alternative for updating an offset outside of a maintenance log.

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?

All annotations are false, so the description carries the full behavioral disclosure burden. It does so well by revealing active-context binding, the risk of logging a shot to the wrong bean, the taste-pending filing behavior for tag-less/rating-less shots, and the fact that the diagnosis engine consumes tags and metrics rather than free-text flavor_notes. This goes far beyond what the schema exposes.

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 dense sentences, each carrying a distinct operational rule. It front-loads the core purpose and active-context behavior, then layers the exception cases. There is no filler; every sentence earns its place given the complexity 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?

The description covers the critical decision points: active context overrides, explicit bean identification, backdating, taste reporting, and the clean-taste distinction. Combined with the output schema, this is enough for correct invocation in the main scenarios. It does not walk through secondary parameters like observations, data_confidence, temp_taste, or best_brew, but those are adequately covered by the input 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 65% schema coverage, the schema already documents many parameters. The description adds high-value meaning to bean_id, pulled_at, sensory_tags, tasted, and flavor_notes: bean_id must be forced when the user names a coffee, pulled_at enables backdating, and tasted=1 with no sensory_tags is the only correct way to record a clean shot. It does not clarify every remaining parameter, but it targets the ones most likely to cause incorrect behavior.

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

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

The description opens with a specific verb and resource: 'Log an espresso or alternative shot/brew attempt.' This clearly identifies the tool as a creation/logging operation. It does not explicitly contrast itself with siblings like update_shot or diagnose_shot, so it stops short of full sibling differentiation.

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

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

The description gives strong conditional usage rules: ALWAYS pass bean_id when the user names a coffee, use pulled_at for backdating, add sensory_tags when taste is reported, and pass tasted=1 for clean shots. These are excellent within-tool guidelines, but it never says when to prefer log_shot over a sibling tool such as update_shot or diagnose_shot, so it is not a 5.

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

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

Annotations provide only false hints, so the description carries most of the behavioral disclosure burden. It indicates a write/create operation but does not disclose duplicate behavior, default field values, lifecycle side effects, or whether re-registering a bag is problematic. This is thin coverage for a 40-parameter create 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?

One clear, front-loaded sentence with no filler. It earns its place by stating the action and entity, though the extreme brevity means it delivers very little information relative to the tool's complexity.

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 40-parameter create operation with only 38% schema coverage and sparse annotations, a single generic sentence is completely inadequate for correct invocation. The description does not mention required parameters, creation defaults, duplicate handling, or the meaning of registration, and the output schema does not resolve the input-side 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?

With schema description coverage at only 38%, the description needed to orient the agent around required parameters or key bean fields. It names none of the parameters and adds no semantic meaning beyond the phrase 'bag of coffee beans', so it fails to compensate for the schema's gaps.

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 action ('register') and a distinct resource ('bag of coffee beans'), with 'new' clarifying that this is a create operation. This is enough to tell it apart from siblings such as register_grinder, register_scale, and 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?

Provides no guidance on when to use this tool versus update_bean or other register_* tools, and gives no exclusions or alternatives. The only usage signal is the implied 'create a new bag' meaning of the verb, which the agent must infer.

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 are all false and provide no real safety or behavior context, so the description carries the disclosure burden. It only says 'Register,' without explaining persistence effects, uniqueness expectations, validation requirements, or any other runtime 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 a single front-loaded sentence with no filler. It conveys the core action, the accepted grinder types, and the key settings aspect in minimal words.

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 13-parameter registration tool with an output schema, the description is quite thin. It does not explain registration prerequisites, the relationship to grinder_math or set_grinder_position, or when compound settings/components_spec become relevant.

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 77%, and the description adds only the terms 'manual or electric' and 'dial settings scheme,' which loosely map to motor_type and setting_scheme. It does not add meaning for required but undocumented parameters like burr_type or direction_convention.

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 ('Register') and resource ('grinder'), and adds a meaningful qualifier: 'manual or electric ... dial settings scheme.' This clearly distinguishes it from sibling tools like list_grinders and set_grinder_position.

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

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

The description implies its use when adding a new grinder to the system, but it does not explicitly state when to use it versus alternatives such as list_grinders, set_grinder_position, or grinder_math. No exclusions or selection criteria are provided.

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 this is a non-read-only, non-idempotent write, but the description adds no behavioral detail beyond the word "Register." It does not mention record creation, duplicate behavior, required ownership, or any side effects, so transparency beyond annotations is minimal.

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 clear sentence with no filler. It is front-loaded with the core purpose and does not waste tokens on redundant 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?

Given a 12-parameter registration tool with an output schema, the description is thin, but the input schema covers most parameters with useful descriptions such as prep_style and prep_type. Missing context includes when to register a machine versus other equipment and the behavioral implications of creating a non-idempotent record, so the description is only partially complete.

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

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

Schema description coverage is 67%, and the description itself adds no parameter-level meaning. The phrase "espresso or alternative preparation machine" loosely hints at prep_type, but the schema already documents that. Important fields like control_type and boiler_type remain undocumented in the description, and the tool description does not compensate for the uncovered 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 a specific verb and resource: "Register an espresso or alternative preparation machine." It clearly identifies the object being created and distinguishes this tool from siblings like register_grinder and register_program by naming the machine resource directly.

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 guidance on when to use this tool versus alternative registration tools, nor any mention of prerequisites or exclusions. The only signal is the word "machine" in the name and description, leaving the agent to infer applicability.

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 indicate this is a write operation (readOnlyHint=false) and not explicitly destructive (destructiveHint=false). The description adds useful domain behavior, such as how programs cut off shots by weight or time and that a machine can mix both program types, but it does not describe side effects like overwriting an existing program or validation failures.

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

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

The description is three concise sentences with no filler. The main purpose is front-loaded, and the conditional program-type logic is explained efficiently.

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

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

For a registration tool with an output schema and moderate parameter complexity, the description covers the essential distinctions and the core conditional parameter logic. It does not address every edge case, such as whether registering an existing program_number replaces it, but the provided information is sufficient for most correct invocations.

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 the schema already documents each parameter. The description adds valuable cross-parameter meaning by linking program_type 'volumetric' to target_volume_g and 'timed' to target_time_s, which helps prevent incorrect combinations. It does not add much about volume_source, but the schema handles that.

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: 'Register a programmed shot button on a machine,' and clarifies the two program types ('volumetric' and 'timed'). This clearly distinguishes it from sibling registration tools like register_machine, register_scale, or register_coffee.

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

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

The description gives clear context for when to use the tool: when registering a shot program on a machine, and it explains the two modes supported. It does not explicitly name alternative tools or say when not to use it, but the context is strong enough to route an agent correctly.

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 are all negative hints (readOnlyHint=false, idempotentHint=false) and provide no positive behavioral profile. The description adds no side-effect transparency: it does not explain duplicate-name handling, whether registration overwrites, what the response contains, or whether the operation is reversible. For a write operation this is a notable gap.

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

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

The description is a single front-loaded sentence with no filler and a useful clarifying clause. It is efficient and readable, though it leaves room for more substantive guidance.

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 input schema and output schema are comprehensive, so much of the operational detail is already structured. However, given the number of parameters and the sibling toolset, the description itself is thin on when to use it and what registering entails behaviorally. A little more context would make the tool fully self-explanatory.

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 carries rich, actionable descriptions, so the schema does the heavy lifting. The description adds only contextual flavor about what a brewing scale is; no additional parameter semantics are needed.

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 ('Register') and a clear resource ('brewing scale'), and adds domain context by defining the scale as 'the instrument that weighs the dose and the yield.' It is identifiable among siblings by object type, though it does not explicitly distinguish itself from other register_* tools.

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

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

The intended use is implied by the name and description: use this when registering a new scale. However, there is no explicit guidance about when to prefer this over list_scales, register_grinder, or other sibling tools, and no mention of prerequisites or 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 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 convey idempotence, non-read-only, and non-destructive behavior. The description adds useful account scoping and source-list context, but it does not describe failure behavior or side effects beyond switching; with annotations present, this is acceptable 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?

Three short sentences front-load the action and resource, then give the value source and the key exclusion. There is no filler or redundant detail.

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 plus schema and annotations are mostly complete, especially with an output schema present. A slight gap is that the prose omits the program_id component, though the schema covers it fully.

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 schema descriptions already cover all four parameters at 100% and explain that null means unchanged and values come from list calls. The description reinforces the list-source idea but does not add meaningfully beyond the schema, so the baseline of 3 applies.

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

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

The description opens with a specific action and resource: switching the active bean, grinder, or machine for this account. It also distinguishes itself from register_coffee by noting that registration already makes something active, so the agent clearly sees why set_active exists.

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

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

It explicitly says the IDs come from list_beans, list_grinders, and list_machines, and it gives a concrete when-not-to-use rule: do not call this after register_coffee. This is strong usage guidance that routes the agent to the correct 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?

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 indicate this is a mutating but non-destructive, idempotent operation. The description adds a meaningful behavioral consequence beyond the annotations: source='measured' resets verification freshness. This helps the agent understand the side effect of choosing that source value.

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

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

The description is two short sentences with no filler. The main action is front-loaded, and the additional behavioral note is concise and relevant.

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 mutating tool with annotations and an output schema, the description covers the essential semantics. The main missing piece is routing guidance against sibling tools, but that gap is already accounted for in 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 description adds semantic value for 'source' by explaining the freshness-reset behavior, which is not in the schema. However, 'grinder_id' is left undocumented in both schema and description, and 'setting_label' only gains mild context from the phrase 'collar position'. With 67% schema coverage, the description partially compensates but does not fully cover the gaps.

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 states the action ('Set') and the resource ('current grinder collar position'), which directly matches the tool name and title. It is specific enough to distinguish from read-oriented siblings like get_dial_state, but it does not explicitly name or differentiate from sibling tools.

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

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

The description gives no guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. The note about source='measured' resetting verification freshness is a behavioral detail, not usage 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?

The description goes well beyond the annotations by explaining the composition behavior of offsets, the semantics of zero as a legitimate measured value, and the effect of omitting offset_value to clear the measurement. These are non-obvious behavioral details that an agent could not infer from the annotations or the input schema alone.

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

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

The description is dense but well-organized: the core action and object are front-loaded, the entry-vs-equipment distinction earns its place, and the zero/omission clarification prevents a classic edge-case mistake. No sentence is redundant 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?

The description covers the essential call context, the composition semantics, and the value-clearing behavior, while the presence of an output schema covers return values. It assumes some familiarity with the concept of a calibration epoch, but both the description and the schema reference the same concept, giving the agent enough grounding for typical usage.

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 adds conceptual value by explaining why the offset is attached to the entry rather than equipment and by clarifying that zero must be treated as a real measurement. This supplements the offset_value schema description and helps the agent avoid common mistakes.

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

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

The description opens with a specific verb-resource pair ('Record how far a maintenance job moved the reference') and immediately constrains the target to 'an entry that opened a calibration epoch.' It also explicitly differentiates this tool from equipment-level operations by stating 'Takes an ENTRY, not a piece of equipment,' making the tool's purpose unambiguous.

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

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

The description clearly establishes when to use the tool: when recording an offset on the maintenance entry that opened a calibration epoch. It also gives an explicit exclusion—this is not for pieces of equipment—and explains why the entry-level attachment matters for composed offsets. However, it does not name alternative sibling tools or state conditions where another tool would be more 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate safety. It adds that the result is a 'single' step and comes 'from the reasoning engine,' which is useful, but it does not disclose anything about error behavior or the meaning of 'next.'

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 definition is a single, front-loaded sentence with no filler. 'Single' and 'reasoning engine' both earn their place by constraining the result.

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

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

For a one-parameter, read-only, idempotent tool with an output schema, the description is close to sufficient. However, it lacks any explanation of what a valid bean_id is, what 'next' means relative to, and when this tool should be selected, leaving some context for the agent to infer.

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

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

The input schema has one required integer parameter, bean_id, with 0% schema description coverage, and the description never mentions bean_id or explains what values are valid. The name is somewhat self-explanatory, but the description adds no semantic 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 names a concrete operation ('Retrieve ... next experiment step') and a source ('reasoning engine'), so an agent can tell what the tool returns. It does not explicitly differentiate from sibling tools, but none has an obviously similar name.

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

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

No guidance is given about when to call this tool versus alternatives such as diagnose_shot or log_recommendation, and no prerequisites or exclusions are mentioned. The intended use must be inferred from the name and one-line description.

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

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

Annotations already establish that this is a mutating but non-destructive, idempotent operation. The description adds a genuinely useful behavioral fact: changing dial_category alters engine advice (G5, C10), and recommends recording the reason in the note. It does not contradict annotations, though it leaves partial-update/auth details undisclosed.

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

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

Two sentences with no filler; the core action is front-loaded and the caveat is placed immediately after. Every clause earns its place.

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

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

For a large update tool, the description is brief, but the schema carries the field details, annotations carry safety/idempotency, and an output schema exists. The only high-risk behavior, dial_category's effect on engine advice, is explicitly called out, making the definition largely complete. It lacks sibling differentiation, already penalized in 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?

With schema coverage at 33%, the description does not compensate broadly, but it adds valuable semantics for dial_category (engine advice) and reason (where to explain changes). bean_id and fields are left to their names/schema, and most field details are already described inside the input 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?

Description names a specific verb ('Update') and resource ('coffee bag fields'), and the title reinforces it. It is easily distinguished from sibling update_shot and the registration tools. The dial_category sentence adds context, making the tool's core purpose unambiguous.

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

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

The description gives no guidance on when to choose update_bean over alternatives such as update_shot or register_coffee, and no exclusions or prerequisites. The only usage note is a field-level caution about dial_category and the optional reason, not a tool-selection rule.

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

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

Beyond the idempotentHint and destructiveHint annotations, the description discloses important derived behavior: changing grind_label re-derives the numeric grind position, and changing yield/time/dose/tds automatically keeps flow rate and extraction yield consistent. This adds genuine behavioral context beyond the structured annotations.

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

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

Three sentences, each earning its place: the first establishes what the tool does, the second gives concrete usage examples, the third explains key derived behaviors. No filler or redundancy.

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

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

Given the rich input schema, detailed field descriptions, output schema, and annotations, the description provides the high-level context an agent needs: when to use it, what it can correct, and what behaviors to expect. Nothing essential is missing for correct tool selection and 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%, so the baseline is 3. The description adds value by mapping concrete use cases to specific fields like bean_id and pulled_at, and by highlighting the automatic consistency effect for yield/time/dose/tds, which is not in the schema's field descriptions.

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

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

The description clearly states the tool's function: correcting fields on an already-logged shot in place. It distinguishes this from delete-and-re-log behavior and signals it operates on existing shots, separating it from log_shot and delete_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 description gives explicit use cases: fixing dose/yield/time, correcting grind label, re-filing bean_id, backfilling rating/tasting notes, and fixing pulled_at. It also provides an alternative framing ('no need to delete and re-log'), though it does not explicitly name the sibling tools or state when not to use update_shot.

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