Chat Start

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

With no annotations, the description carries the full burden and does so: it discloses server-side execution independent of call outcome, both return statuses and their meaning, the ~20-30s polling guidance, double-generation prevention via already_running, the ~30-minute pollability window, and the no-replay rule after source_add/chat_configure. This is unusually rich behavioral context.

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 core purpose is front-loaded in one sentence and the return shapes are bulleted for scannability. It is on the long side, but nearly every clause carries actionable information (timeouts, polling interval, retention window), so little is wasted.

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 background-task tool with no annotations, the description covers the full lifecycle an agent needs: when to use it, what it returns, how to poll, how long results persist, and how repeated asks behave. Output schema exists, yet the description still usefully explains status semantics that a schema alone would not convey.

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. It does partially by stating parameters mirror chat_ask's ask path and that history/suggest_followups are chat_ask-only, but it never explains notebook, question, references (lite/full enum), source_ids, or conversation_id semantics. Some compensation, but a real gap remains.

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 sentence states a specific verb (start) and resource (chat ask) plus the key behavioral fact (detached background task, returns immediately). It explicitly contrasts itself with chat_ask and chat_status, so an agent can distinguish it from siblings 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?

It states exactly when to use this tool (generation may run long; remote transports cut blocking calls at ~60s of silence) and names the alternative for the opposite case ('For questions expected to answer quickly, chat_ask stays the one-call path'). It also directs the agent to chat_status for collection, which is the required follow-up.

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