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

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

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

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

Two concise sentences, front-loaded with the main action and followed by a necessary usage constraint. No superfluous wording.

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

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

The tool is simple with only two parameters and no output schema. The description provides the main purpose and the critical precondition. It doesn't cover edge cases like activating an already-open tab or stale buffer_ids, but given the simplicity, the description is sufficient.

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

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

Schema coverage is 100% and each parameter has a clear description. The tool description itself adds little beyond the schema, but the schema already documents buffer_id and cell_to_focus well, including the null option for cell_to_focus. Baseline 3 is appropriate.

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

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

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

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

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

Explicit when-to-use guidance is provided: 'ONLY call this after the user has explicitly agreed to be taken to the notebook.' It also gives a clear exclusion: 'Never call it to auto-switch while the user is working elsewhere.' This is strong, actionable usage guidance.

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

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

With no annotations, the description carries full disclosure burden and does so thoroughly. It reveals return behavior (new cell id, per-query status array), execution semantics (invalid statements skipped, reads run in parallel), and safety caveats (DDL/DML never auto-run, no row/column data returned). This goes well beyond a simple 'adds a cell' statement.

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

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

The description is dense and front-loaded, starting with the action and return value before covering important caveats. It is fairly long, but the length is justified given the complexity of run semantics and markdown behavior. Every sentence adds meaningful information.

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

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

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

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

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

Schema description coverage is 80%, but buffer_id is undocumented in both schema and description. The description enriches sql (multi-statement chart overlay, markdown source), run (parallel reads, invalid statement handling), and type (markdown render-only). It does not add meaning for buffer_id or after_cell_id, though those are partly covered by the schema.

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

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

The description clearly states the core operation: 'Append a cell to the notebook.' It differentiates from sibling tools like update_cell, run_cell, and delete_cell by explicitly covering SQL vs markdown cell creation. The 'append' wording is slightly narrow given after_cell_id insertion, but the action remains unambiguous.

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

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

The description gives concrete conditional guidance: use type:'markdown' for prose cells, and explicitly warns that DDL/DML and markdown cells are never auto-run, advising 'Take consent from the user, then call run_cell explicitly.' It references run_cell semantics but does not explicitly contrast add_cell with update_cell or delete_cell, so alternative selection is not fully exhaustive.

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

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

With no annotations, the description carries full burden and pays it off: it discloses destructive deletion of missing cell ids, id generation, preserve_value semantics, DDL/DML statements never auto-executing, markdown never auto-running, parallel execution, skipped entries, and the runs[] response shape. These go well beyond a generic mutation description.

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

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

The description is dense and front-loaded, and nearly every sentence conveys a necessary caveat. However, it packs many critical behaviors into long flowing prose with semicolons rather than scannable structure; given the tool's complexity this is appropriate, but not maximally concise.

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

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

Covers preconditions (state-freshness gate, call get_workspace_state first), safety and destructive semantics, execution behavior, output response shape, and per-cell overrides. Despite no output schema, the description tells the agent what runs[] and error will contain, making it complete for a complex bulk operation.

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

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

Though schema coverage is high (83%), the description adds meaning the schema can't express: the cells array is a complete PUT that deletes omitted ids, preserve_value is safest on stale reads, apply happens atomically, and auto-executed read-only cells run in parallel. This materially improves parameter understanding.

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

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

Opens with a specific verb and resource: 'Bulk-apply the entire desired state of a notebook in one atomic call.' It explicitly contrasts with update_cell and set_cell_* for small operations, so an agent can distinguish it from siblings without reading their schemas.

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

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

Gives explicit when-to-use guidance ('bulk edits spanning multiple cells or creating a notebook from scratch'), names the alternatives for small operations, and states when to prefer this over chained add/update/set calls. It also mandates calling get_workspace_state first, which is actionable usage direction.

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

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

No annotations provided, so description carries full burden. It discloses multiple behavioral traits: never shows query data, always background creation, never switches active tab, user sees notification and opens it themselves. These go beyond the schema and give critical operational expectations.

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

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

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

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

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

For a single-parameter background action with no output schema, the description covers purpose, side effects, user-facing behavior, and alternative invocation. It provides sufficient context for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, with the label parameter fully documented ('Label shown on the new notebook tab (max 100 characters). Pass null to use the default.'). The description adds no additional parameter semantics, so baseline 3 applies.

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

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

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

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

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

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

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It merely restates the tool's name ('delete a cell') and provides no information about side effects, irreversibility, or any other behavioral traits. This is effectively a tautology and offers no transparency beyond the name.

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

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

