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

Annotations only flag mutation/non-idempotent/non-destructive; the description adds the non-obvious server-driven state machine, the 'added' vs 'question_pending' status values, and the requirement to reuse session_key. It stops short of describing duplicate-add behavior, error modes, or other return fields, which matters since no output schema exists.

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-loads the core purpose and then uses bullets that each carry procedural weight. It is fairly long and dense with no quick-scan summary line, but almost no sentence is 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?

For a complex 10-param, nested-object, stateful tool with no output schema, the description covers the critical loop and status outputs well. It leaves out what a successful 'added' response returns (cart contents, next step), which the absent output schema would otherwise need to carry.

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 already 100%, but the description adds genuine value by clustering parameters by call mode (first-add set vs. answer set with answer={field_id, value}). It does not explain oddities like why all 10 params are non-required.

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 ('Add a product to the live booking cart') and immediately disambiguates the dual purpose ('OR answer a booking question'). This cleanly separates it from siblings like bk_cart_checkout and bk_cart_promo.

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?

Explicitly prescribes the two modes: omit session_key for a first add with a listed param set, or supply session_key + pending_token + answer to resolve a pending question. It also directs the agent to source product_id/operator_id/quoted_price from bk_operator_availability, leaving little to inference.

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