interactions_create_response

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

Annotations only indicate readOnly=false, openWorld=true, idempotent=false, destructive=false. The description adds critical behavioral details: the 3-second hard deadline, one-time-only callback, token scoping for 15 minutes, and auth characteristics. It explains side effects (message acknowledged or returned) and failure modes, going far beyond the annotations.

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 well-structured with bold headings (Purpose, 3-SECOND DEADLINE, Auth, etc.) and every sentence provides distinct value. It is compact given the complexity, front-loads the purpose, and avoids redundancy with the schema.

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 interaction response tool, the description covers purpose, deadline, auth, alternatives, type enum, and return values. It is fully self-contained for an agent to select and invoke it correctly, even with the rich schema and sibling context.

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?

Although schema covers all 5 parameters, the description enriches semantics by listing all INTERACTION_RESPONSE_TYPE values (including 6,7,8 which the schema omits) and clarifying the data shape depends on type. It also elaborates on interaction_token as a scoped credential, adding context beyond the schema's field descriptions.

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 starts with a clear, specific verb+resource: 'Send the initial response to an interaction (slash command, button, modal submit, etc.)'. It explicitly distinguishes this from follow-up interactions by naming interactions_edit_original_response and interactions_create_followup as alternatives, making it distinct from sibling 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?

Provides concrete usage guidance: the 3-second deadline, and if more time is needed, instructs to respond with type=5 and follow up via specific tools. It clarifies the initial callback may be sent once, giving an explicit when-to-use and when-to-defer strategy.

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