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, so the safety profile is covered. The description adds output semantics (days off roast and verdict) but does not disclose details such as how the age is derived or prerequisites like the bean needing a roast date.

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

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

The description is a single, front-loaded sentence with no wasted words. It efficiently communicates the operation and its result in a compact, scannable form.

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

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

Given the simple one-parameter schema, supportive annotations, and the existence of an output schema, the description is complete. There is no missing information an agent would need to correctly invoke this tool in normal use.

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 does not explicitly mention bean_id. However, the single parameter's name is already self-explanatory, and 'coffee age' clearly links the bean_id to the coffee being evaluated, providing enough implied semantic context for a one-parameter tool.

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', names the resource, 'coffee age', and states the exact outputs: days off roast and a resting/staling verdict. This clearly differentiates it from all 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 description implies when to use the tool: whenever coffee age in days off roast or resting/staling verdict is needed. However, it does not explicitly state alternatives or exclusions, though no sibling tool competes with this functionality.

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 discloses the key side effect: restoring the bean's remaining weight, which is derived from logged doses. It also explicitly warns that this is a hard delete with no undo, adding meaningful behavioral context beyond the destructiveHint and idempotentHint annotations. No contradiction with the annotations 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?

Three tightly written sentences convey action, side effects, and the preferred alternative without any fluff. The main purpose is front-loaded, and every sentence serves a distinct informative purpose.

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 single-parameter tool with full schema coverage, output schema present, annotations covering safety traits, and a description that explains side effects and usage context. Nothing critical is missing for an agent to correctly select and invoke this tool.

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

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

Schema description coverage is 100%, and the single parameter shot_id is already documented in the schema. The description does not need to add parameter-level detail, but it also does not contribute anything beyond the schema for parameter understanding. This matches the baseline for high 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 starts with a specific verb and resource: 'Delete a logged shot from history.' It clearly differentiates from update_shot by emphasizing hard deletion and explicitly naming the alternative. An agent immediately understands what this tool does and how it differs from similar 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 explicitly says when to prefer update_shot instead: 'To fix a mistake on an otherwise-valid shot, prefer update_shot over delete-and-relog.' This provides a clear decision rule and contextual guidance beyond a simple definition.

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 readOnlyHint and idempotentHint annotations, the description adds valuable behavioral detail: no verdict is produced, no recommendation-trail entry is written, the logged shot's own bean and age at pulled_at are used, and shot_id mode ignores metric parameters. These are meaningful specifics that the annotations alone do not provide.

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

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

The description is front-loaded with the most important constraint ('Sandbox-only diagnosis, writes nothing') and organizes the two modes efficiently. Every clause adds useful detail, and the length is appropriate for a tool with 10 parameters and multiple usage modes.

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

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

For a 10-parameter tool with an output schema and safe annotations, the description covers side effects, mode selection, parameter interactions, and output-shape expectations. An agent has enough information to select the correct parameters and understand the result without needing additional clarification.

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?

Although schema coverage is 100%, the description adds critical parameter-interaction semantics: shot_id is a dry-run mode that ignores the metric fields, while the full metric set defines a hypothetical shot. It also clarifies sensory_tags override behavior, which goes well beyond the baseline for a well-covered 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 'Sandbox-only diagnosis' and specifies two concrete modes: dry-run a logged shot or evaluate a hypothetical shot from a full metric set. This clearly distinguishes the tool from diagnose_shot by emphasizing that it writes nothing while returning the same output shape.

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

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

The description gives explicit guidance for when to use shot_id versus the full metric set, and explains the optional sensory_tags override. It does not explicitly say 'use diagnose_shot when you want a real, persistent diagnosis,' but the sandbox-only, writes-nothing framing makes the intended context reasonably clear.

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

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

