update_preference

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

With no annotations present, the description carries the full behavioral burden and does substantial work: it discloses persistence semantics ('so the next purchase can reuse it'), a structural constraint ('Persist structured data only'), and a fidelity guardrail ('Never invent fields the owner did not confirm'). It falls just short of 5 because it never clarifies whether updating merges with existing preferences or replaces them.

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 sentences, zero waste, with the action and primary triggers front-loaded. Every sentence earns its place: purpose+triggers, exclusion, post-clarify routing, and data-fidelity constraints. No redundancy with the schema.

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 write tool with a fully unconstrained nested object and no output schema, the description covers the critical invocation decisions: when to persist, when not to, and what must never be written. The remaining gaps — allowable category values and an example data shape — are meaningful but the description is complete enough for the common onboarding and lasting-rule flows.

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 compensate. It adds meaning to `data` via 'Persist structured data only' and 'Never invent fields the owner did not confirm,' and it illustrates `category` with three concrete rule examples. However, it never defines the valid category vocabulary or the expected shape of the data object, leaving the agent to guess for an unconstrained additionalProperties 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?

The description opens with a specific verb+resource pair — 'Update stored preferences for a category' — and anchors it with concrete trigger examples («всегда 2.5%», «не покупай Whiskas», «размер 50»). It clearly distinguishes itself from the read-side sibling get_user_preferences and from sibling save_delivery_address, so an agent can select it without 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?

Explicit when-to-use conditions are stated: after a lasting rule or after the onboarding phrase. It also gives an explicit when-not: 'Do not use for one-off orders,' and a routing rule for clarify answers that should stick. This is the strongest possible usage guidance for an agent deciding between one-off versus durable persistence.

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