mcp-server-questdb
OfficialServer Quality Checklist
Latest release: v0.3.0
- Disambiguation4/5
Most tools have clearly distinct purposes with detailed descriptions. The only real confusion risk is between set_cell_maximized (hide other cells) and set_cell_view_maximized (fill cell with result), which sound nearly identical, plus some overlap between get_cell, list_cells, and get_notebook_state at different granularities.
Naming Consistency5/5All tool names follow a consistent verb_noun snake_case pattern (get_, set_, create_, delete_, run_, validate_, wait_). The naming clearly suggests the action and target, and even similar operations like set_cell_mode vs set_cell_chart_config are distinct.
Tool Count2/5At 34 tools, this is well beyond the 25+ threshold for 'too many'. While the notebook-editing domain is complex, many set_cell_* variants could be consolidated into a single update_cell_config tool, and the sheer volume makes the surface harder to navigate.
Completeness5/5The tool surface thoroughly covers the full workflow: pairing, database querying, schema introspection, SQL validation, documentation lookup, and complete notebook/cell lifecycle management (CRUD, layout, chart config, autorefresh, running). There are no obvious dead ends or missing operations.
Average 4.1/5 across 34 of 34 tools scored. Lowest: 2.7/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 24 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is failing
This repository is licensed under Apache 2.0.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
This server has been verified by its author.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior1/5
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.
Conciseness5/5Is 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.
Completeness2/5Given 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.
Parameters1/5Does 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.
Purpose5/5Does 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.
Usage Guidelines2/5Does 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.
- Behavior2/5
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.
Conciseness4/5Is 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.
Completeness2/5Given 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.
Parameters2/5Does 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.
Purpose5/5Does 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.
Usage Guidelines2/5Does 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.
- Behavior2/5
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.
Conciseness5/5Is 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.
Completeness2/5Given 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.
Parameters2/5Does 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.
Purpose5/5Does 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.
Usage Guidelines2/5Does 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.
- Behavior2/5
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.
Conciseness5/5Is 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.
Completeness3/5Given 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.
Parameters2/5Does 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.
Purpose5/5Does 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.
Usage Guidelines2/5Does 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.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only says 'Get' and 'runtime details/statistics', but does not disclose what these statistics include, whether the operation is read-only (although implied), whether permissions are needed, or error behavior. This is insufficient for a tool with zero 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the verb and resource clearly, with no filler or redundant words. It is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool, the description is minimal but lacks details on the return format or what 'runtime details/statistics' actually encompass. With no output schema, an agent may not know what to expect from the invocation, which leaves the description incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents the single parameter with a description, so the tool description adds no additional meaning. With 100% schema description coverage, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb 'Get' and a specific resource 'table or materialized view', and the phrase 'runtime details/statistics' distinguishes it from siblings like get_table_schema which returns structure. This makes it unambiguous 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.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives like get_table_schema or get_tables. It implies usage for runtime statistics but does not state exclusions or contextual cues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness3/5Given 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.
Parameters2/5Does 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.
Purpose4/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It clearly implies a read-only operation ('Get') and specifies the return type (DDL), but does not mention error handling, permissions, or whether the table must exist. This is adequate for a simple getter but lacks additional 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no filler. It conveys the necessary information in a compact, front-loaded manner.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter and no output schema, the description sufficiently covers purpose and parameter. It could be improved with usage guidance or notes on return format, but the simplicity of the tool makes this a near-complete description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with table_name described as 'The name of the table or materialized view to get schema for'. The tool description reinforces this (mentions table or materialized view) but adds no extra semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Get') and resource ('full schema definition (DDL) for a specific table or materialized view'). It implicitly distinguishes from siblings like get_tables (list tables) and get_table_details (likely non-DDL details) by emphasizing DDL, but does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 get_table_details or validate_query. The description only states what the tool does, leaving the context of use entirely implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness2/5Given 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.
Parameters2/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of disclosing behavior. It states the scope (all tables and materialized views) but does not describe the return format, ordering, inclusion of system tables, or whether the list contains names only or full metadata. This is a significant gap for a read-only tool without annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence with no redundant words. It front-loads the action and resource, making it easy to scan and understand.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (zero params), but there is no output schema, so the description should explain what information is returned for each table/view (e.g., names, schema, type). Without this, an agent cannot fully predict the tool's response, leaving a notable completeness gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool accepts zero parameters, so the schema fully covers parameter definition (100% coverage). The description adds no parameter-specific details, but none are required since there are no inputs. Baseline of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and clearly identifies the resource: a list of all tables and materialized views in the QuestDB database. It unambiguously differentiates this from siblings like get_table_schema and get_table_details, which focus on individual table properties.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for enumerating all tables/views, which is a clear context, but it does not explicitly state when to choose this over other table-related tools or mention any exclusions. Basic implied usage only.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses stateful behavior ('since your last fetch'), coalescing of typing events, and the session-start fallback. This is meaningful behavioral context beyond a simple read, though it does not mention output format or potential side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is unnecessarily long and not front-loaded. It starts with instructions about pairing and workspace state, which are not about this tool's own functionality. The core purpose appears in a later paragraph. The first two sentences do not earn their place for this tool's description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no parameters and no output schema, the description covers the essential aspects: what it returns, when to use it, and the coalescing behavior. It is reasonably complete, though the unrelated pairing instructions add noise rather than missing information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100%. Per the rubric, baseline is 4 for 0-param tools. The description adds no parameter information, which is fine since there are none to explain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Return the digest of user edits to the notebook since your last fetch (or session start)' and explains the purpose as detecting changes. It distinguishes from siblings like get_workspace_state by focusing specifically on user edit digest. However, the purpose is not front-loaded; it is buried after unrelated pairing instructions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage context: 'call get_workspace_state at the start of each notebook turn; the digest of edits since your last fetch is in get_recent_user_actions' and 'Use this to detect that the user changed something the agent might want to react to.' This provides clear when-to-use guidance, though it does not explicitly mention alternatives or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the exact fields returned and explicitly notes that cell data values are excluded, which clarifies scope. While it doesn't mention side effects (none expected for a listing operation), the description is transparent about output limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that leads with the action and resource, then enumerates the return fields without unnecessary words. It also includes a concise note about the absence of cell data, making every word useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool with one parameter and no output schema, the description sufficiently covers the return payload, including the omission of data values. It doesn't specify ordering or pagination, but those are not critical for a basic listing operation. The description is complete enough for an agent to understand what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage with a clear description of buffer_id referencing the notebook_context prefix. The tool description adds no further parameter-level detail, so the baseline score of 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' combined with the resource 'cells' and scoping clause 'in a notebook'. It further distinguishes itself from sibling tools like get_cell by listing the exact return fields (id, type, preview, position, mode, last-run status), making its purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives like get_cell (for a single cell's details) or add_cell/update_cell/delete_cell for modifications. It lacks any mention of typical use cases or exclusions, so an agent must rely on sibling names to infer appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness3/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It explains the semantics of the 'value' parameter (adaptive, off, or fixed interval), which is useful. However, it does not disclose side effects, prerequisites, or behavior when the cell is not in draw-mode.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise, well-structured sentences. The first states the action and target, the second details the parameter options in a compact format. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple setter with no annotations or output schema, the description covers the core purpose and value semantics sufficiently for invocation. It could mention error cases or persistence, but these are not critical for basic use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description thoroughly explains the 'value' parameter, including allowed boolean and string forms. However, it does not describe 'buffer_id' or 'cell_id', and the schema has no property descriptions. These are relatively self-explanatory identifiers, so partial compensation is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Set auto-refresh polling' for a specific resource 'a draw-mode cell's chart'. It distinguishes this tool from other set_cell_* siblings by focusing on auto-refresh behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context that this applies to draw-mode cell charts, implying when it's relevant. Does not explicitly mention alternatives or when not to use, but the context is specific enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears the burden of behavioral disclosure. It does add valuable details about the coordinate system and the w ≤ 12 constraint, which are not apparent from the schema. However, it does not disclose the mutating nature of the operation, potential validation/error behavior, or what happens if the cell is not in grid mode.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, containing only two sentences, with the key information front-loaded. Every word adds value: it states the purpose and the essential grid constraint without unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a simple layout operation but lacks some context. It does not mention what happens if the operation fails, whether it triggers any side effects (like re-rendering), or whether buffer_id/cell_id must refer to an existing cell in the current workspace. Given the absence of annotations and output schema, this is a noticeable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides zero descriptions for its 6 parameters, so the description must compensate. It explicitly defines x/y/w/h as integers (clarifying that the 'number' type should be an integer) and imposes the w ≤ 12 bound, which is crucial. The buffer_id and cell_id parameters are reasonably inferable from their names, but the description still leaves some interpretation to the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Position'), the resource ('a single cell'), and the mode ('in grid mode'). It effectively distinguishes this tool from sibling tools like set_cell_mode or set_layout_mode, which deal with other aspects of cell configuration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'in grid mode' gives a clear context for when this tool is applicable, implying it should be used when the layout mode is set to grid. However, it does not explicitly mention alternatives or exclusions (e.g., 'use set_layout_mode to switch modes first'), so it stops short of the highest score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the tool overwrites preemptively and that cells are auto-saved, which are important behavioral traits. It also warns about the risks of truncated reads, adding valuable context beyond the basic operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each earning its place. The primary action is front-loaded, followed by a behavioral note and a practical usage caution. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with no output schema and no annotations, the description provides enough context for the main use case and includes a critical warning about long cells. However, it omits any explanation of return values or buffer_id semantics, leaving minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the three parameters. Only 'value' and 'cell_id' are vaguely inferable from the phrase 'cell's value,' but 'buffer_id' is entirely unexplained. The description adds very little semantic meaning beyond the parameter names themselves.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Replace a cell's value,' which is a specific action with the resource clearly identified. It also adds behavioral details ('Overwrites preemptively — cells are auto-saved') that distinguish it from related tools like add_cell or run_cell.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage context: 'Use to fix a broken SQL cell' and provides detailed guidance on editing long cells (base the new value on a non-truncated read using get_cell with get_full_content: true). It does not explicitly state when to avoid this tool, but the alternatives are implied through the reference to get_cell.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses the return type (text), the content of the response, and the effect of include_user_events=true. It also implies this is a safe, repeatable call ('start of every notebook turn'). However, it does not explicitly state it is read-only or mention any failure/error behavior, so it doesn't fully cover all behavioral aspects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is not optimally structured. The first paragraph is largely about pairing (a different tool) and repeats 'at the start of each notebook turn' that also appears in the second paragraph. The core purpose is buried in the second paragraph, making it less front-loaded than ideal. It could be tightened without losing key context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter with one optional boolean parameter and no output schema, the description provides substantial context: what the return includes, when to call it, and how the parameter affects the response. It also points to sibling tools for related functionality. It does not describe an output format in detail, but given the tool's simplicity, this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter include_user_events is clearly explained: 'Pass include_user_events=true to also receive the digest of edits the user made since your last fetch.' This adds meaning beyond the bare boolean type in the schema, making the parameter's purpose and effect unambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns 'the current workspace + notebook context as text' and specifies what that context includes (active notebook, cells, layout mode, chart configs, last-run statuses). It distinguishes itself from siblings like get_recent_user_actions by noting that tool handles the user edit digest, but the purpose is slightly obscured by the pairing preamble at the beginning.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: 'call get_workspace_state at the start of each notebook turn'. It also provides an alternative by pointing to get_pairing_credentials if BRIDGE_NOT_PAIRED occurs, and directs user-event digest needs to get_recent_user_actions. This is excellent context for an agent deciding between tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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 thoroughly explains the effects on narrow vs. wide cells and what happens when value is false, giving a complete picture of the toggle's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the primary action, and every sentence adds useful detail. No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple toggle tool, the description covers the behavior well and gives enough contextual cues. It lacks an explicit mention of what the parameters mean beyond value, and does not differentiate from set_cell_maximized, but overall the behavior is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description does not define buffer_id or cell_id. It only implicitly explains value as the boolean toggle ('When this is false'). This leaves the identity parameters unexplained, failing to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Toggle whether the cell's result view (chart OR table) fills the cell, hiding the editor.' This clearly distinguishes it from siblings like set_cell_maximized, which would affect the entire cell rather than the result view within it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when the tool applies: 'Applies to any cell that has a result — not just charts.' It does not explicitly call out alternatives or exclusions, but the context is sufficient for an agent to understand the typical use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters2/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the transparency burden. It discloses background execution (never switches active tab), notification to user, cell ID regeneration, clearing of last-run results, and the label/placement behavior. This is rich, honest behavior disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the core purpose, then progressively adds details. Every sentence contributes unique information: what is copied, the background behavior, and the conditional for activate_notebook. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter, no output schema, and no annotations, the description comprehensively covers behavior, side effects, user experience, and edge-case instruction. It leaves no critical gaps for an agent to misuse the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter buffer_id has 100% schema coverage, so the schema already describes it. The description refers to 'the original' and 'source' implicitly but does not add additional parameter-level meaning beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Duplicate a notebook tab' with a specific verb and resource. It distinguishes from siblings like duplicate_cell and create_notebook by detailing what gets copied (cells, layout), the naming convention, and placement right after the original.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context for when to use (duplicating a notebook) and explicitly cautions against calling activate_notebook unless the user asks to be taken to the copy. However, it does not explicitly mention alternatives like create_notebook for blank notebooks, so it lacks exhaustive when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure and does so excellently. It details the semantics of the 'type' field (markdown vs SQL omission), preview truncation at 120 chars, the presence of 'preview_truncated' and 'full_length' flags, and explicitly states what is not returned (cell data values, columns/rows/count).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet information-dense, with three purposeful sentences. It front-loads the core purpose, then adds essential details about type semantics and preview truncation. No word is wasted, and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and output schema, the description provides a remarkably complete picture of the tool's behavior. It covers what is included (layout, cells, previews, type, statuses), what is excluded (data values, columns/rows/count), and critical edge-case behavior (preview truncation flags). This is more than sufficient for an agent to correctly invoke and interpret the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, buffer_id, is not explicitly explained. The description refers to 'a notebook' but does not state that buffer_id is the notebook's identifier or how to obtain it. With 0% schema description coverage, the description should compensate more thoroughly; it only provides indirect contextual meaning, not explicit parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool provides a 'full structural snapshot of a notebook' and enumerates its contents (layout, cells with previews, kind via type, last-run statuses). It differentiates from sibling tools by explicitly excluding cell data values and columns/rows/count, making its specific role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool: it is appropriate for structural/snapshot needs, not for cell content or write-back. It does not explicitly name alternative tools (e.g., get_cell), but the exclusions and the caveat 'a preview is never a cell's real content to write back' strongly imply the correct use cases and boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: sequential execution stops on first error, return format with per-statement statuses, markdown cells are skipped, and success is only when all statements succeed. It also mentions the 'write' permission requirement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence provides essential information. It is well-structured, starting with the primary action, then behavioral nuances, return format, alternatives, and special cases.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description covers return types, failure semantics, skipped markdown behavior, permission requirements, and distinguishes from sibling tools. It is thorough and actionable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description does not explain the roles of buffer_id and cell_id. While the names are somewhat self-explanatory in context, the description does not compensate for the lack of schema documentation, leaving ambiguity for an agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool executes a SQL cell with a specific verb and resource. It further distinguishes itself by noting it is the only path for agent-initiated DDL/DML and contrasts with run_query for data retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: use run_query instead when data results are needed, and note that apply_notebook_state and add_cell never auto-run writes. It also states permission and consent requirements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
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 4 KB cap, truncated/full_length markers, the fact that truncated values are not real content, the explicit warning never to write back a truncated value, and the errors-above-1 MB behavior for get_full_content. This is exemplary behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence adds value. It front-loads the core purpose, then layers critical caveats (no query data, truncation, write-back warning) in a logical order with imperative warnings. Length is justified by the risk of data corruption if truncated values are written back.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, the description is remarkably complete. It covers return fields, type semantics, truncation behavior, error behavior, and safety instructions. The only minor gap is the lack of explicit guidance on what buffer_id and cell_id are, but those are standard identifiers in this API context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, with only get_full_content described. The description adds substantial meaning to get_full_content (verbatim value, cap, required before rewriting) and explains the cell type semantics (markdown vs SQL) which maps to the returned 'type' field. buffer_id and cell_id are self-evident from their names and context, so the description adequately compensates despite low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Get') and resource ('cell'), and enumerates the exact details returned: value, type, UI flags, chart config, last-run status, and trimmed error. It also clarifies the meaning of 'type' and explicitly excludes query result data, which distinguishes it from sibling tools like run_query and list_cells.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context on when to use this tool by stating what it never includes (query result data) and when to use get_full_content: true (before rewriting a truncated cell). However, it does not explicitly name alternative tools or state when not to use this tool in favor of a sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
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.
Conciseness4/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
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.
Conciseness4/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are given, but the description fully discloses return values (cell id, per-query status), the absence of row/column data, markdown rendering behavior, and run-flag semantics including the skipped response. This is thorough and exceeds what the schema alone offers.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized for the tool's complexity. It is front-loaded with the main purpose and each sentence carries important information without fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers all essential aspects: return values, execution behavior, edge cases (markdown, DQL-only, skipped status), and usage guidance. It fully enables correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even with 80% schema coverage, the description adds substantial meaning: run is clarified as DQL-only with a consent requirement, sql explains multi-statement draw-mode behavior, and type explains markdown semantics. This goes well beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool appends a cell to a notebook, distinguishing it from update/delete/run cell siblings. It also explains the markdown variant, which differentiates the two cell types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly directs the agent to obtain user consent and call run_cell instead of setting run=true, and clarifies that DDL/DML and markdown are never executed. This provides clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the behavioral disclosure burden, and it excels. It discloses critical side-effect behavior: cells missing from the request are DELETED; DDL/DML statements are NEVER auto-executed (skipped: true) so applying state can never trigger write side effects; markdown cells never auto-run; charts with auto_refresh=true render without a separate run_cell call; and the response includes a runs array with per-cell outcome details. It also warns against sending values reconstructed from truncated reads and explains the state-freshness gate. This is far more than typical.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long, but every sentence carries a specific behavioral or usage constraint essential for correct invocation. It is front-loaded with the core purpose and usage contrast, then systematically covers deletion semantics, value/preserve_value, auto-run behavior, DDL/DML safety, response format, and the precondition to call get_workspace_state. The density is justified by the tool's complexity; there is no filler or tautology.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's high complexity (5 required params, nested cell objects, rich side effects), this description is exceptionally complete. It covers the entire lifecycle of an apply call: prerequisites (get_workspace_state first), the atomic full-replace semantics, deletion of missing ids, execution behavior (charts auto-render, run cells auto-execute except DDL/DML and markdown), and the response shape (runs array with success/error/skipped). The guidance on preserve_value and never reconstructing SQL from truncated reads preempts common misuse. There is no gap left for the agent to guess.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even though schema description coverage is 80%, the description adds substantial meaning beyond the schema. For `cells` it explains that the array is the COMPLETE desired list with deletion semantics; for `value` it mandates verbatim/complete SQL and warns against preview/truncated sources; for `preserve_value` it explains the preference and when it is the only safe option; for `mode` it clarifies defaults; for `chart_config` it explains that apply is a full PUT and how queries array maps to statements; and for `variables` it details ordering and DECLARE semantics. The description compensates for and extends the schema rather than repeating it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource+scope: 'Bulk-apply the entire desired state of a notebook in one atomic call.' It clearly distinguishes from siblings by explicitly contrasting with 'update_cell or set_cell_*' for small operations and by positioning itself as the replacement for chained add/update/set calls when composing a multi-cell layout from scratch or restructuring. This leaves no ambiguity about what the tool does and how it differs from alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage guidance is explicit and actionable: it states when to use (bulk edits spanning multiple cells, creating a notebook from scratch, restructuring) and when not to (small operations use update_cell/set_cell_*). It also names the exact alternative flow it replaces and gives a hard prerequisite: 'Always call get_workspace_state first; the state-freshness gate applies.' This is exemplary when-to-use versus when-not-to-use instruction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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 states the tool blocks for up to `timeout_ms`, describes success and timeout payloads, explains the `permissions` scopes, and details the incompatible-bridge flow including required user-facing messages. This goes far beyond minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence adds necessary information about behavior, prerequisites, return values, or error handling. It is front-loaded with the core purpose and prerequisite, then systematically covers success, timeout, and incompatibility cases. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description must explain return values, error cases, and side effects. It covers all of these: success payloads, timeout retry semantics, permission-denied behavior, and incompatible-bridge instructions. It is complete enough for an agent to use this tool correctly without additional information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema already documents `timeout_ms` at 100% coverage, the description adds valuable context: it explains the default (50 s), the maximum (50 s), the polling behavior, and that it is sized to fit under typical MCP client timeouts. This enriches the parameter's meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: "Poll for completion of pairing started by `get_pairing_credentials`." This clearly differentiates it from the sibling `get_pairing_credentials`, which starts the pairing, while this tool waits for completion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It states an explicit prerequisite (show credentials first), explains when to call again (on timeout), and when to stop (incompatible bridge). It also warns against calling without showing credentials because it 'only burns 50 s of polling while the user sees nothing actionable.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/questdb/mcp-server-questdb'
If you have feedback or need assistance with the MCP directory API, please join our Discord server