Api chat sessions message create

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

Annotations already declare readOnlyHint=false, idempotentHint=false, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description earns credit for disclosing the SSE streaming return, which is materially useful for an agent (it must handle a stream, not a JSON object), but omits auth needs, what happens on failure mid-stream, and whether the message mutates session state.

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?

One short, front-loaded sentence with no filler. Terseness is a virtue here structurally, though the brevity is what creates the content gaps noted elsewhere.

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?

There is no output schema, so the description should explain the SSE stream (event types, termination signal, error frames) — it does not. It also fails to explain how the message payload is transmitted given a schema with only `id`. For a non-idempotent, open-world, streaming mutation tool, this leaves the agent under-equipped to call it correctly.

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% for the single required parameter `id`, and the description does not clarify that it is the chat session identifier. Worse, the description promises to 'send a message' yet the schema has no field for message content and sets additionalProperties=false, leaving the agent with no documented way to supply the actual message text.

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?

States a concrete action ('Send a message') and a return characteristic ('streaming SSE response'), but never says what a message is sent to — the chat session linkage only exists implicitly in the tool name. It doesn't differentiate from siblings like chat_sessions_create or chat_agent_runs_create. Purpose is inferable but not self-contained.

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?

No when-to-use guidance, no prerequisites (e.g., must the session already exist? must it be in a particular state?), and no named alternative among the many chat_* siblings. The agent must guess whether this starts a conversation, continues one, or triggers an agent run.

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