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

Annotations mark the tool readOnlyHint=false and openWorldHint=true, but they don't explain the dual-mode nature. The description adds real value by clarifying that the default is a read and a write only happens when add=true, gated by confirm — a nuance the blanket readOnlyHint=false does not convey. It still omits failure behavior for unknown barcodes and rate/network concerns of the external call.

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 purpose followed by the write caveat. The raw REST path is somewhat low-value for an agent consuming an MCP tool, but it is compact and nothing is padded.

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

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

With no output schema, the description never says what an external lookup actually returns (product identification fields? not-found signal?), which is the core question for a lookup tool. The write path is reasonably documented, but the read result is left opaque.

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

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

Schema coverage is 67%, and both 'add' and 'confirm' already have thorough schema descriptions (including that confirm must be the boolean true and false/string values are rejected). The description only restates that add creates a product and needs confirm, adding no syntax or semantics beyond the schema.

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

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

States a specific verb+resource ('External barcode lookup') and includes the underlying endpoint, so the agent knows it queries a barcode against an external source. The qualifier 'external' implicitly separates it from grocy_stock_product_by_barcode, but the sibling is never named, so the distinction must be inferred.

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?

'add=true also creates the product and needs confirm' implies two modes (lookup-only vs lookup-and-create), which gives some usage context. However there is no explicit guidance on choosing this over grocy_stock_product_by_barcode for local lookups, and no statement of prerequisites for the external call.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered structurally. The description adds that each entry carries a next estimated charge time, but says nothing about ordering, empty results, or pagination 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?

Two short sentences, front-loaded with the purpose and followed by the raw endpoint. Everything earns its place, though the endpoint restates the operation for little added value.

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

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

For a zero-parameter read-only list tool with annotations covering the safety profile, this is sufficient to call correctly. With no output schema, it could say slightly more about what a battery record contains, which keeps it from a 5.

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

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

There are zero parameters, so the baseline is 4; the description correctly implies the tool takes no filters. Nothing is left ambiguous about inputs.

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

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

States a clear verb-and-resource pair ('All batteries') plus the salient data point returned ('next estimated charge time'), which separates it from the mutation siblings like grocy_battery_charge. It does not explicitly distinguish itself from grocy_battery_get, so it stops short of a 5.

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

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

The list framing implies usage, but there is no explicit guidance on when to pick this over grocy_battery_get (single battery) or other list tools. The reader must infer that this is the bulk-retrieval option.

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

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

Annotations declare a non-readonly, non-idempotent, non-destructive open-world write, and the description adds the important safety mechanic that omitting confirm yields a dry-run preview rather than a write. It does not disclose error conditions (e.g., nonexistent battery id) or what the resulting record contains, but the dry-run default is the critical behavioral fact and it is surfaced.

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

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

Three short sentences, front-loaded with the action, followed by the endpoint and the one usage caveat. Nothing is wasted and nothing important is buried.

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

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

For a small three-parameter mutation tool with no output schema, the definition covers the action and the dry-run mechanic, but leaves tracked_time undefined and says nothing about what a successful charge response looks like or that the battery must exist. Adequate but with a clear blind spot.

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%: confirm is fully documented in the schema (and repeated in the description), battery_id is self-evident as a path id, but tracked_time is completely unexplained in both schema and description — an agent cannot tell what format or semantics a 'tracked time' string takes. The description does not compensate for that gap.

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

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

States a specific verb+resource ('Track a battery charge cycle') and even names the underlying endpoint, so an agent knows this writes a charge event to a battery. It does not explicitly contrast with grocy_battery_undo_charge or grocy_battery_get, though the verb makes the distinction reasonably inferable.

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?

'Omit confirm for a dry-run' gives a clear usage rule for the key parameter, which is genuinely actionable. However, there is no guidance on when to use this versus grocy_battery_undo_charge or how it relates to the battery lifecycle beyond the one dry-run note.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond restating the endpoint — no behavior for missing/invalid IDs or error semantics, which is where extra context would have earned credit.

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, the purpose front-loaded with the endpoint detail second. Minimal but appropriately sized for a simple lookup.

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 tool with safety annotations, the description is minimally sufficient to select and call it. However, there is no output schema and the description doesn't hint at what a battery record contains or how failures surface, leaving a real 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 0% for the single required battery_id, so the description must carry the burden and it does not: the {batteryId} path token only restates the parameter name, giving no format, range, or existence semantics.

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

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

States a specific verb and resource ('Details of one battery') plus the underlying endpoint, which lets an agent distinguish it from grocy_batteries_list. No explicit sibling naming, but the singular/plural contrast is clear.

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

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

Usage is only implied: fetch a single battery. It doesn't state when to prefer this over grocy_batteries_list or what to do if the ID is unknown, and no prerequisites are given.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true and destructiveHint=false, so the side-effect profile is partly covered structurally. The description adds the valuable dry-run default, but does not say what the print actually produces (PDF? image? server-side print job?) or that a real print has an external, non-idempotent effect on a printer.

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 purpose before endpoint and option details. Nothing is padded, though the endpoint restatement is only marginally useful to an agent.

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

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

For a two-parameter tool with no output schema and annotations covering safety, the description is largely sufficient: purpose, endpoint, and the dry-run/confirm contract are all present. The main remaining gap is the return format of a label print, which is minor 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 50%: confirm is fully documented in the schema while battery_id has no description. The description's "for a battery" and the dry-run sentence map loosely onto both parameters, but adds no format or constraint detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource: "Print the Grocycode label for a battery," which cleanly separates it from the sibling label printers (grocy_recipe_printlabel, grocy_chore_printlabel) by the object being printed. It also gives the underlying endpoint, removing ambiguity about what is invoked.

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?

"Omit confirm for a dry-run" gives a concrete calling pattern, so the agent knows the safe first step. However, there is no statement of prerequisites (battery must exist), no guidance on when to proceed to a real print versus staying with the preview, and no routing away from other battery 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 cover mutability and idempotency; the description adds the crucial behavioral fact that the call is a dry-run unless confirm is supplied, which is the main thing an agent must get right. It does not say what state the battery/charge cycle is left in after undo, a minor omission against otherwise solid annotation coverage.

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, zero waste, with the action stated first and the dry-run safety note last. Nothing is padded or redundant beyond a helpful reinforcement.

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

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

For a two-parameter write tool with no output schema, this is nearly sufficient: action, endpoint, and confirm-gating are all covered. Only the post-undo result state and the meaning of charge_cycle_id are left implicit.

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

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

The confirm parameter's semantics (including that false and string 'true' are rejected) are already fully documented in the schema, and the description only echoes the dry-run point. charge_cycle_id is undocumented in both schema and description, leaving the 50% coverage gap partly unaddressed.

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

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

States a specific verb and resource ('Undo a battery charge cycle') and distinguishes itself cleanly from sibling grocy_battery_charge and the unrelated undo tools (grocy_chore_undo_execution, grocy_task_undo). The endpoint path reinforces the target resource.

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

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

The description makes the safe-invocation rule explicit: omit confirm for a dry-run, so the agent knows the default is non-mutating. It does not name when to use undo versus re-charging or which sibling to prefer, but the scope is narrow enough that ambiguity is low.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that the return value is iCal text, but it does not cover authentication needs, calendar scoping, or rate limits.

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

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

Two short sentences, front-loaded with the resource and format, with no wasted wording. The endpoint path is compact and useful.

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

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

For a zero-parameter read-only tool with annotations covering safety, the description says enough: it returns household calendar data as iCal text. No output schema exists, so the return format being stated is valuable, though calendar scope could be clearer.

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

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

The tool takes zero parameters, so there are no parameter semantics to explain; baseline is 4.

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

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

The description states a specific resource (household calendar) and output format (iCal text), with the backing endpoint. It is clear what the tool does, but it does not differentiate from the sibling grocy_calendar_sharing_link.

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

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

There is no guidance on when to use this tool rather than grocy_calendar_sharing_link or other calendar-related siblings. Prerequisites or intended callers are not 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds almost nothing beyond a REST endpoint: 'public' hints the resulting URL is unauthenticated and sensitive, but there is no note on secrecy, rotation, stability of the link, or whether calling it has side effects such as persisting a token.

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 short, front-loaded sentence. The trailing 'GET /api/calendar/ical/sharing-link.' is largely redundant endpoint plumbing that adds no decision-relevant information, but the whole entry is only two lines.

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

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

No output schema exists, so the description should say what is actually returned (a plain URL string, possibly absolute vs. relative). That key fact is missing, leaving the agent to guess the response shape even though annotations cover the read-only nature of the call.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies.

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

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

