components_v2_send

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

Beyond the annotations, the description discloses pre-send validation via validateComponentsV2, the VALIDATION_FAILED rejection with no API call, the irreversible IS_COMPONENTS_V2 flag, and the two-phase approval flow with payload_hash, one-time approval_id, expiry, and confirmation parameters. This is rich, actionable behavioral context.

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 longer than average, but every paragraph earns its place and the bold headers make it highly scannable. The complexity of the confirmation flow justifies the additional length, and key facts are front-loaded.

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?

The description covers purpose, usage boundaries, validation behavior, the exact two-phase confirmation sequence, and the return payload. Combined with the input schema and output schema, an agent has everything needed to invoke this tool successfully.

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 83%, so the schema already explains most parameters. The description adds value by explaining how __confirm, __confirm_id, and __confirm_hash work together as part of the review-then-confirm flow, and by noting that components are validated before sending. This goes beyond mere parameter repetition.

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 opens with a specific verb and resource: 'Send a Components V2 message - rich layout (Container, Section, MediaGallery, ActionRow, ...)'. It also calls out mutual exclusivity with content/embed/poll/sticker, which clearly distinguishes it from sibling messaging tools.

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?

There are explicit 'When to use' and 'When NOT to use' sections. It names messages_send as the correct alternative for simple text replies, giving an agent concrete routing guidance with no ambiguity.

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