Allows debugging of Observable Notebook Kit notebooks, enabling AI assistants to inspect values, view errors, and capture canvas output from notebooks running in a web browser.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Observable Notebook Kit Debug MCP Server List all values in the notebook"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for debugging Observable Notebook Kit notebooks.
Enables AI assistants to inspect values, view errors, and capture canvas output from notebooks running in a web browser. For a fully working example, see ./example.
The Observable Desktop is really cool, but it had some limitations. For one, okay, so I paid Anthropic some money for Claude Code, but it's not the right Anthropic integration to be able to configure an API key in the app, so I'm out of luck. And I was trying to get some WebGPU experiments running, but the app didn't have access to a WebGPU context. So one thing led to another, and I wrote a quick MCP server to exfiltrate values from notebooks running in the browser.
Related MCP server: Chrome DevTools MCP
npm install @rreusser/mcp-observable-notebook-kit-debugIn your vite.config.js:
import { defineConfig } from "vite";
import { observable, config } from "@observablehq/notebook-kit/vite";
import { debugNotebook } from "@rreusser/mcp-observable-notebook-kit-debug";
export default defineConfig({
...config(),
plugins: [debugNotebook(), observable()],
});vite -c vite.config.jsAdd to your .mcp.json:
{
"mcpServers": {
"Notebook": {
"command": "mcp-notebook-kit-debug",
"args": []
}
}
}Note that you might need an absolute path to the mcp-notebook-kit-debug bin, and you might be using opencode or some other tool, so this step could vary a bit.
You can now use an agent like Claude Code to poke and prod at notebooks running in a web browser, inspecting values and even capturing canvas output as images.
These tools interact directly with the Observable runtime's reactive graph.
Tool | Description |
| List all named values in the Observable runtime's reactive graph |
| Get a value from the runtime by name; returns images for Canvas/SVG elements |
| Get multiple values at once (snapshot of runtime state) |
| Get metadata: state, type, dependencies (inputs), and dependents (outputs) |
| Get the dependency graph showing how values depend on each other |
| Set an input widget's |
| Evaluate an expression with access to all notebook variables |
These tools interact with the browser/DOM context, outside the Observable runtime.
Tool | Description |
| Execute JavaScript in the browser (has DOM access but NOT Observable runtime) |
| Get content from a DOM element by CSS selector; captures canvas/SVG as images |
| Simulate a mouse click at a position or on an element |
| Simulate a mouse drag from start to end position |
| Simulate mouse hover at a position, triggering hover states and tooltips |
| Simulate a mouse wheel scroll at a position |
| Simulate keyboard input to an element |
These tools manage notebook connections and debug sessions.
Tool | Description |
| List all connected notebooks (use when multiple notebooks are open) |
| Set a default notebook for subsequent commands (when multiple are connected) |
| Refresh the page and wait for notebook initialization |
| Navigate a notebook to a different URL (e.g., switch from notebook-a to notebook-b) |
| View console logs from the current session |
| Get all errors (DOM-reported and values in rejected state) |
When multiple notebooks are open in different browser tabs, you can target a specific notebook using the notebook parameter on any tool:
# By path (without .html extension)
notebook: "index"
notebook: "second-notebook"
# By index
notebook: "0"
notebook: "1"
# By URL
notebook: "http://localhost:5173/"If multiple notebooks are connected and you don't specify which one, the tool will return an error listing the available notebooks.
Use ListNotebooks to see all connected notebooks with their URLs and indices.
The Navigate tool allows you to navigate an open notebook to a different URL, or open a URL in your default browser if no notebooks are connected:
// If no notebooks are connected, opens URL in default browser
Navigate({ url: "http://localhost:5173/index.html" })
// Navigate to a different notebook (relative URL)
Navigate({ url: "/second-notebook.html" })
// Navigate using absolute URL
Navigate({ url: "http://localhost:5173/second-notebook.html" })
// Navigate a specific notebook (when multiple are open)
Navigate({ url: "/second-notebook.html", notebook: "index" })
// Skip waiting for page load (useful if target page doesn't have debug plugin)
Navigate({ url: "/some-page.html", wait_for_completion: false })Behavior:
No notebooks connected: Opens the URL in your OS default browser
One notebook connected: Navigates that notebook's browser window to the new URL
Multiple notebooks connected:
Navigates the focused notebook (if you've used FocusNotebook)
Navigates the specified notebook (if notebook parameter provided)
Returns an error listing all notebooks (if no focus is set and no notebook specified)
The tool waits for the new page to load and initialize, similar to Refresh, and reports any errors that occur during initialization.
Values in an Observable notebook can be in one of three states:
fulfilled: The value has been computed successfully
pending: The value is still being computed (e.g., async/Promise)
rejected: The computation threw an error
The GetValue and GetValues tools return state information along with the value or error.
GetValue automatically returns images inline for:
Canvas elements: Captured as PNG
SVG elements: Rendered to canvas and captured as PNG
No need to save to files - images are returned directly in the MCP response.
Use RuntimeEval to evaluate expressions in the Observable runtime context with access to all notebook variables. The body must use a return statement.
// Compute derived values from notebook variables
RuntimeEval({ body: "return number * 2 + rangeValue" })
// Filter or transform data
RuntimeEval({ body: "return data.filter(d => d.value > 0)" })
// Multi-statement expressions
RuntimeEval({
body: `
const doubled = number * 2;
const added = doubled + rangeValue;
return { doubled, added };
`
})
// Persist the result as a named variable for later retrieval
RuntimeEval({
name: "myResult",
body: "return number * 2"
})Dependencies are auto-detected from the expression. If name is provided, the result persists in the runtime and can be retrieved with GetValue. If name starts with _tmp_, it is automatically deleted after the value resolves.
Use SetInputValue to programmatically change the value of interactive input widgets created with Inputs.* (e.g., Inputs.range, Inputs.select, Inputs.text). This sets the widget's .value property and dispatches an input event, triggering reactive updates to dependent values.
// If the notebook has: slider = Inputs.range([0, 100])
SetInputValue({ name: "slider", value: 50 })
// If the notebook has: dropdown = Inputs.select(["A", "B", "C"])
SetInputValue({ name: "dropdown", value: "B" })Simulate mouse events for testing interactive visualizations:
MouseClick: Click at coordinates or on an element (supports left/middle/right buttons)
MouseDrag: Drag from start to end position with configurable duration
MouseHover: Hover at a position, dispatching mouseenter/mouseover/mousemove events
MouseWheel: Scroll at a position with deltaX/deltaY
All mouse tools accept an optional selector parameter to target a specific element, with coordinates relative to that element.
Use SendKeys to simulate keyboard input:
// Type plain text
SendKeys({ keys: "hello world" })
// Use special keys with braces
SendKeys({ keys: "{Enter}" })
SendKeys({ keys: "{Tab}" })
SendKeys({ keys: "{ArrowDown}" })
// Modifier combinations
SendKeys({ keys: "{Ctrl+a}" }) // Select all
SendKeys({ keys: "{Ctrl+c}" }) // Copy
SendKeys({ keys: "{Shift+Tab}" }) // Reverse tab
// Target a specific element
SendKeys({ selector: "#my-input", keys: "typed text{Enter}" })
// Hold modifiers for all keys
SendKeys({ keys: "abc", modifiers: { shiftKey: true } }) // Types "ABC"Supported special keys: {Enter}, {Tab}, {Escape}, {Esc}, {Backspace}, {Delete}, {Insert}, {Space}, {ArrowUp}, {ArrowDown}, {ArrowLeft}, {ArrowRight}, {Home}, {End}, {PageUp}, {PageDown}, {F1}-{F12}.
© 2026 Ricky Reusser. MIT License.
Execute JavaScript in the browser context. Has access to the DOM but NOT the Observable runtime. Use RuntimeEval instead when you need access to notebook variables. Useful for DOM inspection, computed styles, or browser APIs.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | JavaScript code to execute. The result of the last expression is returned. | |
| label | No | Optional label describing the intent of this action (e.g., "expand plot", "zoom in"). Displayed in the notebook's event log overlay. | |
| notebook | No | Target notebook (URL, path like "index" or "voronoi", or index like "0"). Optional if you've used FocusNotebook or only one notebook is connected. | |
| timeout_ms | No | Maximum time to wait in milliseconds |
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 discloses key access boundaries (DOM access, no Observable runtime) and typical safe use cases. It does not explicitly warn about mutating page state or side effects, but 'Execute JavaScript' strongly implies arbitrary code execution, so this is a meaningful but not complete disclosure.
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?
Three short sentences, front-loaded with the core action, followed by the key limitation, the alternative, and use cases. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an arbitrary-JS tool with no output schema or annotations, the description covers purpose, environment boundaries, alternative tool routing, and typical use cases. The schema covers parameter details and the return behavior of the code parameter, so the main gap is a missing explicit note about potential page mutation/side effects, which is somewhat implied by 'Execute JavaScript'.
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 100%, so baseline 3 applies. The description adds environment context relevant to the code parameter but does not elaborate on label, notebook, or timeout_ms beyond what the schema already documents.
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: 'Execute JavaScript in the browser context.' It also explicitly differentiates from RuntimeEval by noting it does NOT access the Observable runtime, making sibling distinction immediate and clear.
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 routes the agent to RuntimeEval when notebook variables are needed, and identifies concrete use cases: DOM inspection, computed styles, and browser APIs. This gives both a when-to-use and a when-not-to-use/alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Focus on a specific notebook. When multiple notebooks are connected, this sets which one receives commands by default. Use ListNotebooks to see available options.
| Name | Required | Description | Default |
|---|---|---|---|
| notebook | Yes | Target notebook (URL, path like "index" or "voronoi", or index like "0") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose the central trait: this is a state-changing operation that alters default command routing. However, it doesn't cover failure modes for invalid notebook identifiers, whether the selection persists, or how success is reported, which are meaningful gaps for a mutation tool with zero annotation coverage.
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?
Three short sentences, each with a distinct job: state the action, explain the effect and its precondition, and point to the companion tool. Zero filler, and the core action is front-loaded.
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 simple tool (1 parameter, no output schema, no annotations), the description covers the essentials: what it does, when to use it, its effect, and how to discover valid inputs. Minor omissions — error behavior and success feedback — are not critical for correct invocation, so this is slightly above adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema already documents the notebook parameter well with format examples (URL, path like 'index' or 'voronoi', index like '0'). The description adds no parameter-level meaning beyond what the schema provides, so the baseline 3 applies.
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 ('Focus') on a specific resource ('notebook') and explains the concrete behavioral consequence: it sets which notebook receives commands by default. This differentiates it from siblings like ListNotebooks (listing), Navigate (movement), and GetValue (reading), even without naming 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?
Provides a clear trigger condition ('When multiple notebooks are connected') that tells an agent when this tool is relevant, and explicitly names ListNotebooks as the companion for discovering valid targets. Stops short of a full 5 because it doesn't state when not to use it (e.g., single-notebook sessions or read-only workflows), but the context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get console messages (log, info, warn, error) from the current or most recent session. Use this to debug console output without triggering a refresh.
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | Filter messages by substring match | |
| channel | No | Filter to a specific console channel. If omitted, returns all channels. | |
| max_chars | No | Maximum output length in characters (default: 2000). Set to 0 for unlimited. | |
| session_id | No | Specific session ID (optional, uses current session if not provided) |
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 usefully discloses that the tool does not trigger a refresh, implying a read-only, non-destructive operation. However, it does not describe output format, session fallback behavior beyond 'current or most recent', or any side effects, leaving some behavioral uncertainty.
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 two sentences with no filler. The core function is stated first, followed by a concise usage directive, making it easy for an agent to parse quickly.
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 simplicity of the tool, all required behavior is plausibly covered: what it retrieves, which session it targets, and that it avoids refresh. There is no output schema, so a slightly richer note about the return format would improve completeness, but the current description is sufficient for a straightforward console-read operation.
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 100%, so the parameters are already well documented in the schema. The description adds no additional parameter-level meaning beyond what the schema provides, warranting the 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?
The description states a specific verb and resource: 'Get console messages' with the channels log, info, warn, and error. It also clarifies scope ('current or most recent session') and contrasts with refresh-triggering tools, making its purpose distinct from siblings like Refresh and Navigate.
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 context: use this tool to debug console output. It also highlights a key behavioral advantage ('without triggering a refresh'), which helps an agent choose it over alternatives, though it does not explicitly name sibling alternatives or exclusion conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the dependency graph from the Observable runtime showing how values depend on each other. Returns nodes (values) and edges (dependencies).
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Focus on a specific node - shows its upstream dependencies and/or downstream dependents | |
| depth | No | Maximum depth to traverse when using "name" filter (default: unlimited) | |
| pattern | No | Filter nodes by name pattern (supports * wildcard, e.g., "chain*", "*Error") | |
| notebook | No | Target notebook (URL, path like "index" or "voronoi", or index like "0"). Optional if you've used FocusNotebook or only one notebook is connected. | |
| direction | No | When using "name" filter: "upstream" shows dependencies, "downstream" shows dependents, "both" shows all connected nodes | both |
| timeout_ms | No | Maximum time to wait in milliseconds | |
| include_anonymous | No | Include anonymous values (cell 1, cell 2, etc.) in output. These are intermediate values from cells without named exports. Default false to reduce noise. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of explaining behavior. It discloses the output structure ('nodes and edges') and the general nature of the operation, but it does not describe traversal semantics, filtering behavior, or side effects. For a read-only graph retrieval tool this is adequate but not deeply transparent.
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 two tight sentences with no filler. It front-loads the main action and then clarifies the return format, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal but the schema covers the parameters well. Still, with no output schema and no annotations, an agent might benefit from additional context about how the graph is structured, how the optional name filter changes the output, or when this tool is preferable to related value-listing tools. The core information is present, but there are clear gaps in guidance.
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 100%, so the schema already documents all 7 parameters thoroughly. The description adds no additional parameter-level meaning, such as how name, depth, direction, and pattern interact, which is acceptable because the schema already provides that detail.
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 retrieves a dependency graph from the Observable runtime and specifies the return shape as nodes and edges. It does not explicitly distinguish it from sibling tools, but the object of the action is specific enough for an agent to understand what it does.
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 when to use this tool: when you need to understand how values depend on each other. However, it does not mention alternatives such as ListValues or GetValueMetadata, nor does it state when not to use this tool, leaving the comparison to siblings implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get content from a DOM element by CSS selector. Auto-detects element type: returns text/HTML for regular elements, returns image content for canvas/SVG elements.
| Name | Required | Description | Default |
|---|---|---|---|
| notebook | No | Target notebook (URL, path like "index" or "voronoi", or index like "0"). Optional if you've used FocusNotebook or only one notebook is connected. | |
| selector | Yes | CSS selector for the element (e.g., "#cell-31", ".my-class", "svg.chart") | |
| timeout_ms | No | Maximum time to wait in milliseconds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure, and it does so meaningfully by explaining auto-detection of element type and the different return kinds (text/HTML vs. image content for canvas/SVG). This adds context beyond the schema, though it does not cover failure behavior or timeout semantics.
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 two sentences with no superfluous wording. The core action is stated first, followed by the key behavioral nuance (auto-detection and return types), making it front-loaded and 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?
For a simple getter, the description explains the main return behavior sufficiently, especially given no output schema exists. It could be more explicit about exact return formats (e.g., 'text/HTML' ambiguity, image encoding), but the essential calling context is covered.
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 100%, so the schema already documents all three parameters. The description only mentions 'CSS selector' and auto-detection, adding no new parameter-level details; thus the baseline of 3 is appropriate.
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 action ('Get content from a DOM element') and its resource ('by CSS selector'), making its purpose unmistakable. It uniquely distinguishes itself from sibling getters like GetValue or GetConsoleMessages by specifying DOM element extraction rather than notebook values or console output.
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 when to use the tool—whenever content from a DOM element is needed—but does not explicitly contrast it with alternatives like BrowserEval or GetValue. No when-not-to-use guidance or excluded scenarios are provided, leaving usage context to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get errors from the notebook. Returns both Vite build/parse errors (e.g. syntax errors that prevent the page from loading) and Observable runtime errors (values in a rejected state). If the page fails to load due to a syntax error, call this first — it will surface the Vite error even without a connected runtime. For console.error messages, use GetConsoleMessages with channel="error".
| Name | Required | Description | Default |
|---|---|---|---|
| verbose | No | Include full stack traces (default: false) | |
| notebook | No | Target notebook (URL, path like "index" or "voronoi", or index like "0"). Optional if you've used FocusNotebook or only one notebook is connected. | |
| timeout_ms | No | Maximum time to wait in milliseconds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. It reveals important behavioral details: Vite errors can be retrieved even without a connected runtime, and console.error entries are are not handled by this tool. It does not specify the exact return shape or side effects, but for a read-style 'Get' tool the description adds meaningful transparency beyond a bare summary.
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?
Three sentences with no wasted words. The first sentence states the core purpose and outcome, the second gives a specific call-first scenario, and the third routes to a sibling tool for a different message type. Every sentence earns its place and information is front-loaded.
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 lacking an output schema, the description provides a solid high-level return contract by naming both error kinds and clarifying the verbose stack-trace option through the parameter schema. It could be slightly more explicit about the exact return structure or timeout behavior, but the coverage is strong enough for an agent to select and invoke the 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 100%, with all three parameters (verbose, notebook, timeout_ms) already documented meaningfully in the schema. The tool description adds contextual routing for console errors but not new parameter-level semantics, so the baseline score of 3 is appropriate.
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?
Uses a specific verb and resource: 'Get errors from the notebook'. It clearly enumerates the two error categories returned (Vite build/parse errors and Observable runtime errors) and gives a concrete example (syntax errors that prevent the page from loading), making the tool's scope 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 gives explicit usage guidance: if the page fails to load due to a syntax error, call this tool first, and it will surface the Vite error even without a connected runtime. It also explicitly routes console.error messages to a sibling tool, GetConsoleMessages with channel='error', which clearly distinguishes when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a value from the Observable runtime by name. Returns the value along with its state (fulfilled, pending, or rejected). Automatically returns image content for Canvas and SVG elements.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the value to retrieve | |
| notebook | No | Target notebook (URL, path like "index" or "voronoi", or index like "0"). Optional if you've used FocusNotebook or only one notebook is connected. | |
| timeout_ms | No | Maximum time to wait for the value to resolve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It usefully reveals that results include value state (fulfilled, pending, rejected) and that Canvas/SVG values are automatically converted to image content, but it omits timeout outcomes, error behavior, and any 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 two sentences with no filler. It front-loads the primary action and then adds the most important return behavior and special rendering 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?
For a three-parameter tool with no output schema, the description covers the return value and noteworthy image behavior, but it lacks error semantics, timeout behavior, and usage context among many sibling tools. An agent would still need to infer important invocation details.
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 100%, so the baseline is 3. The description only reinforces the 'name' parameter through the phrase 'by name' and adds no new meaning for notebook or timeout_ms beyond what the schema already provides.
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 retrieves a value from the Observable runtime by name and returns its state. It is specific enough to distinguish the core action from siblings like ListValues or GetValueMetadata, though it does not explicitly name 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?
No guidance is given about when to use GetValue versus GetValues, ListValues, or GetValueMetadata. The description implies a single named lookup but does not state prerequisites, exclusions, or alternative selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get metadata about a value in the Observable runtime including its state, type, dependencies (inputs), and dependents (outputs) without fetching the full value.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the value | |
| notebook | No | Target notebook (URL, path like "index" or "voronoi", or index like "0"). Optional if you've used FocusNotebook or only one notebook is connected. | |
| timeout_ms | No | Maximum time to wait in milliseconds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it does disclose a meaningful behavioral trait: the tool avoids fetching the full value. It also enumerates the returned metadata categories (state, type, dependencies, dependents), giving the agent a concrete expectation of behavior beyond the tool name.
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, well-structured sentence that front-loads the core action and resource, then efficiently lists the metadata contents and the key non-fetching behavior. There is no redundant or vague wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately covers what the tool returns and its key non-behavior, and the input schema fully documents parameters and the notebook selection mechanism. It does not describe edge cases like missing values or timeout behavior, but for a metadata retrieval tool the description is sufficiently complete for an agent to invoke it 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 100%, so the schema already documents all three parameters. The description adds no additional parameter-specific semantics beyond the overall value metadata context, which matches the baseline of 3 for high schema coverage.
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 identifies a specific verb ('Get metadata'), a specific resource ('a value in the Observable runtime'), and the exact scope of that metadata ('state, type, dependencies (inputs), and dependents (outputs)'). It also differentiates itself from GetValue/GetValues by adding 'without fetching the full value.'
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 'without fetching the full value' provides clear contextual guidance: use this tool when you only need metadata rather than the complete value. It stops short of explicitly naming alternatives such as GetValue or GetDependencyGraph or stating when not to use it, so it does not reach a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get multiple values from the Observable runtime at once. If no names provided, returns all values. Useful for getting a snapshot of the runtime state.
| Name | Required | Description | Default |
|---|---|---|---|
| names | No | Names of values to retrieve (omit for all values) | |
| notebook | No | Target notebook (URL, path like "index" or "voronoi", or index like "0"). Optional if you've used FocusNotebook or only one notebook is connected. | |
| timeout_ms | No | Maximum time to wait per value |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It does add useful behavioral signals: it is a batched read and the phrase 'snapshot' implies a non-mutating view of runtime state. However, it does not disclose timeout/partial-failure behavior, whether values are returned as a map, or how this differs from evaluating expressions (RuntimeEval).
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?
Three short sentences, each earning its place: the core action, the default no-names behavior, and the intended use case. It is front-loaded and contains 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 read-only tool with zero required parameters and fully documented schema, this is largely complete. The main omissions are the return shape (no output schema) and explicit routing against GetValue/ListValues, but the basics needed to select and invoke the tool correctly are present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters. The description's 'if no names provided, returns all values' restates the names parameter's schema description rather than adding new semantic detail. Baseline 3 is appropriate.
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 action ('Get multiple values'), a clear resource ('Observable runtime'), and a distinguishing batch dimension ('at once') that separates it from the singular GetValue sibling. The all-values-when-no-names behavior and snapshot framing further pin down its purpose.
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 suggests a use case ('getting a snapshot of the runtime state') but never explicitly instructs when to choose this over GetValue, ListValues, RuntimeEval, or other siblings. The batch/plural semantics imply the distinction, but that is left to inference rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all connected notebooks. Use this to see which notebooks are available before targeting a specific one.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the tool lists all connected notebooks, which implies a read-only operation and defines its scope. It does not mention return format, potential errors, or prerequisites, but for a simple 0-parameter list tool this is adequate though not richly transparent.
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 exactly two sentences with no filler. The primary action 'List all connected notebooks' is front-loaded, and the second sentence provides practical usage guidance. Every word 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 the low complexity (0 parameters, no output schema), the description covers the essential what and when. It could mention what specific identifiers or details are returned, but for a straightforward enumeration tool the missing return format is a minor gap, not a critical omission.
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 tool has no parameters, so the schema is trivially complete. The description adds meaningful context about what the result represents (all connected notebooks) without needing to explain parameter syntax. Baseline 4 is appropriate for a 0-parameter tool.
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 'List' and the resource 'all connected notebooks', making the tool's function unambiguous. It adds usage context by saying to see available notebooks before targeting a specific one, which helps differentiate it from notebook-specific operations. However, it does not explicitly name a sibling alternative, so it falls just 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?
The description explicitly tells the agent when to use this tool: 'Use this to see which notebooks are available before targeting a specific one.' This implies that it is the preliminary enumeration step for later notebook-specific actions. It does not mention exclusions or alternatives explicitly, but the guidance is clear and contextually sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all named values in the Observable runtime's reactive graph.
| Name | Required | Description | Default |
|---|---|---|---|
| notebook | No | Target notebook (URL, path like "index" or "voronoi", or index like "0"). Optional if you've used FocusNotebook or only one notebook is connected. | |
| timeout_ms | No | Maximum time to wait in milliseconds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the action 'List,' which implies read-only enumeration, but it does not describe what happens when multiple notebooks are connected, whether the call can block, or what the returned list actually contains. This is sparse for a tool with no annotation safety net.
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, efficient sentence with no filler or repetition. The core action and object are front-loaded, making it easy for an agent to parse quickly.
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 only two optional parameters and full schema coverage, the tool has no annotations and no output schema. The description does not explain the response shape, how notebook disambiguation works, or how this relates to sibling tools, leaving meaningful gaps for an agent deciding whether and how to call it.
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 100%, so both notebook and timeout_ms are already documented in the input schema. The tool description adds no additional parameter-level meaning, which puts it at the baseline of 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?
The description uses a specific verb ('List') and a clear target resource ('all named values in the Observable runtime's reactive graph'), so an agent understands the core operation. However, it does not explicitly distinguish this from sibling tools like GetValues or GetValue, which could appear to overlap in function.
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 intended use case is implied: use this tool to enumerate all named values in the runtime. But there is no explicit guidance about when to choose ListValues over GetValues, GetValue, or GetValueMetadata, and no mention of exclusions, prerequisites, or fallback behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Simulate a mouse click at a position. Can target a specific element or coordinates.
| Name | Required | Description | Default |
|---|---|---|---|
| x | No | X coordinate (relative to element if selector provided, otherwise viewport) | |
| y | No | Y coordinate (relative to element if selector provided, otherwise viewport) | |
| label | No | Optional label describing the intent of this action (e.g., "expand plot", "zoom in"). Displayed in the notebook's event log overlay. | |
| button | No | Mouse button (0=left, 1=middle, 2=right). Default: 0 | |
| notebook | No | Target notebook (URL, path like "index" or "voronoi", or index like "0"). Optional if you've used FocusNotebook or only one notebook is connected. | |
| selector | No | CSS selector for target element. If provided, position is relative to element. | |
| timeout_ms | No | Maximum time to wait in milliseconds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description must carry the behavioral burden. It discloses that the action is simulated and can target elements or coordinates, but it doesn't mention likely side effects (navigation, button activation) or failure behavior. This is adequate for a simple click but not rich.
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 two short sentences and gets to the point immediately. It is not padded, though 'at a position' and 'element or coordinates' are slightly 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 simple click tool, the description plus a fully documented schema is mostly sufficient to invoke it. It lacks discussion of edge cases, side effects, or what happens when no target is given, which keeps it from being fully complete.
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 100%, so the parameters are already fully documented. The description adds little beyond the schema, only summarizing that targeting can be by element or coordinates, which is already implied by the optional selector and x/y fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('simulate a mouse click') and the two targeting modes ('element or coordinates'), which clearly distinguishes it from sibling pointer tools like MouseDrag, MouseHover, and MouseWheel. An agent can understand what this tool does and how it differs from nearby tools.
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 context: use this tool for mouse clicks, targeting either an element or coordinates. It doesn't explicitly name alternatives or exclusion conditions, so it stops short of a 5, but the intended usage is not ambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Simulate a mouse drag from start to end position. Emits mousedown, mousemove events per animation frame, then mouseup.
| Name | Required | Description | Default |
|---|---|---|---|
| endX | No | Ending X coordinate | |
| endY | No | Ending Y coordinate | |
| label | No | Optional label describing the intent of this action (e.g., "expand plot", "zoom in"). Displayed in the notebook's event log overlay. | |
| button | No | Mouse button (0=left, 1=middle, 2=right). Default: 0 | |
| startX | No | Starting X coordinate | |
| startY | No | Starting Y coordinate | |
| duration | No | Duration of drag in milliseconds. Default: 300 | |
| notebook | No | Target notebook (URL, path like "index" or "voronoi", or index like "0"). Optional if you've used FocusNotebook or only one notebook is connected. | |
| selector | No | CSS selector for target element. If provided, positions are relative to element. | |
| timeout_ms | No | Maximum time to wait in milliseconds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It transparently explains event sequence (mousedown, mousemove per animation frame, mouseup), duration parameter, and selector-relative positioning. It doesn't mention side effects like whether this moves focus or triggers native drag-and-drop behavior, but the event-level detail is strong.
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 concise sentences with no wasted words. The first sentence states the core action, and the second specifies the exact event sequence. Both are front-loaded and information-dense.
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 simulated input tool with 10 parameters but no output schema, the description covers the essential behavior well. The coordinate system and event sequencing are explained. It could be improved by noting that drags may need to land on target elements and don't trigger OS-level drag and drop, but the core call contract is clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so every parameter already has a description in the schema. The tool description adds value by explaining the behavioral meaning of duration (per animation frame) and selector-relative positions, which goes beyond the bare schema. Some parameters like timeout_ms lack detailed semantics, but the schema covers their basics.
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 action (simulate a mouse drag), its lifecycle (mousedown, mousemove per frame, mouseup), and its core inputs (start/end positions). It distinguishes this from sibling tools like MouseClick and MouseHover by specifying the drag sequence, though it doesn't 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?
The description implies usage for drag operations and mentions that positions can be relative to an element, but it doesn't explicitly state when to use this vs MouseClick/MouseHover. There is no guidance on prerequisites like the element being visible or notebook focus, though the notebook parameter hints at connection context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Simulate mouse hover at a position. Dispatches mouseenter, mouseover, and mousemove events to trigger hover states and tooltips.
| Name | Required | Description | Default |
|---|---|---|---|
| x | No | X coordinate (relative to element if selector provided, otherwise viewport) | |
| y | No | Y coordinate (relative to element if selector provided, otherwise viewport) | |
| label | No | Optional label describing the intent of this action (e.g., "expand plot", "zoom in"). Displayed in the notebook's event log overlay. | |
| notebook | No | Target notebook (URL, path like "index" or "voronoi", or index like "0"). Optional if you've used FocusNotebook or only one notebook is connected. | |
| selector | No | CSS selector for target element. If provided, position is relative to element. | |
| timeout_ms | No | Maximum time to wait in milliseconds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It clearly reveals that this is a synthetic simulation and specifies the dispatched mouse events, giving the agent a solid understanding of what happens during invocation. It stops short of describing failure behavior or limitations of synthetic events, but the essential actions are disclosed.
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 exactly one sentence, front-loads the core action, and immediately follows with the key event detail and purpose. Every word contributes value, and there is no wasted repetition of schema 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 that the schema covers all parameters and the tool has no output schema, the description is reasonably complete: it states the action, the events fired, and the intended effect. It could add more context about adjacent tool behavior, but for a simple hover action the essential operating context is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage and already documents all six parameters, including coordinate relativity, optional notebook targeting, label intent, and timeout. The description adds limited semantic value beyond calling the action a 'hover at a position,' so the baseline score of 3 is appropriate.
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: 'Simulate mouse hover at a position' and names the exact events dispatched. This clearly distinguishes it from sibling tools like MouseClick, MouseDrag, and MouseWheel, leaving no ambiguity about the tool's function.
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 communicates the intended use case: triggering hover states and tooltips. It implies when to use the tool, though it does not explicitly mention when not to use it or directly name an alternative such as MouseClick for click actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Simulate a mouse wheel scroll at a position.
| Name | Required | Description | Default |
|---|---|---|---|
| x | No | X coordinate (relative to element if selector provided, otherwise viewport) | |
| y | No | Y coordinate (relative to element if selector provided, otherwise viewport) | |
| label | No | Optional label describing the intent of this action (e.g., "expand plot", "zoom in"). Displayed in the notebook's event log overlay. | |
| deltaX | No | Horizontal scroll amount. Default: 0 | |
| deltaY | No | Vertical scroll amount (positive = scroll down). Default: 0 | |
| duration | No | Duration of scroll animation in milliseconds. Default: 300 | |
| notebook | No | Target notebook (URL, path like "index" or "voronoi", or index like "0"). Optional if you've used FocusNotebook or only one notebook is connected. | |
| selector | No | CSS selector for target element. If provided, position is relative to element. | |
| timeout_ms | No | Maximum time to wait in milliseconds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosing behavior. It only states the high-level action and says nothing about side effects, event generation, coordinate-space implications, notebook requirements, or animation behavior. This leaves the agent without a clear behavioral profile.
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 focused sentence with no filler, and the core action is front-loaded. It is structurally concise, though it omits contextual detail that would make it more useful.
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 9 parameters, no annotations, and no output schema, a single high-level sentence is not enough. The description does not cover usage context, prerequisites such as notebook focus or connection, or return/error behavior; the rich schema compensates for parameter meaning but not for the missing overall context.
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 100%, so the baseline is 3. The description itself adds no parameter-level meaning, but x/y, deltaX/deltaY, duration, selector, notebook, and timeout are all documented with descriptions and defaults in 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 uses a specific verb ('Simulate') and resource ('mouse wheel scroll'), and adds a positional scope. It distinguishes itself from sibling mouse tools like MouseClick, MouseDrag, MouseHover, and SendKeys by naming the wheel action, though it does not explicitly contrast with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to choose MouseWheel over alternatives such as MouseDrag or MouseHover, nor does it mention any exclusions or prerequisites. The appropriate usage must be inferred entirely from the tool name and the single-sentence definition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Trigger notebook page refresh and wait for completion. Captures all logs and errors from the new session.
| Name | Required | Description | Default |
|---|---|---|---|
| notebook | No | Target notebook (URL, path like "index" or "voronoi", or index like "0"). Optional if you've used FocusNotebook or only one notebook is connected. | |
| timeout_ms | No | Maximum time to wait in milliseconds | |
| wait_for_completion | No | Wait for session_end signal (recommended) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the behavioral disclosure burden. It does so by stating that it waits for completion and that it captures logs and errors from the new session, which is meaningful behavior beyond just 'refresh.' It does not fully describe side effects like invalidation of prior element references or page state loss, but these are reasonably implied by the term refresh.
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 two concise sentences and front-loads the core purpose first, then adds the key behavioral outcome. Every word earns its place, with no redundancy or 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?
Given no output schema, the description appropriately indicates what the agent can expect from the result: logs and errors from the new session. Combined with the fully documented parameter schema, this is sufficient for correct invocation. It does not specify the exact return structure, but that is not required for making the call.
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 100%, so the schema already documents notebook, timeout_ms, and wait_for_completion thoroughly. The description adds some alignment by mentioning waiting for completion, which maps to the wait_for_completion parameter, but it does not add meaningful semantics beyond what the schema already provides.
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 ('Trigger... refresh') and a clear resource ('notebook page'), and adds outcome details ('wait for completion', 'captures all logs and errors from the new session'). This clearly distinguishes Refresh from sibling navigation tools like Navigate or FocusNotebook, which are about changing focus/location rather than reloading and collecting session output.
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 clearly implies the tool is used when you need a fresh notebook session after a page reload and want to collect its logs and errors. It does not explicitly mention when to use an alternative tool such as GetConsoleMessages, but the context is clear enough for an agent to select this over Navigate or GetErrors in typical refresh scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Evaluate an expression in the Observable runtime context, with access to all notebook variables. Must use a return statement. Prefer this over Eval when computing derived values from runtime state. Examples: "return a + b" computes a sum; "return data.filter(d => d.value > 0)" filters a dataset.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | JavaScript code to evaluate. Must use "return" to produce a result. All notebook variables are accessible. | |
| name | No | If provided, the result persists in the runtime as a named variable for subsequent GetValue queries. If omitted, the result is returned and discarded. | |
| notebook | No | Target notebook (URL, path like "index" or "voronoi", or index like "0"). Optional if you've used FocusNotebook or only one notebook is connected. | |
| timeout_ms | No | Maximum time to wait for the value to resolve (default: 10 seconds) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral requirements: use of a return statement, access to all notebook variables, and persistence behavior when a name is provided. With no annotations present, the description carries the burden, but it does not mention potential side effects of executing arbitrary code, error behavior, or async resolution. It adds useful context but is not fully transparent.
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 and front-loaded: it states the operation, then the critical return rule and usage preference, then illustrative examples. Every sentence adds useful information without repetition or 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?
Given the tool's moderate complexity, the description adequately covers the essential usage context: what it evaluates, the return requirement, the runtime scope, and the persistence option. It could go further by explaining error or timeout behavior, but the schema already documents timeout and the return value is dynamic, so the absence of an output schema is not a major 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 100%, so the baseline is 3. The description adds value beyond the schema by providing concrete examples of expressions, emphasizing the return requirement, and clarifying that the evaluation context includes all notebook variables. This extra guidance helps an agent construct a correct body parameter.
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 a specific action ('Evaluate an expression') and a specific resource ('in the Observable runtime context') with access to notebook variables. It also differentiates itself from the similar Eval tool by positioning itself as the preferred choice for derived values from runtime state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Prefer this over Eval when computing derived values from runtime state,' giving clear context for when to use it. However, it does not mention when not to use it or how it compares to BrowserEval, another sibling tool, so it lacks a full set of exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Simulate keyboard input. Dispatches keydown, keypress (for printable characters), and keyup events to the target element.
| Name | Required | Description | Default |
|---|---|---|---|
| keys | Yes | Keys to send. Plain characters are sent as-is. Special keys use braces: {Enter}, {Tab}, {Escape}, {Backspace}, {Delete}, {ArrowUp}, {ArrowDown}, {ArrowLeft}, {ArrowRight}, {Space}, {Home}, {End}, {F1}-{F12}. Modifier combos: {Ctrl+a}, {Shift+Tab}, {Meta+s}. | |
| notebook | No | Target notebook (URL, path like "index" or "voronoi", or index like "0"). Optional if you've used FocusNotebook or only one notebook is connected. | |
| selector | No | CSS selector for target element. If not provided, sends to the currently focused element. | |
| modifiers | No | Modifier keys to hold during all keystrokes | |
| timeout_ms | No | Maximum time to wait in milliseconds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It adds meaningful detail about the dispatched events and that keypress occurs only for printable characters, which is beyond what the schema provides. However, it doesn't mention side effects, focus requirements, or return values.
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 with no filler: the core purpose is front-loaded, followed by a precise behavioral detail. Every word 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?
The schema richly covers all parameters, but with no output schema and no annotations, the description alone doesn't explain return behavior or when to prefer this over siblings. It gives the essential purpose and event detail, but leaves some selection context to inference.
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 100% with detailed per-parameter descriptions, so the baseline is 3. The description adds no additional parameter semantics beyond what the schema already documents.
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 ('simulate keyboard input') and resource ('target element'), and clarifies the event sequence (keydown, keypress for printable characters, keyup). This clearly distinguishes it from the mouse-oriented sibling tools.
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 purpose statement implies use when keyboard input is needed, but there is no explicit when/when-not guidance or mention of alternatives like SetInputValue or BrowserEval. The agent must infer the use case from the tool name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the .value property of an input widget in the Observable runtime (e.g., Inputs.range, Inputs.select, Inputs.text) and dispatch an input event, triggering reactive updates to dependent values.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the cell containing the input widget (e.g., "slider" if defined as `slider = Inputs.range([0, 100])`) | |
| value | Yes | The value to set (number for range, string for text/select, boolean for toggle, array of strings for checkbox) | |
| notebook | No | Target notebook (URL, path like "index" or "voronoi", or index like "0"). Optional if you've used FocusNotebook or only one notebook is connected. | |
| timeout_ms | No | Maximum time to wait in milliseconds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. It does disclose the key side effects: setting the property, dispatching an input event, and triggering reactive updates. It could also mention failure modes or notebook-focus requirements, but the core mutating behavior is transparent.
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 dense sentence with no filler. It front-loads the action and target, then explains the side effect, and the examples are compact and useful.
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 the schema fully documents parameters and the description clearly captures the operation and reactive consequence, the definition is adequate for invoking the tool. It does not describe return behavior or explicit error/edge cases, but those are not essential for a straightforward input setter.
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 100%, so the schema already documents all four parameters and their value types. The description adds only clarifying examples of widget kinds without going beyond the schema, so the baseline score of 3 is appropriate.
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 ('Set'), a precise target ('.value property of an input widget in the Observable runtime'), and concrete examples (Inputs.range, Inputs.select, Inputs.text). It clearly distinguishes this tool from read-oriented siblings like GetValue and GetValues.
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 intended use is implied by the description: it is for programmatically setting widget values and triggering reactive updates, as opposed to simulating mouse input. However, it does not explicitly name alternatives or state when not to use this tool, so the agent must infer the selection from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.0.2BrowserEvalFocusNotebookGetConsoleMessagesGetDependencyGraphGetElementContentGetErrorsGetValueGetValueMetadataGetValuesListNotebooksListValuesMouseClickMouseDragMouseHoverMouseWheelNavigateRefreshRuntimeEvalSendKeysSetInputValueTools are largely purpose-specific: value retrieval is split into single/bulk/metadata/list, and evaluation is split into browser vs runtime contexts. A few boundaries require care—GetErrors vs GetConsoleMessages both surface errors, and GetValues with no names overlaps with ListValues—but descriptions clarify intended usage.
Most tools follow a PascalCase VerbNoun pattern (ListNotebooks, GetValue, SetInputValue, SendKeys). Exceptions break the pattern: Refresh and Navigate are bare verbs, while BrowserEval/RuntimeEval and MouseClick/Drag/Wheel/Hover put the context or object before the action, making the convention less predictable.
20 tools is at the high end for a debugger and feels slightly heavy, with multiple value-retrieval variants and five input-simulation tools. The breadth is defensible because the server covers runtime state, DOM inspection, and mouse/keyboard interaction, but it is borderline rather than clearly well-scoped.
The server covers the main notebook debugging loop: discover/connect notebooks, inspect runtime values and dependencies, read console/errors, manipulate inputs, and simulate interactions. Obvious gaps such as a dedicated screenshot or wait-for-condition tool are workaroundable via BrowserEval/RuntimeEval, but they are minor omissions.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Live browser debugging for AI assistants — DOM, console, network via MCP.
Hosted browser for AI agents: screenshots, post-JS DOM, console, WCAG. No install, no API key.
Renders interactive Chart.js charts and dashboards inline in AI conversations.
Data + AI observability — monitor and troubleshoot production-grade agents and the context they use.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/rreusser/mcp-observable-notebookkit-debug'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