The description substantially enriches the readOnly/idempotent annotations by disclosing exactly what the engine reads (metrics and sensory_tags, not notes), how bean age is computed (at pulled_at using the shot's own bean), and what output context is emitted (bean_context). This is meaningful behavioral information beyond the structured annotations, and there is no contradiction with the declared readOnlyHint, idempotentHint, or destructiveHint.

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 composed of three dense sentences, each earning its place: the first states the core outputs, the second explains bean-resolution semantics and safety, and the third states the key input prerequisite and failure mode. It is front-loaded with the main purpose and contains no filler or redundant restatement.

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 single optional parameter, the presence of an output schema, and readOnly/idempotent annotations, the description covers the essential operational context: what data is used, how bean context is resolved, what must be prepared before calling, and what can go wrong. The only minor omission is an explicit pointer to diagnose_preview, but the description is otherwise complete for safe and 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 input schema already documents shot_id as optional with a default of the last pulled shot, so schema coverage is 100%. The description adds meaningful parameter-related context by explaining that diagnosing an older or differently-filed shot is safe because the shot's own bean and pulled_at are used. This goes beyond the schema's basic field documentation and helps the agent reason about the optional shot_id 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 states a specific verb and resource: 'Evaluate shot metrics to provide ranked hypotheses (C6) and warn on flip-flops (G2) or fatigue (G6).' It clearly describes what diagnose_shot does and distinguishes itself by clarifying it uses the shot's own bean rather than the active profile and reads sensory_tags rather than free-text notes. However, it does not explicitly name or contrast a sibling tool like diagnose_preview, so sibling differentiation is implicit rather than explicit.

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 usage guidance: taste feedback must be recorded as sensory_tags via log_shot or update_shot before diagnosing, and free-text notes are explicitly not read. This gives the agent a concrete precondition and warns about a common misuse. It does not explicitly state when to prefer an alternative tool such as diagnose_preview, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description does not need to restate safety. It adds 'current' temporal semantics and lists returned categories, but provides no additional behavioral nuance such as freshness guarantees or how 'recent' is defined. No contradiction with annotations 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, front-loaded sentence states the action and then lists the key returned data in a compact enumeration. There is no fluff or unnecessary restatement beyond what is needed to convey the tool's scope.

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

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

For a no-parameter, read-only getter with output schema available, the description fully identifies the purpose and the data categories returned. Annotations already cover safety and idempotency, so nothing essential for correct invocation is missing.

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

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

The tool has zero parameters and schema coverage is 100%, so there is nothing for the description to document. The baseline of 4 applies because the absence of parameters is fully captured by the schema and no 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 ('Retrieve') and a precise resource ('current dialing state'), then enumerates the contents: active context, recent shots, recommendations, and locked recipes. It is clearly distinct from siblings like get_stats or get_rule by naming a specific state domain.

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 implies the tool is used to fetch current dial state and related context, but it does not explicitly state when to prefer this over alternatives or provide any exclusions. There are no alternative tools for the same resource mentioned, so the guidance is adequate but not 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 communicate read-only, idempotent, and non-destructive behavior. The description adds only the 'current' scoping detail, which distinguishes it from changelog or historical queries, but no further behavioral context such as error cases or caching is provided.

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 with no filler. The verb and object are front-loaded, making it instantly scannable.

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

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

For a zero-parameter, read-only tool with a rich annotation set and an output schema, the description fully covers what an agent needs. There are no edge cases or parameters to document.

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 zero parameters, so there is no parameter information to convey. The baseline of 4 applies because the description is not expected to add meaning beyond an empty 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 a specific verb ('Retrieve') and resource ('the current version of the knowledge base'), making the tool's purpose immediately clear. The qualifier 'current' differentiates it from history-related siblings like kb_changelog.

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

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

While there is no explicit 'when to use' or 'use instead' language, the description clearly implies its use case: fetching the current knowledge base version. This is sufficient context given the tool's trivial nature and distinctness from sibling getters.

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, covering the safety profile. The description adds context that the tool retrieves 'detailed text' from the 'knowledge base', but reveals no additional behavioral traits such as error handling, rate limits, or access requirements. It adds modest value beyond annotations.

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

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

A single sentence that is entirely on-point: it states what is retrieved, from where, and by what key. No filler, front-loaded with the core action.

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

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

The tool is simple: one required parameter, a full output schema, and annotations that cover safety and idempotency. The description together with the schema and annotations provides everything an agent needs to correctly select and invoke the tool.

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

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

Schema description coverage is 100% and the parameter has a clear description with an example ('e.g. CAT.DARK'). The description's mention of 'by its rule ID' adds little beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Retrieve'), resource ('detailed text of a specific rule'), source ('from the knowledge base'), and access mechanism ('by its rule ID'). It is clearly distinct from siblings like get_kb_version or get_dial_state, which target different resources.

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

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

The description implies when to use the tool: when you have a rule ID and need its detailed text. However, it provides no explicit exclusions or alternatives, though no direct sibling appears to conflict. The usage context is implicit 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 cover the safety profile with readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the 'compact flat' output-shape hint, which is useful, but it does not describe aggregation behavior, data source, or other operational side effects. No contradiction with annotations 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?

The description is a single, front-loaded sentence with no redundant words. It states the result shape (‘compact flat usage stats’) and the scope values without restating the title or schema.

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

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

For a simple two-parameter read operation with comprehensive annotations and an output schema present, the description is nearly complete. It could more explicitly clarify that the ID is scoped by the chosen type, but the schema's enum and 'entity ID' description already handle that detail.

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

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

Schema description coverage is 100%, so both 'scope' and 'id' are already documented with descriptions and an enum. The description only restates the scope values ('grinder, machine, or bean') and adds no additional parameter-level meaning beyond what the schema provides.

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

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

The description uses a specific verb and resource: 'Get compact flat usage stats', and explicitly enumerates the valid scopes: 'grinder, machine, or bean'. This clearly distinguishes get_stats from sibling tools like list_shots, get_dial_state, or diagnose_shot, none of which provide statistical usage aggregates.

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 compact usage stats are needed for a grinder, machine, or bean — but it does not explicitly contrast it with alternatives or state when not to use it. No sibling routing or exclusion guidance is 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, idempotentHint, and destructiveHint false, so the safety profile is well covered. The description aligns with this by framing the tool as a read-only calculation. It does not disclose edge-case behavior such as invalid label handling or grinder-state dependencies, but the annotations reduce the burden.

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 compact sentence with no filler, placing the verb and core concept first. The parenthetical '(C3)' is slightly unexplained and could be confusing, but overall the structure is efficient.

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

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

