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

With no annotations, the description carries the transparency burden. It discloses the key effects: the editor switches, the tab becomes visible and focused. It also conveys an important behavioral constraint (requires explicit user consent). It does not explain error handling or what happens if the buffer_id is invalid, but for a UI-focus action this is reasonable.

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, front-loaded with the main action and followed by a necessary usage constraint. No superfluous 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 tool is simple with only two parameters and no output schema. The description provides the main purpose and the critical precondition. It doesn't cover edge cases like activating an already-open tab or stale buffer_ids, but given the simplicity, the description is 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?

Schema coverage is 100% and each parameter has a clear description. The tool description itself adds little beyond the schema, but the schema already documents buffer_id and cell_to_focus well, including the null option for cell_to_focus. 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?

The description clearly states the action: 'Switch the user's editor to the given notebook tab so it becomes visible and focused.' This uses a specific verb, identifies the resource (notebook tab), and distinguishes it from sibling tools like create_notebook or delete_notebook by focusing on activation/switching behavior.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use guidance is provided: 'ONLY call this after the user has explicitly agreed to be taken to the notebook.' It also gives a clear exclusion: 'Never call it to auto-switch while the user is working elsewhere.' This is strong, actionable usage 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, the description carries full disclosure burden and does so thoroughly. It reveals return behavior (new cell id, per-query status array), execution semantics (invalid statements skipped, reads run in parallel), and safety caveats (DDL/DML never auto-run, no row/column data returned). This goes well beyond a simple 'adds a cell' statement.

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 dense and front-loaded, starting with the action and return value before covering important caveats. It is fairly long, but the length is justified given the complexity of run semantics and markdown behavior. Every sentence adds meaningful 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?

For a 5-parameter mutation tool with no output schema, the description covers return values, execution behavior, and non-execution cases well. The main gap is buffer_id, which is left entirely to context, and error conditions or permission requirements are not mentioned. Overall, it is near-complete with minor omissions.

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 80%, but buffer_id is undocumented in both schema and description. The description enriches sql (multi-statement chart overlay, markdown source), run (parallel reads, invalid statement handling), and type (markdown render-only). It does not add meaning for buffer_id or after_cell_id, though those are partly covered by 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 core operation: 'Append a cell to the notebook.' It differentiates from sibling tools like update_cell, run_cell, and delete_cell by explicitly covering SQL vs markdown cell creation. The 'append' wording is slightly narrow given after_cell_id insertion, but the action remains 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 concrete conditional guidance: use type:'markdown' for prose cells, and explicitly warns that DDL/DML and markdown cells are never auto-run, advising 'Take consent from the user, then call run_cell explicitly.' It references run_cell semantics but does not explicitly contrast add_cell with update_cell or delete_cell, so alternative selection is not fully exhaustive.

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 the full burden and does so thoroughly: it discloses atomic deletion semantics, preserve_value behavior, result-carryover rules, automatic chart rendering, auto-execution exclusions for DDL/DML and markdown, parallel execution, response shape (runs, results_cleared), and the state-freshness gate.

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 long but front-loaded with the core purpose and routing guidance, and most sentences carry operational detail needed for a destructive bulk API. Some clauses are dense and could be tightened, but the size is justified by the tool's complexity.

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 bulk mutation tool with no output schema, the description covers deletion semantics, auto-execution rules, consent requirements, response fields, and state freshness. It leaves no major behavioral gap an agent would need to call the tool safely.

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 83%, so the baseline is 3, but the description adds substantial meaning beyond the schema: the cells array is a complete desired list where missing ids are deleted, value and preserve_value are mutually exclusive alternatives, and apply is a full PUT that clears omitted chart/highlight/name settings.

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 precise verb (bulk-apply), resource (notebook state), and atomic scope, and explicitly contrasts itself with update_cell, set_cell_*, and chained add_cell/update_cell operations. An agent can tell exactly what this tool replaces without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use conditions (bulk edits across cells, notebook from scratch, multi-cell layout, many-cell changes, restructuring) and when-not-to-use alternatives (small operations via update_cell or set_cell_*). It also mandates calling get_workspace_state first and taking consent before run_cell.

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 carries full burden. It discloses multiple behavioral traits: never shows query data, always background creation, never switches active tab, user sees notification and opens it themselves. These go beyond the schema and give critical operational expectations.

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?

Four sentences, front-loaded with the core action, and every sentence adds behavioral or usage detail. No redundancy or fluff.

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 single-parameter background action with no output schema, the description covers purpose, side effects, user-facing behavior, and alternative invocation. It provides sufficient context for an agent to use 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 the label parameter fully documented ('Label shown on the new notebook tab (max 100 characters). Pass null to use the default.'). The description adds no additional parameter semantics, so 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?

