send_message

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

No annotations are provided, so the description carries the full burden. 'Send' implies a write/mutation action, but the description doesn't disclose whether sending succeeds silently, whether there are rate limits, what happens on failure (e.g., if the thread index is stale), or any side effects on the conversation state. The dry_run parameter hints at preview behavior but the description doesn't explain it.

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 a single concise sentence with no wasted words. However, it's arguably under-specified given the complexity of three targeting modes; 'appropriate size' for this tool would warrant a bit more detail about targeting precedence. It's clean but minimal.

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 4-parameter mutation tool with no annotations and no output schema, the description is too terse. It doesn't explain the dry_run flag, how targeting modes interact or which takes precedence, error behavior, or return semantics. Sibling tools like start_conversation and comment_on_post create ambiguity that the description fails to resolve.

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 0%, and the description adds essentially no parameter detail beyond the schema itself. It names the three targeting mechanisms (thread, URL, index) at a high level but doesn't explain the relationship or precedence between `index`, `thread_url`, and the open-thread mode, nor the meaning of `dry_run`. For a 4-parameter tool with zero schema coverage, this is insufficient.

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 'Send a message in the currently open thread, a thread URL, or by conversation index' which clearly identifies the verb (send) and resource (message) with three targeting methods. However, it doesn't distinguish from sibling tools like start_conversation or comment_on_post, and a message could be confused with posting content. The purpose is clear on what it does but not why it exists versus alternatives.

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 explains the three target methods (open thread, URL, index) which half-serves as usage context, but gives no guidance on when to pick this over start_conversation (for new conversations vs existing ones) or how the targeting precedence works when multiple are provided. No exclusions or alternatives are named.

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