For a calculation tool with three required parameters and no parameter descriptions, this is thin. It does not state when to use it, what units the result uses, how labels are represented, or what failure modes exist. The presence of an output schema helps, but the overall context remains minimal.

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 add meaning. The phrase 'between setting labels' clarifies that from_label and to_label are endpoints of a comparison, and the result is described as steps/clicks difference and direction. It does not explain label format, allowed values, or the role of grinder_id beyond obvious identification.

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 ('Determine') and a concrete object: steps/clicks difference and direction between two setting labels. It clearly conveys a calculation tool and is not a tautology, though it does not explicitly contrast with sibling tools or explain what 'C3' refers to.

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 case is implied: call this when the agent needs to compute a steps/clicks difference and direction between two setting labels. However, there is no explicit guidance on when to prefer this over related grinder tools like get_dial_state or set_grinder_position, and no exclusions or prerequisites are 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 the operation read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds that the changelog contains 'updates and version differences,' but it does not disclose additional operational behavior such as ordering, pagination, or scope limits. This is adequate but not rich context.

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 that leads with the action and resource, then provides the necessary qualifiers about content. 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?

This is a simple, zero-parameter, read-only retrieval operation with a likely output schema, so the description covers the essential context for invoking it correctly. It could be slightly more complete by explicitly addressing the relationship to get_kb_version, but that is more of a usage-guidance enhancement than a missing invocation requirement.

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 ambiguity and the description cannot meaningfully add parameter semantics. With no inputs required, the baseline score of 4 applies.

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

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

The description states a clear verb ('Retrieve') and a specific resource ('the changelog') scoped to 'the knowledge base.' It further specifies the content as 'updates and version differences,' which distinguishes this tool from the sibling get_kb_version that presumably returns only 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 description implies the tool should be used when a user wants to see update history or version differences for the knowledge base, but it does not explicitly contrast it with get_kb_version or state when not to use it. The intended usage is inferable from the wording but not directly guided.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable non-obvious behavioral context: row ids are account-local, start at 1, are safe to show, and are what other tools expect. This is genuine information beyond what structured annotations and schema 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 two sentences with no filler. The primary action and scope are front-loaded, and the second sentence provides important ID guidance without excess 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 simple read-only list with one optional parameter, a comprehensive enum in the schema, rich annotations, and an output schema, the description is complete. It covers the tool's scope, filtering behavior, and the key ID convention needed for downstream use.

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%: the status parameter has both an enum and a descriptive default. The description merely refers to 'status filter' without adding parameter-level detail, so baseline 3 is appropriate since the schema carries the full semantic load.

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

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

The description opens with a specific verb and resource: 'List coffee beans registered for the account.' It also names the status filter, and the account scoping distinguishes it from sibling list_* tools such as list_shots and list_machines. The matching title 'List bags of coffee' is consistent with the described functionality.

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

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

The description makes clear what is being listed and that an optional status filter is available, which gives the agent adequate context for selecting this tool over resource-specific siblings. It does not explicitly state when not to use it, but the distinct resource and schema-provided defaults make the intended usage clear.

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

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

The annotations already establish read-only, idempotent, non-destructive behavior. The description usefully adds meaning about the returned `id` semantics: it is account-specific, stable, safe to display, and expected as input by other tools. This is valuable behavioral context beyond the annotations.

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

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

The description is two sentences with no fluff. It front-loads the core purpose and status filter, then adds the important ID caveat in a compact second sentence.

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 parameter, full schema coverage, an output schema, and complete annotations, the description covers everything an agent needs to call it correctly. It also clarifies the subtle ID numbering behavior, making it effectively complete.

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

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

Schema coverage is 100%, with the single `status` parameter fully documented including its enum values and default. The description only mentions 'status filter' without adding new semantic detail, so the schema already carries the full burden; the baseline 3 is appropriate.

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

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

The description clearly states the tool's function: listing grinders registered for the account, with an optional status filter. This distinguishes it from sibling list_* tools by specifying the resource ('grinders') and its account scope.

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 says what the tool does but gives no guidance on when to prefer it over alternatives such as list_machines or register_grinder. It does not state exclusions, prerequisites, or scenarios where another tool would be more appropriate, leaving that entirely to inference.

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

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

Annotations already cover the read-only and non-destructive nature of the tool. The description adds valuable behavioral detail about the 'id' field: it is account-relative, safe to display, and expected by other tools. This goes beyond the structured annotations and clarifies an important operational contract.

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 compact and front-loaded, with the primary action stated first. The additional sentence about 'id' semantics earns its place by conveying a subtle and important detail that agents need for correct downstream calls.

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 operation with a single optional parameter, rich annotations, an output schema, and a clear account-scoped resource, the description covers everything needed. It explains the filtering behavior and the meaning of the returned identifiers, leaving no critical gap.

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

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

Schema description coverage is 100%, with the 'status' parameter fully documented via enum and default. The description only mentions 'with status filter' without adding new semantic detail, so it meets the baseline but does not elevate it.

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

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

The description clearly states a specific verb ('List') and resource ('machines registered for the account'), and includes the status filter. This unambiguously differentiates it from the many other list_* siblings such as list_beans or list_grinders.

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 on what is listed (machines registered for the account) and how filtering works, but does not explicitly mention alternatives or when not to use it. For a simple resource-specific listing tool, this context is generally sufficient.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavior beyond those annotations: the id is a per-account, 1-based row number, safe to show, and is the exact value other tools expect back. It does not mention pagination or ordering, but the output schema reduces the need for that.

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

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