Description opens with a specific verb+resource: 'Create a new QuestDB notebook tab in the editor.' It further clarifies scope by stating it 'only scaffolds the tab' and never shows query data, distinguishing it from data-returning tools. It also differentiates from sibling activate_notebook by explicitly mentioning it.

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 usage conditions: the tab is always created in the background, and 'only call activate_notebook if they explicitly ask to be taken there.' This gives a clear when-not with an alternative. Also states the binding behavior ('if it isn't already bound to a notebook'), which helps decide when to invoke.

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 the full burden of behavioral disclosure. It merely restates the tool's name ('delete a cell') and provides no information about side effects, irreversibility, or any other behavioral traits. This is effectively a tautology and offers no transparency beyond the 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 concise sentence with no wasted words. It is appropriately sized for such a simple tool, though under-specification is penalized in other dimensions. The structure is front-loaded with the key action and object.

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, output schema, and schema parameter descriptions, the tool is under-specified. The description does not explain required parameters, the broader notebook context, or any behavioral consequences, making it insufficient for an agent to confidently invoke the 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 description coverage is 0% and the description does not mention either parameter (buffer_id or cell_id). The schema provides only types and requiredness, which is insufficient. The description fails to compensate, leaving parameter meanings entirely unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Delete a cell from the notebook' clearly states the verb (delete), resource (cell), and context (notebook). It distinguishes itself from sibling tools like delete_notebook and other cell operations, making the purpose 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?

No guidance is provided on when to use this tool versus alternatives or any prerequisites. The description simply states the action, leaving usage entirely implicit. There is no mention of exclusions or alternative tools, which is a clear gap.

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 weight and excels: it discloses that the action is a soft-delete, moves to history, is user-restorable, does not destroy query data, and makes chat bindings stale. This prevents misuse and sets correct expectations.

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, each earning its place: the action, the safety/recovery behavior, and the edge case with chat binding. No filler or redundancy; information is front-loaded and scannable.

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 deletion tool with one parameter and no output schema, the description covers all necessary context: what happens, what is preserved, and how to recover. It also distinguishes itself from siblings and addresses a specific consequence (stale binding), making it operationally 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?

The input schema already fully describes buffer_id (100% coverage) with context about where to find it. The description adds no additional parameter-level detail, but the schema is sufficient, matching the baseline 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 states 'Archive (soft-delete) a notebook tab' with a specific verb and resource. It distinguishes itself from permanent deletion and names create_notebook for the stale binding case, effectively separating it from 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?

It explains when to use this tool (the same as closing a notebook tab) and provides an explicit alternative: 'start a new one with create_notebook' when the binding goes stale. The soft-delete and restore behavior also clarifies when not to use it (for permanent destruction).

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 present, so the description must carry the full burden. It only states the action and placement, but does not disclose whether the cell's content, outputs, or configuration are copied, whether a new cell ID is generated, or whether special permissions are needed. It also doesn't mention if the original is unaffected, though that is implied by 'duplicate'.

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, front-loaded sentence with no filler. Every word ('Duplicate', 'cell', 'immediately after', 'original') adds meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no annotations, no output schema, and two undocumented parameters, the description provides only the core action and placement. It omits expected response, effect on existing cells, and any prerequisites, so an agent would have limited ability to anticipate side effects.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has two parameters with zero description coverage, and the tool description does not define buffer_id or confirm that cell_id refers to the source cell. While 'original' hints at cell_id, buffer_id's role (presumably the notebook buffer containing the cell) is left ambiguous.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'duplicate', names the resource 'cell', and adds placement detail 'immediately after the original'. This distinguishes it from sibling tools like add_cell (create new), update_cell (modify), and move_cell (reposition).

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 this tool versus add_cell or update_cell. There are no use-case scenarios, prerequisites (such as the cell existing or the buffer being writable), or exclusion conditions.

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 and does so: it discloses copied content, the naming convention, placement next to the original, cell-id regeneration, background execution, best-effort snapshot copying, and the caveat that last_run_status is history only and does not imply a snapshot exists. These are precisely the non-obvious traits an agent would otherwise guess wrong about.

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

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

Purpose and scope are front-loaded in the first sentence, and each following sentence carries distinct operational information (naming, background behavior, run history caveat, tab-switch rule). It is slightly dense across four sentences, but no sentence is redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no annotations and no output schema, the description fully assumes the disclosure burden for a mutation tool: what is copied, where the result goes, that it runs in the background, and what the user experiences afterward. Nothing needed to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter (buffer_id) and schema description coverage is 100%, so the schema already explains the argument. The description adds no format or sourcing detail beyond the schema's own note that the id comes from the notebook context prefix, so this sits at the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Duplicate a notebook tab') and immediately separates itself from sibling duplicate_cell and create_notebook by specifying that the whole notebook, its cells, layout, and run history are copied into a NEW notebook. An agent can distinguish it from the cell-level duplicate without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly prescribes behavior after the call: the copy is ALWAYS in the background, the user's active tab is never switched, and activate_notebook should only be called if the user explicitly asks. That is a precise when-not rule with the alternative named, which is exactly the routing guidance an agent needs.

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

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

With no annotations, the description carries the full behavioral burden and does so richly: live-only fields (refreshing, last_refresh_error, auto_refresh_blocked), the rule that absence never means 'not refreshing', the distinction between last_run_status and refresh state, and the critical warning that truncated values must never be written back. This is exactly the context an agent needs.

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

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

Front-loaded with what is returned, and the length is justified by the many live-only fields and the write-back hazard. A few clauses are tightly packed, but nothing is redundant 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?

No output schema exists, so the description has to explain return values, and it fully does: per-field semantics, null-value rules for markdown cells, truncation flags, and what is deliberately excluded (query result data). An agent can interpret the response without any schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 33% — cell_id and buffer_id have no descriptions anywhere. The description reinforces get_full_content semantics (4 KB cap, 1 MB error ceiling, re-read before rewriting), but buffer_id/cell_id stay undocumented, so it only partly compensates for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Get full details of a cell') and enumerates the returned facets, which implicitly separates it from list_cells and get_notebook_state. It stops short of explicitly naming the sibling it replaces when you only need a summary.

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?

