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

readOnlyHint=true already declares the safety profile, and the description adds real behavior: the tool returns a browser_url and instructs how to surface it as a clickable link. It also conveys the breadth of what the server watches in the background. It stops short of describing pagination, latency, or how the acknowledge/clear affordances are triggered.

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

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

Front-loaded with the verb and resource, and the parenthetical enumeration is informative rather than padded. The trailing browser_url rendering instruction is slightly operational noise but useful enough to keep.

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

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

With no output schema, the description compensates by naming the returned browser_url and its intended use, and by summarizing the view's contents. Nothing critical is missing for a parameterless view-open tool, though the relationship to alerts_data/alerts_badge remains unstated.

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

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

The tool takes zero parameters and schema coverage is 100%, so the baseline of 4 applies. There is no parameter behavior left 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?

States a specific verb and resource ('Open the Alerts view') and enumerates the alert categories it surfaces (long queries, failed pipelines, node memory/disk thresholds, nodes offline). This clearly distinguishes it as a view-opening tool, but it does not explicitly differentiate itself from siblings like alerts_data or alerts_badge.

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

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

Usage is only implied: the agent can infer this opens the Alerts UI, but there is no explicit when-to-use versus alternatives (alerts_data, alerts_check_now, alerts_badge) or any stated preconditions. An agent must guess whether it wants the view or the underlying data.

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?

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, establishing the mutation and safety profile. The description adds only the scope of acknowledgment and says nothing about side effects, reversibility, or permission requirements beyond what the annotations cover.

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 wasted words. It delivers the core action and scope immediately, which is appropriate for a simple two-parameter tool.

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 low-complexity tool with annotations covering safety, the description is minimally viable but leaves gaps around id format and parameter interaction. It does not explain return values, though no output schema exists to relieve that burden.

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

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

With 0% schema description coverage, the description compensates partially by mapping 'by id' to the ids parameter and 'or all of them' to the all parameter. It does not specify id format, null handling, or what happens if both parameters are supplied, so it is adequate but incomplete.

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 gives a specific verb and resource: 'Acknowledge alerts,' and clarifies scope with 'by id, or all of them.' It does not explicitly distinguish this tool from related siblings like alerts_clear or alerts_update, so it falls short of a 5.

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

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

It states the two acknowledgment modes (by id or all) but offers no guidance on when to use this tool versus alternatives such as alerts_clear or alerts_update. There are no exclusions or contextual conditions provided.

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

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

Annotations already declare readOnlyHint=true, so safety is covered structurally. The description adds real behavioral context beyond that: the value is in-memory state only (possibly stale / not a server fetch) and is cheap to poll, which tells the agent about cost and freshness characteristics it could not get from the 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?

A single front-loaded sentence with the resource, the UI context, and the freshness/cost caveat in parentheses. No filler, nothing redundant, and the most decision-relevant detail leads.

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

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

For a zero-parameter, read-only badge counter with no output schema, the description covers purpose, cache semantics, and cost profile. The only minor gap is that it does not state the return type (a bare integer count), though 'count' strongly implies it.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing parameter-related for the description to clarify or omit.

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

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

The description states a specific resource and verb-like outcome: the count of unacknowledged alerts, scoped to the workspace rail UI. That distinguishes it from siblings such as alerts_data or alerts (which presumably return the alerts themselves) without naming them explicitly, so it stops short of a 5.

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

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

The phrase 'cheap to poll' implicitly endorses repeated/frequent invocation, which is genuine usage guidance. However, it never states when to prefer this over alerts_data, alerts, or alerts_check_now, nor any condition under which to avoid it, leaving the agent to infer.

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

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

The readOnlyHint=true annotation already establishes the safety profile, so the description's '(read-only queries)' largely restates structured data. It does add that all enabled checks are triggered and that the new state is returned, but says nothing about cost, duration, rate limits, or whether it modifies alert state.

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?

A single sentence with no filler, and the key action ('Run every enabled check now') is front-loaded before the read-only qualifier and the return value.

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

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

For a zero-parameter tool with no output schema and a readOnly annotation, the description covers the essential behavior. Return values need not be enumerated since no output schema exists, though a note on expected latency or side effects on alert state would have made it fully complete.

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

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

The tool takes zero parameters and schema coverage is 100%, so there is nothing for the description to disambiguate. Baseline 4 applies for a no-param tool.

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

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

The description states a specific verb and resource: run every enabled check now and return the new state, including the read-only nature of the queries. It is clear what the tool does, though it does not explicitly contrast itself with siblings like alerts_update or alerts_ack.

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

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

The phrase 'Run every enabled check now' implies forcing an immediate refresh versus waiting for scheduled checks, which is a useful usage cue. However, no alternatives are named and there is no explicit when/when-not guidance relative to alerts, alerts_data, or alerts_update.

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?

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety profile is largely covered structurally. The description adds the all-vs-acknowledged scope, but it never says whether a cleared alert is gone permanently or merely hidden from the list, nor whether the clearance is server-side or view-only — the one behavioral question an agent actually has here. The "Remove" wording also sits in tension with destructiveHint=false and is never reconciled.

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?

A single front-loaded sentence with the verb first and the scope qualifier in parentheses; nothing is wasted. It is arguably too terse for a mutation tool, but it is structurally clean.

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-optional-parameter tool with no output schema and annotations covering the safety profile, the description covers purpose and parameter meaning adequately. It is missing the durability/irreversibility note, which is the one piece of context an agent would want before invoking a removal operation.

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

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

Schema description coverage is 0%, so the description must carry the parameter. It does: "all, or only the acknowledged ones" fully explains what acknowledged_only=true vs false (the default) means, which is the only parameter. It stops short of naming it, but the semantics are 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 gives a specific verb ("Remove") and resource ("alerts from the list"), and the parenthetical clarifies the scope of the removal. It is clear on its own, but it makes no reference to any sibling (e.g., alerts_ack, alerts_update), so an agent gets no help distinguishing this from the other alert-mutating tools.

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

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

The parenthetical "all, or only the acknowledged ones" hints at the two operating modes, but there is no guidance on when to clear versus acknowledge (alerts_ack) or update (alerts_update), nor any statement of preconditions. The agent must infer when this tool is the right choice.

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?

The readOnlyHint annotation already declares this a safe read, so the behavioral bar is lower. The description adds real context by stating the scope covers alerts/rules/checker status and excludes cluster queries, though it says nothing about return shape, freshness, or pagination.

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?

A single front-loaded sentence with no filler, and the scope exclusion is tacked on efficiently. It is a fragment rather than a full sentence, but nothing is wasted.

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 no-param, no-output-schema read tool this covers the essentials: it says what data is returned and what is out of scope. It stops short of describing the return contents or how the alerts/rules/checker status are structured, which the absent output schema would otherwise require.

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

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

The tool takes zero parameters, so the schema requires no semantic elaboration. Baseline 4 applies; there is nothing for the description to compensate for.

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?

It names the resources (alerts, rules, checker status) and scopes them to the Alerts view, which is more specific than a tautology. However, it lacks a clear verb (fetch/list) and does not distinguish itself from the sibling `alerts` tool, so an agent can't fully disambiguate from the name alone.

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 parenthetical '(no cluster queries)' hints at an exclusion and effectively routes cluster data to `cluster_monitor_data`, which is a small piece of guidance. But there is no explicit when-to-use, no named alternative, and no prerequisites.

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?

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, so the mutation and idempotency profile is covered structurally. The description adds the field shape but omits whether updates are partial or full replacements and what permissions are needed, so it adds only modest behavioral value beyond the 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?

