send_message

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

Annotations only tell us this is a mutation (readOnlyHint=false); the description supplies the behavioral detail the annotation lacks: queuing vs. starting a turn, the Codex-only steer restriction, and that model/effort changes persist to later continuations (with per-runtime caveats). It says nothing about what the call returns or failure handling, which is a moderate gap.

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 key mode behavior is front-loaded, but the second half is a dense parenthetical chain of runtime-specific caveats (Codex/Claude Code, '預かって届けるときから') that is hard to parse. Every claim is relevant, but the packaging costs readability.

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 mutation tool with no output schema, the description covers the important state transitions and the side effects of changing model/effort. What an agent gets back and how errors surface are not covered, which is the main remaining hole.

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 50%, and the description compensates well: it defines the meaning of mode values including the default, and explains that profile/model/effort change the model for this request onward, with model and effort taking precedence (matching the schema notes). Only message and threadId, which are self-evident, go unexplained.

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 opening clause names a specific verb and resource: sending a message/request into a conversation. It is clearly distinct from siblings like start_session or read_session, though it never explicitly names an alternative tool.

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?

It spells out how mode="auto" behaves (queue on a running conversation vs. start a new turn on a stopped one) and when mode="steer" applies (interrupting a running turn, Codex only). It stops short of routing between this tool and siblings such as start_session or wait_events.

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