Embedded guidance exists for the truncation workflow: re-read with get_full_content: true before rewriting, and use preserve_value: true to avoid clobbering. However, there is no explicit statement of when to choose get_cell over list_cells or get_notebook_state.

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 the full burden and does substantial work: it discloses LIVE-ONLY fields (refreshing, last_refresh_error, auto_refresh_blocked), warns that field absence does not imply the negative state, clarifies last_run_status is unrelated to refresh state, and explains markdown null semantics. It omits operational traits like permissions or whether the notebook must be active, so it is strong but not exhaustive.

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 snapshot purpose is front-loaded, but the body is a dense, comma-chained block of field semantics that is hard to scan and mixes many distinct topics (view state, live-only flags, type markers, preview truncation) without structure. Most clauses are informative, yet the run-on density works against quick comprehension.

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?

There is no output schema, so the description must explain the return shape and it does so in depth — field presence/absence semantics, null handling, truncation caps, and the distinction between previews and real content. Given no annotations and a single input param, this is nearly complete, missing only the input parameter's meaning.

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 sole parameter buffer_id has 0% schema description coverage and is never mentioned in the description. The description must compensate for the low coverage but instead spends all its text on return-value semantics, leaving the meaning, format, and source of buffer_id entirely undocumented.

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 opening sentence names a concrete verb+resource: a full structural snapshot of a notebook, and enumerates what the snapshot contains (layout, cells with previews, semantic pane dimensions, kind, last-run statuses). It also draws a boundary by stating what is excluded (no cell data values, no columns/rows/count), which helps separate it from list_cells/get_cell. It never explicitly names or contrasts a sibling, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to use this tool versus alternatives such as list_cells, get_cell, or get_workspace_state, and no prerequisites or preconditions are given. Usage is only inferable from the field inventory (it is a read-oriented snapshot), which is exactly the 'implied usage' floor. No exclusions or routing guidance are provided.

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 the tool's side effect of auto-opening the browser, the exact return fields (deep_link, ws_url, token, userMessage), the fact that it returns paired:true if already paired, and the behavioral guarantee of a timeout if the flow is not followed. This is comprehensive transparency beyond what any annotation would typically provide.

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 about 150 words, longer than average, but every sentence earns its place given the criticality of the pairing flow. It is front-loaded with purpose, then the required sequence, then behavioral detail. Some redundancy exists (e.g., repeating the timeout guarantee) but it does not detract significantly.

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 1-param tool with no output schema, the description fully enumerates all return values (deep_link, ws_url, token, userMessage, paired:true if already paired) and positions the tool within the larger pairing workflow (as the step before wait_for_pairing). It covers the parameter, the flow, the side effects, and the fallback behavior, leaving no important gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already documents auto_open_browser with 100% coverage, making baseline 3. The description adds practical semantics: 'By default this also auto-opens the deep link in the user's default browser; pass auto_open_browser:false to suppress that', plus concrete use cases (headless/CI/background, avoiding focus stealing). This elevates the parameter understanding beyond the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states it 'Get the credentials the user needs to pair their browser with this MCP bridge' and clarifies 'calling this tool does NOT itself pair anything', clearly distinguishing it from the sibling wait_for_pairing. The verb+resource combination is specific and 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?

Provides a REQUIRED FLOW with numbered steps, explicitly says 'DO NOT skip step (2)', and explains the consequence of skipping: 'calling wait_for_pairing without first showing the credentials guarantees a timeout'. It also gives guidance for when to suppress auto-open (headless/CI/background contexts) versus when to leave it enabled.

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 the full burden of behavioral disclosure. It indicates a read-only retrieval operation but does not describe return format, error handling, or any potential side effects. For a simple getter, it is adequate but lacks rich behavioral context.

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 fluff. The first sentence front-loads the purpose, and the second adds a valuable efficiency note. 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 simple two-parameter schema and no output schema, the description is mostly complete, but it fails to explicitly mention that users should first obtain the table of contents via get_questdb_toc to know valid item names. This prerequisite is only in the schema description, not the main tool description, leaving a slight 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%, with detailed descriptions for both 'category' and 'items', including enum values and the exact-match requirement. The description adds little beyond the schema, so 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 action ('Get documentation') and the resource ('specific QuestDB functions, operators, or SQL keywords'), making it obvious what the tool does. It also implicitly differentiates from the sibling get_questdb_toc by focusing on specific items rather than listing all documentation.

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 for when to use this tool: 'much more efficient than loading all documentation.' It also references the prerequisite of matching items to the table of contents in the schema, which implies a workflow with get_questdb_toc. However, it does not explicitly name the alternative tool or state 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?

No annotations are provided, so the description carries the full burden. It states what the tool returns (a TOC listing) but does not explicitly disclose that it is a read-only operation or describe the output format. For a simple getter, this is adequate but lacks explicit safety/behavioral detail.

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

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

Two sentences, front-loaded with the core action, and no fluff. The second sentence provides practical usage guidance. Excellent conciseness.

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 parameterless tool with no output schema, the description explains the purpose, content, and usage sequence. It is complete enough for an agent to invoke it correctly, though more detail on the return structure would be helpful.

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 0 parameters, so the baseline is 4. The description adds context about the content of the TOC, which is sufficient given there is nothing to parameterize.

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 'Get' with a resource 'table of contents listing all available QuestDB functions, operators, and SQL keywords'. This clearly differentiates it from siblings like get_questdb_documentation, which presumably fetches detailed docs for specific items.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides explicit timing guidance ('Use this first') and the context ('before requesting specific items'), which implies a sequential workflow relative to get_questdb_documentation. However, it does not explicitly name alternative tools or state 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.

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 real behavioral traits: the digest window is 'since your last fetch (or session start)' and events are 'coalesced' so multiple typing events collapse to one 'edited' entry. It does not describe the empty/no-edit case or the digest's full shape, which is the main gap.

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

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

