notebook_run

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

With no annotations, the description carries the full burden and does disclose one important side effect: 'replay' *silently* rebuilds state from cell 0 first, which tells the agent about hidden re-execution. It omits other key traits such as whether the call blocks or returns asynchronously (the existence of run_status/run_cancel siblings hints at async but is never stated), permission requirements, and the fact that outputs are written back to the .ipynb by default.

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?

Two sentences, front-loaded with the core action, then a compact enumeration of the modes. Every clause carries information and nothing is padding.

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 an 8-parameter execution tool with no annotations and no output schema, the description covers the most important behavioral axis (kernel state per mode) but leaves the agent guessing about blocking vs async execution, timeout behavior, backup/write-back defaults, and the optimistic-lock hash. Adequate but with clear gaps.

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 100%, so the baseline is 3, but the description adds genuine meaning the schema cannot: it explains the runtime semantics of resume/replay/full rather than just listing enum values. It leaves 'auto', cell_selector, create_backup, write_outputs, timeout_seconds, and expected_content_hash entirely to the schema, which limits it below a 5.

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+resource ('Execute notebook cells') and immediately distinguishes three execution strategies by their kernel-state semantics. It does not explicitly name the sibling tools it differs from (notebook_edit, notebook_read), but the action is unambiguous enough that an agent can separate it from them.

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 mode semantics imply when each is appropriate ('resume' keeps live state, 'replay' rebuilds from cell 0, 'full' re-runs everything), which is useful implied guidance. However, it never states when to choose one over another, what 'auto' resolves to, or when to pair the call with notebook_run_status/notebook_run_cancel for long executions.

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