The description is a single concise sentence with no wasted words. It is appropriately sized for such a simple tool, though under-specification is penalized in other dimensions. The structure is front-loaded with the key action and object.

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

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

Given the lack of annotations, output schema, and schema parameter descriptions, the tool is under-specified. The description does not explain required parameters, the broader notebook context, or any behavioral consequences, making it insufficient for an agent to confidently invoke the tool.

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

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

Schema description coverage is 0% and the description does not mention either parameter (buffer_id or cell_id). The schema provides only types and requiredness, which is insufficient. The description fails to compensate, leaving parameter meanings entirely unexplained.

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

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

The description 'Delete a cell from the notebook' clearly states the verb (delete), resource (cell), and context (notebook). It distinguishes itself from sibling tools like delete_notebook and other cell operations, making the purpose unambiguous.

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

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

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

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

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

With no annotations provided, the description carries full weight and excels: it discloses that the action is a soft-delete, moves to history, is user-restorable, does not destroy query data, and makes chat bindings stale. This prevents misuse and sets correct expectations.

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

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

Three sentences, each earning its place: the action, the safety/recovery behavior, and the edge case with chat binding. No filler or redundancy; information is front-loaded and scannable.

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

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

For a simple deletion tool with one parameter and no output schema, the description covers all necessary context: what happens, what is preserved, and how to recover. It also distinguishes itself from siblings and addresses a specific consequence (stale binding), making it operationally complete.

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

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

The input schema already fully describes buffer_id (100% coverage) with context about where to find it. The description adds no additional parameter-level detail, but the schema is sufficient, matching the baseline for high schema coverage.

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

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

The description clearly states 'Archive (soft-delete) a notebook tab' with a specific verb and resource. It distinguishes itself from permanent deletion and names create_notebook for the stale binding case, effectively separating it from sibling tools.

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

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

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

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

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

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

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

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

The description is a single, front-loaded sentence with no filler. Every word ('Duplicate', 'cell', 'immediately after', 'original') adds meaning.

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

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

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

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

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

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

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

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

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

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

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

No guidance is given about when to use this tool versus add_cell or update_cell. There are no use-case scenarios, prerequisites (such as the cell existing or the buffer being writable), or exclusion conditions.

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

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

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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 it is exceptionally thorough. It explains live-only field semantics, that refreshing is reported separately from last_run_status, that markdown cells have type:'markdown' while SQL cells omit type, the 4 KB cap, truncation flags, and that a truncated value is not the cell's real content. This is far more transparent than typical descriptions.

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

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

The description is long and dense, but every sentence carries load-bearing information: output contents, live-only fields, refresh semantics, markdown vs SQL, truncation, and safe writeback behavior. The purpose is front-loaded and the critical warnings are grouped well, though the long parenthetical constructions make it harder to scan quickly.

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

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

Given that there are no annotations and no output schema, the description is remarkably complete for an agent to call the tool correctly. It covers the return value's composition, the cap and how to bypass it, the meaning and non-meaning of absence for live-only fields, and the dangerous destructive interaction of writing back truncated values. The only small gap is the semantics of buffer_id and cell_id, but those are standard identifiers and the context is sufficient.

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

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

Schema coverage is only 33%, so the description must compensate for undocumented parameters. get_full_content is well explained both in the schema and the description, but buffer_id and cell_id are never defined or contextualized beyond the tool name and the word 'cell'. The description adds meaningful semantics around truncation and content retrieval, but it does not fully compensate for the low schema coverage of the required identifiers.

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

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

The description names a specific verb and resource ('Get full details of a cell') and enumerates the exact content: value, type, UI flags, chart config, last-run status, and trimmed error. It also clarifies what the tool is not ('Never includes query result data'), distinguishing it from query/run siblings.

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

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

The description gives concrete usage guidance: it warns against writing a truncated value back via update_cell/apply_notebook_state, tells the agent to re-read with get_full_content: true first or use preserve_value: true, and explains when absence of live-only fields should not be interpreted as absence of activity. It does not explicitly enumerate sibling alternatives for when to choose this tool over list_cells or get_notebook_state, but the guidance is strong.

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

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

With no annotations present, the description carries the full behavioral burden and does so thoroughly. It discloses live-only field semantics, absence meaning, the independence of last_run_status from refresh, type conventions for markdown vs SQL cells, and preview truncation behavior. This is exemplary transparency.

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

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