The actual purpose is buried in the second paragraph while the lead is a cross-tool pairing/workspace-state instruction that belongs to get_pairing_credentials and get_workspace_state rather than this tool. The relevant sentences are tight, but the front-loading is poor and the preamble doesn't fully earn its place here.

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 zero-parameter, read-only digest tool with no output schema, the description explains what it returns, when to call it, and its coalescing semantics, which is close to complete. Only the empty-result behavior and digest entry shape are left implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters and the schema is empty, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter confusion is possible.

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 second paragraph states a specific verb and resource: 'Return the digest of user edits to the notebook since your last fetch.' It distinguishes itself from get_workspace_state (start-of-turn full state) and get_notebook_state, so an agent can tell them apart. The leading paragraph about pairing is off-purpose but the core function 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?

It gives clear usage context: 'Use this to detect that the user changed something the agent might want to react to,' and situates itself relative to get_workspace_state at the start of every notebook turn. It lacks explicit when-not guidance, but the selection condition is reasonably clear.

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 of behavioral disclosure. It only says 'get runtime details/statistics' without explaining what those details include, whether the operation is read-only (though 'get' implies it), any error conditions, or what the response structure is. This is minimal disclosure for a tool with no annotation support.

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 that immediately states the action and the resource. It is front-loaded and contains no extraneous words, achieving maximum conciseness without losing clarity.

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 one-parameter get tool with no output schema, the description is adequate but not complete. It tells what the tool does but does not specify the nature of the 'runtime details/statistics' or the response format. Given the lack of an output schema, some additional detail about the return value would be helpful, so it falls short of 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 baseline is 3. The description does not add any information about the parameter beyond what the schema already provides; it merely restates the accepted object types. No extra semantic value is contributed.

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 verb ('Get') and resource ('runtime details/statistics of a specific table, materialized view, view or live view'). It differentiates from siblings like get_tables (which lists tables) and get_table_schema (which returns schema), making its purpose 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 implies usage when runtime details/statistics are needed, but it does not explicitly mention alternatives or when not to use this tool. There is no guidance on choosing between this and get_table_schema or get_tables, leaving it to the agent to infer.

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 the full burden. It accurately indicates a read-only listing operation apa pun, but it does not disclose output format, ordering, whether system objects are included, or any pagination/limits. It is minimally transparent but not misleading.

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 that states the verb, resource, and scope immediately, with zero filler or redundancy. It is appropriately 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 zero-parameter listing tool, the description is largely sufficient: it identifies the database object types returned. However, it does not specify whether the result contains names alone or full object metadata, which would help an agent know what to expect from the response.

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 zero parameters)Skip, so there is nothing for the description to clarify beyond what the empty schema already shows. The baseline of 4 for a no-parameter tool 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?

The description clearly states the action ('Get a list') and the exact resource scope ('all tables, materialized views, views and live views in the QuestDB database'). This distinguishes it from singular-table siblings like get_table_details and get_table_schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given about when to use this tool versus alternatives such as get_questdb_toc, get_table_details, or get_table_schema. The intended use is somewhat implied by the description, but there are no explicit exclusions or alternative routing.

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 the full burden. The verb 'Get' implies a read-only operation, and 'full schema definition (DDL)' hints at the return content, but no mention is made of error handling, permissions, or side effects. It is adequate but minimal.

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 wasted words. It front-loads the primary action and the specific resource type, making it immediately scannable 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 tool with one well-documented parameter and no output schema, the description is mostly complete. It specifies the purpose and the input, and implies the return format (DDL). However, it could explicitly state that it is read-only or describe the response structure, but given the simplicity, it is 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?

The schema description for table_name is 100% coverage, clearly defining the parameter as the name of the table, materialized view, view, or live view. The tool description adds no additional parameter semantics beyond what the schema already provides, so a 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 verb 'Get' and the resource 'full schema definition (DDL)' for a specific table, materialized view, view, or live view. It is specific about the output (DDL) and the accepted object types, distinguishing it from siblings like get_tables (listing tables) and get_table_details (likely other metadata).

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 on when to use this tool versus alternatives such as get_tables or get_table_details. The description only states what it does without mentioning prerequisites, exclusions, or alternative tools, leaving the agent to 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, the description carries the burden and does well: it explains the auth flow (browser-based pairing, the bridge never sees credentials), the response type (text), and interpretation details like SQL/draw cells reporting a pane view and mode. It stops short of rate limits or failure modes beyond the pairing case.

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?

Dense but nearly every sentence carries weight, and the field-by-field view/mode semantics are actionable. Slight deduction because it opens with the failure/pairing branch rather than the tool's own purpose, so the primary function is not fully 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?

No output schema exists, yet the description compensates by describing the returned context and the view/mode/result_height semantics for cell types. For a zero-required-param read tool this is close to complete, with only minor gaps around error behavior aside from pairing.

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% for the single boolean, so the description must compensate. It does: 'Pass include_user_events=true to also receive the digest of edits the user made since your last fetch' explains both the toggle and the delta semantics beyond the schema's bare boolean.

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 ('Return the current workspace + notebook context as text') and enumerates what that context includes: active notebook, cells, layout mode, chart configs, last-run statuses. It also distinguishes itself from siblings by noting the edit digest lives in get_recent_user_actions, so an agent can route between the two without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit usage rule ('call get_workspace_state at the start of every notebook turn'), a recovery branch for BRIDGE_NOT_PAIRED that names the alternative tool (get_pairing_credentials), and the condition that selects get_recent_user_actions. When-to-use and alternatives are both 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?

