Tip a Rappi order

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the charge behavior is partly carried. The description adds real value beyond annotations: the FAIL-CLOSED semantics (defaults to refusing unless explicit conditions met), the personal-token auth requirement, and reinforcement that explicit_user_intent must be true. This is context the structured fields cannot express. No contradiction with annotations — destructiveHint=true aligns with "Charges a tip."

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?

Three tight fragments — "FAIL-CLOSED. Charges a tip. Requires mutations, explicit_user_intent, and a personal token." — with the most critical behavioral warning (fail-closed) front-loaded. Every element earns its place; there is no filler or repetition of the title.

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 destructive, money-moving mutation with no output schema, the description under-delivers. It does not state what happens on success or failure, whether the tip is the final charge, or how errors surface. With two of four params undocumented in both schema and description, an agent lacks enough to safely invoke a financial write end-to-end.

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 25% (one of four params documented), so the description must compensate but does not. It never explains the meaning of tip (currency? inclusive?), order_id, or response_format. The only parameter value added is "Requires explicit_user_intent," reinforcing the schema's own documentation of that field. With a low-coverage schema and a monetary amount parameter, this is a genuine gap.

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 states a specific verb plus resource — "Charges a tip" — which unambiguously names the action and target. It is clearly distinct from siblings like rappi_rate_order, rappi_cancel_order, and rappi_place_order, though it never names them explicitly. The leading "FAIL-CLOSED" is a behavioral note rather than a purpose statement, so the purpose itself is clear but not differentiated by reference.

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 gives prerequisite conditions (requires mutations, explicit_user_intent, personal token) which inform when the tool can be invoked, but it provides no guidance on when to prefer this tool over alternatives and no exclusions. Nothing tells the agent to use rappi_rate_order or rappi_get_order instead in any scenario. Prerequisites are useful, but active tool-selection guidance is absent.

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