Set iFood cart payment

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

Annotations already establish that this is a read-only=false, destructive write. The description adds meaningful behavioral context beyond annotations: the operation is gated and does not charge, which is important for an AI agent deciding whether this action has financial consequences. This exceeds what the structured annotations alone provide.

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 two short, front-loaded sentences with no filler. Every word adds value: 'gated' signals a precondition, 'cart write' identifies the resource and mutation, and 'does not charge' prevents a critical misunderstanding.

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 no output schema, the description explains the core intent and a key non-effect (no charge), and the explicit_user_intent schema property covers gating. But it lacks prerequisites, return behavior, and explicit relationship to sibling tools like checkout or list_payment_methods, leaving some invocation context incomplete.

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%; only explicit_user_intent has a schema description. The description does not explain cart_id, payment_method_ids, response_format, or the intent-gating requirement beyond the schema. 'Gated' hints at explicit_user_intent, but most parameter semantics are left undocumented.

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 phrase 'Gated cart write. Does not charge.' clearly identifies the operation as a write to a cart's payment method and explicitly distinguishes it from charging/checkout behavior. The specific resource ('payment method') is only implied by the name and title, but combined with the context this is sufficiently clear.

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 'Gated' wording implies that explicit user intent is required before invoking this write, and 'Does not charge' implies it is intended for cart configuration rather than checkout. However, there is no explicit when-to-use vs. when-not-to-use guidance, and no alternative tools are named.

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