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

Goes well beyond the annotations: values are printed verbatim on images and persist for every later set, an empty value removes a fact, the call is free, and it returns 'the product with updated facts and missingFacts' (valuable since there is no output schema). This is consistent with the supplied readOnlyHint=false, idempotentHint=true, destructiveHint=false profile while adding persistence and cost context the annotations cannot express.

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

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

Front-loaded with what gets written and where the keys come from, then the constraint, cost, and return. The example payload is genuinely useful for the nested facts object, but the single run-on opening sentence could be split for readability.

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

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

No output schema exists, yet the description states the return shape (product plus missingFacts) and covers the nested facts object's key/value rules and deletion sentinel. What remains thin is the downside of not answering: it says images are made without those numbers, but not whether facts can be corrected later or which downstream calls re-print them.

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%, and the description compensates by explaining that fact keys come from missingFacts[].key, giving concrete key examples (dimensions, pack-count, key-ingredients), and defining the empty-string sentinel as deletion. The credentials example shows value formatting verbatim. product_id semantics are only implied by the return statement, not described in the description itself.

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?

Specific verb+resource: 'Saves product facts the person knows' plus a correction mode ('corrects a fact read from the label'). It anchors key naming to 'missingFacts[].key from create_product', which tells an agent exactly which keys this tool expects, though it never names edit_product as the nearest sibling for non-fact edits.

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?

Clear when-to-use: fill facts that create_product reported as missing, or fix a label-derived fact. It also states the fallback path ('Never make values up: ask the person, or skip (images are then made without those numbers)'), giving an explicit alternative to calling the tool with invented values, though it doesn't spell out when to prefer edit_product instead.

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