States the specific resource clearly: a public sharing link for the iCal calendar. An agent can tell this generates/returns a URL rather than calendar data itself, which separates it from grocy_calendar_ical, though the distinction is left implicit rather than stated.

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

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

No guidance on when to call this versus grocy_calendar_ical (which presumably returns the actual iCal feed). No mention of prerequisites such as whether a link must be generated/rotated first, or what an agent should do with the returned link.

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 and destructiveHint=false, so the safety profile is partly known. The description adds meaningful value by disclosing the dry-run mechanism via omitting confirm, which is important behavioral context for a write tool that is not marked destructive.

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 waste, and the dry-run safety note is placed prominently enough to influence invocation. The definition is appropriately sized for the amount of information provided.

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

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

For a 5-parameter mutation tool with low schema coverage and no output schema, the description covers the dry-run behavior but omits the meaning of done_by, skipped, and tracked_time. The core execution path is clear, but an agent would need to infer parameter intent from names alone.

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

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

Schema description coverage is only 20%, so the description must compensate for undocumented parameters. It mentions only confirm (which the schema already documents) and leaves done_by, skipped, and tracked_time with no semantic explanation, and only implicitly identifies chore_id through the endpoint path.

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 ('Track a chore execution') plus the backing endpoint, which lets an agent separate it from read-oriented siblings like grocy_chores_list and grocy_chore_get. 'Track' is slightly softer than 'execute/record', but the endpoint and dry-run note remove ambiguity.

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

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

The dry-run guidance ('Omit confirm for a dry-run') gives useful operational context for the confirm flag. However, there is no explicit guidance on when to use this tool versus alternatives such as grocy_chore_undo_execution or grocy_chores_list, leaving usage largely implied.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that – no note on error behavior for nonexistent IDs, no rate/permission context, no indication of what a chore record includes.

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, front-loaded fragments with no filler, but the brevity reflects under-specification rather than tight writing – the second sentence merely repeats the tool's transport rather than adding meaning.

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

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

For a simple read-only single-record fetch with one integer parameter and no output schema, the bar is low and the annotations cover safety. Still, an agent learns nothing about the shape of the returned chore or how to obtain a chore_id, leaving a real 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 0% and the sole parameter chore_id is undocumented in the schema, so the description carries the burden. The {choreId} path template only restates that an ID is required; it does not say where the ID comes from (e.g., grocy_chores_list) or the accepted type/range.

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?

"Details of one chore" plus the endpoint path makes clear this returns a single chore record, which does distinguish it from the sibling grocy_chores_list. However, it is a noun phrase with no verb and no statement of what the details contain, so it stays at minimum viable rather than specific.

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

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

There is no statement of when to use this tool versus grocy_chores_list or grocy_chore_execute, and no prerequisites such as needing a valid chore_id obtained from the list call. Usage is only inferable from the name.

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

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

The annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds the dry-run gate and the POST verb, but omits the important behavior for a destructive merge: whether execution history, assignments and intervals of the removed chore are transferred or discarded, and whether the merge is reversible.

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, no filler, with the action stated first and the dry-run affordance last. Every sentence carries distinct information.

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

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

There is no output schema and no annotation explaining consequences, so the description is the only place to learn what a merge does to the surviving chore. It covers invocation but not outcome or reversibility, which is a meaningful gap for a destructive, open-world write.

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

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

Schema coverage is only 33%, and the two integer IDs carry no schema descriptions. The endpoint template partially compensates by mapping keep/remove roles onto the parameter names, but it does not explain what "merge" means for either chore's data, so the semantics of the IDs remain underspecified.

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

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

States a specific verb and resource ("Merge two chores") and pins the REST endpoint, which clarifies that choreIdToKeep survives and choreIdToRemove does not. It does not name a sibling, though the only superficially similar one (grocy_stock_merge_products) is a different resource, so confusion risk is low.

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?

"Omit confirm for a dry-run" gives a concrete invocation pattern an agent can act on. However, it says nothing about when merging is appropriate versus deleting or renaming a chore, nor about what preconditions must hold (e.g. both chores exist, same assignment period).

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the dry-run/confirm behavior, which is real value, but it never says what a confirmed call actually does — issue a print job to a physical printer, or return label data — which is the key behavioral question for a print tool with openWorldHint=true.

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 the purpose and the behavioral rule front-loaded, plus the endpoint for verification. Nothing is padding, though the raw endpoint adds less than a note on what a confirmed call returns would have.

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

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

With no output schema, the description is the only place an agent could learn what comes back from a print call, and it says nothing about return values or whether printing has external side effects. The dry-run hint covers the riskiest decision, but a mutation tool with openWorldHint=true needs more.

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

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

Schema coverage is 50%: the confirm parameter is richly documented in the schema itself (const true, rejected values), while chore_id has no schema description. The description partially compensates by implying chore_id via the endpoint path and by explaining the confirm omission semantics, but it adds nothing about chore_id's meaning or validity constraints.

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

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

States a specific verb and resource ('Print the Grocycode label for a chore') and includes the backing endpoint, which lets an agent separate it immediately from grocy_battery_printlabel and grocy_recipe_printlabel. No ambiguity about what the tool produces.

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 sentence 'Omit confirm for a dry-run' gives a concrete operational rule for switching between preview and execution, which is genuinely useful. However, it offers no guidance on when to use this versus grocy_chore_get or grocy_chores_list, and no statement of prerequisites (e.g., chore must exist, label must be configured).

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and the description adds that this is a POST write with a dry-run mode. But that dry-run nuance is already spelled out fully in the confirm parameter's schema description, so the description contributes little beyond the endpoint string. It never says what existing assignments are overwritten or that unchanged calls may still reshuffle state.

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

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

Three short sentences, front-loaded with the action and resource, with no filler. The dry-run sentence duplicates schema text rather than adding new information, which is the only wasted line.

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 mutating, non-idempotent recalculation with two parameters and no output schema, the definition leaves key questions unanswered: what chore_id scopes, what the dry-run preview returns, and what assignment state is replaced. Annotations cover safety but not the operational picture.

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

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

Schema coverage is 50%: confirm is thoroughly documented in the schema, but chore_id has no description anywhere. The tool description never mentions chore_id, so an agent cannot tell whether omitting it scopes the recalculation to all chores or to none — the exact gap the description should have filled.

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

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

States a specific verb and resource ('Recalculate next chore user assignments'), which an agent can clearly distinguish from siblings like grocy_chore_execute or grocy_chore_undo_execution. It does not explicitly name the siblings it differs from, but the purpose is unambiguous.

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

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

'Omit confirm for a dry-run' gives one concrete usage instruction for the write path, so the calling pattern is implied. However, it never says when this recalc is appropriate (e.g., after chore changes) versus just executing a chore, so the alternative routing is left to inference.

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

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

Annotations already establish this as a read-only, non-destructive operation, so the safety profile is covered. The description adds the useful fact that results include next estimated execution, but says nothing about ordering, pagination, or filters.

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?

Extremely short and front-loaded, with the useful content in the first sentence and the endpoint detail as a secondary aid. Borderline under-specified rather than padded.

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

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

For a no-parameter read tool with annotations covering safety, the description is minimally sufficient, but it omits return-shape details (there is no output schema) and any mention of ordering or volume of results.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies.

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

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

States the resource (chores) and that it returns all of them with their next estimated execution, which differentiates it from grocy_chore_get by scope. But there is no explicit verb and no direct mention of siblings, so the listing intent is only implied by the name.

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

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

No when-to-use guidance, no prerequisites, and no pointer to alternatives like grocy_chore_get for a single chore or grocy_chores_calculate_assignments. The agent must infer usage from the name alone.

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

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

Annotations already declare this is a non-readOnly, non-destructive, open-world write. The description adds a genuinely useful behavioral fact the annotations do not convey: the tool defaults to a dry-run unless confirm is supplied. It says nothing about what state is actually restored by an undo (stock, chore due date, assignment history), which matters for a non-idempotent mutation.

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

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

Three short sentences, action first, endpoint second, the one non-obvious parameter behavior last. Nothing is wasted and the dry-run caveat is not buried.

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

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

For a 2-parameter mutation tool with no output schema, the essentials are present but thin. Missing: how to obtain an execution_id, what the undo actually reverts, and what a dry-run preview returns, all of which an agent needs to call this confidently.

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

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

Schema coverage is only 50%: confirm is fully documented in the schema, and execution_id has no description anywhere. The description's dry-run note largely repeats what the confirm schema description already says, and adds nothing about execution_id (where to obtain it, what it identifies).

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

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

States a specific verb and resource ("Undo a chore execution") plus the exact endpoint, which cleanly separates it from grocy_chore_execute and grocy_chore_get in the sibling list. Sibling differentiation comes from the verb alone rather than explicit contrast, so it stops short of a 5.

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

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

