patch_one_time_product

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

With no annotations, the description must disclose behavioral traits. It does state that the operation is create-or-update and is disabled in read-only mode, adding some context. However, it doesn't mention potential side effects like overwriting existing fields, permission requirements, or what happens when the product doesn't exist beyond implied creation.

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

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

The description is extremely concise: two short sentences, front-loaded with the primary purpose. No filler words; every phrase adds value. The note about read-only mode is relevant and placed appropriately.

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 complexity (5 params, nested product object, output schema exists), the description is minimal but covers the core semantics. It doesn't explain the use of update_mask or regions_version, but those are documented in schema. The output schema covers return values. It is adequate but lacks context like common use cases or how to differentiate from similar patch operations.

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

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

The schema has 100% parameter description coverage, so the baseline is 3. The description adds no extra meaning about parameters beyond saying 'patch is create-or-update', which relates to the update_mask semantics but doesn't add detail not already in the schema. It fulfills the baseline without enhancing it.

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

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

The description clearly states the purpose: 'Create or update a one-time product' with an explicit note that 'patch is create-or-update'. This is a specific verb+resource and distinguishes from sibling patch tools like patch_in_app_product or patch_subscription by naming the resource and clarifying upsert semantics.

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 choose this tool over alternatives is provided. The description does not mention when to use this versus list_one_time_products or patch_in_app_product, nor any prerequisites or exclusions. The only extra note, 'Disabled in read-only mode', is a condition, not usage guidance.

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