Notebook Query Start

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

With no annotations, the description carries the full burden of behavioral disclosure. It clearly states that the tool returns immediately with a query_id rather than waiting for the result, and that the result must be obtained by polling notebook_query_status. This is strong transparency, though it does not mention error behavior or side effects beyond asynchronous execution.

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 compact, front-loaded with the core purpose, and every sentence contributes: when to use it, timeout guidance, return behavior, and the follow-up workflow. There is no filler or redundant restating of the tool name.

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?

The description provides a complete mental model for the agent: why this tool exists, when to prefer it, what to expect upon invocation, and how to retrieve the eventual result. The presence of an output schema further reduces the need to describe return values in prose.

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?

Input schema coverage is 100%, so the schema already documents all parameters meaningfully. The description reinforces the timeout guidance from the schema, but it does not add substantive new parameter-level semantics beyond that.

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 a specific action (start an asynchronous query), a target use case (source-heavy notebooks or long questions), and a clear resource (notebook). It also distinguishes itself from sibling tools by naming notebook_query and notebook_query_status and explaining the async vs. polling relationship.

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 explicitly says to use this tool instead of notebook_query when the response may exceed the 120-second budget, and it provides a suggested 180-second timeout for source-heavy notebooks. It also gives a terse workflow: notebook_query_start -> notebook_query_status.

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