The dry-run instruction ("Omit confirm for a dry-run") gives real invocation guidance for the confirm parameter. There is no guidance on when to reach for this versus related siblings such as grocy_task_undo or grocy_chore_merge, and no 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds one genuinely useful behavioral fact — that passwords are redacted from the response — plus the underlying endpoint, but says nothing about permission fields or what else the payload contains.

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 fragments, front-loaded with the resource identity and ending with the redaction caveat. The 'GET /api/user' fragment is largely redundant implementation detail, but nothing else is wasted.

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

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

For a zero-parameter, no-output-schema getter, the description covers what is returned (the authenticated user) and one important return-value caveat (redacted passwords). An agent has enough to call it and interpret the result, though a note on what identity fields are present would round it out.

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 the schema is an empty object, so there is nothing to document. The baseline for a parameterless tool 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?

Identifies the resource precisely as the authenticated (current) Grocy user, which distinguishes it in intent from the sibling grocy_users_list that returns all users. It does not name that sibling explicitly, but the scope is unambiguous.

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

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

Usage is only implied: the tool takes no parameters and returns the caller's own user record, so an agent can infer it is a self-lookup. There is no explicit 'use this when you need the calling user's identity rather than grocy_users_list' guidance or any stated exclusions.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and the HTTP endpoint is provided, so the safety profile is largely covered. The description adds one genuinely useful behavioral fact beyond annotations: omitting confirm yields a dry-run rather than an error, which changes call strategy. It stops short of saying the deletion is irreversible or what happens when the file is absent.

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, zero filler, front-loaded with the action, then the endpoint, then the dry-run caveat. 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 destructive, no-output-schema mutation, the description covers what it does and the dry-run pattern, and annotations cover the risk profile. It omits how to obtain a valid file_name (i.e., using grocy_files_get first) and what a dry-run response versus a real deletion returns, which leaves a real gap for an agent invoking it cold.

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%, so the description must carry weight, and it does explain the confirm semantics (dry-run when omitted) — though the schema's own confirm description already covers this in more detail. group's enum and file_name's length bounds rely entirely on the schema, and the description adds no guidance on valid group values or file-name sourcing.

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?

"Delete a file" is a specific verb+resource, and the endpoint path DELETE /api/files/{group}/{fileName} makes the target entity unambiguous. Against siblings like grocy_files_get and grocy_files_put, an agent knows instantly this is the removal path.

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

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

The only usage guidance is in the sentence "Omit confirm for a dry-run," which gives a safe-preview workflow but not a when-to-use/when-not statement. Nothing tells the agent to look up an existing file name first or what to do if the caller is unsure of the group.

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 mark this as read-only, non-destructive, and open-world, so the safety profile is covered. The description adds meaningful behavioral context beyond that: it explains base64 encoding, that small files return text or base64 while large files return size only, and that server paths are omitted.

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 short, front-loaded with the main action, and each sentence adds useful information. There is no wasted wording 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?

The description covers the basic download action and important return-shape behavior for small versus large files. However, with five parameters and low schema description coverage, it leaves three optional parameters unexplained, which is a gap for an agent trying to use image-resizing or forced-content options correctly.

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

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

Schema description coverage is only 40%, so the description should compensate for undocumented parameters. It clarifies that file_name is the plain name and mentions base64 encoding, but does not explain group semantics beyond the enum, nor does it explain best_fit_width, best_fit_height, or force_serve_as.

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 ('Download a file') and adds the endpoint path, making it clear this is a file retrieval tool. It implicitly distinguishes from sibling tools like grocy_files_put and grocy_files_delete, but does not explicitly name or contrast 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?

The description gives no explicit guidance on when to use this tool versus alternatives such as grocy_files_put or grocy_files_delete. Usage is only implied by the word 'Download' and the endpoint path.

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

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

Annotations already declare readOnly=false, idempotent=true and destructive=false, so the bar is lower; the description still adds real context by disclosing the octet-stream payload format, the endpoint path, and the dry-run gate. It does not mention permissions, whether an existing file with the same name is overwritten, or the size ceiling that the schema enforces.

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

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

Four short sentences, front-loaded with the action and payload type, with no filler. Each sentence contributes either format, endpoint, or a calling rule.

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

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

A write tool with no output schema that nevertheless explains payload encoding and the confirmation/dry-run protocol, so an agent can call it correctly. The main remaining gap is overwrite/conflict behavior for an idempotent PUT, which matters for a file upload.

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% (only 'confirm' is documented), so the description needs to compensate. It clarifies content_base64 as 'the file bytes', which is genuinely useful, but says nothing about the five enum values for group, the 200-char file_name limit, or the 750k base64 cap, and its dry-run note duplicates the schema text.

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

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

States a specific verb and resource (upload a file) plus the exact endpoint and content type, which immediately separates it from the sibling read/delete file tools (grocy_files_get, grocy_files_delete). An agent can identify the tool without opening the schema.

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

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

The 'Omit confirm for a dry-run' sentence gives a usable calling convention, but there is no guidance on when to prefer this tool over siblings or when not to upload (e.g., duplicates, overwriting existing files). Usage is implied rather than framed against alternatives.

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

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

Annotations already declare readOnly=false, idempotent=false, destructive=false, and openWorld=true, so the safety profile is covered. The description adds the genuinely useful dry-run semantics and the endpoint mapping, but says nothing about validation failures, what happens when fields are missing or wrong, or that each entity has its own required field set — the main failure mode for this tool.

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

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

Three short sentences, front-loaded with the action, then the endpoint, then the parameter role, then the dry-run caveat — no filler and nothing repeated from the schema verbatim.

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 generic create over 35 entity types with an unconstrained free-form fields object and no output schema, the description should point at how to learn required fields (e.g. via grocy_objects_list or entity metadata). Dry-run and endpoint context help, but an agent can still easily call this with an invalid field set and no way to know in advance.

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 enum of 35 entities plus the confirm const-rejection behavior are fully documented in the schema, so the schema does the heavy lifting. The description only restates that fields is the entity JSON, which clarifies the free-form object but adds no formatting or per-entity field guidance.

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

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

States a specific verb and resource ("Create one Grocy object") and pins the underlying endpoint POST /api/objects/{entity}. The "one" and "create" wording implicitly distinguishes it from grocy_objects_update/delete, though those siblings are never named.

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 dry-run convention ("Omit confirm for a dry-run") is a real usage rule, but there is no guidance on when to use this generic creator versus entity-specific siblings like grocy_users_create, grocy_stock_add, or grocy_objects_update, and no mention of how to discover valid fields per entity.

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

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

The annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false, and openWorldHint=true. The description adds the dry-run behavior via omitting confirm, but it does not explain irreversibility, cascade effects, authorization requirements, or what the dry-run preview returns; with annotations carrying the safety profile, a 3 is appropriate.

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

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

The description is three short, front-loaded sentences with no wasted text. It states purpose, endpoint, and the key confirmation/dry-run behavior immediately.

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

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

Given the schemas, annotations, and lack of an output schema, the description covers the essential invocation details: what it deletes, the endpoint shape, and how to request a dry-run. It is slightly thin on destructive-operation consequences and permissions, but annotations already signal destructiveness.

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 fully documents entity, object_id, and confirm, including that confirm must be boolean true and that omitting it triggers a dry-run. The description does not add parameter details beyond the schema, so the baseline 3 is correct.

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

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

The description states a specific verb and resource: 'Delete one Grocy object,' and includes the exact DELETE endpoint. This clearly distinguishes it from sibling tools such as grocy_objects_create, grocy_objects_update, grocy_objects_get, and grocy_objects_list.

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

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

It gives clear operational guidance for the dry-run: 'Omit confirm for a dry-run.' The deletion use case is obvious, but it does not explicitly state when to avoid deletion or mention related alternatives; however, there is no sibling delete tool for arbitrary Grocy objects.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The endpoint path adds the useful signal that this is a thin passthrough to the Grocy REST API returning a raw entity record. It says nothing about error behavior for a non-existent id or per-entity permission requirements, which matters for openWorld access.

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 fragments, front-loaded with the action and followed by the route; nothing is wasted. It is arguably too terse for its remaining gaps, but as prose it is well-structured and 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?

There is no output schema, so the description should indicate that a single raw entity record is returned and what happens on a miss; neither is stated. For a generic tool spanning 36 entity types that overlaps with many dedicated getters, this leaves the agent without the context needed to choose it confidently.

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 36-value entity enum and a positive-integer object_id fully documented, so the schema does the heavy lifting. The description only mirrors the path template ({entity}/{objectId}) and adds no syntax, format, or cross-entity nuance beyond 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?

