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

With no annotations, the description carries the full burden. It adequately discloses the unique name constraint, placement semantics, and the special `run='stale'` behavior that executes cells and returns results. However, it does not mention potential side effects like saving or error handling.

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 concise, with three sentences that front-load the purpose and efficiently cover key behaviors. No redundant or irrelevant 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?

Given the tool has 7 parameters and no output schema, the description provides reasonable coverage but lacks return value details for non-stale runs and does not address error conditions or prerequisites. It is adequate but not thorough.

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. It covers `name`, `after`, `index`, and `run` meaningfully, but fails to explain `path`, `source`, and `cell_type` beyond their default values, leaving gaps for 3 of 7 parameters.

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 'Add' and the resource 'cell', and provides details on naming and placement. However, it does not explicitly differentiate from sibling tools like 'update_cell' or 'remove_cell', but the purpose is unambiguous.

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 explains placement options and the `run` parameter behavior, which gives context for when to use this tool. However, it lacks explicit guidance on when not to use it or when to prefer alternatives (e.g., 'update_cell' for modifications).

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?

No annotations provided, so description must disclose behavior. It reveals that the tool creates a new empty notebook and enforces a path uniqueness constraint. However, it does not detail return values, error handling, or side effects beyond the constraint. Adequate but not thorough.

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?

Single sentence, front-loaded with action and resource, no filler. Efficiently conveys core purpose and a critical constraint.

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?

Tool has 2 parameters, an output schema, and 14 siblings. The description covers the primary parameter and precondition, but ignores kernel_name and return value behavior. Output schema may compensate, but without seeing it, the description feels slightly incomplete for a creation tool.

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 description should compensate. It adds meaning for the 'path' parameter by noting the requirement that the path must not exist yet. However, the 'kernel_name' parameter is not mentioned, leaving its purpose to the schema alone. Partial coverage, baseline 3.

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?

Description clearly states verb 'create', resource 'notebook', and specifies the location via path. The constraint 'must not exist yet' adds precision and distinguishes it from update or overwrite operations. Sibling tools like add_cell or run do not create notebooks, so purpose is unambiguous.

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?

Description implicitly states when to use: to create a new notebook at a given path, and explicitly states the precondition that the path must not already exist. While it does not list alternatives, the creation action is distinct enough that an agent can infer usage context.

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?

With no annotations, description fully owns disclosure. It specifies how different data types are handled (dataframes->CSV, figures->images, else repr), which is good transparency.

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?

Single sentence that efficiently conveys the core purpose and behavior. Could be broken into clearer sections, but no 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?

Lacks parameter details and no output schema. However, it covers return behavior well. Adequate but not fully complete given the tool's complexity.

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 has 0% description coverage; description does not explain what 'path' and 'variable' mean, nor the timeout. It adds no semantic value beyond the parameter names and default.

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?

Clearly states it inspects a live kernel variable, listing specific attributes (type, shape, schema/columns, length, Jupyter repr). Distinct from all sibling tools which are cell or notebook operations.

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?

Mentions 'without adding a cell' implying lightweight inspection, but does not explicitly state when to use this tool versus alternatives or 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.

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

With no annotations, the description carries full burden. It discloses key behaviors: kernel state survives and interrupted cells become stale. However, it does not mention permissions, side effects, or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no fluff, front-loaded with the main action. Every word adds value.

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 the output schema exists, return values are covered, but the description lacks parameter explanations. It adequately describes the tool's core functionality but misses details needed for proper 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 should explain parameters. It does not mention 'path' or 'clear_queue' at all, leaving their purpose unclear despite somewhat self-explanatory 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 clearly states the tool interrupts the currently running cell and cancels queued cells, which is a specific action. It distinguishes itself from siblings like 'run' and 'restart_kernel' by mentioning kernel state survival.

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 implies usage for interrupting a running cell and contrasts with restart_kernel by noting that kernel state survives, but it does not explicitly compare with other siblings or state when to use this tool over 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?

No annotations are provided, so the description carries the full burden. It only discloses the two positioning options (after, index) but fails to mention side effects, prerequisites, or mutation behavior (e.g., does it require kernel, affect other cells?). The note about empty string for after moving to top is helpful but insufficient.

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 a single sentence with no fluff, front-loaded with the verb 'Move'. Every word earns its place, making it highly efficient.

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 5 parameters (3 required), no annotations, and no schema descriptions, the description is incomplete. It does not explain the required parameters (name, path, expected_rev) or the output schema, leaving the agent with significant unknowns 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?

With schema description coverage at 0%, the description adds meaning for the 'after' and 'index' parameters (e.g., '' moves to top), but ignores the required parameters 'name', 'path', and 'expected_rev', which remain unexplained. It partially compensates but leaves gaps.

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 'Move' and the resource 'cell', and specifies two distinct ways to specify destination ('after' an existing cell or to an 'index'), which clearly distinguishes this tool from sibling tools like add_cell, remove_cell, or update_cell.

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 implies usage for reordering cells but does not explicitly state when to use this tool versus alternatives like add_cell or update_cell, nor does it provide exclusions or context for 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.

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