Two tight sentences: the first covers purpose and filters, the second explains the crucial ID semantics. No waste, no repetition of schema fields, and the most useful operational note (what the id means) is included.

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, optional-filter list tool with an output schema, the description covers the main behavioral contract and ID expectations. The only notable gaps are not saying 'locked recipes' explicitly and not mentioning where bean_id/grinder_id/machine_id values come from, but these are minor given the title, schema, and sibling naming.

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

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

Schema coverage is only 25% (status is documented; bean_id, grinder_id, and machine_id are not). The description adds meaning by grouping the three integer parameters under 'equipment' and by naming 'status' as another filter, which helps an agent infer their role. It does not, however, explain what each equipment parameter refers to or how to source valid IDs.

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 ('List'), a resource ('recipes'), and the available filter dimensions ('equipment and status'), which clearly separates this from sibling list_beans/list_grinders/list_machines. The only weakness is that the description omits the 'locked' qualifier from the title, leaving slight ambiguity about whether this returns all recipes or only locked ones.

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: call this when you need a recipe list, optionally filtered by equipment or status. It does not provide explicit when-not-to-use guidance or name alternative tools, but the sibling set makes resource-based selection reasonably direct. With four list_* siblings, some explicit routing would have improved it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: ids are per-account sequential numbers starting at 1, are safe to display, and are the values other tools expect as inputs.

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 concise sentences deliver the core function, scope, and ID semantics without wasted words. The main action is front-loaded, and the important ID behavior is added in the second sentence.

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 documented parameter, full annotations, and an output schema, the description is complete. It covers what is listed, the account scope, and the critical ID semantics that other tools depend on, so nothing essential is missing.

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

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

Schema description coverage is 100%, and the single `status` parameter already has a clear enum and explanation. The description does not add new meaning about parameters, 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 uses a specific verb and resource: 'List registered scales for the account', immediately distinguishing it from the other list_* siblings. The added detail about the id field clarifies exactly what kind of entities are returned and how they are identified.

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: this is for listing scales registered to the account, and the note that the id is 'what other tools expect back' signals when an agent should call this tool, i.e., to obtain IDs before using other tools. It does not explicitly name alternatives or exclusions, but the scope is clear enough that an agent would not confuse it with sibling list tools.

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

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

Annotations already declare this operation read-only, idempotent, and non-destructive. The description adds meaningful behavioral context by explaining the derived taste_pending flag's exact condition and pointing to update_shot for backfilling, which goes 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?

Two sentences, each earning its place: the first states the core purpose and capabilities, the second explains a non-obvious derived flag. Purpose is front-loaded and there is no repetition of schema details.

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 output schema exists and annotations cover safety, the description is largely complete: it explains pagination, filtering, and the meaning of the important derived flag. It could more explicitly state that the taste_pending filter can be combined with other filters to find owed tastings, but that is implicitly clear.

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 documents limit, offset, and the filters and their ranges/enums. The description's taste_pending explanation largely mirrors the schema's own filter description, though it does add the backfill pointer. With 67% schema coverage, the description provides moderate added value but doesn't compensate heavily for the undocumented filters wrapper.

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

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

The description states a specific action and resource: 'List shot history'. It also mentions the two key capabilities (pagination and filtering), which clearly differentiates it from sibling list_* tools and from mutation tools like update_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 makes obvious when list_shots is appropriate: to retrieve shot history with pagination/filtering. It also references update_shot as the follow-up for backfilling owed tastings, giving useful workflow context. However, it does not explicitly state when not to use this tool or compare it with an alternative.

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 covered. The description adds value by explaining that IDs are account-local, sequential from 1, safe to show, and expected by other tools—useful behavioral context beyond annotations.

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

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

Two sentences, both purposeful. The core action is front-loaded, and the ID caveat is relevant without being verbose. No wasted words or redundant restatement of the schema.

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

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

For a simple read-only list operation with one documented optional parameter and an output schema, the description is complete. It covers scope, ID semantics, and cross-tool expectations. No critical call-time information 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%: the single optional status parameter is fully documented with enum values and default behavior. The description adds no parameter-level information, 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 states a clear verb-resource pair: 'List registered waters for the account.' It specifies scope (account-level) and distinguishes the resource from other list tools like list_recipes. The ID note reinforces what the tool returns.

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 explicit guidance on when to use this tool versus siblings like list_recipes or list_beans. It does not mention filtering use cases or when status parameters should be used. The ID note implies use with other tools, but that is not a direct usage guideline.

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 provide the safety profile (not read-only, not destructive, idempotent), so the description only needs behavioral context. It adds that the shot must be successful and that the result becomes the reference recipe for the equipment profile, which is useful and 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, and it front-loads the action and object before the purpose clause. Every word contributes 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 low-complexity tool with output schema and annotations, the core behavior is stated, but the description leaves required parameter semantics, especially drink_intent, unexplained. It also does not clarify what happens if a reference recipe already exists, which an agent may need to know.

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 for the two required parameters. It only implies that from_shot_id references a shot, and it does not explain drink_intent at all or connect either parameter to the locking workflow.

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

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

The description states a specific action ("Lock"), a specific object ("a successful shot"), and the resulting role ("reference dialing recipe for this equipment profile"). This clearly separates it from siblings like update_shot, set_active, and suggest_next_step.

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?