States a specific verb ('Get') and scope ('one Grocy object'), plus the underlying REST route, which makes the generic read-one semantics unambiguous. It does not explicitly contrast with the sibling grocy_objects_list or the entity-specific getters (grocy_chore_get, grocy_battery_get), so differentiation is only implied by the singular 'one'.

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

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

No guidance on when to use this generic reader versus grocy_objects_list or the many dedicated getters like grocy_chore_get and grocy_battery_get that overlap with it. The agent must infer that this is the generic fallback for any entity in the enum.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered elsewhere. The description adds only the raw endpoint path and repeats the entity enum already present in the schema; it says nothing about default page size, whether query[] filters are server-evaluated, or the shape of the returned records.

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

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

Three short sentences, front-loaded with the action and endpoint, with no filler. The third sentence partly duplicates the entity enum from the schema, which is the only waste.

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

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

A generic, open-world CRUD list tool with 5 parameters and no output schema needs more than this: pagination defaults/max behavior, what a returned object looks like, and which of the 34 enum entities behave differently. The definition is adequate to attempt a call but leaves meaningful gaps.

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

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

Schema coverage is 60%: order and query[] already carry descriptions, entity has an enum plus description, while limit and offset are undocumented in both places. The description only restates the parameter names ('Optional query[], order, limit, offset') without adding pagination semantics or defaults, so it neither compensates nor detracts.

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

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

States a specific verb+resource ('List objects of a Grocy entity') and backs it with the underlying endpoint GET /api/objects/{entity}. The plural 'List' plus the entity enumeration clearly separates it from grocy_objects_get/create/update/delete, though the description never names those siblings explicitly.

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

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

Usage is implied by the list-vs-get naming and the endpoint shape, but there is no explicit guidance on when to pick this generic lister over the many specialized siblings (grocy_chores_list, grocy_batteries_list, grocy_tasks_list, grocy_stock_overview). No 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 declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, and the description adds genuinely non-redundant context: writes require an explicit confirm=true and otherwise perform a dry-run preview. It does not address permissions or what happens when a field is invalid, but the dry-run gate is the key behavioral fact an agent needs.

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

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

Two sentences, zero filler, and the core action plus endpoint is front-loaded ahead of the dry-run caveat. Nothing to cut.

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 generic mutation over 36 enum entities with a free-form nested fields object and no output schema, yet the description says nothing about which entities are writable versus read-only views (stock_current_locations, sessions, products_average_price look like views) or what the response contains. The dry-run hint is helpful but the entity-surface caveat is missing.

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

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

Schema coverage is 100% and every parameter is described in the schema, including the confirm const-true wrinkle and object_id's exclusive minimum, so the schema carries the load. The description adds only the dry-run framing, which duplicates the schema's confirm description. Baseline 3 applies.

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

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

States a specific verb (Edit) and resource (one Grocy object) plus the underlying endpoint PUT /api/objects/{entity}/{objectId}, which pins scope to a single existing record. The word 'Edit' combined with 'one object' implicitly separates it from grocy_objects_create/delete/list/get siblings, though it never names 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?

The only usage guidance is operational ('Omit confirm for a dry-run'), which is useful but covers how to invoke a mutation, not when to pick this generic tool over entity-specific siblings like grocy_users_update or grocy_chore_merge. An agent must infer the choice from the verb alone.

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

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

Annotations already disclose that this is a non-idempotent write with open-world effects. The description adds a genuinely useful behavior detail - printing has a real physical side effect on hardware and can be previewed by omitting confirm - but it repeats the schema's confirm text and says nothing about failure modes (e.g., no printer configured) or output.

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

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

Three short sentences, front-loaded with the purpose. The embedded raw endpoint path ('GET /api/print/shoppinglist/thermal') adds little for an agent choosing the tool but does no real harm.

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?

Reasonable for a small mutation tool with annotations and no output schema, but it omits what an agent would want before a physical print: the meaning of print_header, and what happens when no printer is configured or printing fails. The list default is only in the schema.

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

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

Schema coverage is 67%, and the description only echoes the confirm dry-run semantics already spelled out in the schema. It says nothing about the list id (or its default) or what print_header toggles, leaving a third of the parameters undocumented in both places.

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

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

States a specific verb and resource ('Print a shopping list') plus the target device ('configured thermal printer'), which is unambiguous. No sibling in the list prints a shopping list, so the tool is easy to distinguish, though it doesn't explicitly name an alternative for non-thermal output.

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

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

Gives no when-to-use or when-not-to-use guidance relative to grocy_shopping_list (which manages list contents) or any other sibling. The only usage-type hint is the dry-run note, which concerns the parameter rather than tool selection.

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

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

Annotations already declare it is a write (readOnlyHint=false), non-destructive and non-idempotent; the description adds the dry-run/confirm gate, which is genuine value. It does not disclose that repeated confirmed calls will duplicate shopping-list entries (idempotentHint=false) or whether existing list quantities are merged — the main behavioral risk for this tool.

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

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

Three short, front-loaded sentences with the purpose first and the dry-run caveat at the end. The raw endpoint string is mildly redundant but compact and does reinforce the resource path.

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

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

For a 3-parameter mutation tool with no output schema, the definition covers intent and the dry-run mechanism but leaves the agent guessing about the excluded_product_ids parameter and about duplicate-entry behavior on repeat calls. Adequate but with clear gaps.

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

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

Schema coverage is only 33%: only confirm is documented, while recipe_id and excluded_product_ids have no descriptions. The description mentions recipeId only implicitly via the endpoint path and never explains excluded_product_ids (a 200-item exclusion filter) — a gap the description should have closed given the low coverage.

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

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

States a specific verb and resource: adding a recipe's unfulfilled products to the shopping list, and names the exact endpoint. An agent can distinguish it from generic shopping-list or stock tools. It does not differentiate from the closest siblings (grocy_recipe_fulfillment, grocy_shopping_list), so it stops short of 5.

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

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

"Omit confirm for a dry-run" gives one useful procedural cue about how to preview safely. However there is no guidance on when to choose this over grocy_recipe_fulfillment or grocy_recipe_consume, nor prerequisites such as needing the recipe to exist with unmet products.

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

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

With annotations already declaring this is not read-only, not idempotent, and not destructive, the description adds useful execution semantics: the endpoint and the dry-run preview path. It does not spell out the stock-level effects of consumption, but the critical safe-preview behavior is disclosed.

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 wasted text. The primary action is front-loaded, followed by the endpoint and the key dry-run instruction.

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

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

For a two-parameter mutation with annotations and no output schema, the description covers the action, endpoint, and safe preview behavior. It could say more about the resulting stock changes, but nothing essential for invocation is missing.

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

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

Schema coverage is 50%: `confirm` is richly documented in the schema, while `recipe_id` has no schema description. The description reinforces the dry-run meaning of omitting `confirm`, but adds no clarification for `recipe_id` beyond the self-evident name.

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

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

The description names a specific verb and resource: consuming in-stock ingredients for a given recipe. It is distinguishable from grocy_stock_consume, which operates on individual stock products, though it does not explicitly name that sibling as the alternative.

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

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

It clearly explains the dry-run behavior: omit `confirm` to preview, and the schema reinforces that only literal `true` executes the write. It lacks explicit guidance on when to prefer this tool over related recipe or stock operations, but the operational condition is clear.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is mostly covered. The description's dry-run note adds a behavioral fact, but it largely restates the confirm parameter's schema description and says nothing about what the write actually does (new recipe ID, name, duplicated contents) or failure modes. Non-idempotency is not called out, leaving the agent unaware that repeated calls create multiple copies.

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 fragments, zero waste, with purpose first and the dry-run caveat immediately after. Nothing is padded or buried.

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

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

For a two-parameter mutation with no output schema, the description is minimally adequate: the agent knows what it does and how to preview. Missing are the outcome (what the copy looks like / what ID is returned) and the non-idempotent consequence of repeated calls, which matter for a write tool.

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

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

Schema coverage is 50%: confirm is thoroughly documented in the schema, while recipe_id has no description. The endpoint path in the description implies recipe_id identifies the source recipe to copy, which compensates slightly, but there is no clarification of the ID domain or of the new recipe's handling.

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

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

States a specific verb and resource ("Copy a recipe") plus the backing endpoint, which cleanly separates it from sibling recipe tools like grocy_recipe_consume and grocy_recipe_fulfillment. It stops short of naming those siblings or stating scope (ingredients/instructions copied?), so it is clear but not fully differentiated.

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

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

