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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive write, so the bar is lower; the description adds real value beyond that with auth scope requirements and the 403 failure mode for unclaimed sandbox workspaces. It does not disclose whether duplicate observations are rejected or what the call returns, which is the remaining gap.

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

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

Front-loaded with the core action and purpose in the first clause, followed by two compact caveat sentences. The prerequisite sentences are dense but each carries non-obvious operational information; nothing reads as filler.

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

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

Covers purpose, prerequisites, and the failure mode for a tool with 11 parameters and no output schema. What's missing is small but real: no mention of the return payload (created observation id) or what happens when an observation can't be matched to a catalog item.

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

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

Schema description coverage is 100%, so the schema already documents all 11 fields including the nested `raw` object, so baseline 3 applies. The description adds only the framing that the record feeds catalog matching (which motivates gtin/external_id), without any per-parameter syntax or default 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 ('Record one competitor price observation by hand') plus the downstream purpose (matching against your catalog). It also implicitly separates itself from the automated collection path ('the cycle usually collects these itself'), though it never names the sibling tool (run_commerce_cycle / contribute_price_data) 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?

Gives a clear usage context: use this for one-off manual entry, since it notes the cycle normally collects observations itself. It also lists two concrete prerequisites (Last Price credential with commerce configure scope, claimed workspace), but offers no explicit 'do not use when' rules or named alternatives.

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