With no annotations provided, the description carries full burden. It adds useful context about the output (deterministic fallbacks for summaries) but does not disclose other behavioral traits like idempotency, cost, or side effects. The read-only nature is implied but not stated.

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 very concise: two sentences plus a brief note. It is front-loaded with the core purpose, follows with usage guidance, and adds a nuanced detail about fallbacks. No unnecessary words.

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 (documenting return values), the description focuses on what is not obvious from the schema: the content of each line, dependency edges, and lint findings. It is mostly complete for a read-only overview tool, though parameter explanation 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%. The tool description does not explain the two parameters ('path' and 'refresh_summaries') beyond what the schema provides (type and default). This leaves the agent guessing about the meaning and usage of parameters.

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 tool provides an index of the notebook with per-cell details and additional features like dependency edges and lint findings. It also positions itself as the starting point when opening a notebook, distinguishing it from sibling tools like read_cells or search_cells.

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 includes 'Start here when opening a notebook,' which gives clear usage context. However, it does not explicitly state when not to use this tool or name specific alternatives, leaving some ambiguity.

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?

No annotations are provided, so the description carries full burden. It discloses that charts are attached as images and that the tool reads cells, implying read-only behavior. However, it lacks explicit statements about non-destructiveness, permissions, or side effects, which would be expected for a read operation.

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 concise with two front-loaded sentences. The first sentence states the purpose, and the second explains the selection and view options. No redundant or unnecessary words.

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 the tool has 4 parameters and no output schema, the description covers selection methods and view modes adequately. It could mention handling when both 'names' and 'indices' are provided or error cases, but it is sufficiently complete for a read operation in the context of 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?

The schema has 0% description coverage, but the description adds meaningful context for three of four parameters: 'names' (list of cell names), 'indices' (Python slice string), and 'view' (full/code/outputs). The required 'path' parameter is not explained in the description, but overall the description provides sufficient guidance 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 tool reads cells with code and condensed outputs, including charts as images. It distinguishes from sibling tools like run, add_cell, and search_cells by its specific read-only purpose and selection methods.

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 explains how to select cells (by names, indices, or whole notebook) and the view parameter options, but does not provide explicit guidance on when to use this tool vs. alternatives like search_cells or summarize_cells. Usage context is implied rather than explicitly 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?

Discloses that deletion depends on a revision and can be undone. With no annotations, this covers key behavioral traits. Could mention what happens on invalid rev or full side effects.

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, no fluff. Every word earns its place. Information is front-loaded (action first, then requirements).

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 core behavior and a key constraint, but lacks explanation of 'name' and 'path' parameters, return value (output schema exists), and error scenarios. Brief but leaves gaps for a 3-param tool.

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?

Only 'expected_rev' is hinted at via 'current rev'; 'name' and 'path' are not described. Schema coverage is 0%, and the description does little to explain these parameters' meaning or format.

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?

Clearly states 'Delete a cell' – a specific verb and resource. Distinguishes from sibling tools like add_cell, update_cell, move_cell.

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 mentions prerequisite ('requires its current rev') and provides alternative/recovery via 'undo with undo_last'. Provides clear guidance on when and how to use.

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?

Discloses destructive effects (state loss, stale cells) clearly. No annotations present, so description bears full burden and handles it well.

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?

Single sentence that is front-loaded with key action and consequences. No superfluous words; highly efficient.

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?

Core action and outcome are covered, and an output schema exists. However, the missing parameter description leaves a gap in completeness.

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%, but the description does not explain the 'path' parameter at all. The agent must infer its meaning from context, risking misuse.

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?

Clearly states the action ('restart') and resource ('kernel') with immediate consequences. Distinguishes from sibling tools like interrupt by specifying state loss.

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?

Implies usage for resetting state via consequences, but no explicit when-to-use or when-not-to-use guidance compared to alternate tools like interrupt.

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?

Despite no annotations, the description fully discloses behavior: outputs persisted, charts as images, background continuation on timeout, and the effect of fresh_deps on cell dependencies. No hidden side effects.

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 a single paragraph that front-loads the main action. It is detailed but not overly verbose; every sentence contributes. However, it could benefit from bullet points for readability.

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 complex tool with 6 parameters, no output schema, and no annotations, the description covers all key behaviors, edge cases (background execution, fresh ancenstors), and references monitoring/interrupt tools, making it self-sufficient.

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 adds significant meaning for cells, quiet, fresh_deps, and wait_seconds. However, timeout_seconds is not explained, and path is not described (though self-explanatory).

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 tool's purpose: 'Execute cells on the notebook's persistent kernel.' It distinguishes default behavior (stale cells) from explicit cell execution, and contrasts with sibling tools like interrupt, read_cells, and notebook_overview.

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?

