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

Annotations already declare this is a non-readonly, non-idempotent, non-destructive mutation, so the safety profile is covered. The description adds the precondition that the notebook must be an existing one and clarifies that text is code/content, but says nothing about whether the new paragraph is auto-run, what happens if index is out of range, or where it lands 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?

The purpose sentence is front-loaded and the args block is scannable. The parameter lines largely restate bare schema titles, so a little of the text is low-value, but overall it is compact.

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?

An output schema exists, so return values need not be explained, and all four parameters are covered. Still, for a mutation tool with zero schema description coverage, the definition omits the insertion-position default, error behavior for missing notebooks, and its relationship to the batch/sibling tools.

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 load, and it does name and explain all four parameters, including that title and index are optional. However, the explanations are shallow: index is described only as "position index" without stating the default (append) behavior, and text's expected syntax (Python code vs markdown) is left ambiguous.

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 ("Add a new paragraph to an existing notebook"), which is clearly distinguishable from read-side siblings like list_paragraphs or get_paragraph. However, it never distinguishes itself from batch_add_paragraph, clone_paragraph, or move_paragraph, which are the closest alternatives.

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 guidance on when to use this versus batch_add_paragraph, clone_paragraph, or create_notebook. The only implied constraint is that the notebook must already exist, which comes from the phrase "existing notebook" rather than an explicit statement.

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

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

The annotations already establish that this is a non-read-only, non-idempotent, non-destructive mutation. The description adds important behavior beyond annotations: paragraphs are created sequentially in the given order, and one failing item does not stop the rest, with failures reported.

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 front-loaded with the core purpose and batch behavior, then supplies the key usage preference and partial-failure semantics. The Args block is compact and no sentence 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 two-parameter batch mutation tool, the description covers purpose, usage preference, sequencing, partial failure behavior, and parameter structure. An output schema exists, so return-value details need not be repeated in the description.

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 needs to carry parameter meaning. It lists both top-level parameters and the nested paragraph fields {text, title?, index?}, which compensates well for the schema gap. However, it does not explain the semantics of index or how ordering interacts with it, leaving a minor gap.

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 verb and resource: adding multiple paragraphs to a notebook in one call. It explicitly identifies itself as the batch version of add_paragraph and distinguishes that from the sibling single-item tool.

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 gives an explicit usage condition: prefer this over many add_paragraph calls when scaffolding several cells because it collapses N round-trips into one. The alternative tool is named directly, so the agent knows when to choose this versus add_paragraph.

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

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

Beyond the destructiveHint annotation, the description discloses that content is automatically backed up before deletion, that deletion is sequential, and that one failing item does not abort the batch — failures are reported in the result. These are precisely the behavioral traits an agent needs before invoking a destructive batch operation, and they are consistent with the annotations.

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 purpose and the key trade-off, then a compact Args block. Every sentence adds information; nothing is redundant.

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 destructive batch tool with an output schema, the description covers safety (backup), failure semantics (partial success, errors in result), and usage routing. Return-value detail is correctly left to the output schema.

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 parameter burden; it does document both params (notebook_id as the containing notebook, paragraph_ids as the IDs to delete). However, it omits array constraints such as maximum batch size, duplicate handling, or empty-list behavior, leaving gaps the schema does not fill.

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 verb and resource ("Delete multiple paragraphs") and explicitly frames itself as the batch counterpart of delete_paragraph. An agent can distinguish it from delete_paragraph and batch_update_paragraph without inspecting the 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 names the alternative explicitly ("Prefer this over many delete_paragraph calls") and gives the condition that selects it (collapsing N round-trips into one). The routing decision is fully spelled out.

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

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

Annotations already flag destructive=true and idempotent=false, but the description adds genuinely new behavioral facts: prior paragraph content is backed up, edits are applied sequentially against the previous result, per-paragraph atomicity (all-or-nothing), and that other paragraphs continue with failures reported. This is exactly the failure/side-effect model an agent needs before a destructive batch mutation.

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 what the tool is and how it differs from its sibling, then ordering, atomicity, and failure reporting each get one short sentence. No filler; the Args block is terse and every line carries distinct information.

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?

Output schema exists so return values need not be described, and the description covers the destructive-mutation concerns (backup, partial failure, ordering) that the annotations alone don't. Nothing an agent needs to invoke this correctly is missing.

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 load, and it does: it documents notebook_id and the edits array shape ({paragraph_id, old_string, new_string, replace_all?}) including the optional flag. It does not define replace_all semantics or its default of false, leaving that to be inferred from the schema title.

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 (find-and-replace edits on paragraphs) and immediately frames itself as the batch version of edit_paragraph, so the agent can distinguish it from that sibling without opening either schema. Scope ('across one or more paragraphs') is explicit.

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?

'batch version of edit_paragraph' plus 'several edits in one call' gives a clear condition for choosing this tool over the single-edit sibling. It never explicitly states the inverse (use edit_paragraph when you have a single edit) or any preconditions, so it stops short of a full when/when-not statement.

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

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