The description is long but every sentence contributes essential behavioral nuance. It is front-loaded with the main purpose and then systematically details edge cases and limitations. The density is justified given the number of subtle return-value semantics.

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

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

There is no output schema, so the description must explain return semantics, and it does so comprehensively. It covers live-only fields, absence interpretations, refresh versus run status, type representation, omission rules, and preview truncation. An agent has enough information to interpret the result correctly.

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

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

The schema has one parameter, buffer_id, with 0% description coverage, and the tool description never mentions buffer_id or explains how to identify the target notebook. The parameter name is self-descriptive to a degree, but the description adds no meaning beyond the schema itself.

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

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

The description opens with 'Full structural snapshot of a notebook' and enumerates the exact contents (layout, cells with previews, kind, last-run statuses). This clearly identifies the verb and resource and differentiates it from sibling tools like get_workspace_state or get_cell.

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

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

The description provides clear context for what the tool returns and explicitly states what it does NOT provide: no cell data values, no columns/rows/count, and previews are not real content to write back. It lacks named alternatives, e.g., directing the agent to get_cell for full cell content, so it falls short of a 5.

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

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

No annotations are provided, so the description carries full burden. It discloses the tool's side effect of auto-opening the browser, the exact return fields (deep_link, ws_url, token, userMessage), the fact that it returns paired:true if already paired, and the behavioral guarantee of a timeout if the flow is not followed. This is comprehensive transparency beyond what any annotation would typically provide.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It indicates a read-only retrieval operation but does not describe return format, error handling, or any potential side effects. For a simple getter, it is adequate but lacks rich behavioral context.

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

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

The description is two sentences with no fluff. The first sentence front-loads the purpose, and the second adds a valuable efficiency note. Every word earns its place.

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

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

Given the simple two-parameter schema and no output schema, the description is mostly complete, but it fails to explicitly mention that users should first obtain the table of contents via get_questdb_toc to know valid item names. This prerequisite is only in the schema description, not the main tool description, leaving a slight gap.

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

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

Schema coverage is 100%, with detailed descriptions for both 'category' and 'items', including enum values and the exact-match requirement. The description adds little beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the action ('Get documentation') and the resource ('specific QuestDB functions, operators, or SQL keywords'), making it obvious what the tool does. It also implicitly differentiates from the sibling get_questdb_toc by focusing on specific items rather than listing all documentation.

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

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

The description provides context for when to use this tool: 'much more efficient than loading all documentation.' It also references the prerequisite of matching items to the table of contents in the schema, which implies a workflow with get_questdb_toc. However, it does not explicitly name the alternative tool or state when not to use it.

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

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

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

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

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

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

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

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

For a parameterless tool with no output schema, the description explains the purpose, content, and usage sequence. It is complete enough for an agent to invoke it correctly, though more detail on the return structure would be helpful.

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

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

The tool has 0 parameters, so the baseline is 4. The description adds context about the content of the TOC, which is sufficient given there is nothing to parameterize.

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

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

The description uses a specific verb 'Get' with a resource 'table of contents listing all available QuestDB functions, operators, and SQL keywords'. This clearly differentiates it from siblings like get_questdb_documentation, which presumably fetches detailed docs for specific items.

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

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

It provides explicit timing guidance ('Use this first') and the context ('before requesting specific items'), which implies a sequential workflow relative to get_questdb_documentation. However, it does not explicitly name alternative tools or state when-not to use this tool.

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

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

With no annotations, the description carries the full burden. 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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

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

No guidance is provided on when to use this tool versus alternatives like 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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, and it does so exceptionally. It explains live-only field semantics, clarifies that absence of those fields never means 'not refreshing' or 'not blocked,' and explicitly states that refresh does not change last_run_status. This prevents serious misinterpretations.

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

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

The description is longer than average, but every sentence earns its place: the main purpose is front-loaded, and the dense live-only clarification is essential for correct interpretation. No filler or redundant repetition of schema content appears.

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

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

Given no output schema and no annotations, the description thoroughly covers what an agent needs: the resource, accepted parameter, returned fields, live-only field semantics, and an explicit statement about what is not returned. Nothing critical is missing for correct selection and invocation.

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

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

Schema description coverage is 100%, so the schema already documents the buffer_id parameter and its source prefix. The description adds no additional parameter-level meaning beyond restating the notebook context, matching the baseline for high coverage.

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

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

