notebook_save

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the write-but-not-destructive profile is already covered. The description adds the useful facts that the payload must be nbformat 4 JSON and that the file lands in the SQL folder, but it never explains what happens when a file with the same name already exists, despite an overwrite parameter.

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?

A single front-loaded sentence with no padding; the verb and resource come first and the qualifiers follow. It is appropriately sized, though terse enough that it underspecifies rather than over-explains.

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 mutation tool with a nested-object parameter, an undocumented overwrite flag, no param descriptions, and no output schema, the description is too thin. An agent lacks the information needed to call it safely when an existing file is present.

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%, so the description must carry the burden, but it only indirectly clarifies the notebook parameter's format (nbformat 4 JSON). The name parameter and the overwrite flag, including its default of false, are left entirely unexplained.

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?

Names a specific verb (save) and resource (notebook), and adds format (nbformat 4 JSON) and destination (.ipynb in the SQL folder), which lets an agent distinguish it from notebook_run or notebook_open. It does not, however, differentiate it from closely related siblings like notebook_files or sql_editor_save_file.

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?

There is no statement of when to use this tool versus alternatives such as notebook_files or notebook_open, nor any precondition guidance. Usage must be inferred entirely from the name and the mention of the SQL folder.

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