The dry-run hint ("Omit confirm for a dry-run") gives real operational guidance on the safe invocation path. There is no explicit when-to-use vs. alternatives guidance, no prerequisites such as permissions or whether the source recipe must exist, so usage is only implied.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description only repeats GET endpoint paths and adds no behavioral context about what fulfillment data is returned, whether it involves computation, or any auth/rate-limit considerations.

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 short and front-loaded with no filler, but it uses terse endpoint notation rather than clear prose. It is concise to the point of under-specification, leaving the agent to infer the tool's actual behavior from Grocy API paths.

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

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

There is no output schema, so the description should explain what fulfillment data is returned, but it does not. It also omits the query parameter semantics and any comparison to sibling recipe tools, making it incomplete for correct tool selection and invocation.

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

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

Schema description coverage is only 33%, so the description must compensate for underspecified parameters. It clarifies the action mapping ('one' vs 'all') and indirectly shows recipe_id in the path, but it does not explain the 'query' array parameter at all.

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 largely restates the tool name ('Recipe stock fulfillment') rather than stating a clear verb and object, such as retrieving stock fulfillment for a recipe. The endpoint paths imply GET operations, but it does not explain what 'fulfillment' means or how this differs from sibling recipe tools like grocy_recipe_consume.

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

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

The description explains the two action values but gives no guidance on when to use this tool versus alternatives. It does not mention grocy_recipe_consume, grocy_recipe_add_missing_to_shoppinglist, or any selection criteria beyond the one/all endpoint split.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the confirm-gate/dry-run behavior, which is genuine context, but that same behavior is already spelled out in the schema's confirm description, and nothing is said about what actually happens server-side when confirmed (side effect on a physical/spooled printer).

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 purpose, then the endpoint, then the dry-run caveat. Nothing is padded, though the raw endpoint adds modest value over the tool name for an agent.

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

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

There is no output schema, so the description would ideally say what comes back (label text? rendered payload? a print job acknowledgement?) and what confirming actually triggers on the server. The dry-run behavior is covered; the post-confirm outcome is not.

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

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

Schema coverage is 50%: confirm is well documented in the schema (and only restated in the description), while recipe_id has no schema description at all. The endpoint pattern /api/recipes/{recipeId}/printlabel implies recipe_id is a path identifier, which is a small but real addition. Baseline 3 for a half-documented two-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 names a specific verb and resource ("Print the Grocycode label for a recipe") plus the underlying endpoint, so an agent can distinguish it from the sibling label tools grocy_chore_printlabel and grocy_battery_printlabel by the resource alone. It doesn't explicitly call out those siblings, but the resource noun does the differentiation work.

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

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

Usage is implied by the tool name — use this when you need a label for a recipe — and the confirm/dry-run note gives a calling convention, but there is no statement of when to prefer this over a generic print/objects path or any preconditions (e.g. the recipe must exist, a printer must be configured).

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true, so the write/destructive profile is known. The description contributes the dry-run behavior and reinforces 'All writes', but never says what `clear` destroys or whether existing list items are replaced or appended by the add_* actions. With annotations carrying the safety burden, this is adequate but thin.

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 telegraphic sentences with no filler, and the action list is front-loaded after the resource name. Slightly clipped to the point of under-specification, but nothing is wasted.

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

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

A destructive, 8-parameter multi-action tool with no output schema and 13% schema coverage needs substantially more description: per-action parameter requirements and what each action returns in dry-run versus execute mode. The definition gives none of that, so an agent must guess which fields to populate for a given action.

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

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

Schema description coverage is only 13% across 8 parameters, so the description must compensate — and it does not. It never maps params to actions: which of list_id, product_id, product_amount, qu_id, note, or done_only belongs to add_product versus clear is left entirely to inference. Only the confirm/dry-run semantic gets any prose, which the schema already covers.

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

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

The description names the resource (shopping list) and enumerates the six supported actions, so an agent can see this is a shopping-list mutation surface rather than a stock or recipe tool. The opener 'Shopping list helpers' is vague, but the action enumeration carries the specific meaning. It is distinguishable from grocy_print_shoppinglist and grocy_recipe_add_missing_to_shoppinglist by virtue of being the direct list-management tool.

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

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

The description implies usage through the action list but never states when to pick this over grocy_recipe_add_missing_to_shoppinglist or grocy_stock_add. The one explicit usage instruction is 'Omit confirm for a dry-run', which tells the agent a safe preview workflow exists. No exclusions or prerequisites are given.

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

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

Annotations already declare a non-read-only, non-idempotent, non-destructive write. The description adds valuable behavior beyond the annotations by disclosing the dry-run preview mechanism: omit confirm to preview, include confirm to execute. It still omits permission requirements, side effects on stock history, and whether dry-run output is returned.

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

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

The description is short and front-loaded, leading with the core action. The endpoint detail is somewhat implementation-focused, but it does support the by-barcode path explanation. No sentence is bloated.

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

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

This is a mutation tool with 11 parameters, no output schema, and only partial schema descriptions. The description omits key operational context such as amount semantics, stock effects, transaction_type behavior, and what the dry-run returns. It is not complete enough for an agent to invoke confidently beyond the simplest case.

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

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

Schema description coverage is only 27% across 11 parameters. The description explains the product_id/barcode alternative and confirm dry-run behavior, but it leaves most parameters undocumented: amount units, price, note, location_id, best_before_date, transaction_type, stock_label_type, and shopping_location_id. It does not compensate for the low 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 states a specific verb and resource: 'Add amount of a product to stock.' It also names the underlying endpoint and the product_id/barcode selection, making the operation distinguishable from sibling stock operations like consume or transfer. However, it does not explicitly contrast with those siblings.

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

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

It gives an important usage rule: 'Omit confirm for a dry-run.' It also says to provide product_id or barcode, but it does not say when to use this tool versus alternatives such as grocy_stock_consume, grocy_stock_transfer, or grocy_stock_inventory. Usage is implied rather than explicitly 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 readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true; the description usefully reinforces that undo is a confirm-gated POST. It adds nothing about permissions, whether undo restores previous stock levels, or error behavior for a nonexistent booking, and the dry-run preview is disclosed only in the schema.

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

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

Three short clauses, front-loaded with the resource and then per-action behavior. No filler and every sentence carries information an agent needs.

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

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

With no output schema, the agent gets no hint of what a get returns (booking fields, product, quantity) or what undo affects on stock levels. For a two-mode tool with a write path, the description should say more about results and preconditions.

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%, so the description carries real weight: it maps action values get/undo to concrete endpoints and identifies bookingId as a path parameter, compensating for the undescribed enum. It still says nothing about booking_id validity or scope beyond the schema's integer constraints.

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

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

Names the resource (stock booking) and enumerates both operations with their underlying endpoints: get a booking by ID and undo a booking. This is enough to separate it from siblings like grocy_stock_consume or grocy_stock_add, though it never explicitly contrasts with 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?

Implies selection between the two actions (use get to read, undo to reverse) and states undo requires confirm, but gives no guidance on when this tool is preferable to adjacent stock tools such as grocy_stock_consume, grocy_stock_transaction, or grocy_stock_product.

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

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

Annotations already flag this as a non-readonly, non-idempotent write, and the description adds the useful dry-run-by-default safety model. However, it says nothing about what consumption does to stock levels, how 'spoiled' differs from normal consumption, what transaction_type changes, or how partial/subproduct substitution behaves — significant gaps for an 11-parameter mutating tool.

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

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

Two tight sentences, front-loaded with the action and followed by the key safety behavior. No padding, though the 'POST consume' fragment is endpoint trivia that doesn't help an agent.

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

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

With 11 parameters, low schema coverage, no output schema, and no annotations covering mutation semantics, the description leaves too much undocumented for an agent to call this confidently beyond the simple amount + product_id/confirm path.

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

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

Schema coverage is only 27% with 11 parameters, and the description only touches product_id/barcode and confirm — both of which the schema already documents. Eight parameters (amount, spoiled, recipe_id, location_id, exact_amount, stock_entry_id, transaction_type, allow_subproduct_substitution) get no explanation anywhere in the description, so it fails to compensate for the coverage gap.

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

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

States a specific verb and resource ('Consume amount of a product from stock') plus the endpoint and the two lookup keys. It implicitly separates itself from siblings like grocy_stock_add and grocy_stock_transfer by naming the consume operation, though it never names the closest alternative (grocy_stock_booking / grocy_recipe_consume).

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?

'Omit confirm for a dry-run' implies a workflow (preview first, then confirm), but there is no explicit statement of when to use this versus grocy_stock_booking, grocy_stock_open, or grocy_recipe_consume, nor any prerequisite/auth guidance.

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

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