With no annotations, the description carries the full burden and does so richly: it explains the meaning of 'mode', explicitly flags three LIVE-ONLY fields and warns that their absence does not imply the absence of refreshing or blocking, and clarifies that last_run_status is unrelated to refresh activity. This is exactly the behavioral context an agent needs.

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

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

Front-loads the core purpose, then adds subsequent sentences that each carry distinct semantic value (return fields, mode meaning, live-only field warnings, last_run_status clarification). No sentence is redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a list tool with no output schema and no annotations, the description is complete: it explains the return shape, the meaning of key fields, and the subtle live-only semantics. An agent has everything needed to interpret results 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 coverage is 100% and the single parameter buffer_id is fully documented in the schema. The description adds no parameter-level detail, so the baseline of 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 ('List') and resource ('cells in a notebook'), and enumerates the key return fields. It is easily distinguished from the singular sibling get_cell without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the listing purpose, but there is no explicit when-to-use guidance or mention of alternatives such as get_notebook_state or get_cell. For a simple list tool this is adequate but leaves routing to inference.

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

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

No annotations are provided, so the description carries the full burden. It clearly states the swap action, but does not disclose edge-case behaviors (e.g., what happens if the cell is already at the bottom) or side effects beyond the swap. The operation is simple and the description covers its primary behavior, but lacks deeper 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?

The description is a single, concise sentence with no unnecessary words. It is front-loaded and directly states the action, earning a perfect score for brevity and clarity.

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?

As a mutation tool with no annotations, no output schema, and minimal parameter documentation, the description is sparse. It does not mention return values, edge cases, or any constraints, leaving the agent with an incomplete picture for a tool that involves a destructive or rearrange 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?