A single compact sentence with no waste, front-loading the verb and resource. The dense brace notation is efficient, though slightly cryptic without further explanation.

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 two optional params and no output schema, the description gives the payload structure but leaves gaps: no mention of partial vs. full replacement behavior, no defaults, and no permission context. Adequate but 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?

Schema description coverage is 0%, so the description carries the burden and does list the nested fields (enabled, seconds, percent, interval_s, notify). However it only names them without explaining their meaning or valid ranges, leaving the semantics of each field unclear.

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

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

The description states a specific verb (Change) and resources (alert rules and settings), and even sketches the payload shape. It is clear what the tool does, though it does not explicitly differentiate itself from sibling alert tools like alerts_ack or alerts_clear.

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

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

No indication of when to use this tool versus the other alert siblings (alerts, alerts_ack, alerts_clear), nor any prerequisite or scope guidance. The agent must infer usage entirely.

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 behavioral transparency burden. It discloses the requirement for a full statement and that alterable clauses are source-specific, which is valuable. However, it does not mention permissions, reversibility, effects on a running pipeline, or the destructive potential of resetting offsets.

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 compact and well-organized: a one-sentence purpose, a short use-case expansion, and a clear Args block. Every sentence earns its place; there is no repetition 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 two-parameter tool with an output schema, the description covers the essential usage: what SQL to supply, what the database parameter does, and why a full statement is needed. It lacks some safety/permission context, but the core calling contract is complete.

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

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

Schema description coverage is 0%, so the description fully compensates by defining alter_pipeline_sql as 'The full ALTER PIPELINE ... statement' and explaining that database defaults to the connection's configured database. This adds meaning beyond the bare property names and types.

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

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

The description clearly states the verb 'Alter' and the resource 'existing pipeline', and specifies that it operates from a full ALTER PIPELINE statement. It distinguishes itself from siblings like create_pipeline and drop_pipeline by mentioning it changes connection strings/credentials or resets offsets.

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 use cases ('change the connection string/credentials or reset offsets') and explains why a full statement is required, referencing create_pipeline for the same rationale. It does not explicitly state when not to use this tool or list alternatives, but the common-use framing provides clear 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?

Annotations already declare readOnlyHint=true, and the description adds genuine behavioral context beyond that: results are not cached by hosts (unlike resources/read) and reflect changes immediately after restart_server. This is useful operational context not present in the structured fields.

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 compact sentences, with the core purpose front-loaded before the caching caveat. No wasted text, though the parenthetical slightly interrupts flow.

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 read-only tool with an output format implicitly being HTML, the description covers purpose and caching behavior adequately. However, with no output schema and an undocumented uri parameter at 0% coverage, the agent lacks the information needed to supply a valid uri.

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 'uri' parameter has 0% schema coverage and the description provides no format, example, or enumeration as to which page URIs are valid. 'One of this server's app pages' gives only a vague domain hint and does not compensate for the documentation gap.

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

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