Provides explicit guidance: default for minimal recompute, with cells for specific execution, fresh_deps to control ancestor pass, quiet to collapse outputs, and background behavior with wait_seconds. References sibling tools for monitoring and stopping.

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?

No annotations are provided, so the description must disclose behavioral traits. It states that the tool returns 'matching cells with the matching lines', which is straightforward. However, it does not explain what 'condensed outputs' means or whether the operation is read-only or has side effects.

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 concise at two sentences, front-loading the purpose. Every sentence provides value without extraneous 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?

Despite having an output schema, the description lacks explanation for parameters and does not clarify the structure of results beyond 'matching lines'. Given the complexity of the tool (3 parameters, 0% schema coverage), the description is insufficient for complete understanding.

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?

The schema has 0% description coverage, and the tool description does not explain any of the three parameters (path, query, regex). An agent cannot determine the meaning of 'path' or the format of 'query', making the tool difficult to use correctly.

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 specifies the verb 'search' and the resource 'cells', and details what is searched (sources, names, summaries, condensed outputs). It distinguishes this tool from siblings like 'read_cells' or 'summarize_cells' by focusing on searching across cell content.

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 does not provide any guidance on when to use this tool versus alternatives (e.g., 'read_cells'). It lacks context on prerequisites, limitations, or conditions that would help an agent decide.

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?

No annotations are provided, so the description must convey behavioral traits. It mentions 'LLM' hinting at AI-generation, but does not state that the tool is read-only, does not modify cells, or require special permissions. Important behavioral context (e.g., latency, non-destructive nature) is missing.

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 concise with two sentences, front-loading the main purpose in the first sentence. However, it could be more structured (e.g., using bullet points) to improve skimmability, and the second sentence appears slightly fragmented. Overall, no wasted words.

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 three parameters and an existing output schema, the description is incomplete. It does not cover the 'path' or 'names' parameters, nor does it describe the output structure (what the 'detailed summaries' contain). Error handling, limitations (e.g., notebook size), and return fields are absent, leaving an agent underinformed.

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?

The input schema has 0% description coverage, so the description must compensate. It explains that include_outputs controls whether cell output summaries are included, but it does not describe the 'path' or 'names' parameters. For example, it does not clarify that 'names' likely refers to cell identifiers. The output schema exists but is not described, leaving gaps.

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 tool provides 'detailed summaries (LLM): per-cell description plus, optionally, a summary of each cell's current output.' It specifies the verb (summarize) and resource (cells), and hints at a cheaper alternative to reading full cells, which differentiates it from read_cells. However, it could more explicitly distinguish from sibling tools like notebook_overview.

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 mentions 'Cheaper than reading full cells when orienting in a large notebook,' giving implied context for when to use it. However, it does not explicitly state when not to use it or name specific alternatives, leaving some ambiguity for an AI 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?

No annotations exist, so description must fully disclose behavior. It discloses the core action but does not mention effects when no prior mutations exist, idempotency, or any destructive side effects. Minimal transparency.

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?

Single sentence, no waste. However, it could include more detail without losing conciseness. Still, it is efficient and directly states the tool's function.

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 the lack of annotations and parameter documentation, the description does not provide sufficient context for safe usage. No mention of return values from output schema, prerequisites, or edge cases.

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 description fails to explain the required 'path' parameter. The user is left to infer that path refers to the notebook, but no explicit meaning or constraints are provided.

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?

Description states 'Restore the notebook to its state before the most recent mutation.' This is a specific verb (restore) and resource (notebook state) with clear scope. It distinguishes itself from sibling tools like add_cell or remove_cell which are mutations.

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?

Implies usage for reverting the last mutation, but does not explicitly state when to use or provide alternatives. Given the tool name and context, it's adequately implied but lacks explicit 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?

With no annotations provided, the description discloses important behaviors: updating source clears outputs, marks the cell and dependents stale, and `run='stale'` triggers execution. Missing details include behavior for rename-only updates and consequences of incorrect `expected_rev`.

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 concise: two sentences plus a code snippet. It front-loads the purpose and then details side effects and special parameters. Slightly verbose with the code snippet, but overall efficient.

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 6 parameters, no output schema, and no annotations, the description covers the main purpose, side effects, and locking, but lacks details on error cases, return values (except for `run`), and the `path` parameter. Gaps remain for a full understanding.

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?

The description explains `expected_rev` and `run` parameters with specific behavior, but does not clarify `path` and `name` (required params) or `source` and `new_name` beyond the main purpose. With 0% schema description coverage, the description partially 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?

The description clearly states the tool's purpose: 'Replace a cell's source and/or rename it.' It identifies the specific verb (replace/rename) and resource (cell), and distinguishes from siblings like add_cell or remove_cell.

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 provides context on when to use the tool, such as requiring `expected_rev` for optimistic locking and the `run` parameter for immediate execution. However, it does not explicitly state when not to use it or mention alternative tools.

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