chat_start

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

No annotations are provided, so the description carries the full behavioral burden and does so richly: the task runs server-side regardless of the call's fate, duplicate asks return already_running without double generation, a finished ask is never replayed and re-asking appends a new turn, and payloads stay pollable ~30 minutes before reporting unknown. This is exactly the lifecycle and side-effect information an agent needs and cannot get from structured fields.

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?

Front-loaded with the one-sentence purpose, then organized into a rationale paragraph and bulleted return states. It is long, but every section (timeout rationale, status semantics, poll window) carries information the agent needs given the absence of annotations, with minimal filler.

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 detached async tool this is nearly complete: it covers start, dedup, polling cadence, and payload expiry, and even describes return shapes despite an output schema existing. The one real gap is that the five input parameters remain semantically unexplained, which slightly undercuts completeness for invocation.

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% across 5 parameters, so the description must compensate but largely does not. It only notes that parameters mirror chat_ask's ask path and that history/suggest_followups are chat_ask-only; it never explains notebook, question, references (the lite/full enum), source_ids, or conversation_id, leaving the agent to guess from the schema alone.

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 specific verb and resource (start a chat ask) plus the defining trait (detached background task, returns immediately). It explicitly separates itself from chat_ask (the one-call path) and chat_status (the collector), so an agent can choose correctly without opening any schema.

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?

Gives an explicit when-to-use: generation that may run long, with the concrete trigger (1-3 min notebooks, ~60s transport silence killing a blocking chat_ask). It names the alternative and the condition that selects it ('for questions expected to answer quickly, chat_ask stays the one-call path'), then prescribes the follow-up (poll chat_status with task_id in ~20-30s).

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