The annotations already declare readOnly=false, idempotent=true, destructive=false, and openWorld=true. The description adds useful context with "Writes need confirm" and endpoint mappings, but it does not disclose what update changes, what printlabel actually returns or affects, or any side effects beyond the confirm gate.

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 short and front-loads the action mappings, but it is written in telegraphic fragments that reduce clarity. "Stock entry." is an ambiguous lead, and the endpoint references occupy space without adding much semantic guidance.

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

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

For a 9-parameter mutation-capable tool with only 22% schema coverage and no output schema, the description is too incomplete. It omits the meaning of most parameters and does not describe return behavior for get or printlabel.

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

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

Schema description coverage is only 22%, with entry_id and confirm documented in the schema. The description does not explain the roles of amount, price, open, location_id, shopping_location_id, or best_before_date, so it does not compensate for the low coverage on a 9-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 names the resource ("Stock entry") and maps each action to an HTTP operation, so the available operations are visible. However, it never states the tool's purpose in a clear verb+resource form beyond endpoint mappings, and it does not differentiate this tool from siblings such as grocy_stock_transaction or grocy_stock_product.

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 notes that writes require confirm, which gives some usage context for update. But it provides no explicit guidance on when to choose get versus update versus printlabel, and no comparison to sibling stock tools, leaving operation selection largely to the enum.

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

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

Annotations already declare this as a non-destructive but writing, idempotent, open-world operation. The description adds critical behavioral context beyond that: the confirm gate controls whether the inventory POST executes or is only a dry-run preview, which is central to safe invocation.

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

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

Three short sentences, front-loaded with the action and resource, followed by endpoint and dry-run behavior. No filler or redundancy.

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

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

For a 10-parameter mutation tool with no output schema and only 40% schema description coverage, the description covers the indispensable confirm gate but leaves most optional parameter interactions and side effects unclear. It is minimally sufficient but not complete.

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

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

Schema description coverage is only 40% across 10 parameters. The description mentions product_id, barcode, confirm, and implicitly new_amount, but leaves note, price, location_id, best_before_date, stock_label_type, and shopping_location_id unexplained, so it does not compensate for the low 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 states a specific verb and resource: 'Set the stock amount of a product.' This distinguishes it from siblings such as grocy_stock_add and grocy_stock_consume by implying an absolute overwrite rather than an incremental change, though it does not name those alternatives explicitly.

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

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

It gives useful invocation details (provide product_id or barcode; omit confirm for a dry-run) but never states when to use this tool instead of grocy_stock_add, grocy_stock_transaction, or grocy_stock_booking. Usage is implied rather than explicitly routed.

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, destructiveHint=false and openWorldHint=true, so safety is covered. Beyond that the description only restates the REST path; it says nothing about whether entries are paginated, whether zero-stock products are included, or what shape the entries take.

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 fragments with no filler, and the resource is front-loaded. The raw endpoint sentence is borderline but does add a small amount of orientation.

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 tool with full schema coverage and annotations, this is still thin: it does not clarify the return content or how it differs from related stock tools, leaving the agent to guess what 'entries' means in this domain.

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

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

Schema coverage is 100% and the single location_id parameter is documented in the schema, so the baseline is 3. The path template {locationId} merely echoes the schema and adds no new meaning.

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

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

Names the resource (stock entries) and scopes it to a location, but uses a noun phrase with no verb, so it is unclear whether this lists raw entry rows or aggregates. It is partially distinguishable from siblings like grocy_stock_entry or grocy_stock_overview only by the 'at a location' qualifier.

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 indication of when to use this over grocy_stock_entry, grocy_stock_overview, or grocy_stock_volatile. The endpoint path hints at a per-location read, but nothing explicit routes the agent among alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the agent knows the operation is a destructive write. The description adds the dry-run behavior, but it does not explain what 'merge' does to stock entries, lots, or the removed product, which is valuable context for a destructive operation.

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

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

The description is three short sentences with no waste. The purpose is front-loaded, followed by the endpoint and the dry-run instruction in a logical order.

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

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

For a destructive merge operation with no output schema and incomplete parameter descriptions, the definition covers invocation basics but omits important context: what happens to the removed product's stock, whether the merge is reversible, and what a successful response contains. Annotations help with safety, but the description remains thin on consequences.

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

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

Schema description coverage is only 33%: the two product ID parameters have no descriptions. The description partially compensates by showing the path placeholders productIdToKeep and productIdToRemove, which clarify their roles, but it does not add meaning beyond the self-descriptive property names.

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

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

The description states a specific verb and resource: "Merge two products into one." This clearly distinguishes the tool from sibling stock operations such as transfer, consume, or inventory. An agent can identify the operation without opening the schema.

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

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

The description gives a concrete invocation guideline: "Omit confirm for a dry-run." However, it does not say when to choose this tool over alternatives such as stock transfer or product update, nor does it state exclusions or prerequisites. Usage is therefore implied rather than fully 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 a non-read-only, non-idempotent, non-destructive write operation. The description adds meaningful behavior beyond annotations: the endpoint style ('POST open'), target selection by product_id or barcode, and the dry-run semantics of omitting confirm. It does not explain the effect on stock quantities, so it falls short of a 5.

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

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

Three short, front-loaded sentences with no wasted language. The core action comes first, followed by targeting and dry-run behavior, which is exactly the information an agent needs in the order it needs it.

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

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

Annotations cover the mutation safety profile and the description covers dry-run behavior and targeting. Yet the definition does not explain what 'opened' does to stock accounting, how amount is applied, or the roles of stock_entry_id and allow_subproduct_substitution, leaving meaningful gaps for a write operation with no output schema.

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

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

Schema description coverage is only 50%. The description helps by explaining that targeting can be done via product_id or barcode and that omitting confirm triggers a dry-run. However, it says nothing about amount, stock_entry_id, or allow_subproduct_substitution, leaving material parameter meaning 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 states a specific verb and resource: 'Mark amount of a product as opened.' This clearly distinguishes the tool from sibling stock operations like consume, add, transfer, and inventory. It stops short of naming sibling alternatives explicitly, which keeps it at a 4 rather than 5.

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

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

It gives useful targeting guidance ('by product_id or barcode') and a dry-run hint ('Omit confirm for a dry-run'). However, it does not explain when to choose this tool over alternatives such as grocy_stock_consume, nor does it state prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds only a data-content hint (each entry carries a next due date); it says nothing about result size, sorting, or whether expired/zero-stock products are included. The trailing 'GET /api/stock' restates the implementation rather than adding 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?

Two short sentences with the essential information front-loaded. The raw endpoint path is filler that an agent cannot act on, but it costs only a few tokens.

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

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

With no output schema and no parameters, the description is the only source of truth about what comes back, and it only names the next due date. It omits whether stock quantities, units, or product IDs are returned and whether the list is filtered or paginated.

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

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

The tool takes zero parameters, so the schema carries no semantics to supplement; baseline 4 applies. The description correctly implies no filtering arguments are required.

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

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

Names the resource and the scope clearly: products currently in stock, with the next due date. The plural 'Products' plus 'currently in stock' distinguishes it reasonably from grocy_stock_product (single product) and grocy_stock_volatile, though neither sibling is named.

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 statement of when to call this versus grocy_stock_product, grocy_stock_volatile, or grocy_stock_location_entries. The agent has to infer from the tool name that this is the aggregate overview rather than a per-product lookup.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, and the description adds real value on top by partitioning the six actions into reads versus writes and stating that the writes are gated on confirm. It does not explain what "copy" actually creates or whether it is reversible, so it stops short of full disclosure.

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

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

Two short sentences with no filler, and the highest-value information (which actions mutate state) is stated directly. The telegraphic phrasing ("action get, locations, entries, price_history are reads") is slightly clipped and reads like notes rather than prose, but nothing is wasted.

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

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

For a six-way multiplexed tool with no output schema, the definition should signal what each read action returns (locations versus entries versus price_history are not differentiated). Annotations carry the safety profile, but the return-shape ambiguity for each action leaves a meaningful gap.

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

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

Schema coverage is 67% and the confirm field is already well documented in the schema, so the baseline is a 3. The description earns above baseline by annotating the action enum with read-versus-write semantics, a distinction the schema's bare enum list does not convey; product_id still gets nothing beyond the schema.

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

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

"Product stock" names the resource but supplies no verb, and the meaning of the tool only emerges from the action list that follows. The six action names (get, locations, entries, price_history, copy, printlabel) do sketch the capability set, but nothing distinguishes this tool from close siblings such as grocy_stock_entry, grocy_stock_overview, or grocy_stock_product_by_barcode.

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 read/write split gives implicit guidance on when the confirm field is required, which is genuinely useful selection logic. However, there is no advice on when to choose this tool over the many stock siblings, and no indication of which action to pick for a given goal beyond the action names themselves.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the raw endpoint path, which is implementation detail rather than behavior — it says nothing about what happens when the barcode is unknown, whether it scans external sources (relevant given openWorldHint), or what shape the response takes.

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, front-loaded with the purpose and with zero filler. It is efficient, though the second sentence spends space on an endpoint path rather than on information the agent lacks.

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

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