"Successful shot" supplies a clear precondition, and "reference dialing recipe" establishes the intended purpose for the tool. It does not explicitly name alternatives or when not to use it, so it stops short of full guidance.

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

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

It discloses the non-obvious calibration-epoch side effect: taking the thing apart opens an epoch, and locked recipes are read through that epoch's offset. It also explains why the offset should be captured at reassembly, which is exactly the kind of behavioral context annotations (all false) cannot supply.

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

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

Three dense sentences, each carrying distinct information: purpose, epoch/offset behavior, and the authoritative source for task data. No filler or repetition of the title.

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

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

For a 10-parameter tool with an output schema and enums, the description covers the non-obvious domain behavior and points to the dynamic task catalog. It does not mention what the response contains or how to choose between this and set_maintenance_offset, but the output schema and parameter docs close the former gap.

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

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

The schema already documents every parameter in detail (100% coverage), so the description's baseline is 3. It earns an extra point by explaining the offset_value semantics in domain terms — 'if you counted the clicks while reassembling, which is the one moment anybody actually knows it' — and by pointing to list_grinders for task-specific details_fields.

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

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

The first sentence uses a direct verb and object — 'Log a cleaning or maintenance job against a piece of equipment' — so the action is unambiguous. It does not, however, explicitly contrast with sibling tools such as set_maintenance_offset, which covers part of the same domain and could be invoked instead.

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

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

It tells the agent where to discover valid tasks and due states ('Read the available tasks, their intervals and their due state from list_grinders') and gives a concrete trigger for including the offset. It stops short of naming when-not-to-use this tool or comparing it to set_maintenance_offset.

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 a non-read, non-idempotent, non-destructive write. The description adds that the entry is stored for later contradiction/oscillation checking, which implies the change is not applied immediately. It does not disclose additional side effects or persistence behavior, but the annotation profile lowers the burden.

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

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

One sentence, front-loaded with action and object, with a concise purpose clause. There is no filler or redundant 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?

For a tool with six parameters, four required, no per-parameter descriptions, and no usage guidance, this description is too thin. An agent may infer the basic intent but lacks enough detail to confidently populate fields like cited_rules and based_on_shot or to know how this log entry interacts with the broader system.

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 does little to compensate. It hints at lever and direction through 'dialing change' but leaves rationale, confidence, cited_rules, and based_on_shot entirely unexplained. The schema enums help, but the description should have clarified how these fields relate to the recommendation workflow.

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

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

The description names a specific action ('Log'), a specific object ('recommended dialing change'), and a clear purpose ('allow contradiction/oscillation checking'). This distinguishes it from sibling tools like log_shot, which logs actual shots, and from tools that directly apply settings.

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 phrasing 'recommended dialing change' implies this is for proposed changes rather than actual observations, and the G2 purpose gives context. However, it never explicitly states when to use this tool versus log_shot or other dialing-related siblings, and it provides no exclusions.

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

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

With all annotations set to false, the description carries the full behavioral disclosure burden, and it does so thoroughly. It reveals that the tool uses the active context unless overridden, that a shot can land on the wrong bean bag without an explicit bean_id, that the diagnosis engine reads tags and metrics rather than flavor_notes, and that a tag-less/rating-less shot is filed as taste-pending. These are meaningful behaviors beyond what the annotations or schema express.

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 every sentence earns its place: purpose first, then active-context overrides, backdating, taste tagging, and the clean-shot indicator. It uses emphasis and examples effectively without 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 31-parameter tool with nested objects and seven enums, the description covers the most consequential behaviors: active-context resolution, overrides, taste workflow, backdating, and a pointer to diagnose_shot. The large number of optional parameters is acceptable because the schema already documents 65% of them and the output schema exists, so the description does not need to explain every field.

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?

At 65% schema coverage, the description adds important semantics to high-risk parameters: bean_id (always pass when a specific coffee is named), pulled_at (backdating and the diagnose_shot implication), sensory_tags (read by the diagnosis engine), and tasted (the explicit marker for a clean shot). It does not enrich every optional parameter, but it targets the ones that most affect correctness.

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 distinguishes the tool from sibling tools like update_shot, delete_shot, and diagnose_shot, so an agent knows exactly what action this call performs.

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 concrete conditional guidance: pass bean_id explicitly when the user names a coffee, use pulled_at when backdating, add sensory_tags for taste reports, and set tasted=1 for clean shots. It even points to diagnose_shot for backdated entries. It does not explicitly list when to avoid this tool in favor of update_shot or delete_shot, but the creation context is otherwise clear.

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

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

Annotations indicate this is a non-read-only, non-idempotent write operation, but the description adds no behavioral context beyond that. It does not mention required inputs, validation behavior, side effects, or what happens on duplicate registrations. With annotations present the bar is lower, but the description still contributes almost nothing about the tool's 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 extremely concise and front-loaded: one sentence that immediately states the action and object. There is no filler or repetition. However, given the complexity of the tool, the extreme brevity comes at the cost of useful context, so it is not fully 'appropriately sized.'

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 creation tool with write semantics and multiple closely related siblings, a one-sentence description is under-specified. It omits required parameters, enum constraints, date conventions, and any sense of what a successful registration returns. An output schema exists, but the description still lacks enough context for an agent to confidently select and invoke this tool.

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

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