States a specific resource ('HTML of one of this server's app pages') and clarifies its role ('the workspace loads its views with this'). It distinguishes itself somewhat from resources/read by contrasting caching behavior, though it does not differentiate from the many sibling tools.

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

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

The caching contrast with resources/read implies a reason to prefer this tool for live views that must reflect changes after restart_server, but there is no explicit when-to-use or when-not-to-use statement. Usage is left to inference.

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

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

Annotations only declare readOnlyHint=true, so the description carries the extra burden and does add meaningful traits: the link is non-persistent ('works on this machine only, until the MCP server restarts') and the result must be presented as a clickable link. It does not cover failure modes or whether the referenced app must already be open/authenticated.

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 purpose is front-loaded, followed by a single usage sentence and an Args block. Every sentence carries information an agent needs, with no filler.

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

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

An output schema exists, so return-value documentation is unnecessary, and the description correctly tells the agent how to use the returned value. Combined with the enumerated tool values and argument examples, it is nearly complete for a 2-parameter tool; only edge behavior (invalid tool, persistence failure) is unaddressed.

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, and it does: it enumerates the accepted app names for 'tool' (pipeline_monitor, query_grid, schema_explorer, cluster_monitor, sql_editor) and gives concrete example payloads for 'arguments'. It stops short of full compensation because it doesn't state the full argument contract for each target app or what happens with an unknown tool name.

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 outcome ('Get a link that opens one of the interactive apps full-window in the user's web browser'), which is clear enough to separate it from direct query/editor tools. It does not explicitly contrast with the nearby sibling 'app_page', so sibling differentiation is implied rather than stated.

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 a concrete trigger: 'Use this when the user wants an app bigger than the chat allows or in their browser', plus a follow-up instruction to hand the returned URL to the user as a clickable link. No alternatives or when-not conditions are named, 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?

Annotations declare readOnlyHint=true and the description corroborates this precisely, explaining nothing is dropped by the call and only the user can drop from the panel. It adds substantial context beyond the annotation: the dry-run mode, the log, the per-table metadata shown, and the returned browser_url that should be posted as a clickable link.

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

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

Front-loaded with the action in the first sentence, then supporting detail. The middle paragraph is dense but each clause (name patterns, per-table columns, confirmation flow) earns its place; the description runs long for a panel-opening tool but wastes little.

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

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

With no output schema and no parameters, the description carries the full burden and does so: it covers what the panel shows, what the call does and does not do, and how to handle the returned browser_url. Nothing an agent needs to invoke or present the result is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline for a parameterless tool is 4.

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: 'Open the Schema Explorer's Clean-up panel for leftover SAS work tables.' The closing clarification ('Nothing is dropped by this call; only the user can drop from the panel') implicitly separates it from sibling tools like schema_explorer_cleanup_drop, but no sibling is named explicitly.

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

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

Provides a clear when-to-use trigger: 'Use this when the user wants to find or clean up leftover, temporary or SAS work tables.' It does not name the alternative tools (schema_explorer_cleanup_scan/settings/drop) 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: the view auto-refreshes, and the result carries a browser_url intended to be posted as a clickable link under the app, which is important for correct agent behavior. It does not describe limits such as refresh interval or whether the browser view persists.

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

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

Three short sentences, front-loaded with purpose, then usage, then output-handling instructions. Every sentence earns its place and the actionable browser_url instruction is not buried.

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 no-argument, read-only UI-opening tool with no output schema, the description supplies everything needed: what is displayed, when to invoke it, and what to do with the returned browser_url. The absence of an output schema is compensated for by naming the key return field.

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 zero parameters and 100% schema description coverage, the baseline is 4; there is nothing to document. The description correctly adds no parameter noise.

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 and resource ('Open a live monitor of the SingleStore cluster') and enumerates exactly what is shown: per-node CPU/memory/disk and currently running queries. It is immediately clear what the tool does, though it never differentiates itself from the sibling cluster_monitor_data, so an agent must infer which one to pick.

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?

'Use this when the user wants to see cluster load, resource usage or what is running' gives a clear triggering condition. It provides no explicit exclusion or alternative-tool routing (e.g. cluster_monitor_data), so it stops short of full 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?

readOnlyHint=true already declares this as a safe read, so the description doesn't need to restate that. 'Refresh' is a read-style operation consistent with the annotation, and adding 'including CPU history' gives a useful hint about content. It still omits what exactly is refreshed, whether it hits the network, or what the call returns.

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?

A single efficient sentence with the key scope detail front-loaded. It is well-sized, though its brevity edges toward under-specification given the unexplained parameter rather than pure 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 tool with no output schema and an undocumented optional parameter, the description does too little. It neither explains include_internal nor describes the shape of the returned data beyond the passing mention of CPU history.

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 sole parameter include_internal is never mentioned in the description. With the schema silent and the description silent, an agent has no idea what toggling include_internal does, so the description fails to compensate for the coverage gap.

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

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

States a specific verb (Refresh) and resource (data for the Cluster Monitor app), plus a concrete scope detail (CPU history). However, it never distinguishes itself from the sibling cluster_monitor tool or clarifies its relationship to it, so an agent must infer the division of labor.

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

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

There is no explicit when-to-use, when-not-to-use, or alternative pointer. The phrase 'for the Cluster Monitor app' hints at context but gives no condition telling an agent when to call this versus cluster_monitor or pipeline_monitor_data.

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?

Annotations only mark it non-read-only and non-destructive; the description adds real behavior beyond that by disclosing that activation also performs a connection test and that token-based connections may require a sign-in step first. It still does not say what happens on a failed test or whether the previous active connection is affected.

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

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

One compact sentence with the primary action front-loaded and the caveat demoted to a parenthetical. No filler, though the caveat sentence could be slightly sharper about the required sign-in flow.

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 mutation with no output schema, the description covers the core action and one prerequisite, which is the minimum viable. It omits failure behavior, state side effects on the previously active connection, and any permissions requirement, so it is adequate rather than 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 0% and the single 'name' property is undocumented. The phrase 'a saved connection' weakly implies the parameter is the name of a previously saved connection, but the description adds no format or lookup details to compensate for the empty 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?

States a specific verb (activate) and resource (saved connection), and adds the secondary effect of testing it. It is distinguishable from connection_test or connection_save, but it never names the closest sibling use_connection, so the boundary is left to inference.

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

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

Usage is implied by the verb rather than stated. The parenthetical about token connections needing a sign-in hints at the connection_sso_sign_in prerequisite, but there is no explicit when-to-use/when-not guidance relative to use_connection or connection_test.

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?

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is covered. The description adds genuine value beyond them by disclosing a second destroyed artifact – the stored password – which the annotations cannot convey. It still omits whether the deletion is permanent or recoverable.

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

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

One short sentence with no filler, and the destructive outcome is front-loaded. Nothing could be trimmed without losing signal.

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 destructive tool with clear annotations and no output schema, the description covers the essentials. The remaining gap is failure/irreversibility behavior, which is a minor omission at this complexity.

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

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

Schema coverage is 0% for the single 'name' parameter, so the description carries the burden. It implies the parameter identifies a saved connection, which is meaningful, but adds no matching rules, case sensitivity, or error behavior for an unknown name.

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 (delete) and resource (saved connection), so an agent can immediately tell it apart from connection_save, connection_test, or connection_activate. It stops short of explicitly contrasting itself with the closest siblings, but the purpose is unambiguous.

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

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

There is no when-to-use guidance, no prerequisite (e.g. that the connection must be saved/inactive), and no mention of the alternative workflows (cleanup_work_tables, connection_save) in the sibling list. The agent must infer all routing from the name alone.

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?

Annotations declare readOnlyHint=false and destructiveHint=false, so safety is partly covered; the description adds meaningfully beyond that by disclosing the write target ('~/.singlestore-mcp'), the one-time nature ('once'), and the return value (the path). It does not mention overwrite behavior if the file already exists, which keeps it short of a 5.

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

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

One sentence, front-loaded with the action and resource, containing destination, purpose, cardinality, and return value with no wasted words. Nothing could be removed without losing 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 no-parameter setup tool with no output schema, the description covers what it fetches, where it writes, that it need only run once, and what it returns. Adding a note about the return type or overwrite handling would make it fully self-contained.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to disambiguate, and it correctly introduces no phantom arguments.

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 ('Download SingleStore's CA bundle') plus the destination and purpose ('needed for Helios / TLS'). No sibling tool performs this setup action, so no differentiation is required, and an agent can immediately tell what this 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 phrase 'needed for Helios / TLS' gives a clear trigger condition for when this tool is required. It does not name alternatives or exclusions, but no competing CA-bundle tool exists among the siblings, so the context is sufficient without that.

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?

Annotations already declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive write. The description adds genuinely useful behavioral detail about the password sentinel (None preserves the stored value, empty string clears it), which is not derivable from the schema. It still omits permission/auth requirements and any indication of what happens to unmentioned profile fields on update.

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, front-loaded with the operation and followed immediately by the one non-obvious parameter rule. 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 mutation tool with a nested profile object, zero schema coverage, and no output schema, the description is far too thin. The password rule is a good start, but 'profile' contents, 'activate' semantics, and 'original_name' behavior are all missing, leaving the agent unable to construct a correct call from the description alone.

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% across 4 parameters, so the description must carry the load and only explains the password sentinel. The nested 'profile' object, 'activate', and 'original_name' (likely the rename key) are left entirely undocumented in both schema and description.

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 pair (create or update) and resource (saved connection), making the upsert nature of the operation explicit. It is distinguishable from connection_delete and connection_activate, though it does not name those siblings directly.

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 on when to use this versus siblings like connection_activate, use_connection, or connection_delete, and no prerequisites or context are given. The agent must infer that this is the persistence step for a connection profile.

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?

Annotations only tell the agent this is non-read-only and non-destructive. The description adds real behavioral context beyond that: it opens a page in the user's browser (interactive, requires user presence) and blocks waiting for a token with a stated 2-minute timeout. That is valuable for an agent deciding whether to call it synchronously.

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

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

One sentence, front-loaded with the action and scope, then the mechanism and timeout. No wasted words; every clause 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?

For a no-output-schema tool the description covers action, mechanism, and timeout, which is decent. It omits prerequisites (does the connection need to exist/be activated first?), what the token result looks like, and failure modes (timeout behavior).

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 sole required parameter 'name' carries no description. The description does not clarify whether 'name' is the connection name, the SSO provider, or something else, so it fails to compensate for the schema gap.

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

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

States a specific verb (browser sign-in) and resource (SSO connections), and narrows scope to Helios or Microsoft Entra ID. It does not explicitly contrast with sibling sign-in tools like sas_viya_sign_in or connection_activate, so sibling differentiation is only partial.

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 parenthetical 'for SSO connections (Helios or Microsoft Entra ID)' implies when this applies, but there is no explicit when-to-use/when-not guidance and no named alternative for non-SSO connections (e.g., connection_activate). Usage is inferred 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description does add one genuinely useful behavioral detail — that the response exposes where passwords are stored, which is a security-relevant disclosure — but it says nothing about freshness, whether it reflects live server state, or what the snapshot contains.

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?

It is short and free of filler, which is good, but it is a trailing noun fragment rather than a front-loaded statement of action, so an agent skimming it gets a topic rather than a purpose.

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

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

With no parameters, no output schema, and only a readOnlyHint annotation, the call surface is trivial and the description is arguably sufficient to invoke it. However, it does not distinguish this snapshot from the many overlapping connection-related siblings, leaving routing ambiguity.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. Schema coverage is nominally 100% and there is nothing for the description to clarify on inputs.

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 is a noun phrase ('Saved connections, the active one and where passwords are stored') rather than a verb+resource statement — it never says it retrieves or returns anything. It hints at scope (saved connections, active connection, credential storage) but gives no clear differentiation from siblings like list_connections, use_connection, or connections_window.

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

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

There is no when-to-use guidance, no mention of prerequisites, and no reference to any alternative tool. The agent must infer that this is a state-snapshot call from the name alone.

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?

readOnlyHint=true is consistent with merely opening a window, so no contradiction. The description adds genuinely useful behavioral context beyond the annotation: the result carries a ``browser_url`` and it should be surfaced as a clickable link under the app, which tells the agent what to expect and do after invoking.

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 paragraphs, front-loaded with the core action, followed by the view identity and output-handling note. Reasonably tight, with only slight redundancy between 'Connections window' and 'Connections view of the SingleStore Workspace'.

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 window-opening tool with no output schema, the description covers what it opens, what it is, and the key return value handling (browser_url -> clickable link). Adequate; only explicit sibling differentiation is missing.

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

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

The tool takes zero parameters, so the baseline is 4. There are no argument semantics to explain and the description correctly adds none.

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 ('Open') and resource ('the Connections window') and enumerates the capabilities it exposes (add, edit, test, switch connections). It does not explicitly distinguish itself from siblings such as connection_test or connection_activate, so the agent must infer that this opens a UI surface rather than performing an operation.

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

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

The description implies usage (opening a connection-management window and posting the returned browser_url as a link) but never states when to pick this over alternatives like connection_test, connection_activate, or connections_state. Guidance is present but 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?

The annotations already declare readOnlyHint=true, which matches the 'try' semantics and raises no contradiction. The description adds the useful behavioral detail that the call accepts either a saved connection reference or ad-hoc form settings, but it says nothing about what success/failure looks like, whether `password` is required for one mode, or any side effects (e.g., does it activate the connection?).

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?

A single front-loaded sentence with no filler, and the two-mode distinction is right up front. It is arguably under-specified rather than over-long, but as written nothing is wasted.

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 3-parameter tool with no output schema and only a read-only hint in annotations, the description should explain the two input paths more concretely (which params pair with which mode) and what the call returns on success or failure. As it stands, key operational details are missing.

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

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

Schema description coverage is 0% and none of the three parameters are documented in the schema. The description hints that `name` refers to a saved connection and that `profile` corresponds to 'the settings from the form', but `password` is never mentioned and the relationship/mutual exclusivity between `name` and `profile` 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?

It conveys the resource (a connection) and the operation (testing it), and distinguishes two input modes: a saved connection by `name` versus form-supplied settings. The verb 'try' is informal and the tool is not differentiated from nearby siblings like `connection_activate`, `connection_sso_sign_in`, or `sas_viya_test`. Purpose is inferable but not sharp.

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

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

There is no explicit when-to-use guidance and no named alternative. An agent cannot tell from the text whether this is a prerequisite step before `connection_activate`, an alternative to `sas_viya_test`, or a purely diagnostic call. The only routing hint is the implicit name-vs-form distinction.

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 behavioral disclosure burden. It does so well by revealing that the tool only checks for the 'CREATE [OR REPLACE] PIPELINE' prefix before running, and that the pipeline is not started automatically. These are meaningful non-obvious behaviors beyond the basic 'create' action.

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 well-structured: it leads with the action, explains why the design is statement-based, states critical behavioral caveats, and includes a representative example. Every section serves a purpose and there is minimal 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?

The description covers the tool's purpose, validation behavior, start semantics, and parameter meanings, and an output schema exists to describe return values. It does not mention error cases or permission requirements, but for this tool the provided context is sufficient for correct use and routing.

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 explains create_pipeline_sql as the full statement text, provides a concrete example, and clarifies that database defaults to the connection's configured database. This adds real meaning beyond the parameter names and types.

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: 'Create a new pipeline from a full CREATE PIPELINE statement.' It clearly distinguishes this tool from siblings like start_pipeline, drop_pipeline, and alter_pipeline by focusing on creation from a complete statement.

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 tells the agent that creating a pipeline does not start it, and directs it to call start_pipeline afterwards. It also explains why the tool takes a full statement rather than structured parameters, which gives context for when it is appropriate. It does not state when not to use alternatives like run_sql, but the guidance is clear enough.

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 must carry behavioral context. 'Show' indicates a read-only inspection, and the default-database note adds useful behavior when the parameter is omitted. However, it does not explicitly state that no data is modified, what happens on a missing table, or any permission requirements.

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 compact and front-loaded with the core purpose, followed by a minimal Args section. There is no filler; every line adds information about the operation or its parameters.

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 two-parameter introspection tool with an output schema available, the description covers the action and all argument semantics, including the database fallback. It lacks explicit usage guidance and behavioral caveats, but those gaps are minor given the tool's simplicity and the output schema's role.

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 compensates by documenting both parameters. It adds real meaning beyond the schema by clarifying that omitting database falls back to the connection's configured database, which is not inferable from the schema's null default.

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

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

The description opens with a specific verb and resource: 'Show column definitions for a table.' This clearly distinguishes the tool from siblings like list_tables (which lists tables) and run_sql (which executes arbitrary SQL), even though no sibling is named.

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 explicit guidance is given about when to use this tool versus alternatives such as run_sql or list_tables. The intended use is only implied by the verb 'Show,' and there is no mention of when not to use it or which sibling to prefer for broader schema exploration.

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 behavioral disclosure burden. It usefully reveals the automatic stopping of running pipelines and that if_exists turns failure into a no-op. It does not explicitly warn that deletion is permanent or mention permission requirements, but the core side effects are disclosed.

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

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

The description is compact and front-loads the primary purpose in the first sentence. The Args block is organized and every sentence contributes useful guidance with no filler.

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

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

The description covers the essential operation, side effects, and parameter semantics, and an output schema exists so return-value documentation is not required. It is nearly complete, though a brief note about irreversibility would have fully closed the gap for a destructive action with no annotations.

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 fully compensates by explaining all three parameters: pipeline_name's role, database's default to the connection database, and if_exists's no-op behavior. This adds real meaning beyond the raw 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 'Delete a pipeline,' a specific verb and resource that clearly identifies the operation. It also notes that running pipelines are stopped automatically, which differentiates dropping from simply stopping a pipeline.

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 the tool is for permanent removal and explains that running pipelines are stopped as part of the drop. However, it does not explicitly contrast drop_pipeline with stop_pipeline or state when dropping is inappropriate.

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?

Annotations already declare readOnlyHint=true, so safety is covered. The description still adds real behavioral context: the default path target and the allowed-root restriction that determines whether a browse will be rejected. It omits return ordering, pagination, and what an out-of-root error looks like.

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, front-loaded with the core action and return content, then defaults and constraints. The kind mapping is the only detail worth its length; the blank-line-wrapped formatting is slightly awkward but wastes no 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 2-parameter, read-only listing tool with no output schema, the description covers action, return contents, default argument behavior, and the access boundary. Reasonably complete; it just lacks return-shape and error-condition detail that an agent navigating a file tree might want.

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 there are no enums, so the description carries the full burden — and it largely does: it maps kind="sql" to .sql files and kind="notebook" to .ipynb files, and explains that path defaults to the SQL folder. It stops short of specifying path format (absolute vs relative) or what values kind accepts beyond the two examples.

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 a folder for the file browser") and enumerates exactly what is returned: subfolders plus .sql or .ipynb files filtered by `kind`. That is precise enough to picture the operation, though it never names a sibling tool it should be preferred over.

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 useful context ("`path` defaults to the SQL folder") and a hard precondition (only folders inside the user's home, the SQL folder, or SINGLESTORE_MCP_FILE_ROOTS can be browsed), which tells the agent when calls will succeed. But it never says when to pick this over notebook_files / sql_editor_files or what to do instead, so usage is implied 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?

With no annotations, the description carries the full burden. 'Get' implies a read-only retrieval and the database default is disclosed, but the description does not state behavior for missing pipelines, permissions, or whether any side effects occur. It does not contradict the absence of 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 compact and well organized: one clear purpose sentence followed by a brief, relevant Args list. Every sentence adds useful information without redundancy or filler.

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

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

For a two-parameter retrieval tool, the description covers the return value, the required parameter, and the optional parameter's default behavior. It does not cover error cases or explicitly route between siblings, but the output schema supplies additional structure and the use case is straightforward.

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 documents both parameters. The database parameter explanation ('defaults to the connection's configured database') adds real meaning beyond the schema's nullable default of null, which is valuable because the schema itself has no property 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 uses a specific verb ('Get') with a precise resource ('full CREATE PIPELINE statement') and outcome ('reproduces an existing pipeline'). This clearly distinguishes it from siblings like create_pipeline, drop_pipeline, and list_pipelines.

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

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

The intended use case is implied: you call this when you need the DDL to reproduce an existing pipeline. However, the description does not explicitly mention alternatives or when not to use it, leaving the agent to infer the choice from sibling names.

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?

Annotations already declare readOnlyHint=true, so the bar is lower, and the description still adds real value: no passwords are returned and the active connection affects all tools and apps. That is behavioral context an agent cannot get from the annotation alone.

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?

Sentence one front-loads the action and its output constraints; the following two sentences each add distinct context (the significance of 'active' and where management lives). No filler.

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

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

An output schema exists, so return-format detail is unnecessary, and the description covers scope, semantics of the active flag, and the sibling for management. Only minor edge behavior (e.g., empty connection list) is unaddressed.

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

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

The tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to disambiguate. Schema coverage of 100% means no compensating detail is needed.

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

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

States a specific verb (List) and resource (saved SingleStore connections) and adds meaningful scope: passwords are excluded and the active connection is flagged. It is clearly distinguishable from mutation siblings like connection_activate/connection_save, though it never directly contrasts itself with the close-named connections_state.

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

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

Routes the agent: this tool is for reading the connection list, while management happens in the Connections window (connections_window tool or the Connect view). That gives a clear division of labor, but there are no explicit when-not conditions or a named alternative for related reads like connections_state.

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

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

The description discloses that results depend on the connected user's visibility, implying permission-based filtering and no modifications. Although no annotations exist, the read-only nature of a list action is sufficiently conveyed by the verb 'List'.

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?

A single sentence front-loads the action and resource, with the scope qualifier placed at the end. Every word earns its place; there is no filler or redundancy.

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

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

Given zero parameters, an existing output schema, and a simple read-only enumeration, the description covers everything an agent needs to invoke the tool correctly. The user-visibility qualifier is a useful contextual detail.

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

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

The tool takes no parameters and the input schema is empty. There are no parameter semantics for the description to clarify, so it correctly remains brief.

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

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

The description uses a specific verb ('List'), a clear resource ('databases'), and an explicit scope ('visible to the connected user'). It is easily distinguishable from sibling tools like list_tables and list_pipelines because it names the object type directly.

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 explicit when-to-use or alternative guidance is provided, but the operation's purpose is self-evident: it enumerates databases, which is a distinct step from listing tables or pipelines. The context is clear and there are no exclusions or preconditions to state.

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

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

With no annotations, the description itself must convey behavioral expectations. It does disclose the key output trait—returning pipeline states (Running/Stopped/Error)—which is useful. However, it does not mention that this is a read-only operation, whether permissions are required, or what happens with an invalid or missing database. It is adequate but not rich.

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

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

The description is two sentences with no fluff. The primary purpose is front-loaded, and the parameter explanation is minimal and directly useful. Every sentence 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?

For a simple list operation with one optional parameter and an output schema present, the description is nearly complete. It gives the resource, scope, state categories, and default parameter behavior. It could be improved by noting the absence of side effects, but this is a minor gap 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?

Although schema description coverage is 0%, the description fully explains the one parameter: database is the target database and defaults to the connection's configured database. This adds real semantic value beyond the schema's type/default fields and compensates for the lack of schema-level documentation.

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

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

The description states a specific verb ('List all') and a clear resource ('pipelines in a database'), and it differentiates itself from the more specific pipeline_status sibling by explicitly covering all pipelines and their current state. This is unambiguous and lets an agent understand the exact scope of the tool.

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

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

The description implies when to use the tool: whenever you need the full set of pipelines and their states in a database. It does not explicitly contrast this with pipeline_status or other read-only siblings, nor does it give exclusions. The default-database note is helpful context but not a full usage guideline.

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 burden of behavioral disclosure. It usefully notes that views are included and that the database parameter defaults to the connection's configured database. It does not mention permissions, output sorting, or whether system tables are included, but the 'list' wording strongly implies a read-only operation.

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

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

The description is short, front-loaded with the core purpose, and adds an Args section only where it adds value. Every sentence earns its place and there is no redundant filler.

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

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

For a simple list tool with one optional parameter and an output schema available, the description covers the essential details: what is listed, the target database, and the default behavior. It is slightly incomplete only in not routing the agent to sibling tools for related tasks like listing databases or describing a specific table.

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 only defines 'database' as a nullable string with default null and 0% schema description coverage. The description compensates by explaining the parameter means 'Database to list tables from' and clarifying the default behavior. This goes beyond the schema, though it could still specify expected format or accepted values.

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

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

States a specific action ('List') and resource ('tables (and views) in a database'), making the tool's purpose immediately clear. It is naturally distinguished from sibling tools like list_databases and describe_table because it explicitly targets tables/views within a database.

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 list tables or views from a database. However, it does not explicitly mention alternatives or exclusions, such as using list_databases to discover available databases or describe_table for individual table details.

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?

Annotations only supply readOnlyHint=true, and the description adds real behavioral context: Python cells get pandas, matplotlib and a `conn` connection, SQL results become DataFrames, and the result carries a `browser_url` that should be posted as a clickable link. It does not explain session lifetime, kernel startup side effects, or persistence 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?

Efficient and front-loaded, opening with the verb+resource before elaborating on execution semantics. The middle paragraph is slightly dense but each sentence carries information the agent needs; nothing is pure filler.

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

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

No output schema exists, yet the description discloses the key return artifact (browser_url) and how to use it, and it covers both zero-required parameters. Minor gap: it doesn't clarify what happens to an existing notebook vs. a new one, or the relationship to the kernel-control siblings.

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 carries the full burden, and it does: `name` is a notebook file with an example ('sales.ipynb') plus the omit-to-create semantics, and `database` is scoped to SQL cells and flagged case-sensitive. That is meaningfully more than the bare anyOf string 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?

States a specific verb and resource ('Open a SingleStore notebook') and explains what the resource is: SQL and Python cells on a Jupyter kernel, stored as .ipynb in the user's SQL folder. It even names an equivalence with a sibling ('the Notebook view ... sql_editor with view="notebook"'), though it never differentiates itself from the very similar notebook_open/notebook_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?

Usage context is implied rather than stated: the args section gives 'omit for a new notebook' for name, which tells the agent how to trigger new-notebook creation, and the browser_url instruction implies a UI-flow. But there is no explicit when-to-use / when-not-to-use versus notebook_open, notebook_run or sql_editor.

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 readOnlyHint=true already covering the safety profile, the valuable addition here is the asynchronous delivery behavior: the answer is not returned inline but lands in sql_editor_inbox. That is a real behavioral trait the annotations do not convey. It omits auth, rate-limit, or kernel-requirement details, keeping it below a 5.

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

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

A single front-loaded sentence with zero filler: verb first, resource next, delivery destination last. Nothing is repeated from the name or schema, and no sentence is wasted.

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 the critical async-retrieval behavior and points at the sql_editor_inbox sibling for fetching the reply, which is the most important missing piece for an agent. It still leaves the 'context' and 'profile' parameters and any execution prerequisites unexplained, so it is only minimally complete for a 4-parameter tool with no output schema.

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

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

Schema description coverage is 0% across all 4 parameters, so the description is the only place semantics could be supplied. It mentions only implicitly the notebook and question, and says nothing at all about the optional 'context' or 'profile' parameters, leaving half the surface undocumented in both schema and prose.

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 ("Ask") and a specific resource (the in-app assistant about the notebook), so the agent knows exactly what the tool does. It does not explicitly distinguish itself from closely named siblings like sql_editor_ask, query_history_ask, or notebook_assistant_warm, so it falls short of a 5.

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

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

Usage is only implied: stating that the reply arrives in the notebook inbox (sql_editor_inbox) signals an asynchronous, fire-and-retrieve pattern and gives the agent the follow-up tool. However, there is no explicit when-to-use vs. when-not guidance and no named alternative among the many sibling ask/assistant 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?

Annotations declare readOnlyHint=true, and the description is consistent with that. It adds real value beyond the annotation by disclosing 'no model call', telling the agent this is a free, latency-optimizing action rather than an inference request. It does not address idempotency or prerequisites, so it stops short of a 5.

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

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

A single front-loaded sentence with the action first and the crucial qualifier ('no model call') in parentheses. Nothing is wasted.

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 pre-warm tool with annotations covering the safety profile and no output schema, the core intent is conveyed. However, the unexplained 'profile' parameter and the unstated behavior when the notebook is not open leave it only minimally 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 0% and the description mentions no parameters at all. The required notebook_id is at least obvious from the name, but the optional 'profile' parameter is completely undocumented in both the schema and the description, leaving a real gap.

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

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

States a specific verb and resource ('Start the notebook's assistant process') and clarifies the trigger point ('ahead of the first question'). It implicitly separates itself from notebook_ask via that timing cue, though it never names the sibling it is a precondition for.

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?

'Ahead of the first question' clearly conveys when to use it: as a pre-warm before asking. There are no exclusions or explicit pointer to notebook_ask, so the routing is inferred 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?

The `readOnlyHint` annotation already signals a safe read operation, so the bar is lower. The description adds that it covers install progress, which is useful context beyond the annotation, but it does not explain what the status response contains or whether it is a blocking or polling call.

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?

A single sentence with no filler, and the core resource is front-loaded. 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?

For a zero-parameter read-only status tool with no output schema, the description is adequate to identify the endpoint, but it leaves gaps: it doesn't clarify the relationship to `notebook_environment_install` or what the returned status includes. Given the crowded sibling set, a bit more routing context would help.

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

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

The tool takes no parameters, so the schema has nothing to document. Baseline for zero parameters is 4; the description does not need to add parameter meaning.

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 identifies a specific resource (notebook Python environment) and what it reports (status plus install progress), so an agent knows this is a read-only status check. It does not explicitly differentiate itself from sibling `notebook_environment_install` or `notebook_packages`, which is the main gap for a 5.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as `notebook_environment_install` for triggering installs or `notebook_packages` for package listing. Usage is only faintly implied by the word 'Status'.

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?

Annotations already declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive mutation. The description usefully adds the package list and the installer (uv), but says nothing about idempotency, overwrite behavior on an existing environment, or expected duration for a dependency install.

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?

A single front-loaded sentence with the action first and the package set in parentheses. No filler, nothing that could be trimmed without losing 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?

No output schema exists, so the description could reasonably explain the result of the install (success signal, whether packages are verifiable afterward). For a mutation tool with zero parameters, the description is adequate but leaves the post-install state and failure modes unspecified.

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

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

The tool takes zero parameters, so there is no schema to compensate for; the baseline for 0 params is 4. The description's package list is informational rather than parameter guidance.

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 concrete verb (Create) and resource (notebook Python environment) and enumerates the exact packages installed, so an agent knows what it produces. It does not explicitly distinguish itself from the nearby sibling notebook_packages_install, which is the main remaining 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?

Usage is implied: 'Create the environment' suggests running this when the notebook environment does not yet exist, versus notebook_packages_install for adding packages to an existing one. However, no alternative is named and no precondition (e.g., environment must not already exist) is 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?

readOnlyHint=true already declares this is a safe read, so the description only needs to add context. It contributes the result ordering ('newest first'), which is genuine behavioral information, but says nothing about which folder path is used, whether results are paginated or truncated, or how entries are represented.

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?

A single front-loaded sentence with no filler. Every clause (file type, folder, ordering) carries 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 zero-argument read tool with a readOnlyHint annotation this is close to sufficient, but with no output schema the description would ideally convey what a returned entry looks like or how to act on it. As written, an agent knows scope and ordering but not the shape of the result.

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

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

The tool takes zero parameters and schema coverage is 100%, so there is nothing for the description to compensate for. Baseline 4 applies for a parameterless call.

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?

Names a specific resource (.ipynb notebooks), its location (the SQL folder), and its ordering (newest first), so an agent can tell roughly what it returns. It lacks an explicit action verb like 'list', and it does not distinguish itself from neighbors such as files_browse, sql_editor_files, or notebook_open that also surface notebook files.

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

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

There is no statement of when to use this over the many adjacent listing tools (files_browse, sql_editor_files, notebook_open). The 'SQL folder' scope is the only implicit usage cue, leaving routing to inference.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; they do not tell the agent that restart/shutdown discard all in-memory variables and kernel state. The description adds no such behavioral context, nor any note on permissions or what the caller observes afterward. With annotations providing minimal coverage, the description leaves a real gap for a state-altering operation.

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

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

One sentence, front-loaded with the verb set, with the action enumeration in parentheses. No filler and nothing buried.

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 two-parameter tool with no output schema, the description covers the action domain adequately, and the annotations carry the (thin) safety profile. It still omits notebook_id semantics and the state-loss consequences of restart/shutdown, which an agent needs to choose this tool responsibly.

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 action parameter has no enum in the schema, so naming 'action: interrupt | restart | shutdown' in prose is genuinely additive. However, notebook_id is left entirely undefined, and there is no indication of what notebook_id should reference or the failure mode for an unknown id.

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 gives a concrete verb set (Interrupt, restart, shut down) against a specific resource (the notebook's kernel), and even enumerates the accepted action values. It is clearly distinguishable from notebook_kernel_start and notebook_kernel_state by implication, though it never names those siblings explicitly.

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

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

The action list conveys what operations exist but not when to use each one (e.g. interrupt vs restart when a cell is stuck, or shutdown when freeing memory). No alternatives, prerequisites, or when-not-to-use conditions are 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?

Annotations already declare readOnlyHint=true, so the safety profile is partly covered. The description usefully clarifies '(no code runs)', which explains why a kernel-start operation is non-destructive, but says nothing about idempotency if a kernel is already running, latency, or whether the notebook must be open. Adds some context beyond annotations, not rich 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?

A single front-loaded sentence with no filler; the scoping clarification sits in a tight parenthetical rather than bloating the text.

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 tool with no output schema, the description covers the essentials of what the tool does and its non-destructive nature. It omits prerequisites (must the notebook be open?) and behavior when a kernel already exists, which are relevant for a kernel lifecycle tool.

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

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

Schema coverage is 0% and the description never addresses notebook_id, so it adds no meaning beyond the schema. However, with a single, self-evidently named identifier parameter, the practical risk of misinterpretation is low, so an adequate-but-minimal 3 is appropriate.

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

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

States a specific verb and resource ('Start the notebook's Python kernel') and adds the timing nuance 'ahead of the first cell'. It is distinguishable from notebook_run (which runs code) and notebook_kernel_state, though it does not explicitly name those 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 phrase 'ahead of the first cell' implies the use case: pre-warming the kernel before executing cells. It never explicitly states when to use this instead of notebook_run or notebook_kernel_control, leaving the routing to inference from the tool name.

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?

readOnlyHint=true already declares this is a safe read, so the bar is lower. The description adds genuine value by listing the six possible states (stopped, starting, idle, busy, error, dead), which tells the agent what to expect back. It does not explain how states transition, whether the call blocks, or what happens for an unknown notebook_id.

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?

A single tight sentence with the states front-loaded and zero filler. It is minimal without being wasteful, though the fragment omits any verb tying it to an action.

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 with no output schema, the description partially fills the return-value gap by enumerating the state values, which is the key thing an agent needs. However it omits any guidance on usage, error behavior, or how the state maps to next actions, leaving notable 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?

Schema description coverage is 0% and the single parameter (notebook_id) is left entirely unexplained in the description. The name is fairly self-evident, but the description does nothing to compensate for the missing schema documentation as the rubric requires at 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 states a specific resource (the notebook kernel's state) and enumerates the exact possible values it can take, so an agent knows it is a state-read, not a start/stop/control action. It is a noun phrase rather than a verb, and it does not name the sibling tools it differs from (notebook_kernel_start, notebook_kernel_control), but the intent is unambiguous.

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

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

There is no explicit when-to-use guidance and no alternatives named. An agent can infer it should be called to check kernel status before running a notebook, but the description never says so, nor does it mention polling or when to prefer notebook_poll.

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?

readOnlyHint=true already declares the safe-read profile, so the description only needs to add scope. It adds that the notebook comes from the 'SQL folder' and that exactly one is returned, but says nothing about what 'reading' yields (content vs. handle) or size limits.

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

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

One short, front-loaded sentence with zero filler. The verb and scope lead, and nothing is wasted.

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

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

No output schema exists, so the description carries the burden of explaining the return value, which it does not — an agent cannot tell whether it gets notebook JSON, raw text, or a handle. For a read tool whose result drives the next call, this is a meaningful 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 0%, so the single 'name' parameter is undocumented anywhere. The description hints it is a notebook name located in the SQL folder, but gives no format, extension expectation, or path semantics to compensate for the coverage gap.

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

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

States a specific verb+resource+scope: read one .ipynb notebook from the SQL folder. This distinguishes it from notebook_run (execution) and notebook_files (listing), though it doesn't name those siblings explicitly.

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

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

No when-to-use guidance and no alternatives named. An agent must infer that this opens a single notebook by name, with no indication of prerequisites or when to prefer it over notebook_files or notebook.

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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful context by naming the fields returned, which partially compensates for the absent output schema, but it says nothing about scope (which kernel/environment it reflects) or whether results are cached/live.

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?

A single compact, front-loaded fragment with no filler; the resource comes first and the returned fields follow. It is appropriately sized, though a fragment rather than a full sentence limits it slightly.

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

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

For a zero-param, read-only tool with no output schema, listing the return fields is the main thing an agent needs, and the description supplies it. Minor gaps remain around which environment/kernel is being reported and any pagination or size limits.

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

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

The tool takes zero parameters, so the baseline is 4. There is no parameter meaning to clarify and the description correctly does not invent any.

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 resource (packages installed in the notebook Python environment) and enumerates the returned fields (name, version, summary, core). The implicit 'list' verb and the word 'installed' distinguish it from the sibling notebook_packages_install, though the naming contrast is not stated explicitly.

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

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

No when-to-use guidance, no prerequisites, and no pointer to alternatives. With siblings like notebook_packages_install and notebook_environment present, the description should say when to call this versus those, and it does not.

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?

Annotations declare readOnlyHint=false and destructiveHint=false, so the mutation profile is partly covered. The description adds input-format context (space-separated, optional pins) but says nothing about whether the environment must restart, whether installs take effect immediately, or reversibility.

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

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

One front-loaded sentence with zero filler and the resource, format, and target all conveyed compactly.

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 install tool with no output schema and annotations covering the safety profile, it is adequate but thin. It omits what success looks like, restart/refresh requirements, and behavior on failure.

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 a single parameter at 0% schema description coverage, the description carries the full burden and does so by explaining the syntax: space-separated names with optional version pins. That is meaningful guidance beyond the bare string type.

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?

Clear specific verb 'Install' plus resource 'packages' and target scope 'into the notebook environment'. However, it does not distinguish itself from the similarly-named sibling notebook_environment_install, which an agent could easily confuse with 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?

No when-to-use guidance and no exclusions. The sibling set contains notebook_environment_install and notebook_packages, yet the description offers nothing about which to pick or under what 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?

The readOnlyHint annotation already signals a safe read operation, and the description adds incremental polling semantics by mentioning 'since output index after' and 'running (or finished) cell'. It does not describe return format, pagination, rate limits, or error behavior, so it is adequate but not rich.

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

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

The description is a single, front-loaded sentence with no wasted words. It is appropriately sized for the tool's simple polling purpose.

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

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

For a polling tool with three parameters at 0% schema coverage and no output schema, the description does not explain run_id, cleared, return values, or polling behavior. It is too incomplete for an agent to invoke confidently without additional context.

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

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

Schema description coverage is 0%, so the description must explain all three parameters. It only clarifies the 'after' index meaning; run_id and cleared are left undocumented in both schema and description, leaving significant gaps.

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

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

The description states that the tool returns new output from a running or finished cell since a given output index, which is a specific resource and operation. It does not explicitly differentiate itself from siblings like notebook_run or notebook, but the polling intent is clear from the name and phrasing.

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 explicit guidance is provided on when to use this tool, when not to use it, or which alternatives exist. A reader can infer it is for polling after a cell run, but the description leaves all usage context to inference.

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

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

Goes well beyond the annotations: it discloses that SQL results become a DataFrame named 'df' (and 'name' if given), that data/schema-changing statements return 'needs_confirmation' unless 'confirmed', and that SAS runs in the SAS Viya session with libref S2 mapped to the notebook database. This is exactly the kind of mutation-confirmation and side-effect context the destructiveHint annotation alone cannot convey.

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

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

Front-loads the core action and return pointer, then structures the rest by cell_type, so every line earns its place. Slightly dense but no filler.

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

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

For a 6-param mutation tool with no output schema, it covers return value (run id), the confirmation flow, and per-type behavior adequately. It stops short of describing failure behavior or setup prerequisites, but nothing critical is missing for correct invocation.

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

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

With 0% schema description coverage the description must carry the load, and it explains cell_type values thoroughly, plus name, confirmed, and the database mapping via libref S2. notebook_id and source are left implicit, so it compensates well 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?

States a specific verb and resource ('Run one notebook cell in its kernel') and immediately distinguishes itself from sibling notebook_poll by noting it returns a run id to poll with it. An agent can differentiate it from notebook_open/notebook_save/notebook_ask without inspecting 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?

Points clearly to the follow-up step ('poll with notebook_poll') and enumerates how each cell_type is handled, giving strong usage context. However, it does not state prerequisites (e.g., that a kernel must be started via notebook_kernel_start) or when to prefer this over siblings like notebook_ask, so guidance is strong but not fully explicit.

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?

Annotations declare readOnlyHint=false and destructiveHint=false, so the write-but-not-destructive profile is already covered. The description adds the useful facts that the payload must be nbformat 4 JSON and that the file lands in the SQL folder, but it never explains what happens when a file with the same name already exists, despite an overwrite parameter.

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?

A single front-loaded sentence with no padding; the verb and resource come first and the qualifiers follow. It is appropriately sized, though terse enough that it underspecifies rather than over-explains.

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 a nested-object parameter, an undocumented overwrite flag, no param descriptions, and no output schema, the description is too thin. An agent lacks the information needed to call it safely when an existing file is present.

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

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

Schema description coverage is 0%, so the description must carry the burden, but it only indirectly clarifies the notebook parameter's format (nbformat 4 JSON). The name parameter and the overwrite flag, including its default of false, are left 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?

Names a specific verb (save) and resource (notebook), and adds format (nbformat 4 JSON) and destination (.ipynb in the SQL folder), which lets an agent distinguish it from notebook_run or notebook_open. It does not, however, differentiate it from closely related siblings like notebook_files or sql_editor_save_file.

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

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

There is no statement of when to use this tool versus alternatives such as notebook_files or notebook_open, nor any precondition guidance. Usage must be inferred entirely from the name and the mention of the SQL folder.

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?

The readOnlyHint=true annotation already establishes this is a safe read. The description adds ordering ('most recent') and scope ('one pipeline'), but says nothing about rate limits, what error fields are returned, or how the limit interacts with ordering — useful context that is missing.

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

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

A single short, front-loaded sentence with no filler. It is efficient, though the terseness contributes to the gaps in other dimensions rather than being purely a virtue.

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

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

With no output schema, 0% parameter documentation, and only a readOnly annotation, the description is too thin for a tool that requires two identifiers and exposes a limit. It omits return shape, identifier semantics, and limit behavior.

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 carries the full burden and adds essentially nothing about the three parameters. It does not explain that pipeline_name and database are required, nor what limit controls (default 25), nor the relationship between the two 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 states a clear verb+resource: retrieving the most recent errors for a single pipeline. An agent can tell this returns error data, but it never distinguishes itself from closely related siblings like pipeline_monitor_data or pipeline_status, leaving some ambiguity about which to pick.

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

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

There is no guidance on when to use this versus pipeline_monitor, pipeline_monitor_data, pipeline_status, or test_pipeline. 'For the Pipeline Monitor app' is context about the domain, not a usage condition or exclusion.

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 readOnlyHint=true, the safety profile is already covered, yet the description adds genuinely useful context: the view offers start/stop/test buttons and auto-refresh, and the result carries a browser_url. That pre-empts confusion about whether this tool itself mutates anything. It does not mention permissions or any limits, so it is not exhaustive.

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

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

Front-loaded with the action and the usage trigger, then result handling, then args — a sound ordering. Slightly padded and it mixes prose with a Python-style 'Args:' block, but every sentence carries 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 single-parameter, no-output-schema tool, the description covers purpose, trigger, the shape of the return (browser_url) and the parameter's semantics. There is no material gap an agent would need filled before calling it.

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

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

Schema description coverage is 0%, so the description carries the full burden for the single optional parameter — and it does: 'Limit to one database. Omit to show pipelines in all databases.' Scope and default behavior are both fully specified, leaving nothing 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?

States a specific verb and resource ('Open an interactive monitor of SingleStore pipelines') and immediately scopes it to the visual/interactive surface, not raw data. The phrase 'see or manage pipelines visually' implicitly separates it from text-based siblings such as list_pipelines and pipeline_status. An agent can route to it without opening the schema.

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

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

Gives an explicit trigger ('Use this when the user wants to see or manage pipelines visually') and even post-call guidance ('post it as a clickable link right under the app'). It never names the sibling it replaces for non-visual cases, so the when-not 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?

The description says the tool 'refreshes data', which connotes a state-changing operation (reloading/regenerating data), while the annotations declare readOnlyHint=true. That is a direct conflict about whether the tool mutates anything. The description also adds no other behavioral context (auth needs, cost, side effects), so it fails the one job it had here.

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?

It is a single short sentence with no padding, which is structurally clean. However, the brevity is under-specification rather than economy: the one sentence conveys almost no actionable information, so it does not fully earn 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?

For a tool with an undocumented parameter, no output schema, and only a single readOnlyHint annotation, the description is far too thin. It leaves the agent unable to resolve the read/write ambiguity, the meaning of the 'database' argument, or when this is preferable to pipeline_monitor or pipeline_status.

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 optional 'database' parameter has no schema description (0% coverage), and the description never mentions it at all. The agent cannot tell whether 'database' scopes which database's pipeline data is refreshed, whether omitting it means all databases, or what values are valid. The description does not compensate for the coverage gap.

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

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

The description gives a verb (refresh) and an object (data for the Pipeline Monitor app), so the general intent is graspable. But it never says what 'refresh' concretely does or what data is involved, and it does nothing to distinguish itself from siblings like pipeline_monitor, pipeline_status, or pipeline_errors. Purpose is vague rather than tautological.

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

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

There is no guidance on when to call this versus pipeline_monitor, pipeline_status, or any other sibling. No preconditions, no exclusions, no alternatives are named. The agent is left to infer usage entirely from the name.

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