States a specific verb and resource: list cells in a notebook. Enumerates the fields returned and explicitly says 'No cell data values,' which disambiguates it from sibling cell-content tools like get_cell.

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

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

The context of use is clear—listing notebook cell metadata—but it does not explicitly name alternatives or state when not to use this tool. The 'No cell data values' statement implies get_cell would be needed for content, but that is left to inference rather than stated.

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

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

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

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

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

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

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

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

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

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

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

The schema description coverage is 0%, and the description does not explain the parameters 'cell_id' or 'buffer_id' at all. The property names provide some hint, but the description adds no meaning beyond the schema, failing to compensate for the low coverage.

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

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

The description 'Swap a cell with the one below it' uses a specific verb ('swap') and resource ('cell'), clearly distinguishing the tool from its sibling 'move_cell_up' which swaps with the cell above. It unambiguously states what the tool does.

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

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

The description implies when to use the tool (when you need to move a cell down) but provides no explicit context about when not to use it or alternatives like 'move_cell_up'. The sibling tools list offers hints, but the description itself lacks direct guidance.

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

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

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

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

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

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

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

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

Given the lack of annotations and output schema, the description is incomplete for a mutation tool. It omits prerequisites, edge cases, and any behavioral context. The presence of move_cell_down as a sibling creates a pair, but the description doesn't explain how this tool fits into that context.

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

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

With schema description coverage at 0%, the description needed to explain the parameters. It does not mention cell_id or buffer_id at all, leaving their meanings to be inferred from names alone. The description adds no semantic value beyond the schema.

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

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

The description 'Swap a cell with the one above it' uses a specific verb ('swap') and resource ('cell'), and clearly distinguishes this from the sibling tool move_cell_down by specifying direction ('with the one above it'). This leaves no ambiguity about the tool's function.

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

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

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

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

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

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

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

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

The description is long but every sentence carries essential operational information. It is front-loaded with the core action and then layers execution semantics, return format, security, and exclusions without redundancy.

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

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

For a tool with no annotations and no output schema, this description covers everything an agent needs to call it correctly: execution model, expected results strings, no data returned, permissions, consent, and the markdown edge case. The only gap is parameter provenance, which is already reflected in the parameter_semantics score.

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

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

Schema coverage is 0%, so the description needed to explain buffer_id and cell_id, but it never mentions either parameter or how to obtain them. The word 'cell' gives some context, but an agent receives no guidance on the meaning or provenance of the two required parameters.

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

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

The first sentence states the action and resource precisely: 'Execute a SQL cell.' It then distinguishes itself from run_query ('You do NOT see columns, rows, or values — call run_query if you need data') and from apply_notebook_state/add_cell by being the only path that executes writes.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The input schema already fully describes both parameters (`sql` and `limit`) with 100% coverage, including default and max for `limit`. The description reinforces this by mentioning default limit 100 and max 10000, but does not add significant new parameter-level meaning beyond what the schema provides.

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

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

The description clearly states the tool's function: executing arbitrary SQL against QuestDB and returning result rows. It distinguishes itself from the sibling `run_cell` by explicitly noting that unlike `run_cell`, this tool returns data values.

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

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

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

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it delivers: it explains per-cell override semantics, engine-blocking of write cells, the `auto_refresh_blocked: "contains_write"` signal, markdown rejection, and the polling precondition. A mutation tool rarely gets this transparent.

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

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

The description is dense but every sentence carries distinct information. Purpose and differentiation come first, followed by applicability, blocking behavior, and value semantics. There is no filler or repetition.

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

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

Given no annotations and no output schema, the description is highly complete for a config setter: it explains the target, the alternatives, edge cases, and all value semantics. The only remaining gap is the lack of explicit definitions for `buffer_id` and `cell_id`, which are required parameters and left to inference.

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

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

Schema description coverage is 0%, so the description must compensate. It thoroughly documents `value` including true/false, fixed interval strings, and null-clearing behavior. However, `buffer_id` and `cell_id` are never explicitly described; their roles are only weakly implied by 'cell' and 'notebook default', leaving two of three required parameters under-specified.

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

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

The description states the exact action ('Set auto-refresh polling for a cell') and identifies it as a per-cell override of the notebook default, naming sibling set_notebook_autorefresh. This clearly differentiates it from the many cell-related and notebook-default sibling tools without ambiguity.

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

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