Annotations declare readOnly=false, idempotent=false, destructive=false; the description goes further, explaining sequential (not parallel) execution because cells share interpreter state, that N round-trips collapse to one, and how stop_on_error reports remaining paragraphs as skipped. It adds real value, but doesn't explain output size characteristics or what happens to already-run cells on failure.

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?

Purpose, usage, and execution semantics are front-loaded, and the Args block is consistently structured. Slight redundancy: the token-saving defaults are stated in prose and then repeated verbatim in the Args section, which costs a few lines.

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 six-parameter batch tool with no schema descriptions, the description supplies execution order, merge precedence, output truncation defaults, and error-handling policy. An output schema exists, so return-value detail is correctly not required.

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 full burden, and it does — every one of the six parameters is explained: runs with an inline example, the shared-vs-per-item params merge rule with precedence, repeatable paragraph_id for parameter sweeps, max_rows with 0=unlimited and header-row behavior, include_html, and stop_on_error defaults.

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 ('Run several paragraphs one after another in the given order, in a single call') and immediately contrasts with the sibling 'run_paragraph'. An agent can distinguish it from run_paragraph, run_all_paragraphs, and run_paragraph_async without opening the 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?

Explicitly names the alternative it replaces ('instead of many run_paragraph calls') and the condition that selects it ('when you need a specific sequence of cells run — e.g. setup cells before the cells that depend on them'). The ordering rationale is spelled out rather than inferred.

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

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

Beyond the annotations (destructiveHint=true, idempotentHint=true), the description discloses that previous content is automatically backed up, that updates run sequentially, and that a failing item does not abort the batch but is reported in the result. Those are exactly the risk/partial-success semantics an agent needs before invoking a destructive batch mutation.

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 purpose, then batching rationale, then failure semantics, then arguments — a clean information hierarchy. The Args block partly restates the schema's nested object shape, but that is justified by the 0% schema coverage.

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?

Covers scope, batching trade-off, backup behavior, partial-failure handling, and argument meanings; an output schema exists so return values need not be described, and the description still points at where failures surface. Nothing needed to call it correctly is missing.

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 load, and it does: notebook_id is identified as the containing notebook, and updates is described as a list of edits shaped {paragraph_id, text, title?}. It could still state whether title omission preserves the existing title, which is the one ambiguous case.

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 ("Update multiple paragraphs in one call") and immediately anchors it to its non-batch sibling ("batch version of update_paragraph"). An agent can distinguish it from update_paragraph and batch_edit_paragraph 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?

Explicit routing rules are given: prefer this over many update_paragraph calls when editing several paragraphs, and prefer batch_edit_paragraph for small targeted changes. Both the when-to-use and the when-to-use-something-else conditions are named.

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

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