The description provides zero parameter-level meaning, while the schema covers only 38% of 40 parameters. It does not highlight the four required fields (name, roast_date, roast_level, process_type) or clarify any ambiguous optional fields. The schema does contain some property descriptions, but the tool description itself fails to compensate for the large undocumented surface.

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 ('a new bag of coffee beans'), making the core action clear. The word 'new' also suggests creation rather than updating an existing bean entry, which helps distinguish it from siblings like update_bean. However, it does not explicitly contrast with sibling tools or mention the broader context.

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 about when to use this tool versus alternatives such as update_bean or list_beans. The only implied usage signal is 'new,' which weakly suggests this is for adding bags, not modifying or querying them. No exclusions or alternative recommendations are given.

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

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

Annotations only say the operation is not read-only, not idempotent, and not destructive; they don't convey side effects. The description adds only that registration includes the dial-settings scheme; it does not disclose behavior on duplicate names, required initial state, or whether re-registration is allowed.

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

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

One sentence with no filler, front-loading the verb and resource; every word adds information. It is appropriately brief even though other dimensions note missing context.

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

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

For a 13-parameter write operation, one purpose sentence is thin. It lacks usage guidance, duplicate/idempotency behavior, required-field emphasis, and relationship to list_grinders or set_grinder_position, despite the output schema and annotations covering only some 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 77% schema description coverage, the schema carries most parameter meaning. The description adds helpful mapping for motor_type ('manual or electric') and setting_scheme ('dial settings scheme'), but leaves direction_convention and burr_type semantics unexplained at the tool level.

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 resource ('grinder'), and adds scope ('manual or electric') and content ('dial settings scheme'). It is clearly distinguishable 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?

No explicit guidance about when to register vs use related tools. An agent can infer that registration is for adding a new grinder, but the description does not mention alternatives or exclusions, and there are many sibling registration tools.

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

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

Annotations are all false and offer no safety profile. The description implies creation but does not disclose whether duplicates are allowed, what validation occurs, or what the response looks like. With no annotation coverage, the description carries the burden and fails to provide meaningful behavioral context.

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 wasted words, front-loaded with the verb and resource. However, its brevity means it forgoes the chance to include any behavioral or usage detail, so it is concise but thin.

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 12-parameter tool with a subtle prep_style constraint and a family of register_* siblings, this description is too thin. It doesn't explain the 'alternative preparation machine' scope, the required control_type, or how it relates to update or list tools. An output schema exists, so return values are covered, but call-level context is largely missing.

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

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

Schema description coverage is 67%, leaving notes, boiler_type, control_type, and basket_size_grams undocumented in both schema and description. The description adds no parameter-level meaning and does not help disambiguate closely related fields like prep_type vs. prep_style.

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 (Register) and resource (espresso or alternative preparation machine), which clearly identifies the tool's core purpose. It distinguishes from sibling register_* tools by resource type (machine vs. grinder/scale/coffee), though it doesn't explicitly name them.

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

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

No guidance is provided on when to use this tool versus alternatives like register_grinder or list_machines. The only implied usage is the word 'register' meaning create a new machine, but no exclusions or prerequisites are 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 provide no behavioral signals, so the description carries the burden. It adds useful context: programs cut shots off by weight or time, and a machine can mix both types. However, it does not disclose behavior around duplicate program numbers, overwriting, or other registration side effects.

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 with no filler. The purpose is front-loaded, the mode-specific parameter guidance is compact, and the mixed-mode note adds useful context without 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 7-parameter tool with an output schema and 71% schema coverage, the description covers the essential mode-selection logic and the mixed-mode rule. It does not address duplicate registration or machine prerequisites, but those are not necessary for basic 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 description goes beyond the schema by explicitly linking program_type to the correct target parameter: 'set target_volume_g' for volumetric and 'set target_time_s' for timed. This clarifies the relationship between mutually exclusive parameters and compensates for incomplete 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 opens with a specific action: 'Register a programmed shot button on a machine', and then defines what a program is. This makes the resource and scope clear, and it is easily distinguished from sibling register_coffee, register_grinder, etc.

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: registering a shot program on a machine, with two possible modes. It does not explicitly name alternatives or say when not to use it, but the register_* tool family is naturally separated by resource type.

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 only says 'Register', indicating a write operation, but provides no details on side effects (e.g., duplicate name handling, generated IDs, whether existing records are modified). The annotations (readOnlyHint=false) already signal a mutation, and the description adds little beyond that domain flavor.

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. 'Register a brewing scale' is front-loaded, and the parenthetical adds a concise definition in just a few words, using the dash efficiently with nothing extraneous.

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 schema and annotations provide complete input documentation and an output schema, so the description does not need to repeat those details. However, the description is very thin on conveying when to select this tool over alternatives and what the registration action implies behaviorally. It is adequate but not rich for a 15-parameter create operation.

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

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

Schema description coverage is 100%, so all 15 parameters are already documented in the schema. The tool description adds no parameter-specific information; the phrase 'weighs the dose and the yield' is domain context, not a parameter explanation. 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 uses a specific verb+resource pair ('Register a brewing scale') and adds domain context ('weighs the dose and the yield') that distinguishes this from sibling register_* tools for other equipment. Even without naming a sibling, the resource noun and the role it plays make the target 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?