There is no output schema, so the description is the only place an agent could learn what 'stock details' comprises (amounts, best-before, location, price). With one undocumented parameter and no return-value context, the definition is under-specified for anything beyond a name-based guess.

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

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

Schema coverage is 0%, so the description carries the full burden for the single required parameter, yet it only restates the name 'barcode' via the URL template. It gives no format guidance (EAN/UPC/GTIN, scannable code vs. internal product barcode) or hint about what a valid value looks like.

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

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

The description names the resource (stock details of a product) and the selector (by barcode), so the core action is recoverable. However, "stock details" is vague about what is returned, and nothing distinguishes it from the sibling grocy_barcode_lookup or grocy_stock_product, both of which plausibly overlap.

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

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

There is no statement of when to use this tool versus grocy_barcode_lookup (which likely also resolves barcodes) or grocy_stock_product (which likely fetches the same data by product id). The agent is left to infer routing from tool names alone.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the safety bar is lower. The description adds that undo 'reverts' a transaction and that undo 'needs confirm', which is real behavioral context beyond the annotations. It does not say whether the undo is reversible, what 'reverts' means concretely for stock levels, or that omitting confirm yields a dry run (that detail lives only in the schema).

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

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

Three short sentences with no padding, and the mode behaviors are front-loaded. The only weak spot is the throwaway opener 'Stock transaction.', which restates the name instead of adding information.

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

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

For a two-mode tool with no output schema and only partial schema descriptions, the description covers the actions but not the outcome: it doesn't say what the get response looks like, what undo returns, or what happens to stock after a revert. An agent can pick the right action but cannot fully predict the effects.

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

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

Schema description coverage is only 33%: the action enum and confirm are documented in the schema, but transaction_id has no description anywhere. The description partially compensates by explaining what each enum value does (get lists bookings, undo reverts), which is value beyond the raw enum. It leaves the required transaction_id entirely unexplained – what a transaction id is and where to obtain it remains unclear.

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

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

The description names the resource (stock transaction) and enumerates the two modes: 'action get lists bookings' and 'undo reverts the transaction'. However, the opening phrase 'Stock transaction.' is a noun fragment rather than a verb+resource statement, and it never distinguishes this tool from close siblings such as grocy_stock_booking or grocy_stock_entry, so the agent must infer the boundary.

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 implies when each action applies (get to list bookings, undo to reverse one) and notes undo requires confirm, which is genuinely useful routing information. It gives no explicit guidance on when to prefer this over sibling booking/stock tools, and no exclusion conditions, so usage is inferred rather than stated.

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

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

The annotations already declare a non-read-only, non-idempotent write operation, and the description adds useful behavior: POST transfer and dry-run preview by omitting confirm. It still does not describe side effects on source and destination stock beyond the obvious transfer.

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

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

Three short sentences, front-loaded with the core action, then the product lookup method, then the dry-run behavior. There is no wasted wording.

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

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

The definition is adequate for a moderate-complexity mutation tool with no output schema, but it omits stock_entry_id and does not explain the required location semantics or the effect on source and destination stock. The schema covers confirm in detail, which partially offsets the gaps.

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

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

Schema description coverage is only 43%, so the description needs to compensate. It clarifies the product_id-or-barcode alternative and the confirm dry-run behavior, but it leaves amount, location_id_from, location_id_to, and especially stock_entry_id without added meaning.

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

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

The description states a specific verb and resource: transfer an amount of a product between locations. It is clearly a stock movement operation, distinct from siblings like grocy_stock_add or grocy_stock_consume, but it does not explicitly name or route against those alternatives.

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

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

It implies when to use the tool by saying it transfers between locations and notes that omitting confirm produces a dry-run. However, it does not explain when to choose this over related stock tools or when not to use it.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the endpoint and the categories of volatile stock returned, but says nothing about response shape, ordering, or whether missing products include zero-stock items.

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 compact fragments with the result categories front-loaded. The raw endpoint path is arguably filler for an agent, but nothing is bloated or buried.

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

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

With no output schema and no parameter documentation in either schema or description, the agent cannot know what due_soon_days controls or what the response entries contain. The description should explain the parameter's threshold semantics and at least sketch the returned fields.

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

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

Schema description coverage is 0%, so the description must carry the burden for the single parameter. 'Optional due_soon_days' gives no units, default threshold, or effect (e.g., items expiring within N days); only the parameter name hints at meaning.

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

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

The description names the specific resource set ('due soon, overdue, expired, and missing products') and maps it to GET /api/stock/volatile, which is clearly distinct from product-level or overview siblings. It stops short of an explicit verb like 'list', but the purpose is unambiguous.

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

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

There is no guidance on when to choose this over grocy_stock_overview or grocy_stock_product, nor any stated preconditions. The category names imply an expiry-monitoring use case, but the agent must infer that.

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, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds genuinely new behavioral context by warning that filesystem paths are stripped from the result, which prevents an agent from expecting raw path values. It stops there and says nothing about response size or caching.

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 compact fragments with the resource stated first and the behavioral caveat last; nothing is padded. The bare endpoint string is slightly machine-flavored redundancy but is consistent with an API-mirroring toolset.

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-param read tool with no output schema, the description should hint at the shape of the returned config object, since "all config settings" is a large and undocumented structure. It covers the safety and one transformation (path stripping) but leaves the agent guessing about what keys come back.

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

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

The tool takes zero parameters and the schema is empty with 100% coverage, so there is nothing for the description to disambiguate. Baseline 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?

"All Grocy config settings" plus the concrete endpoint (GET /api/system/config) makes the resource and read nature unmistakable. It stops short of distinguishing itself from adjacent siblings such as grocy_system_info, grocy_system_localization, or grocy_system_time, so an agent must infer the boundary.

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

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

Usage is only implied: an agent deduces it should call this when it needs configuration values. There is no explicit 'use this instead of grocy_system_info when...' guidance and no stated prerequisites or exclusions despite a crowded system_* family.

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, destructiveHint=false, and openWorldHint=true, so safety is covered structurally. The description adds the underlying HTTP endpoint, which is mild context but says nothing about the return type (Unix epoch vs ISO string), caching, or failure behavior.

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

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

Two short sentences with the meaning front-loaded before the endpoint reference. The endpoint restatement is close to redundant but does not bloat the definition.

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-param read tool with no output schema, the description should still say what the returned timestamp looks like. It omits return format, which is the only real ambiguity an agent would face 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter claims are made or 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?

Names the specific resource (the timestamp of the last database change) and pins it to a concrete endpoint, so an agent knows exactly what value it returns. It does not explicitly distinguish itself from the close sibling grocy_system_time (current server time), leaving that inference to the agent.

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

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

There is no statement of when to call this versus grocy_system_time, grocy_system_info, or grocy_system_config, all of which live in the same system group. The endpoint path implies 'read-only lookup' but offers no selection guidance or exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered structurally. The description adds genuinely new operational context: the exact endpoint (GET /api/system/info) and the required GROCY-API-KEY auth header, which an agent needs before calling.

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 fragments, front-loaded with the return payload, then endpoint and auth. Zero waste, though the telegraphic style leaves 'client' undefined.

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-arg read tool with annotations covering safety and no output schema, the description supplies everything needed to invoke it correctly: payload contents, HTTP route, and auth header. 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the schema is empty and the description correctly makes no parameter claims.

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

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

States a specific verb (Get) and enumerates exactly what is returned: version, PHP, SQLite, OS, and client environment details. That distinguishes it from siblings like grocy_system_time and grocy_system_config, though it never names those alternatives to sharpen the boundary.

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

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

Usage is only implied – an agent can infer this is a diagnostic/health check, but the description never says when to reach for it versus grocy_system_config or grocy_system_db_changed_time. No exclusions or prerequisites beyond the auth note.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds one useful behavioral fact — the result is scoped to the authenticated user's language — but says nothing about caching, size of payload, or whether it depends on a user setting.

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, front-loaded fragments with no filler. The trailing 'GET /api/system/localization-strings' restates the resource as a URL rather than adding information, costing a small amount of signal.

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 trivial no-parameter read the definition is close to sufficient, and annotations carry the safety profile. However, with no output schema, the description never says what the payload looks like (a key-to-string map?), which is the one thing an agent actually needs 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?

The tool takes zero parameters, so there is nothing for the description to explain. Baseline 4 applies; the implicit 'authenticated user language' selector is at least useful context.

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

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