The schema description coverage is 0%, and the description does not explain the parameters 'cell_id' or 'buffer_id' at all. The property names provide some hint, but the description adds no meaning beyond the schema, failing to compensate for the low 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 'Swap a cell with the one below it' uses a specific verb ('swap') and resource ('cell'), clearly distinguishing the tool from its sibling 'move_cell_up' which swaps with the cell above. It unambiguously states what the tool 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 the tool (when you need to move a cell down) but provides no explicit context about when not to use it or alternatives like 'move_cell_up'. The sibling tools list offers hints, but the description itself lacks direct 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states a swap occurs but does not disclose edge cases (e.g., behavior when above cell doesn't exist), error conditions, or any side effects beyond the swap. For a mutation tool, this lacks necessary 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?

The description is a single, efficient sentence with no unnecessary words. However, it might be slightly under-specified, sacrificing clarity for brevity, so it doesn't earn a 5.

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 output schema, the description is incomplete for a mutation tool. It omits prerequisites, edge cases, and any behavioral context. The presence of move_cell_down as a sibling creates a pair, but the description doesn't explain how this tool fits into that 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?

With schema description coverage at 0%, the description needed to explain the parameters. It does not mention cell_id or buffer_id at all, leaving their meanings to be inferred from names alone. The description adds no semantic value 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 'Swap a cell with the one above it' uses a specific verb ('swap') and resource ('cell'), and clearly distinguishes this from the sibling tool move_cell_down by specifying direction ('with the one above it'). This leaves 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?

No guidance is provided on when to use this tool versus alternatives like move_cell_down, nor are any prerequisites or conditions (e.g., what happens if the cell is already at the top) mentioned. The description merely states the operation without 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?

Even though annotations are absent, the description clearly discloses parallel vs sequential execution, failure/skip semantics, permission and consent requirements, the exact return shape, and markdown-cell behavior. This fully carries the behavioral burden.

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 long but every sentence carries essential operational information. It is front-loaded with the core action and then layers execution semantics, return format, security, and exclusions without 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 a tool with no annotations and no output schema, this description covers everything an agent needs to call it correctly: execution model, expected results strings, no data returned, permissions, consent, and the markdown edge case. The only gap is parameter provenance, which is already reflected in the parameter_semantics score.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description needed to explain buffer_id and cell_id, but it never mentions either parameter or how to obtain them. The word 'cell' gives some context, but an agent receives no guidance on the meaning or provenance of the two required 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 first sentence states the action and resource precisely: 'Execute a SQL cell.' It then distinguishes itself from run_query ('You do NOT see columns, rows, or values — call run_query if you need data') and from apply_notebook_state/add_cell by being the only path that executes writes.

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 tells an agent when to choose this tool: when a SQL cell must be executed, especially any agent-initiated DDL/DML, and names alternatives for data retrieval and note that other cell tools never auto-run writes. This removes ambiguity about tool selection.

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

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

With no annotations provided, the description carries the full burden of disclosing behavior. It covers row limit defaults, payload size cap, truncation behavior, response fields (`truncated`, `total_count`, `returned_count`), the fact that DDL/DML executes live, and that authentication is handled by the user's session. This is exemplary 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?

The description is dense but every sentence earns its place: purpose, comparison to `run_cell`, limit behavior, truncation, response fields, mutation warning, and auth context. It is front-loaded with the core purpose and uses clear warnings like 'be deliberate'.

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 tool that executes arbitrary SQL with mutation potential and pagination/truncation nuances, the description covers all essential context: what data is returned, how limits work, what happens when the payload is too large, and that DDL/DML mutates the live database. No output schema exists, so describing the response fields (`truncated`, `total_count`, `returned_count`) is important and done well.

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 already fully describes both parameters (`sql` and `limit`) with 100% coverage, including default and max for `limit`. The description reinforces this by mentioning default limit 100 and max 10000, but does not add significant new parameter-level meaning beyond what the schema 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's function: executing arbitrary SQL against QuestDB and returning result rows. It distinguishes itself from the sibling `run_cell` by explicitly noting that unlike `run_cell`, this tool returns data values.

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 contrasts with `run_cell`, clarifying when to use this tool (when you need data back) versus the alternative. It also gives use cases: inspect data, validate work, compose follow-up queries. This is strong when/when-not guidance.

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

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

With no annotations, the description carries the full burden and does so: DDL/DML cells store the value but the engine blocks ticks, read tools surface auto_refresh_blocked: "contains_write", markdown cells are rejected, and no polling happens without a value or default. This is exactly the kind of non-obvious system behavior an agent cannot infer from the schema.

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?

Every sentence carries load and the scoping statement is front-loaded before the value semantics. It is a single dense block, though, and could be broken into shorter units for easier scanning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no annotations and no output schema, the description covers behavior, rejection cases, blocking semantics, and inheritance rules — everything needed to invoke it correctly. Little is left 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 coverage is effectively low (only the value property carries a description), yet the description fully explains value: true = adaptive poll, false = off, fixed interval string with range 50ms–60m and examples, null = clear the override and inherit the notebook default. buffer_id and cell_id remain undocumented, but their meaning is self-evident.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (set auto-refresh polling for a cell) and immediately positions it as a per-cell override of set_notebook_autorefresh, a named sibling. An agent can distinguish it from set_notebook_autorefresh without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly frames this as the per-cell counterpart to set_notebook_autorefresh, states it applies to both chart and grid cells, that markdown cells are rejected, and that nothing polls without a per-cell value or notebook default. When-to-use and when-not conditions are all present.

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 fully carries the behavioral disclosure burden. It explains auto-combine semantics, index-aligned query configs, the always-included first query, enabled:false opting out, required ohlc mapping for candlesticks, and patch semantics including replacement vs reset behavior. This is exemplary 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?

The description is dense and information-packed; every sentence contributes meaningful detail with no filler. However, it is one long paragraph that mixes high-level behavior, edge cases, and patch semantics, making it harder to scan. A little structural separation would improve readability without losing content.

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?

This is a complex configuration tool with no output schema, yet the description thoroughly covers combine rules, per-query types, axis handling, numeric-x limitations, candlestick requirements, and patch semantics including rejection conditions. It leaves few open questions and is complete for 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?

The schema covers 60% of parameters with descriptions, but the tool description significantly extends this by explaining index-alignment, replacement semantics for the queries array, conditionality of ohlc, axis behavior, and the meaning of x_column as the shared x-axis. It adds meaning far beyond the structured schema 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 opens with 'Configure the chart for a draw-mode cell,' a specific verb+resource statement that clearly distinguishes this tool from sibling cell operations like set_cell_mode or set_cell_layout. It precisely names the target (chart config for draw-mode cells) and the action (configure), leaving no ambiguity about what the tool 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 provides detailed contextual guidance on how to use the tool, including combining rules, when numeric-x charts cannot be combined, and when pie/scatter/stackedBar render only as single-query charts. It does not explicitly name alternative tools, but the unique scope makes exclusions unnecessary and the usage context is strong.

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 the full burden and does so thoroughly: it flags view="editor" as destructive, explains that it discards result and snapshot, clears presented mode, and that the response carries mode:null and result_discarded:true, while also noting the markdown no-op/null-reporting behavior.

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

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

Front-loads the core action and then layers behavior in a readable progression from general to cell-type-specific. It is dense and a touch long, with some overlap between the height guidance and the schema constraints, but nearly every sentence adds operational 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?

No output schema exists, and the description goes further than required by describing the response fields (mode:null, result_discarded:true) and the null-reporting behavior for markdown and empty cells. For a 5-required-param mutation tool with no annotations, this is 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 coverage is only 60%, but the description compensates heavily: null preserves, "auto" restores content/result-driven sizing, numbers pin, plus cell-type-specific minimums (86px polished markdown title, chart result ≥296px, table ≥100px) and the markdown caveat that result_height and view are ignored.

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 (resize) and resource (cell) plus the secondary capability of choosing pane view, and uses precise terminology (semantic pane dimensions in CSS pixels) that separates it from siblings like set_cell_layout or set_cell_mode.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear per-context usage rules (SQL/draw cells vs markdown cells, null to preserve, "auto" to restore), which tells the agent when a given argument shape applies. It does not, however, name any alternative sibling tool or state when NOT to use this one, so it stops short of explicit routing guidance.

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

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

With no annotations, the description carries the behavioral load well: it discloses that the whole config is replaced (PUT), that highlight_config: null clears it, that one config applies per cell across every statement's grid, and that grids lacking the column are unaffected. It omits auth/permission requirements and any error behavior.

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 first sentence front-loads the purpose and the behavioral facts (PUT semantics, clearing, per-cell scope) come next. The color list partially duplicates the schema enum, but the example and pairing advice are dense and earn their 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?

For a mutation tool with no annotations and no output schema, the description covers replacement semantics, clearing, rule evaluation ordering, and defaults. The notable gaps are the unexplained buffer_id/cell_id parameters and no mention of failure modes, but overall an agent can 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?

Top-level schema coverage is low (33%) and cell_id/buffer_id are undocumented anywhere, but the description compensates for highlight_config with a concrete example, the theme-aware hue palette, and the red/green loss-gain convention. Much rule detail (kinds, ops, defaults) already lives in the nested schema, so added value is moderate.

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+resource (set/clear highlight rules on a run-mode cell's result grids) and immediately scopes it with '(trend coloring)'. It is clearly separable from siblings like set_cell_chart_config, set_cell_autorefresh, and set_cell_mode.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It names a companion tool ('Pair with set_cell_autorefresh so the grid ticks') and gives a concrete typical watchlist example that shows intended usage. It does not, however, state explicit when-not conditions or name an alternative tool for related coloring needs.

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

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

No annotations are provided, so the description carries the full burden. It discloses the 12-column width cap, that height is derived from semantic pane dimensions, and the return shape including that editor-only and markdown cells report mode null and markdown also reports view null. It omits mutation side effects and permissions, but the behavioral disclosure is unusually rich for an unannotated tool.

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

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

Front-loads the core action in the first sentence, then adds grid semantics and return details. Three sentences, each earning its place, though the return-value clause is somewhat dense since no output schema exists.

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 no output schema, the description appropriately explains the response; with no annotations, it covers the safety-neutral mutation context reasonably. Gaps remain around unresized cells' behavior and validation failures, but nothing essential to calling it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% for 5 parameters. The description adds real meaning for x/y/w ('integers in the react-grid-layout grid; width is limited to 12 columns'), but buffer_id and cell_id receive no explanation, so it only partially compensates for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Position') plus resource and scope ('a single cell in grid mode'), and explicitly names set_cell_dimensions as the sibling for a different operation. An agent can distinguish it from set_layout_mode and set_cell_dimensions without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives the operating context ('in grid mode') and an explicit alternative: 'Use set_cell_dimensions to resize a cell or change its view.' It does not cover edge cases or when this tool is inappropriate, but the primary routing decision is clear.

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 the burden of behavioral disclosure. It does disclose a key behavior (hides other cells) and the null reset behavior, but it does not clarify persistence, permissions, or any other side effects beyond the view-level hiding.

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, front-loaded with the main action, and every word adds value. It is neither over-specified nor under-specified in length.

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 two-parameter tool, the description covers the core effect and the null behavior, but it leaves gaps like the meaning of buffer_id, how it differs from 'set_cell_view_maximized', and any potential return or persistence details. It is adequate but not 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 only 50% (buffer_id has no description). The description adds little for cell_id, essentially restating the schema's 'or null to clear' as 'or null to restore normal layout', and provides no information about buffer_id, failing to compensate for the low 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 states the action ('Spotlight one cell') and its effect ('Hides other cells'), making the tool's purpose unambiguous. However, it does not differentiate itself from the very similar sibling tool 'set_cell_view_maximized', which could cause agent confusion.

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 (to focus on a single cell) and mentions the null behavior for restoring the layout. It does not explicitly mention alternatives or when not to use it, especially given the existence of a nearly identically named sibling tool.

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

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

With no annotations provided, the description carries full responsibility and does so well. It discloses auto-execution behavior for draw mode, and the multi-series anchoring rules (first query's timestamp becomes x-axis, subsequent queries add series). These are important behavioral traits beyond what the schema can convey. No contradictions with annotations exist because none are present.

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 four sentences that front-load the core purpose, then add a critical warning and a multi-series tip. Every sentence earns its place; there is no filler or redundant restating of the tool name or schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is relatively simple, but has nuance in multi-series behavior. The description covers the main action, the auto-execution side effect, and advanced usage with multiple SELECT statements. No output schema exists, so return values aren't required. It provides complete context for an agent to use 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?

The schema has zero parameter descriptions, and the description only elaborates on 'mode' semantics by specifying run vs draw output. It does not explain buffer_id or cell_id, which are required parameters, leaving two of three params underspecified. Some value is added for mode, but it's insufficient for an agent to know how to populate the ID 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 opens with 'Switch a SQL cell between run (table output) and draw (chart output)', which is a specific action and outcome. It clearly distinguishes from siblings like run_cell and set_cell_chart_config by focusing on the mode toggle and resulting output type. No ambiguity.

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 warns 'Draw cells auto-execute — do not call run_cell afterwards', providing a direct when-not-to-use guideline for an alternative sibling tool. It also explains the multi-series usage scenario with multiple SELECT statements. However, it doesn't explicitly compare with chart-configuration siblings like set_cell_chart_config, but the auto-execute warning covers the key risk.

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 the transparency burden. It discloses the null-to-clear behavior, the display label rendering, and the chart title side effect. It does not mention error handling or permissions, but these are less critical for a simple setter.

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 short sentences, each with a distinct purpose: the first states the primary action and UI context, the second covers applicability and the clear behavior. 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?

For a simple setter with 3 parameters and no output schema, the description covers the core functionality, the null case, and the chart-cell nuance. It lacks details on return values or errors, but those are not essential given the tool's simplicity.

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 adds meaningful context for the 'name' parameter (display label, chart title, null to clear), but it does not clarify buffer_id or cell_id, which have no schema descriptions. With only 33% schema coverage, this is a partial gap, but the main parameter is well covered.

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 ('Set or clear') and the resource ('a cell's name'), and even adds the nuance that for chart cells it becomes the chart title. This distinguishes it from sibling cell-editing tools like set_cell_layout or set_cell_mode.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly says 'Applies to any cell' and describes the special behavior for chart cells, giving clear context for when to use it. It does not name alternatives or exclusions, but the specificity of the purpose makes the appropriate scenario obvious.

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 of behavioral disclosure. It states the action 'Switch' implies a mutation but does not disclose side effects, persistence, permissions, reversibility, or any impact on notebook state. This is a significant gap for a mutation tool with no annotation support.

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 concise sentence that is front-loaded with the verb and resource. Every word earns its place, with no redundancy or unnecessary detail. It is an example of efficient, clear communication.

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?

While the tool is simple (2 params, one enum, no output schema), the lack of parameter descriptions in the schema means the description must fill the gap. It covers the core purpose but leaves 'buffer_id' unexplained. With no annotations or output schema, this is minimally viable but has clear gaps in parameter semantics.

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 only hints at the 'mode' parameter by naming 'list and grid layouts' but does not explain the 'buffer_id' parameter or how it maps to the notebook. The enum already documents mode values, so the description adds no value beyond what the schema 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 'Switch' with resource 'a notebook' and clearly specifies the scope 'between list and grid layouts'. It distinguishes itself from sibling tools like set_cell_layout by targeting notebook-level layout rather than cell-level, making its purpose 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 no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. It simply states what it does, leaving the agent to infer usage from the name and siblings. There is no mention of when to prefer this over set_cell_layout or other layout-related tools.

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 the full burden and does well: it discloses that DDL/DML cells are skipped, that auto-refresh never executes a write, that the reset is atomic, and that nothing re-runs. It omits authorization/permission requirements and any return or confirmation behavior, which keeps it short of a 5.

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

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

Front-loads the core purpose, then layers override relationships, exclusions, and parameter semantics. Dense but nearly every clause earns its place; the value/reset explanation is somewhat verbose but justified by the zero schema coverage.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema and no annotations, so the description must stand alone for a 3-required-param mutation tool, and it largely does — covering scope, inheritance, exclusions, and two of three parameters. The unexplained buffer_id is the main remaining gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is essentially 0% (only the interval-string variant hints at format), so the description must compensate. It explains value thoroughly (true=adaptive, false=no polling, or fixed interval with range 50ms–60m and examples) and explains reset_cell_overrides including its atomicity, but leaves buffer_id undocumented and doesn't note that all three are required.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Set the notebook-level auto-refresh default') and immediately scopes it to cells showing a chart or a grid. It distinguishes itself from the sibling set_cell_autorefresh by naming it and defining the override relationship, so the agent can tell them apart without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly describes inheritance semantics (cells without a per-cell value inherit this default), the override rule (set_cell_autorefresh wins), the exclusion (DDL/DML cells skipped), the pre-state ('Until this is set, nothing polls'), and the effect of reset_cell_overrides. This is genuine when-to-use and what-happens 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, the description carries the full burden and does so thoroughly: it discloses overwrite-before-save behavior, auto-save, precise result-carryover semantics by statement content, and when results are cleared. This is far more transparent than a generic 'update' statement.

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?

Four dense sentences, each earning its place: action, side-effect behavior, intended use, and read-source warning. The most important fact is front-loaded, and the warning is placed at the end without padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation with no annotations and no output schema, the description covers purpose, destructive consequences, result carryover, and a data-loss-prevention read pattern. It only omits return/error behavior, which is not necessary for selecting or invoking 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?

The schema has 0% description coverage and the description does not explicitly define buffer_id or cell_id, though their names are self-explanatory. It adds important semantics for value as the full replacement content—especially the warning about non-truncated reads—so it partially compensates for the missing schema descriptions but not completely.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with 'Replace a cell's value', a specific verb and resource, and immediately conveys the tool's purpose. The follow-up 'Use to fix a broken SQL cell' clarifies when this mutation is relevant, making it easy to distinguish from siblings like get_cell, run_cell, or add_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?

Provides clear usage context: use it to fix a broken SQL cell, and when editing a long cell, read the full value with get_cell using get_full_content: true rather than a truncated preview. It does not explicitly state when not to use it or name sibling alternatives, so it stops short of a 5.

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 the full burden. It discloses that the tool only checks syntax correctness (not execution), implying a non-destructive read-only operation, and specifies use of QuestDB's validator. It does not describe error handling or return format, but the core behavioral trait is clear.

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, each earning its place: first explains purpose, second gives usage directive. No redundancy, front-loaded with the most important 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's simplicity (one parameter, no output schema), the description is largely complete. It states what the tool does and when to use it. It could mention return behavior, but for a validation tool the purpose is clear enough for an agent to select and invoke 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?

The input schema covers 100% of the single parameter with description 'The SQL query to validate', so the baseline is 3. The tool description adds no further detail about query format, length limits, or constraints 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?

Description clearly states the specific verb 'validate', the resource 'SQL query', and the mechanism 'QuestDB's SQL syntax validator'. This distinguishes it from sibling tools like run_query and get_tables, which have different purposes.

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 usage context: 'All generated SQL queries should be validated using this tool before responding to the user.' This gives a clear directive on when to use the tool, though it does not mention alternatives or exclusions explicitly.

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 behavioral burden. It discloses blocking behavior, timeout and retry limits, return payloads for each outcome, the need to show userMessage verbatim, and permission-scope implications with PERMISSION_DENIED fallback. This is comprehensive.

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 long but information-dense, with each sentence serving a purpose (prerequisite, timeout behavior, failure handling, permission scopes). It is front-loaded with the most critical prerequisite. Slight verbosity in permission explanations, 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?

For a polling tool with one optional parameter, no output schema, and no annotations, the description covers everything an agent needs: when to call, what to expect, how to handle each outcome, and follow-up actions. No gaps found.

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%, but the only parameter is timeout_ms, which has a schema description already. The description adds the default value and intent ('poll length'), plus a test use case, which is slightly more than schema. Baseline 3 is raised due to the tiny parameter set.

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: polling for completion of pairing started by get_pairing_credentials. It specifies the blocking behavior, timeout semantics, and distinguishes itself from credential acquisition, making it easy to differentiate from siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states a hard prerequisite (showing credentials) and warns against calling without it. It also provides guidance on when to call again after timeout and when to stop polling due to incompatible bridge. Alternatives are implied through the flow.

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