No when-to-use or when-not-to-use guidance is provided. The only sentence states the action and object, leaving the agent to infer from the 'register' verb that this creates a new scale record. No alternatives, preconditions, or exclusions are mentioned.

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 convey that this is a non-read-only, non-idempotent write operation, and the description adds no behavioral context beyond the word 'Register'. It does not disclose duplicate handling, whether an entry is created, or any side effects, though 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 one short sentence with no filler or repetition. Every word, including 'custom or commercial', adds some information about what can be registered.

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 schema covers fields and units, and an output schema exists, so the minimal description is functional for a straightforward creation tool. However, it leaves contextual gaps such as duplicate-name behavior or the relationship between hardness values and mineral concentrations, making it adequate but not complete.

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

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

The input schema has 100% coverage, with descriptions for GH, KH, TDS, name, type, notes, calcium, and magnesium. The description contributes no additional parameter meaning, so it stays at the baseline of 3.

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

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

The description uses a specific verb ('Register') and a concrete resource ('water formulation'), so the agent can tell it from sibling registration tools like register_coffee or retrieval tools like list_waters. It does not explicitly mention 'recipe' or contrast it with list_waters, but the core purpose is unmistakable.

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

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

There is no guidance about when to choose this tool over alternatives, such as using list_waters for retrieval or register_coffee for other entities. 'Custom or commercial' gives a slight scenario hint, but no conditions, prerequisites, or exclusions are stated.

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

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

Annotations already establish mutation, idempotence, and non-destructiveness; the description adds useful domain context: registering something automatically makes it active, so set_active is for switching to existing entries. It does not contradict annotations. This extra context goes beyond what the annotations alone convey.

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

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

Three short sentences, front-loaded with the verb and object, followed by the source rule and a usage caveat. No filler or repetition of annotation 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?

The description plus rich schema and annotations covers selection and safe invocation for bean/grinder/machine, and the output schema removes return-value ambiguity. The only notable gap is that program_id is missing from the description, so an agent focused on programs might not recognize set_active as the right tool.

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

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

Schema description coverage is 100%, so the baseline is 3; each param already carries an exact source and null semantics. The description's 'numbers come from list_*' note reinforces the schema but mainly duplicates it, and it omits the program_id source (active machine's list).

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

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

States a clear action ('Switch the active bean, grinder or machine') with account scope, and the source-of-truth sentence distinguishes it from list_* and register_* siblings. However, it omits program_id, which the schema lists as a settable field, so the stated resource set is incomplete.

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 tells the agent when to use it ('switch back to something that exists') and when not to ('not after register_coffee'), naming the list_* tools as the source for valid IDs. It doesn't mention how to handle the program_id case, but the other guidance is unambiguous.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, covering the core safety profile. The description adds no extra behavioral context beyond restating the action, but it does not contradict the annotations either.

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 with no filler. Every phrase contributes useful identifying information, and the action is front-loaded.

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 three-parameter schema with complete property descriptions, an output schema, and annotations conveying idempotence and non-destructiveness, very little is missing. A small gap remains in explaining what archival means in the domain or how it interacts with related statuses like active.

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

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

Schema description coverage is 100%, and the schema already explains id, kind, and archived with enumerations and descriptions. The description adds no parameter-level meaning beyond what the input schema provides.

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

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

The description states a clear action ('Archive or restore') and identifies the resource and scoped kinds ('a grinder, machine, water, or scale'), matching the kind enum. It is specific but does not explicitly distinguish itself from siblings such as set_active, which could also change an equipment status.

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

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

The description gives no guidance about when to choose this tool over alternatives, no prerequisites, and no exclusions. The intended use is only implied by the verb 'archive or restore'.

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 readOnly=false, idempotentHint=true, and destructiveHint=false. The description adds a non-obvious behavioral detail: source='measured' resets verification freshness. This is exactly the kind of extra context that helps an agent predict side effects beyond the structured 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?

Two short sentences with no filler. The main action is stated first, and the important behavioral caveat is delivered in the second sentence. 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 three-parameter setter with an output schema and annotations, the description covers the core semantics and an important side effect. The only real gap is usage routing relative to sibling tools, which is captured in the usage_guidelines dimension.

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 includes useful comments for setting_label and source. The description adds value by tying setting_label to the physical 'collar position' and by explaining that source='measured' resets verification freshness, which goes beyond the schema's enum explanation. grinder_id remains implicitly obvious but undocumented.

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

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

The description clearly states the verb and resource: 'Set the current grinder collar position.' This is specific and distinguishes it from most siblings by naming the physical collar position being set. However, it does not explicitly compare itself to related tools like set_active or get_dial_state.

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 no guidance on when to use this tool versus alternatives such as get_dial_state or grinder_math. The note about source='measured' is condition-like but it addresses semantics of a parameter, not selection between tools. An agent would have no basis for choosing this tool over a sibling.

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

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