States a specific resource and scope: localization strings for the authenticated user's language. That is enough for an agent to distinguish it from the closely named sibling grocy_system_log_missing_localization, though the two are never explicitly contrasted.

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; the sentence only describes content plus a raw endpoint path. The near-identical sibling grocy_system_log_missing_localization is not mentioned, so the agent gets no routing help.

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

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

Annotations already declare the write (readOnlyHint=false), non-idempotent and non-destructive profile, so the description's main added value is the dry-run behavior. That dry-run detail largely restates the confirm field's schema description, and nothing is said about write scope or side effects of logging beyond the confirm gate.

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 front-loaded sentences with the core action and dry-run behavior first. The endpoint path is arguably redundant given the tool name, but nothing is padded or buried.

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

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

For a two-parameter write with full schema coverage and annotations covering safety, the description plus schema gives an agent enough to call it correctly. It would be stronger if it clarified what logging does (and whether repeated logs are meaningful given the non-idempotent hint), but 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%; both text and confirm are fully documented in the schema including the strict const=true and rejection of string 'true'. The description's dry-run note adds no syntax or meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Log a missing localization string') plus the concrete endpoint, which pins down a diagnostic operation distinct from sibling grocy_system_localization. It does not explicitly contrast with that sibling, so it stops short of a 5.

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

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

The 'Omit confirm for a dry-run' sentence tells the agent how to preview versus execute, which is real usage context. However it never says when an agent should log a missing localization string at all, nor does it point to any alternative tool or precondition.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered by structured data. The description adds the concrete endpoint and the fact that the offset is optional, but says nothing about the returned time format or timezone, which matters for interpreting an offset.

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 fragments, front-loaded with the resource, with zero padding. The endpoint path is arguably redundant but aids traceability; the telegraphic style leaves a bit of ambiguity in the third fragment.

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

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

For a zero-required-parameter read tool with full schema coverage and annotations carrying the safety profile, this is nearly complete. The only meaningful omission is what the response looks like (unix epoch vs ISO string, timezone), which the agent would need to apply the offset correctly.

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

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

Schema coverage is 100% and the single parameter has its own description ('Offset of the timestamp in seconds') plus min/max bounds. The description's 'Optional offset seconds' only restates optionality, which the schema already encodes via zero required parameters, so the baseline 3 applies.

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

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

States a specific resource and verb-equivalent: it returns the current Grocy server time, and it even names the backing endpoint (GET /api/system/time). It does not explicitly differentiate itself from the nearby grocy_system_db_changed_time or grocy_system_info siblings, so it stops short of a 5.

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

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

There is no statement of when to call this versus grocy_system_db_changed_time or grocy_system_info, nor any note about prerequisites such as authentication. Usage is only inferable from the phrase 'Current Grocy server time'.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description discloses the non-obvious behavior that omitting confirm makes the call a no-op preview rather than a write. It stops short of saying whether the completion is reversible via the undo sibling.

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 terse sentences: the action, the endpoint, and the safety rule. Nothing is redundant and the most consequential fact (dry-run default) is stated outright.

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

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

For a mutation tool with no output schema and low parameter coverage, the description covers the key gotcha (confirm/dry-run) but omits done_time's purpose and whether a completed task can be restored. Adequate to call safely, incomplete to call fully correctly.

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

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

Schema coverage is only 33%, so two of three parameters (task_id, done_time) are undocumented in both places. The description partially compensates by explaining confirm's dry-run semantics, but the meaning of done_time — presumably backdating the completion — is left entirely to inference.

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

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

States a specific verb and resource ('Mark a task completed') plus the underlying endpoint, so the agent knows exactly what changes. It does not name the closest sibling, grocy_task_undo, which would have made the intent unambiguous against the reverse operation.

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?

'Omit confirm for a dry-run' gives a critical usage rule that steers callers toward safe preview first. However, it never states when to prefer this over grocy_task_undo, or what preconditions must hold (task must exist and not already be completed).

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 and destructiveHint=false, so safety is covered, but the description adds nothing beyond restating the endpoint: no indication of ordering, whether overdue tasks are flagged, whether completed tasks are excluded server-side, or what the payload looks like.

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

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

It is two very short sentences with the scope stated first. The trailing 'GET /api/tasks.' conveys little to a model-driven caller but costs almost nothing in space.

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

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

For a zero-parameter read tool with annotations and no output schema, the description is minimally adequate: an agent knows it yields unfinished tasks. It stops short of saying what a task record contains or how results are ordered, which for a list endpoint is the main remaining ambiguity.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the only gap is that no optional server-side filtering is mentioned, which is not required for a parameterless call.

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?

It names the resource (tasks) and the filter ('not done yet'), so the purpose is inferrable, but there is no verb such as 'list' and no differentiation from the sibling task tools (grocy_task_complete, grocy_task_undo). The API path adds nothing that clarifies intent.

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

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

There is no guidance on when to call this instead of grocy_task_complete or grocy_task_undo, and no stated preconditions. An agent must infer the listing role purely from the phrase 'not done yet'.

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 idempotent=true, destructive=false and readOnly=false, so the safety profile is mostly covered. The description adds real value by disclosing the two-phase dry-run/confirm protocol and the endpoint, which the annotations do not convey. It stops short of saying what state the task reverts to (e.g. whether the completion date is cleared).

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 compact sentences, zero waste, with the core action front-loaded and the dry-run caveat immediately after. Nothing is padded or repeated from the 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?

With no output schema and a simple two-parameter mutation, the description covers action, endpoint, and the dry-run safety path adequately. Minor gaps remain around the resulting task state and behavior when the task is not currently completed.

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

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

Schema coverage is 50%: confirm is fully documented in the schema (including the true-only constraint and rejection of false/"true"), while task_id has no schema description. The description restates the dry-run meaning of confirm and implies task_id via the {taskId} path, but adds no new semantics for task_id or error conditions.

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

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

States a specific verb and resource: 'Mark a task not completed', plus the concrete endpoint POST /api/tasks/{taskId}/undo. It implicitly contrasts with the sibling grocy_task_complete by describing the inverse, but never names that sibling explicitly.

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

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

The dry-run instruction ('Omit confirm for a dry-run') gives clear operating guidance for one parameter, and the verb implies when to use it. However, there is no explicit statement of when-not to use it, nor any disambiguation from grocy_chore_undo_execution, which is the nearest adjacent undo tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description contributes nothing beyond the raw endpoint path — no note on whether an empty result is possible for objects without userfields, nor on auth requirements. It adds minimal value past the structured data.

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

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

Two short fragments with no waste and the resource named up front. The endpoint-path sentence duplicates information rather than front-loading additional meaning, but the definition is not bloated.

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

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

There is no output schema, so the description is the only place a return-value shape (a map of userfield keys to values) could be conveyed, and it is not. Annotations cover safety, which limits the damage, but an agent cannot predict the response format from this definition.

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 a documented enum for entity and a constraint (exclusiveMinimum 0) on object_id, so the schema carries the meaning. The description merely restates the path template and adds no semantics beyond it; baseline 3 applies.

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

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

The description names the resource ('userfield values') and scopes it to 'one object', and the endpoint path /api/userfields/{entity}/{objectId} clarifies the addressing model. But it is a noun fragment with no verb (get/retrieve), and it does nothing to distinguish itself from sibling grocy_userfields_put or from grocy_objects_get. Purpose is inferable but not stated crisply.

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 statement of when to use this versus alternatives such as grocy_objects_get or grocy_userfields_put. The agent must infer from the tool name alone that this is the read counterpart to the put tool.

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

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

Annotations already declare that this is a non-read-only, idempotent, open-world, non-destructive operation, and the description adds important dry-run/confirm behavior. However, it does not clarify whether "replace" removes userfields not present in the fields map or leaves them untouched, which is a meaningful behavioral detail.

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 plus the endpoint, with the action front-loaded and no filler. Every sentence contributes to understanding the operation or its dry-run behavior.

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

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

For a four-parameter mutation with full schema descriptions and safety annotations, the description covers the core action and the important dry-run mode. The only notable gap is the exact replacement behavior for omitted userfields, which keeps it from being fully complete.

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

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

Schema description coverage is 100%, so entity, fields, object_id, and confirm are already documented. The description's note about omitting confirm for dry-run repeats schema guidance and adds no further parameter semantics, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource: "Replace userfield values for one object." The PUT endpoint reinforces the scope and distinguishes this from read-only userfield retrieval and generic object update 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?

It gives a useful dry-run instruction via "Omit confirm for a dry-run," but it does not explicitly say when to use this tool instead of grocy_objects_update or grocy_userfields_get. Usage is implied by the replace semantics rather than fully guided.

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