Add to Rappi cart

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

Annotations already mark destructiveHint=true and readOnlyHint=false, so the write nature is known. The description adds the gating requirement (RAPPI_ALLOW_MUTATIONS and explicit_user_intent) and states it does not checkout, which provides additional context. However, it doesn't reveal other side effects (e.g., whether it replaces existing cart items) or response behavior.

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 just two sentences and contains no fluff. It avoids wordiness and is short, but the content is too sparse to fully inform. For conciseness alone, it earns a high mark, though the structure could be improved by front-loading the actual action.

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 mutating tool with 5 parameters and no output schema, the description omits crucial context: what the operation does, when it should be used, and what responses to expect. It doesn't even state it adds to cart, nor does it explain how it relates to other cart operations, making it incomplete for an agent.

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 only 20% (only explicit_user_intent has a description). The description itself provides no parameter details, leaving product_id, quantity, store_id, and response_format unexplained. With low schema coverage, the description should compensate but does not.

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 says 'Gated write' but never states that the tool adds a product to the cart. The title 'Add to Rappi cart' suggests the action, but the description itself is vague and does not clearly specify the operation (e.g., 'Adds a product to the cart'). It only mentions it does not checkout, which is a distinction but not a clear purpose.

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?

The description states preconditions (RAPPI_ALLOW_MUTATIONS=true, explicit_user_intent=true) and clarifies it does not checkout, but it does not guide when to use this tool over siblings like rappi_update_cart_item, rappi_reorder, or rappi_place_order. No explicit reasoning for choosing this tool is provided.

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