The description discloses subtle behavioral semantics that are not visible in the annotations: zero means a legitimate measurement of no movement, while omitting offset_value clears the measurement to unmeasured. It also explains how multiple offsets compose for a recipe locked before them. These are precisely the kinds of non-obvious behaviors an agent needs to invoke the tool correctly.

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 carrying distinct information: the core action, the entry-not-equipment distinction with its compositional rationale, and the zero-vs-clear edge-case. The second sentence is dense and somewhat complex, but the complexity mirrors the domain nuance. Front-loading the purpose works well.

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, together with the 100%-covered schema and output schema, gives an agent everything needed to call the tool correctly: the object type, the meaning of the parameter values, how to handle zero and clearing, and why the abstraction exists. The annotation set covers idempotency and non-destructiveness, so no safety-relevant behavior is left unstated.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by clarifying the critical semantics of offset_value (0 vs omitted) and reinforcing that entry_id refers to an entry, not equipment. It does not add detail for source or evidence beyond what the schema already states, so the score remains 4 rather than 5.

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

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

The description opens with a specific verb and resource: 'Record how far a maintenance job moved the reference, on an entry that opened a calibration epoch.' It clearly differentiates the target ('Takes an ENTRY, not a piece of equipment') from siblings that operate on equipment, so an agent can distinguish set_maintenance_offset from tools like 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 gives clear context for when to use this tool: recording offsets for maintenance entries that opened calibration epochs, and explains why the entry-centric semantics matter for composing recipes locked earlier. It does not name specific alternative tools or state explicit when-not-to-use conditions, but the entry-versus-equipment distinction serves as a strong routing signal.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, and the description only adds that the result is a single step from the reasoning engine. It does not add meaningful behavioral context beyond the annotations, but it does not contradict them either.

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

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

A single, front-loaded sentence with no filler. Every word earns its place, and the description avoids redundantly repeating the title.

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

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

For a one-parameter read-only tool with an output schema, the description is nearly adequate for selection, but it leaves parameter semantics and when-to-use context to inference. A brief note on bean_id's role would make it complete.

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

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

Schema description coverage is 0% and the description never mentions bean_id or why it is needed. The name 'bean_id' gives minimal self-evident meaning, but the description does not compensate for the missing schema documentation or explain how to select the value for a next-step request.

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?

Uses a specific verb ('Retrieve') and identifies the exact resource ('the single next experiment step') and source ('reasoning engine'). This makes the tool's function unambiguous and distinguishes it from the read-only sibling tools, none of which claim to return a suggested next step.

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 'next experiment step' implies this is the tool for advancing an experiment, but the description does not explicitly state when to prefer it over other getters like get_rule or get_stats, nor any exclusions or prerequisites. Usage guidance is left to inference.

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

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

Annotations already communicate mutability, idempotency, and non-destructiveness. The description adds a genuinely non-obvious side effect: changing dial_category alters what the engine advises (G5, C10), and it recommends explaining the change in the optional note. This goes beyond what annotations and schema alone 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?

Two sentences with no filler. The general update action is front-loaded, and the important dial_category caveat immediately follows. Every sentence 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 tool with this many updatable fields, the combination of description, nested schema, annotations, and output schema is sufficient. The only notable gap is lack of explicit alternative routing, which is already reflected in the usage_guidelines score, so it is not double-penalized here.

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

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

Schema coverage is only 33% at the top level, but nested fields are individually described in the schema. The description adds meaningful coupling between dial_category and the reason parameter, explaining a consequence not present in the schema. It does not discuss bean_id or the fields wrapper, but those are structurally evident.

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 'Update coffee bag fields' — a specific verb and resource — and the title reinforces the scope. It does not explicitly name sibling tools to distinguish from, but 'coffee bag fields' clearly separates it from siblings like update_shot and 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 action itself is stated directly, but there is no guidance on when to use this tool versus alternatives such as register_coffee, set_active, or update_shot. The dial_category note is a useful within-tool instruction, not an alternative-routing or when-not-to-use 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?

The description discloses meaningful behavioral side effects beyond the annotations: changing grind_label re-derives the numeric grind position from the shot's grinder, and changing yield/time/dose/tds automatically keeps flow rate and extraction yield consistent. It also makes clear this is an in-place mutation ('correct fields... in place'), which complements the idempotentHint and destructiveHint annotations. No contradiction with annotations 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?

The description is compact and front-loaded: it states the core purpose in the first clause, then gives concrete usage examples, and finishes with the most important behavioral caveats. Every sentence earns its place, and nothing is redundant with the schema or annotations.

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 is complete for a two-parameter tool with a nested fields object. It explains the correction workflow, highlights which field changes trigger automatic recalculation, and gives enough use-case context for an agent to decide when to call it. Since an output schema exists and all parameters are documented in the input schema, the description does not need to restate return values or field types.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds important cross-field semantics: grind_label re-derives the grind position and yield/time/dose/tds changes trigger automatic consistency adjustments. These meanings are not visible from individual schema property descriptions. The description also frames fields like bean_id, pulled_at, and grind_label with purposeful examples rather than just type definitions.

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

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

The description states a specific verb and resource: 'Correct fields on an already-logged shot in place.' It clearly distinguishes the tool's purpose from delete_shot and log_shot by explicitly saying 'no need to delete and re-log.' Concrete use cases ('fixing a wrong dose/yield/time or grind label, re-filing a shot onto the right bean') make the purpose unmistakable.

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

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

The description gives explicit usage guidance: use this when correcting an existing shot instead of deleting and re-logging. It enumerates common scenarios like fixing dose/yield/time, re-filing onto a different bean, backfilling rating/tasting notes, and fixing timestamps. This tells the agent both when to reach for this tool and why alternatives like delete_shot + log_shot are not needed.

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