It explicitly names the alternative tool (set_notebook_autorefresh) and gives concrete applicability rules: works for chart and grid cells, DDL/DML cells never poll, Markdown cells are rejected, and polling requires a per-cell value or notebook default. This is explicit 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.

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

With no annotations, the description fully carries the behavioral disclosure burden. It explains auto-combine semantics, index-aligned query configs, the always-included first query, enabled:false opting out, required ohlc mapping for candlesticks, and patch semantics including replacement vs reset behavior. This is exemplary transparency.

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

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

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

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

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

This is a complex configuration tool with no output schema, yet the description thoroughly covers combine rules, per-query types, axis handling, numeric-x limitations, candlestick requirements, and patch semantics including rejection conditions. It leaves few open questions and is complete for the tool's complexity.

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

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

The schema covers 60% of parameters with descriptions, but the tool description significantly extends this by explaining index-alignment, replacement semantics for the queries array, conditionality of ohlc, axis behavior, and the meaning of x_column as the shared x-axis. It adds meaning far beyond the structured schema fields.

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

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

The description opens with 'Configure the chart for a draw-mode cell,' a specific verb+resource statement that clearly distinguishes this tool from sibling cell operations like set_cell_mode or set_cell_layout. It precisely names the target (chart config for draw-mode cells) and the action (configure), leaving no ambiguity about what the tool does.

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

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

The description provides detailed contextual guidance on how to use the tool, including combining rules, when numeric-x charts cannot be combined, and when pie/scatter/stackedBar render only as single-query charts. It does not explicitly name alternative tools, but the unique scope makes exclusions unnecessary and the usage context is strong.

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

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

With no annotations, the description carries the full burden and does so thoroughly: it reveals that h is not in column units, gives the exact pixel formula h*10+(h-1)*20, the 44px header, and chart padding behavior, plus worked examples. This is far beyond a generic mutation warning.

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

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

The description is long but dense and front-loaded with its purpose. Every sentence contributes either a formula, a constraint, or a concrete example; the structure makes the complex sizing behavior easier to apply, not harder.

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

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

For a geometry-heavy tool with no annotations and no output schema, this is nearly complete: it covers units, limits, header/padding, and examples. It only omits obvious selection semantics for buffer_id/cell_id and what happens outside grid mode, which are minor given the opening sentence.

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

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

Schema description coverage is 0%, and the description compensates well by defining x/y/w/h as integers in the react-grid-layout grid and explaining the width/height constraints. buffer_id and cell_id are left to name inference, so it is not a full 5.

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

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

The description opens with a clear verb and resource: 'Position a single cell in grid mode.' It immediately distinguishes this tool from layout-mode or cell-mode siblings, and the rest of the text reinforces that this is about geometry.

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

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

It tells the agent this is for positioning one cell in grid mode and warns that the 12-column rule only constrains width. It does not explicitly name alternatives such as set_layout_mode or set_cell_mode, but the stated grid-mode context is clear enough to route most calls.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It does disclose a key behavior (hides other cells) and the null reset behavior, but it does not clarify persistence, permissions, or any other side effects beyond the view-level hiding.

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

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

The description is two short sentences, front-loaded with the main action, and every word adds value. It is neither over-specified nor under-specified in length.

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

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

For a simple two-parameter tool, the description covers the core effect and the null behavior, but it leaves gaps like the meaning of buffer_id, how it differs from 'set_cell_view_maximized', and any potential return or persistence details. It is adequate but not complete.

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

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

Schema description coverage is only 50% (buffer_id has no description). The description adds little for cell_id, essentially restating the schema's 'or null to clear' as 'or null to restore normal layout', and provides no information about buffer_id, failing to compensate for the low coverage.

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

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

The description clearly states the action ('Spotlight one cell') and its effect ('Hides other cells'), making the tool's purpose unambiguous. However, it does not differentiate itself from the very similar sibling tool 'set_cell_view_maximized', which could cause agent confusion.

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

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

The description implies when to use the tool (to focus on a single cell) and mentions the null behavior for restoring the layout. It does not explicitly mention alternatives or when not to use it, especially given the existence of a nearly identically named sibling tool.

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

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

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

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

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

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

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

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

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

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

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

The schema has zero parameter descriptions, and the description only elaborates on 'mode' semantics by specifying run vs draw output. It does not explain buffer_id or cell_id, which are required parameters, leaving two of three params underspecified. Some value is added for mode, but it's insufficient for an agent to know how to populate the ID fields.

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

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

