adhoc_message_send

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

With no annotations, the description carries the full burden. It discloses a key side effect: setting is_learning_related=true will persist a SessionEvent. It also mentions free conversation limitations, but it does not describe other behavioral traits such as deduplication via client_message_id, return values, or error conditions.

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 three sentences and front-loaded with the primary purpose. Every sentence adds operational information: the thread context, free-form nature, rich content encoding, and learning-related behavior. No redundant phrases.

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 6-parameter tool with nested objects and no output schema, the description covers the core use case well: response mechanism, rich content, and learning flag. It lacks explicit alternative comparison (live vs adhoc) and details about client_message_id deduplication, but the schema compensates for parameter-level details.

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 67% (4/6 parameters have descriptions). The description adds semantic context for is_learning_related (SessionEvent) and explains the payload shorthand, but it does not elaborate on content or thread_id beyond what the schema already implies. This adds marginal value over the schema.

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 clearly states the tool's purpose: the agent responds to users in an AdHoc thread. It distinguishes from siblings like live_message_send by explicitly specifying the AdHoc thread context and noting that it supports free conversation not limited by move_type.

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 indicates when to use the tool (for agent responses in AdHoc threads) and provides guidance on rich content via payload and learning-related flag. However, it does not explicitly name alternatives or state when not to use it (e.g., in live sessions), so it stops short of full exclusionary guidance.

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