grocy_stock_product

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.