The description opens with 'Switch a SQL cell between run (table output) and draw (chart output)', which is a specific action and outcome. It clearly distinguishes from siblings like run_cell and set_cell_chart_config by focusing on the mode toggle and resulting output type. No ambiguity.

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

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

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

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

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

With no annotations provided, the description carries the transparency burden. It discloses the null-to-clear behavior, the display label rendering, and the chart title side effect. It does not mention error handling or permissions, but these are less critical for a simple setter.

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

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

Two short sentences, each with a distinct purpose: the first states the primary action and UI context, the second covers applicability and the clear behavior. No wasted words.

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

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

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

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

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

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

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

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

The description clearly states the action ('Set or clear') and the resource ('a cell's name'), and even adds the nuance that for chart cells it becomes the chart title. This distinguishes it from sibling cell-editing tools like set_cell_layout or set_cell_mode.

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

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

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

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

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

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action 'Switch' implies a mutation but does not disclose side effects, persistence, permissions, reversibility, or any impact on notebook state. This is a significant gap for a mutation tool with no annotation support.

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

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

The description is a single concise sentence that is front-loaded with the verb and resource. Every word earns its place, with no redundancy or unnecessary detail. It is an example of efficient, clear communication.

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

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

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

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

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

Schema description coverage is 0%, so the description must compensate. It only hints at the 'mode' parameter by naming 'list and grid layouts' but does not explain the 'buffer_id' parameter or how it maps to the notebook. The enum already documents mode values, so the description adds no value beyond what the schema provides.

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

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

The description uses a specific verb 'Switch' with resource 'a notebook' and clearly specifies the scope 'between list and grid layouts'. It distinguishes itself from sibling tools like set_cell_layout by targeting notebook-level layout rather than cell-level, making its purpose unambiguous.

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

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

The description gives no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. It simply states what it does, leaving the agent to infer usage from the name and siblings. There is no mention of when to prefer this over set_cell_layout or other layout-related tools.

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

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

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses that auto-refresh never executes writes, that DDL/DML cells are skipped, that the call is atomic when resetting overrides, that nothing re-runs, and that false/null leaves existing per-cell overrides in place.

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

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

The description is dense but every sentence earns its place: purpose, precedence, safety, polling behavior, value semantics, override-reset semantics, and side effects. Important claims are front-loaded before detailed parameter behavior.

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

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

The description covers what the tool does, when to use it, how it interacts with per-cell overrides, what side effects occur, which cells are skipped, and what the value parameter means. The only minor omission is buffer_id semantics, which is a parameter-level gap rather than a contextual one.

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

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

The description thoroughly explains `value` (true, false, or interval string) and `reset_cell_overrides` (true deletes all overrides atomically; false/null leaves them in place). However, `buffer_id` is not explained at all, and with 0% schema description coverage the schema provides no help either, leaving a clear gap.

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

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

The description uses a specific verb ('set'), names the exact resource ('notebook-level auto-refresh default'), and defines the scope ('every cell showing a chart or a grid'). It also explicitly distinguishes itself from set_cell_autorefresh, so an agent can select the right tool immediately.

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

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

The description clearly explains when this tool applies: cells without a per-cell value inherit the default, and set_cell_autorefresh creates a per-cell override that wins. It also states that until this is set nothing polls, and that DDL/DML cells are skipped, giving the agent clear selection and safety context.

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

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses overwrite-before-save behavior, auto-save, precise result-carryover semantics by statement content, and when results are cleared. This is far more transparent than a generic 'update' statement.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool only checks syntax correctness (not execution), implying a non-destructive read-only operation, and specifies use of QuestDB's validator. It does not describe error handling or return format, but the core behavioral trait is clear.

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

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

Two concise sentences, each earning its place: first explains purpose, second gives usage directive. No redundancy, front-loaded with the most important information.

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

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

Given the tool's simplicity (one parameter, no output schema), the description is largely complete. It states what the tool does and when to use it. It could mention return behavior, but for a validation tool the purpose is clear enough for an agent to select and invoke correctly.

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

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

The input schema covers 100% of the single parameter with description 'The SQL query to validate', so the baseline is 3. The tool description adds no further detail about query format, length limits, or constraints beyond what the schema already provides.

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

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

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

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

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

Provides explicit usage context: 'All generated SQL queries should be validated using this tool before responding to the user.' This gives a clear directive on when to use the tool, though it does not mention alternatives or exclusions explicitly.

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

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

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.