Goes beyond annotations (which only give readOnly=false, idempotent=true, destructive=false) by disclosing merge semantics ('each config is deep-merged with that paragraph's existing config'), execution order (sequential), and partial-failure handling ('one failing item does not stop the rest; failures are reported in the result'). Those are exactly the behaviors an agent needs to predict outcomes of a batch mutation.

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-loads the purpose and the strongest usage guidance in the first three sentences, with prerequisites before the Args block. The Args block partially restates schema titles but adds real meaning; a little redundancy, no 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 mutation tool with an output schema and annotations present, the description covers merge behavior, prerequisites, ordering, and error semantics — enough to call it correctly. The only soft spot is that the per-item config schema is left to a sibling reference, requiring the agent to look up update_paragraph_config.

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 load: it documents notebook_id as the container and configs as a list of {paragraph_id, config}, and points to update_paragraph_config for the config dict shape (graph.mode, keys/groups/values). The nested ParagraphConfig is explained at the top level but the per-item config internals are deferred to a sibling rather than described inline.

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 ('Update visualization/chart config for multiple paragraphs') and immediately frames itself as the batch counterpart of update_paragraph_config. An agent can distinguish it from update_paragraph_config, batch_update_paragraph, and batch_edit_paragraph from the first sentence alone.

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?

Explicit routing guidance: 'Prefer this over many update_paragraph_config calls — it collapses N round-trips into one.' It also states a prerequisite (run each paragraph at least once first, or column index/aggr cannot be auto-filled) with the fallback behavior spelled out, so both when-to-use and when-not-to-expect-autofill are covered.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=false, so the mutation profile is known. The description genuinely adds the default naming/location behavior ('auto-generates a name in the source's parent folder'), but it does not disclose what a clone actually copies (paragraphs, config, permissions) or whether the source is modified.

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 behavioral summary is front-loaded in two short sentences, followed by a compact Args block. The Args block partly restates schema titles, but given 0% schema coverage that restatement is justified rather than wasteful.

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?

With only two parameters, complete param docs, and an output schema handling return values, the definition is usable. The remaining gap is what the clone contains and whether source permissions/collaborators carry over — material for a mutation tool with no destructive hint to warn about side effects.

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 parameter meaning and largely does: new_name is defined as a full path/name with a concrete example and an explicit default-behavior fallback. notebook_id's entry ('The notebook ID to clone') is thinner and adds little beyond the parameter name.

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 ('Clone an existing notebook') with the added nuance that renaming is optional, which cleanly distinguishes it from create_notebook. It never names or contrasts with the closest siblings (create_notebook, import_notebook, clone_paragraph), so differentiation is implied rather than explicit.

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?

Usage is only implied by the word 'clone' — the agent can infer you use it to duplicate an existing notebook rather than make a blank one. There is no explicit guidance on when to prefer this over create_notebook or import_notebook, and no stated prerequisites (permissions on the source).

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

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

The annotations already declare this is a mutating, non-idempotent, non-destructive operation. The description adds substantial behavioral detail: the copy is placed directly below the source, carries over code/title/visualization config, title gets a " (copy)" suffix, and untitled paragraphs remain untitled. It also discloses the internal read/create/config-copy sequence needed because Zeppelin has no dedicated clone endpoint.

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 front-loaded with the core action and behavior, then uses a short Args section. The implementation note about Zeppelin's endpoint limitation earns its place because it explains why the tool performs multiple internal steps in one call.

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?

An output schema exists, so return-value details need not be described. With annotations covering mutation safety and non-idempotency, the description supplies the remaining behavioral context an agent needs: copy placement, content carryover, title handling, and the internal multi-step implementation.

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 compensate for the two parameters. It lists notebook_id as the notebook containing the paragraph and paragraph_id as the paragraph to clone, which clarifies their roles but adds little format or validation detail. This is minimally adequate for two self-named IDs.

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 verb and resource: "Clone a paragraph within the same notebook." It also clarifies the copy location and what is carried over, so the operation is easy to understand. However, it does not explicitly differentiate this from sibling tools such as add_paragraph or update_paragraph.

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?

Usage is implied by the clone semantics, but the description does not explicitly state when to use this tool versus alternatives like add_paragraph or update_paragraph. It provides useful context that Zeppelin lacks a dedicated clone endpoint, but not when-not conditions or alternative routing guidance.

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

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

The annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is largely covered. The description adds that the notebook is empty and gives the path format, but it omits duplicate-path behavior, permission requirements, and whether parent folders are auto-created.

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 short and front-loaded, with the core action in the first sentence and the parameter explanation immediately after. The Args formatting is standard and does not add unnecessary bulk.

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?

An output schema exists, so return values do not need description coverage, and annotations cover safety traits. However, for a create operation the description still leaves important calling context unstated, including duplicate-path behavior and folder/path prerequisites.

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 explain the sole parameter, and it does: "Full path for the new notebook" with a concrete example containing spaces and nested path segments. It could still be more explicit about root-relative vs absolute path handling.

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 verb and resource: "Create a new empty notebook." The phrase "new empty" helps distinguish it from import_notebook and clone_notebook, but it does not explicitly name those alternatives.

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 does not say when to use this tool versus clone_notebook, import_notebook, or other notebook creation paths. There is also no guidance on prerequisites such as whether parent folders must exist.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is known. The description adds a useful non-obvious detail: content is automatically backed up before deletion, though it does not discuss permissions or backup retention.

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?

It is front-loaded and compact: one sentence for the operation, one for the backup behavior, then a short Args block. Every part contributes useful information, especially given the schema has no descriptions.

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?

With an output schema present, return values need not be explained, and annotations carry the safety profile. The description covers the operation, backup behavior, and both parameters, leaving only usage alternatives unaddressed.

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 is the only parameter documentation. It identifies both parameters and gives brief meaning, but does not specify ID formats, validation, or whether notebook_id must correspond to the paragraph's actual notebook.

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 verb and resource, 'Delete a paragraph,' which is immediately distinguishable from siblings such as batch_delete_paragraph and update_paragraph. The singular scope is clear without needing to open the 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 does not say when to use this tool versus batch_delete_paragraph or other alternatives, nor does it state any prerequisites or exclusions. Usage is only implied by the operation name itself.

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

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

Annotations already declare destructiveHint=true, and the description adds the crucial mitigating context that previous content is automatically backed up before changes. It also discloses failure-relevant behavior: the match must occur exactly once unless replace_all is set, and replace_all is the escape hatch for renames.

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 purpose and the sibling routing rule, then matching constraints, then per-parameter notes. Every sentence adds information an agent would otherwise have to guess, and nothing is repeated from the schema beyond parameter names that are then given meaning.

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 five-parameter destructive mutation with 0% schema coverage, this covers everything needed to call it correctly: routing versus siblings, exact-match and uniqueness requirements, backup behavior, and replace_all semantics. Return values are covered by the output schema, so their absence from the description is not a gap.

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 carries the full burden, and it documents all five parameters with real semantics — not just names. old_string and new_string get exact-match and uniqueness rules, replace_all gets a concrete use case (renames), and the two IDs are identified by role.

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 ('Replace an exact snippet of paragraph code') and immediately frames it as find-and-replace. It explicitly names the sibling update_paragraph and the boundary between them, so an agent can distinguish this from whole-paragraph rewrites without opening either 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 routing rule: prefer this over update_paragraph for targeted changes, use update_paragraph for whole rewrites. It also states the precondition for correct invocation (old_string must match exactly, copied from get_paragraph_code rather than get_notebook/get_paragraph because of 2-space indentation) and how to disambiguate repeated snippets.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful operational context by warning that output can be very large for notebooks with many paragraphs or large results.

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 short and front-loaded: purpose, warning, then the single argument. Every sentence adds useful information for invoking or interpreting the tool.

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 one-parameter read-only export tool with annotations and an output schema, the description covers the purpose, key warning, and parameter. Nothing essential for correct agent use is missing.

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 parameter meaning. It identifies the sole parameter as the notebook ID to export, but adds little beyond that label and does not explain ID format, source, or constraints.

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: export a notebook as JSON, and names migration/backup as the purpose. It is clear, but it does not explicitly distinguish itself from nearby siblings such as get_notebook, clone_notebook, or import_notebook.

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 gives clear usage context: cross-server migration or backup. It does not state explicit exclusions or alternatives, but the intended use case is understandable.

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

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

Read-only, idempotent, and non-destructive traits are already covered by annotations, so the description focuses on payload behavior: outputs are excluded and large-notebook reads should be narrowed first. It stops short of stating anything about response size limits, truncation, or pagination for very large notebooks, which would have earned a 5.

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 summary sentence, then a scope exclusion, then size-based routing advice, then the args block. Every sentence adds decision-relevant information and nothing is repeated from the schema beyond the parameter names needed for the mapping.

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?

An output schema exists, so return values need no explanation. With two parameters, one of which is fully elaborated, and clear sibling routing, an agent has everything required to select and invoke this tool correctly.

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, and it largely does: include_config is spelled out as adding visualization/chart config plus presentation flags (editorHide, runOnSelectionChange) with a stated default of False. notebook_id is left as a bare restatement, which is the only gap.

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 ('Get notebook overview') and enumerates exactly what is returned: paragraph code, titles, and status. It also explicitly bounds the payload by excluding paragraph output, which distinguishes it from get_paragraph without requiring the schema to be opened.

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?

Names alternatives and the conditions that select them: get_paragraph for output inspection, list_paragraphs first for large notebooks, then get_paragraph_code for targeted reads. This is explicit when-to-use/when-not-to-use routing against three named siblings.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description goes far beyond: it enumerates exactly which fields are hashed vs excluded (execution status, output, forms, chart configs, paragraph order) and explains that excluded fields do not flag the notebook stale. It also discloses the conditional response shape (match/diff on success, spec_note on failure) — behavior not visible in annotations.

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 purpose, then usage, then argument semantics — a sensible order with no filler sentences. The trailing 'Args:' block restates the schema's parameter names, but each entry adds operational meaning, so the small redundancy is justified rather than wasteful.

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 moderately complex tool with an output schema, the description covers everything an agent needs: what is compared, where the comparison happens, the two input modes, their precedence, and the conditional return fields. Nothing required to call it correctly is left unstated.

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 — and it does, documenting all four parameters with meaning the schema cannot convey: spec_path must live under $WIKI_DOCS_PATH, known_units is a per-paragraph sub-hash map, and known_* take precedence over spec_path. This fully compensates for the bare schema.

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: 'deterministic content fingerprint of a notebook, plus per-paragraph sub-hashes'. No sibling tool does fingerprinting, and the description immediately frames it as a 'cheap freshness check', so an agent can distinguish it from get_notebook or list_paragraphs without opening the 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 decision tree: preferred path is passing spec_path (server does the comparison), fallback is explicit known_fingerprint/known_units when there is no docs repo, and it states the precedence rule if both are supplied. It also names the anti-pattern ('never hand-compare hash maps'), which is exactly the guidance an agent needs.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that results are grouped into owners/writers/readers, which is useful context, but says nothing about failure modes, access requirements, or whether visibility is limited to the caller's own permissions.

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 sentence is front-loaded and precise with no filler. The Args block is boilerplate that merely restates the single parameter, costing a little space without adding information.

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?

An output schema exists and annotations cover the safety profile, so the description needn't explain return structure or side effects. With one documented parameter and a clear stated scope, an agent has enough to call it correctly; only caller-permission caveats are absent.

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 0%, so the description must carry the parameter, and it does identify notebook_id as the notebook to fetch permissions for. However, it adds no format, source, or constraint details beyond restating the parameter name, so it only barely compensates.

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 (get) and resource (notebook permissions) plus the exact categories returned (owners, writers, readers). It is distinguishable from the sibling set_notebook_permissions by being the read counterpart, though it never names that sibling explicitly.

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?

No explicit when-to-use or when-not-to-use guidance is given; usage is only implied by the read-only framing of the name. The natural pairing with set_notebook_permissions is left for the agent to infer from the sibling list rather than stated.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds meaningful beyond-annotation context: default truncation of table output to 50 rows, omission of HTML by default to save tokens, and the guarantee that the header row is always included.

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 key behavior and token-saving defaults are front-loaded, followed by actionable guidance and a clean args list. Every sentence adds practical value with no repetition.

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?

Given that an output schema exists and annotations cover the safety profile, the description is complete: it explains what content is returned, the default truncation behavior, and how to adjust parameters for fuller output.

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?

With 0% schema description coverage, the description fully compensates by documenting all four parameters, including defaults (max_rows=50, include_html=False) and the special semantics of max_rows=0 meaning unlimited.

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 names a specific verb and resource ('Get full content of a single paragraph') and enumerates what is included (code, output, dynamic forms, chart config, presentation flags), which distinguishes it from partial-content siblings like get_paragraph_code and get_paragraph_forms.

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 gives concrete situational guidance: set max_rows=0 when investigating data discrepancies, and include_html=True when the paragraph uses HTML rendering, plus a SQL alternative. It does not explicitly route between this tool and the content-specific siblings such as get_paragraph_code, so it is clear but not fully exhaustive on alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the useful disclosure that the payload omits outputs and forms, which explains the smaller response; it does not cover truncation or error behavior, but that is minor for a simple read.

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 routing guidance and the core verb are front-loaded in the first two sentences, and the Args block is short. No wasted prose.

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?

An output schema exists, so return shape needn't be spelled out, and the description covers scope, the alternative, and both parameters. A brief note on what happens with non-code paragraph types would round it out.

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 carries the burden and does list both parameters in an Args block. However the annotations are near-tautological ('The paragraph ID to retrieve'), adding little beyond the parameter names and types.

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 ('Get only the code/text content of a paragraph') plus an explicit exclusion ('without output or forms'), which separates it cleanly from get_paragraph and get_paragraph_forms among the many paragraph siblings.

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?

Names the alternative explicitly ('Use this instead of get_paragraph') and gives the condition that selects it ('when you only need to read the code') along with the reason (output size). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that it returns both form definitions and current parameter values, which is useful context, but adds little beyond that. Since the output schema also exists, a 3 is appropriate.

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 sentence is front-loaded and zero-waste, followed by a compact Args list. Efficient and well-structured, though the args phrasing is somewhat redundant.

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 read-only two-parameter tool with an output schema and annotations, the description covers the basics. It omits the relationship to the update counterpart and any hint of return shape, but those gaps are partially mitigated by the output schema and annotations.

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 compensate. The Args block names both parameters and briefly states what each ID refers to, but adds no format or scoping detail ('containing the paragraph', 'to inspect' are near-restatements). Minimal compensation for the coverage gap.

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 verb and resource: 'Get dynamic form definitions and current parameter values for a paragraph.' An agent can tell it inspects form definitions, not just paragraph content. It doesn't explicitly differentiate from the update_paragraph_forms sibling, so it falls short of a 5.

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?

No when-to-use context and no mention of the natural alternative update_paragraph_forms (read vs. write). The agent has to infer the intended usage from the name alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the async-polling context, which is useful, but says nothing about what the status values mean, whether results are cached, or how freshness works.

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 purpose sentence is front-loaded and the Args block is compact. The parameter notes lightly duplicate the schema titles, but at 0% coverage that duplication earns its place.

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?

An output schema exists, so return values needn't be spelled out. For a two-parameter read-only status check with annotations covering safety, the description supplies enough to call it correctly; only the semantics of the status values themselves is left implicit.

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 0% and the schema carries only bare titles, so the description is the sole source of parameter meaning. The Args block explains both parameters in terms of the notebook containing the paragraph and the paragraph to check, which is thin but meaningfully more than the schema titles 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 ('Get execution status of a specific paragraph'), which clearly separates it from siblings like get_paragraph (content) or list_paragraphs. It implies the distinction from run_paragraph_async via 'after async run' but never names the sibling explicitly.

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 parenthetical 'useful after async run' gives a clear triggering context, effectively routing agents to poll this after run_paragraph_async. There are no explicit exclusions or named alternatives, so it stops short of full when/when-not guidance.

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

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

Annotations already disclose that this is a non-read-only, non-idempotent, non-destructive operation. The description adds that the input must come from export_notebook and that renaming is optional, but it does not describe side effects such as whether import creates a new notebook, how name conflicts are handled, or permission requirements.

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 short and front-loaded: the core operation is stated first, followed by optional renaming and compact parameter notes. There is no redundant or filler text.

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?

An output schema exists, so return-value explanation is unnecessary. The description covers both parameters and the export/import pairing, but it omits conflict handling and permission expectations, leaving a small gap for an import mutation.

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 parameter meaning. It does so for both parameters: notebook_json is 'The full notebook JSON string from export_notebook' and new_name is an optional 'new name/path.' The only minor ambiguity is what 'path' means in new_name.

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 uses a specific verb and resource: 'Import a previously exported notebook JSON,' and notes the optional rename. It distinguishes the operation from generic creation by tying input to export_notebook, though it does not explicitly contrast with sibling tools like create_notebook or clone_notebook.

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 phrase 'previously exported notebook JSON' implies this should be used with output from export_notebook, giving an implicit usage context. However, there is no explicit when-to-use vs when-not guidance or named alternative tool selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful operational context about volume and filtering, but does not go beyond that in behavioral detail.

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 short, front-loaded, and structured with a compact Args section. Every sentence adds useful information without waste.

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 tool is simple, annotations cover safety, an output schema exists, and parameter behavior is well described. The main contextual gap is the lack of guidance distinguishing this tool from the sibling search_notebooks.

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?

Despite 0% schema description coverage, the description fully documents both parameters: name_filter is a case-insensitive substring match against the full path, and limit defaults to 100 with 0 meaning unlimited. This adds substantial meaning beyond the schema.

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 clearly states the verb and resource: list notebooks on the Zeppelin server. It does not differentiate the tool from the sibling search_notebooks, which is a meaningful omission for selection.

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 gives clear usage context: always use name_filter because the server may have thousands of notebooks. It does not explicitly say when to use this instead of search_notebooks or other alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuinely non-obvious interpretive context: what the inline markers mean ([editor visible], [runs on selection change]) and that unmarked paragraphs are properly finalized, including the underlying field logic (editorHide, runOnSelectionChange). It does not cover ordering or pagination, but the marker legend is substantial added value.

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 core purpose in the first sentence, then the marker legend, which is dense but every clause carries semantic meaning. The trailing Args block largely duplicates the schema and is the only wasted space.

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?

An output schema exists and annotations carry the safety profile, so the description needn't enumerate return values; it instead supplies the one thing the schema can't — how to read the inline flags. Combined with the stated scope exclusion, nothing an agent needs to call and interpret this correctly is missing.

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% and the sole parameter is only restated ('notebook_id: The notebook ID to list paragraphs for') without format, example, or what happens for an unknown/foreign notebook. Because there is only one obvious scoping parameter, the gap is small — minimum-viable rather than deficient.

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 (list) and resource (paragraph metadata) with the enumerated fields (index, id, title, status) and an explicit scope exclusion ('without code or output'), which separates it from siblings like get_paragraph_code and get_paragraph_forms. An agent can tell what this returns without opening the 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?

The 'without code or output' phrasing implicitly routes the agent to the get_paragraph_* siblings when full content is needed, but there is no explicit 'use this when / use X instead' statement, nor any mention of prerequisites or when listing is preferable to fetching a single paragraph. Usage is inferable, not stated.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the same-notebook scoping constraint, but omits key mutation behavior: whether other paragraphs' indices shift, what happens if new_index is out of range, and whether permissions are required.

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?

One front-loaded sentence gives the action and scope, followed by a compact args block for the three parameters. No filler, no restatement 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?

An output schema exists, so return values need not be described. However, for a reordering mutation with three required params, the description leaves unresolved what happens to sibling paragraph positions and what errors to expect, which an agent would want before calling.

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 carries the full burden — and it does document all three parameters, including the genuinely additive detail that new_index is 0-based. It stops short of stating the valid range or how out-of-range values are handled, so it doesn't fully compensate for the coverage gap.

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 concrete verb and resource ('Move a paragraph') and adds a meaningful scope constraint: the move happens 'within the same notebook.' This is enough to distinguish it from siblings like update_paragraph or edit_paragraph, which modify content rather than ordering, though the description never explicitly names an alternative.

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?

Usage is only implied — an agent infers it should call this to reorder paragraphs. The 'same notebook' phrase implicitly rules out cross-notebook moves, but there is no explicit when-to-use/when-not statement and no mention of when a move would fail or be rejected.

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

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

Annotations declare a non-read-only, non-destructive, non-idempotent operation, and the description adds real context beyond that: it blocks until completion and uses the async job endpoint specifically to preserve chart/visualization settings. It stops short of saying what happens on partial failure (abort vs. continue).

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 tight sentences plus a short Args block; the core action is front-loaded in the first line and every sentence earns its place by adding execution semantics or parameter detail.

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?

An output schema exists, so return values need no explanation, and the description covers the blocking behavior and the visualization-preservation rationale. The one gap is failure semantics for a multi-paragraph run, which an agent would want before invoking.

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 carries the full burden, and it does document both parameters — notebook_id as the target notebook and params as an optional dict of dynamic form values with a concrete example. It could go further on how params keys map to form field names.

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 verb and scope: 'Run all paragraphs in a notebook and wait for completion.' The 'all paragraphs' phrasing implicitly distinguishes it from the single-paragraph siblings (run_paragraph, run_paragraph_async), though it never names them explicitly.

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?

Usage is only implied through the word 'all' and the note about the async job endpoint; there is no explicit 'use this instead of run_paragraph when...' guidance, nor any mention of prerequisites such as notebook permissions or how this relates to batch_run_paragraph.

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

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

Annotations only declare the non-read-only, non-idempotent, non-destructive profile; the description goes well beyond that by disclosing token-saving truncation defaults (50 rows, HTML omitted), the header-row guarantee, the async-endpoint behavior, and crucially that errors return error output that should be examined before retrying. It stops short of noting that executing a paragraph may have side effects on notebook data or what permissions are required.

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 purpose followed by a clean Args block, and every sentence carries information. The only waste is mild duplication: the max_rows/include_html behavior is explained once in prose and again in the Args block, and the 'On error' note is buried mid-paragraph rather than surfaced.

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?

An output schema exists, so return-value explanation is correctly omitted, and the truncation/error behavior is covered. The remaining gap is routing: with 30+ siblings including several run variants, the definition doesn't help an agent decide that this is the right execution tool for a single paragraph.

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 carries the full burden and does so: every one of the five parameters is documented in the Args block, including the non-obvious semantics of max_rows (default 50, 0 = unlimited, header always included) and include_html (converted to plain text), plus a concrete example for the dynamic params dict.

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 ('Run a paragraph and return the result') and adds real scope information: it uses the async job endpoint and preserves chart/visualization settings. However, it never distinguishes itself from close siblings like run_paragraph_async, batch_run_paragraph, or run_all_paragraphs, which is especially confusing given it claims to use the 'async job endpoint'.

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 gives good conditional guidance for parameters ('Set max_rows=0 for unlimited rows when you need full results for analysis', 'Set include_html=True to see HTML output'), which implies usage contexts. But it says nothing about when to choose this tool over the many sibling run/status tools, leaving the core selection decision to inference.

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

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

Adds real behavioral context beyond annotations: execution is non-blocking and requires a poll-with-get_paragraph_status workflow, and chart/visualization settings are preserved automatically — a useful side-effect disclosure for a non-idempotent execute tool. It does not cover permissions or concurrency limits, which is the remaining gap.

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 core behavior and the immediate follow-up workflow in the first two sentences; the Args block is compact and, given 0% schema coverage, each line earns its place.

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?

Given an output schema exists, return values needn't be described, and the description supplies the async lifecycle (start → poll status → read results) an agent needs to use it correctly. Minor omissions are auth requirements and what a failed run looks like, but the definition is usable as-is.

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 carries the full burden and largely does: it explains notebook_id and paragraph_id as identifiers and clarifies that params is an optional dict of dynamic form values with a concrete example ({"city": "Seoul"}). That example goes meaningfully beyond the bare anyOf object in the schema, though the format of the IDs themselves is unstated.

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 paragraph execution') plus the defining behavioral distinction ('return immediately without waiting for results'), which is exactly what separates it from the synchronous run_paragraph and batch_run_paragraph siblings. An agent can pick this over its look-alikes without opening either 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 usage scenario ('run multiple paragraphs in parallel') and names the correct follow-up tools (get_paragraph_status, get_paragraph) as the alternatives for polling and retrieving output. It stops short of stating when NOT to use it (e.g. use run_paragraph for a single blocking call), leaving that inference to the agent.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds that max_results=0 means unlimited, which is behaviorally useful, but says nothing about case sensitivity, ranking/ordering of results, or which paragraph content is indexed. Given annotation coverage, a 3 is appropriate.

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?

One sentence plus a short Args block; front-loaded with the purpose and free of filler. The Args block largely restates schema field titles, which is modest waste.

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?

An output schema exists, so return-value shape need not be described. However, for a search tool the description omits what is searched (markdown source, code, outputs), how results are ordered, and how max_results interacts with result ranking — gaps an agent must guess at.

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 carries the full burden. It clarifies that 0 means unlimited and that the default is 20 — genuinely beyond the schema — but 'query: Search query string' is a tautology with no syntax, operator, or scope information, leaving a real gap.

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 (full-text search) and resource (notebook paragraphs) with scope 'across all notebook paragraphs', which implicitly distinguishes it from list_paragraphs and get_paragraph. It does not explicitly name or contrast with those siblings, keeping it at a 4.

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 never says when to use this instead of list_notebooks, list_paragraphs, or get_paragraph, nor what kind of queries it suits (exact phrase, fuzzy, code search). An agent must infer the selection criteria from the tool name alone.

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

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

Annotations declare readOnlyHint=false and idempotentHint=true, but the critical behavioral question for a permissions setter — does this replace the full ACL or merge with existing grants — is never answered. Callers must also guess whether passing empty lists revokes access, a consequence with real blast radius that destructiveHint=false does not disambiguate.

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?

One-sentence summary front-loaded, followed by a compact Args block — standard and efficient. The parameter lines are mostly restatements of schema titles, so a few sentences don't fully earn their place, but nothing is bloated.

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?

An output schema exists so return values need no explanation, and annotations cover the safety profile, but for a five-parameter mutation tool, the absence of replace-vs-merge semantics and the optionality of runners leaves the definition materially incomplete for correct 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%, so the description must carry the load. It does name all five parameters and their role semantics (owner/write/read/runner), which adds meaning beyond bare titles, but it omits that runners is optional and defaults to null, and gives no format guidance for usernames.

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: "Set permission information for a notebook." The name plus description makes it clearly distinguishable from the read-only sibling get_notebook_permissions, though the description itself never names that sibling explicitly.

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?

No guidance on when to use this versus get_notebook_permissions, no prerequisites (does the caller need to be an owner?), and no warning about when not to call it. The agent is left to infer that this is the write counterpart to the read tool.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, and the description is consistent with that mutation profile. The description adds the motivating scenario (long-running/stuck queries) but says nothing about the resulting paragraph state, whether partial output is preserved, or the effect of stopping an already-stopped paragraph.

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 purpose sentence is front-loaded and the args block is compact with no filler. The Args section is conventional boilerplate that carries little weight but wastes no space.

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?

Output schema exists so return values need not be explained, and the safety profile comes from annotations. Still, for a cancel operation the description omits post-condition behavior (does the paragraph end in an error/idle state, are results kept), which an agent would want when deciding to interrupt a query.

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 compensate, and it does minimally by explaining that notebook_id identifies the containing notebook and paragraph_id identifies the target paragraph. This is essentially a restatement of the parameter titles plus light context, not deep semantics like ID formats or where to obtain them.

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: "Stop a running paragraph", which clearly contrasts with run_paragraph, run_paragraph_async, and run_all_paragraphs in the sibling set. It stops short of naming any sibling explicitly, so it is clear but not maximally differentiated.

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?

"Use this to cancel long-running or stuck queries" gives a concrete triggering condition rather than leaving usage implicit. It does not state when not to use it or what happens if the paragraph is already idle, but the positive guidance is strong for a simple tool.

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

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

Annotations already declare non-read-only, idempotent, and destructive, and the description adds genuine context beyond them: previous content is automatically backed up before changes, and the call replaces the whole text rather than patching it. It stops short of describing failure modes (e.g. mismatched notebook_id/paragraph_id) or what the response contains, but the destructive-safety picture is materially improved.

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 full-replacement vs. snippet distinction is front-loaded in the first two sentences, which is the highest-value information. The Args block is slightly redundant with the schema field names but earns its place given zero schema description coverage.

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?

An output schema exists, so return values needn't be described, and the description covers replacement semantics, backup behavior, and the sibling routing rule. For a four-parameter mutation tool it is nearly self-sufficient, missing only error/ID-consistency behavior.

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 load, and its Args block documents all four parameters — including that title is optional and that text is the full new content. It doesn't specify ID formats or whether notebook_id must match the paragraph's actual notebook, leaving a small gap.

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 ("Update paragraph code/text") and immediately distinguishes itself from the closest sibling, edit_paragraph. An agent can tell which of the two paragraph-modification tools to reach for without opening either 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?

Explicitly names the alternative (edit_paragraph) and the condition that selects it: small targeted changes should use edit_paragraph because it sends only the changed snippet. That is a real when-to-use decision rule, not vague guidance.

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

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

Annotations declare idempotentHint=true and destructiveHint=false, and the description genuinely adds beyond that: it discloses that changes are deep-merged into the existing config rather than replacing it, and that columns are passed through unchanged when no saved output exists. Missing only permission/authorization context and failure modes.

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-loads purpose, then merge semantics, then the auto-fill caveat, then a structured Args block with an example. Slightly verbose in the auto-fill explanation but every sentence carries actionable information; nothing is 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?

An output schema exists so return values needn't be described. Given a nested free-form config object, the description supplies the merge model, the accepted enum values, an example payload, and the output-dependency prerequisite — everything needed to call it correctly on the first try.

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 carries the full burden and does: it explains each of the three params in an Args block, clarifies that only 'name' is needed for column entries because index/aggr are auto-filled, and enumerates the valid graph.mode values plus a worked example for the free-form config object.

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?

Opens with a specific verb and resource: 'Update paragraph visualization/chart config (graph type, columns, display settings)'. An agent can distinguish it from update_paragraph or update_paragraph_forms, though it never explicitly names those siblings to route away 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?

Gives a concrete prerequisite: the paragraph must have saved output from a prior run, otherwise index/aggr auto-fill cannot happen — which implicitly routes the agent to run_paragraph first. It does not mention the batch sibling (batch_update_paragraph_config) as an alternative for multi-paragraph edits.

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

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

Annotations already declare non-read-only, idempotent, non-destructive, so the description doesn't need to repeat safety. It adds genuinely new behavioral context: the paragraph is not re-executed and chart settings survive the update. It omits permission requirements and what happens with invalid/unknown keys in params.

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 purpose statement followed by a short Args block; no filler. Minor redundancy between "Update dynamic form values" and "change form parameters", but each sentence still carries information.

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?

An output schema exists, so return values need no explanation, and all required params are described. Given the nested free-form params object, a pointer to the sibling that lists valid form keys would close the remaining gap.

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 0%, so the description must compensate, and the Args block does document all three parameters with role descriptions for notebook_id and paragraph_id plus a concrete example for the free-form params dict. It does not say where valid key names come from (presumably get_paragraph_forms), leaving the nested object partly opaque.

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 ("Update dynamic form values") and adds a differentiating constraint ("without re-executing the paragraph"), which separates it from run_paragraph and update_paragraph. The second line reinforces the scope: changing form parameters while preserving chart settings.

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?

"Safest way to change form parameters when chart settings must be preserved" gives a clear condition for choosing this tool over re-running or reconfiguring the paragraph. It stops short of naming explicit alternatives (e.g. update_paragraph_config) or stating when not to use it.

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