Добавление в корзину

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

Описание раскрывает важное неочевидное поведение: при превышении доступного остатка возникает CART_QUANTITY_CONFLICT, корзина не записывается, количество не уменьшается автоматически. Это существенно дополняет аннотации readOnlyHint/destructiveHint, которые не говорят о семантике ошибок и отсутствии частичного применения.

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?

Описание компактное, в три коротких предложения, без воды. Сначала входные данные, затем обязательные параметры и связность с другими вызовами, потом критичное поведение при ошибке и инструкция по восстановлению. Ключевые предупреждения размещены в конце и обоснованы.

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?

Описание покрывает обязательные входные данные, межзависимость с grocery_stores/grocery_cart/grocery_checkout и сценарий конфликта, поэтому агент может корректно вызвать инструмент. Есть выходная схема, поэтому описание не должно объяснять возвращаемое значение. Небольшой вычет за формальное расхождение с input-schema: в описании app_id/point_id обязательны, но схема помечает их как необязательные с default.

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?

При 0% описания в схеме, описание компенсирует это: указана структура items = JSON [{id, count}, ...], обязательность app_id/point_id и источник их значения — grocery_stores(). Однако id не связан явно с источником товаров, например grocery_search, а остаток countAvailable только упомянут без пояснения, где его получить.

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?

Описание называет конкретное действие — «Добавить товары в корзину» — и явный объект (корзина), что позволяет отличить его от grocery_cart и grocery_checkout. Однако явного противопоставления близкому саблингу grocery_set_cart нет, поэтому различение с саблингами неполное.

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?

Даётся ясный контекст: app_id/point_id надо брать из grocery_stores(), они обязательны, и тот же магазин нужен для grocery_cart и grocery_checkout. Также описан сценарий повторного вызова после конфликта. Нет явного «когда не использовать» и сравнения с альтернативами вроде grocery_set_cart или grocery_plan_order.

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