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

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint), and the description adds genuinely new behavior: the wait_seconds bound, the 'pending' status and polling loop, and the caveat that answer/SQL are MODEL-GENERATED and not authoritative. The 'EXECUTION+READ_ONLY' label is consistent with the read-only annotation.

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 core action and return, then workflow, then a caveat. Multi-line but every sentence carries information (return shape, poll mechanism, model-generated warning); nothing is 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?

With an output schema present the description needn't restate return values, yet it still summarizes them and explains the pending/poll lifecycle, which is the main risk of misuse. Nothing needed to call this correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents space_id, question, message_id, conversation_id, wait_seconds, and max_rows. The description reinforces the polling semantics (omit question, reuse ids) but adds little parameter-level syntax beyond the schema. Baseline 3 applies.

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

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

The first sentence names a specific verb and resource ('Ask a natural-language question in a Genie space') and states the return. It is distinguishable from execute_sql and the manage_* siblings by scoping to Genie spaces and NL questions.

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

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

It gives clear conditional usage: start vs follow-up with conversation_id, and explicitly says to poll by calling again with the returned ids and no question. It does not name sibling alternatives (e.g. execute_sql) for when a raw SQL path is preferable, 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 flag readOnlyHint=false/destructiveHint=false, and the description adds real value by explaining what is and isn't destroyed (manifest entry only, not the resource), which directly explains the non-destructive classification. It omits auth requirements or reversibility of the manifest edit, but adds more than the annotations 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?

Front-loaded with the core action and the important non-deletion caveat in the first sentence. The trailing 'Safety classification: WRITE.' is largely redundant with the annotations, costing a little efficiency but nothing is 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 three-parameter, output-schema-backed tool, the description covers the action, the scope boundary and the alternative tool. The dry_run parameter is never mentioned in prose, but the schema handles it, leaving the definition essentially complete.

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

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

Schema description coverage is 100%, so resource_id, resource_type and dry_run are already documented with examples and defaults. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Remove an entry from the local project manifest') and disambiguates scope with '(stop tracking it)'. It clearly separates itself from the manage_* siblings that mutate the actual Databricks resource.

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

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

Explicitly tells the agent when NOT to use it ('This does NOT delete the Databricks resource itself - use the matching manage_* tool for that'), which is the key routing decision. It doesn't mention when to prefer this over list_tracked_resources or any prerequisite sequencing, but the context is clear.

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

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

Goes well beyond the annotations: fresh execution context per call with no state kept between calls, temp notebook path, stdout/stderr capture, success/failed/pending return semantics with ids to poll, and explicit cost/security note ('code can change data and costs money'). The safety classification (EXECUTION/READ_ONLY/WRITE depending on input) adds nuance the static destructiveHint=false does not 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 one-line purpose, then uses tight action-scoped bullets. It is dense and slightly long, but nearly every clause earns its place (compute semantics, state behavior, timeout/polling).

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

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

Covers compute selection, state model, return shapes, timeout/polling lifecycle, and the SQL alternative. With an output schema already present, the return-format detail is bonus rather than a requirement, and nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it groups parameters by action (which ids apply to get_status/cancel vs run), explains the compute tradeoff, and ties timeout_seconds to the 'pending' return. The only gap is that it does not elaborate on confirm/dry_run beyond the schema.

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

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

States a specific verb (Execute) and resource (Python/SQL/Scala/R code on Databricks compute) and returns output. It enumerates the three sub-actions (run, get_status, cancel) and explicitly names the sibling execute_sql for the SQL-on-warehouse case, so an agent can distinguish it from siblings without opening any schema.

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

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

Explicit routing: 'For SQL on a SQL warehouse prefer execute_sql.' It also tells the agent when to use cluster vs serverless (serverless is Python-only, slower to start) and when to call get_status/cancel (pending executions). Alternatives and conditions are stated, not inferred.

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 by disclosing the statement classification scheme (read/write/destructive/security-sensitive and what falls in each bucket), the confirm gating behavior, row capping via max_rows, and the 'pending' status when wait_timeout_seconds elapses. The annotations only broadly declare destructiveHint=true; the description explains exactly which inputs trigger destructive behavior and what the response envelope 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?

Front-loaded with the core action, then classification/safety rules, then response shape and timeout behavior. Dense but each sentence carries actionable content. The trailing 'Safety classification' line restates the classification rules already enumerated above, which is mild 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?

Covers classification, safety gating, dry-run/confirm flow, timeout and polling, row capping, and warehouse selection for a 10-parameter, high-stakes tool. An output schema exists, yet the description still usefully sketches the data.result/data.execution split, leaving no material gap 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?

Schema description coverage is already 100%, so the baseline is 3. The description adds operational meaning by tying parameters together: max_rows caps returned rows, the wait_timeout/pending path connects to a follow-up tool, and warehouse selection falls back through env var to automatic selection reported in the response. Some of this repeats the schema, keeping it below 5.

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

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

States a specific verb+resource (execute one SQL statement) and the exact backend (Databricks SQL warehouse via the Statement Execution API). It also implicitly distinguishes itself from the sibling execute_sql_multi (scripts) and manage_sql_statement (polling a pending statement by id), so an agent can separate it from neighbors without opening schemas.

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

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

Gives concrete conditional guidance: destructive/security-sensitive statements require confirm=true, and a still-running statement should be polled with manage_sql_statement. It does not explicitly say when NOT to use this tool (e.g. multi-statement scripts), though that alternative is named in the statement parameter description rather than in the prose.

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?

Despite destructiveness already flagged in annotations, the description adds substantial context: no transaction/rollback semantics, stop-at-first-failure default, 'skipped' reporting for remaining statements, and the union-of-classifications safety model requiring confirm=true. This goes well beyond what structured fields 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?

The core behavioral rules are front-loaded and dense with no filler. The trailing 'Safety classification: depends on input (...)' line is a somewhat terse tag list, but it is short and does not bloat the definition.

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 annotations covering the safety profile, a full 100% schema description coverage, and an output schema handling return values, the description supplies exactly the behavioral context an agent needs for a multi-statement, non-transactional executor. Nothing critical is missing.

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

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

Schema coverage is 100%, establishing a baseline of 3, but the description adds genuine meaning for continue_on_error ('remaining statements reported as skipped') and confirm (required for destructive/security-sensitive actions), clarifying behavior the schema text does not fully capture.

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

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

The opening clause states a specific verb and resource: 'Execute several SQL statements sequentially, preserving order.' This clearly differentiates it from the single-statement execute_sql sibling by emphasizing multiplicity, though it never names the sibling explicitly to route the agent.

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 explains the continue_on_error and confirm behaviors well, but gives no explicit when-to-use guidance relative to execute_sql or execute_code. The choice of this tool over its single-statement sibling is only implied by the word 'multi'.

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?

Adds real context beyond annotations: external resources are blocked (only inline data: URIs), it discloses the return payload (path, size, page count, SHA-256), the optional dependency, and the destructive/write classification. Annotations already cover readOnly/destructive/openWorld hints, so the description's environment and output disclosures are the value-add; slightly more on overwrite semantics would push this to 5.

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

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

Front-loads the core action and format behaviour, then safety classification. Dense but each sentence carries information. Minor redundancy between the parenthetical normalization note and the mention of html/text/markdown 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?

An output schema exists so return values need not be re-explained, but the description still names them helpfully. With annotations and full schema coverage, the description covers inputs, environment restrictions, and safety classification. The confirm/dry_run workflow could be spelled out slightly more for a destructive 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 100%, so all 8 parameters including confirm, dry_run, and overwrite are already documented. The description reinforces input format conversion (Markdown/plain text to escaped HTML) but adds little syntax beyond the schema, making baseline 3 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 (render to PDF and upload) and resource (Unity Catalog Volume path ending in .pdf), and enumerates accepted input formats. No sibling tool does this, so it is distinguishable 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 concrete context: input format options, destination constraint, dependency requirement. It also implies the confirm/dry_run flow for destructive actions. But it does not name an alternative (e.g., manage_volume_files) or say when NOT to use this vs. generic file 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 only declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true. The description adds substantial context beyond that: the SECURITY_SENSITIVE+WRITE safety classification, the fact that the token is withheld by default, exactly what connection details are returned, and that reveal_token requires confirm=true and must be treated as a secret. This is rich disclosure that the structured fields do not provide.

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

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

The purpose is front-loaded in the first sentence, followed by mode routing, default-return behavior, and secret handling. Sentences are dense and mostly earn their place, though the trailing 'Safety classification' tag reads as metadata rather than guidance.

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 annotations present, an output schema available, and 100% schema coverage, the remaining burden on the description is the mode selection and the token-reveal safety contract, both of which are covered. An agent has everything needed to call this correctly and safely.

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

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

Schema coverage is 100%, so the per-parameter documentation baseline is 3. The description goes beyond the schema by documenting inter-parameter relationships the schema cannot express: kind selects which of instance_names/claims vs endpoint/ttl_seconds apply, and reveal_token is gated on confirm. That added coupling justifies a 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 (Generate) and resource (short-lived OAuth credential) with scope (for Lakebase Postgres, as the current identity), which cleanly separates it from siblings like manage_lakebase_database and manage_lakebase_branch. An agent can identify the tool's function 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?

The description routes the caller between the two operating modes (kind='provisioned' vs kind='autoscaling') and tells which parameters apply to each, which is clear contextual guidance. It does not, however, name any sibling alternative or state when-not to use this tool, so it stops short of explicit when/when-not routing.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false. The description adds real value beyond them: it discloses the returned identity scopes and explicitly states 'Never returns credentials', which is a security-relevant guarantee the agent could not infer from 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 tightly written sentences, front-loaded with the verb and resource, followed by the return scope and the credential caveat. 'Safety classification: READ_ONLY' mildly restates the readOnlyHint annotation but is short and harmless.

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 and an existing output schema, the description only needs to orient the agent, which it does. It could have noted failure behavior when the session is unauthenticated, but nothing essential for invoking the tool 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 and the schema is empty, so there is nothing for the description to disambiguate. Baseline 4 applies; the field enumeration is a return-value concern rather than a parameter one.

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

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

States a specific verb and resource ('Return the Databricks identity this server is authenticated as') and enumerates exactly what that identity includes (username, user id, display name, groups, home folder, workspace). No sibling tool overlaps with identity retrieval, so the agent can distinguish it immediately.

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

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

Usage is implied by the phrase 'this server is authenticated as' — the tool is for resolving the acting principal — but there is no explicit when-to-use, when-not-to-use, or named alternative. In practice no sibling competes with it, so the missing routing guidance costs little.

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 destructiveHint=false, so the safety baseline is covered. The description goes further by disclosing that exact_count scans the table and that a warehouse may be started (auto never starts one), plus the 'depends on input' safety classification — useful side-effect and cost context beyond 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?

Front-loaded with the core action and the returned-field inventory, then the alternate listing mode and safety note. It is dense but every clause carries information; the long parenthetical field list is borderline verbose but useful for an inspection 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?

With an output schema present and full schema coverage, the description needn't detail return shapes, and it correctly focuses on the dual mode, stats cost semantics, and safety classification. An agent has enough to call it correctly; only explicit sibling alternatives 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 100%, so the schema already carries name, stats enum, pagination, and warehouse resolution details. The description largely restates these (pagination for schema listing, stats categories) without adding format or syntax beyond the structured fields, so the baseline of 3 applies.

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

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

States a specific verb (Inspect) on a specific resource (Unity Catalog table), enumerates exactly what metadata is returned, and covers the distinct second mode (listing tables in a schema from a two-part name). This is easily separable from the manage_* siblings, which are mutations.

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 two usage modes (full table name vs catalog.schema) are explained, which is genuinely helpful routing. However, there is no explicit when-to-use/when-not-to-use guidance or named alternative (e.g. execute_sql, manage_uc_objects) for overlapping needs.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety burden is covered, yet the description still adds real behavioral detail: recursion is bounded by max_depth/max_entries caps, the scan is capped at 10000 entries, results are paginated, and directories with _delta_log are reported as Delta tables. This is meaningful context 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?

Front-loads the verb and resource in the first clause, then branches cleanly into directory and file cases. Dense but every clause about formats, caps and delta detection earns its place; the trailing 'Safety classification: READ_ONLY.' is mildly redundant with the annotations.

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 values need not be described, yet the description helpfully enumerates them anyway. Combined with annotations covering safety and a fully documented schema, an agent has nearly everything needed; only sibling routing is missing.

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

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

Schema coverage is 100%, so the schema already documents all seven parameters and the baseline is 3. The description still adds interpretive value by explaining what the recursive, max_depth and max_entries parameters jointly govern and what delta detection actually probes 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?

States a specific verb (inspect) and resource (a Unity Catalog Volume path) and clearly distinguishes directory vs file behavior. It does not, however, differentiate itself from the obvious sibling manage_volume_files, so the agent must infer the boundary itself.

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 explains what is returned but never says when to use this tool versus alternatives such as manage_volume_files, nor any precondition or exclusion. Usage is left entirely to inference from a sibling list the description ignores.

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, destructiveHint=false and openWorldHint=true, so the 'Safety classification: READ_ONLY' sentence merely restates structured data and earns no credit. The description adds useful context about what the listing exposes (current state, node types, runtime versions), but says nothing about auth needs, result caps, or pagination behavior beyond what the schema already carries.

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 and compact: the core scope sentence comes first and reads cleanly. The trailing 'Safety classification: READ_ONLY' line is pure redundancy against the readOnlyHint annotation and should be dropped, which is the only real waste.

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 an output schema present, the description need not explain return values, and it does adequately convey the two resource families and their attributes. Given 4 parameters at full schema coverage and rich annotations, the remaining gap is the absence of any guidance on narrowing results with the filter or handling pagination.

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

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

Schema description coverage is 100%, so all four parameters (filter, resource, page_size, page_token) are already documented with semantics and defaults. The description only loosely echoes the resource categories through its mention of node types and runtime versions, adding little beyond the enum's own description. Baseline 3 is appropriate.

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

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

States a specific verb ('List') plus the concrete resource set it covers ('all-purpose clusters and SQL warehouses') and enumerates the returned attributes (state, node types, Photon support, Databricks Runtime versions). This cleanly separates it from the manage_cluster and manage_sql_warehouse siblings, which are mutation-oriented.

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 and the scope statement, but there is no explicit guidance on when to call this versus manage_cluster, manage_sql_warehouse, or get_table_stats_and_schema, and no mention of prerequisites or follow-up tools. An agent can infer the read-only inventory role but gets no routing help.

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, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds real behavioral context beyond them: the manifest-only scope, that verify performs a Databricks existence check per item and reports missing ones, and that results are paginated. Cost side-effects of verify are disclosed, though the trailing 'Safety classification: READ_ONLY' merely restates 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?

Four sentences, front-loaded with the purpose and scope before the verify behavior and pagination note; no filler in the body. The final 'Safety classification: READ_ONLY.' sentence is redundant with the readOnlyHint annotation and could be cut, which keeps it short of a 5.

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

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

With an output schema present, the field list is a bonus rather than a requirement, and the annotations cover safety. The description supplies the scope, the verify side-effect, and pagination, which is everything an agent needs to call this read-only list tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents verify, page_size, page_token, and resource_type. The description reinforces verify semantics ('missing ones are reported') and implies pagination, adding only marginal meaning beyond the schema. Baseline 3 is appropriate when the schema carries the parameter burden.

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 tracked resources) and immediately defines the scope: resources recorded in the local project manifest created through this server. It enumerates the returned fields (type, id, name, creating tool, creation time, workspace), which makes the tool self-differentiating from siblings like list_compute and delete_tracked_resource without needing to open a schema.

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

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

The verify=true clause gives concrete context for when that option is wanted, and mentioning pagination hints at iterative use. However, there is no explicit when-to-use-this-vs-alternatives guidance or prerequisite statement (e.g., use before delete_tracked_resource, only sees resources created via this server). 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?

Annotations already flag destructiveHint=true/openWorld, but the description adds real value beyond them: safety level varies by action (DESTRUCTIVE/EXECUTION/READ_ONLY/SECURITY_SENSITIVE/WRITE), create/deploy/start/stop return 'pending' unless wait=true (bounded), `logs` is unavailable, and created apps are tracked in the manifest. Return format is left to the output schema, which exists.

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 purpose, then a scannable action list, then behavioral notes. Dense but every clause carries signal (async semantics, partial-update semantics, safety variance); only mildly verbose overall.

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 an output schema exists, return values need not be described, and the description covers actions, async/wait behavior, and per-action safety. The confirmation/dry_run flow is delegated to the schema, which is acceptable but leaves a little room.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful action-to-parameter mapping (e.g. deploy = source_code_path + mode SNAPSHOT|AUTO_SYNC, update = partial fields) that orients the agent before reading the schema.

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

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

States a specific verb+resource (manage Databricks Apps) and enumerates the full action set, so the agent knows exactly the operation surface without opening the schema. The name and scope cleanly separate it from sibling manage_* tools targeting clusters, warehouses, jobs, etc.

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?

Maps each action to its relevant inputs (create takes name/app/no_compute, deploy takes source_code_path/mode, etc.), which gives clear invocation context. It does not, however, explicitly route between siblings or state when-not-to-use, 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?

Discloses behavior far beyond annotations: confirm gating, refusal for clusters matching protected production name/tag patterns, immediate vs. wait behavior for lifecycle actions, and a full safety classification mapping each action to READ_ONLY/WRITE/DESTRUCTIVE. This is exactly the context a mutation dispatcher needs.

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

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

Dense but front-loaded and well-sectioned under 'Actions:' and 'Safety classification:', with no filler sentences. It repeats the terminate/delete semantics already in the action enum description, a minor redundancy.

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

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

For a 13-parameter, 10-action dispatcher with an output schema present, the description covers every action, the confirm/dry_run/wait contract, and the safety profile. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real value by supplying the create spec body example field names ({cluster_name, spark_version, node_type_id, num_workers/autoscale, autotermination_minutes}) and the partial-update semantics for spec, which the schema does not enumerate.

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 ('Manage all-purpose clusters') and enumerates every action (list, get, events, create, update, resize, start, restart, terminate, delete) with a parenthetical clarifying each. An agent can distinguish it from siblings like list_compute or manage_jobs 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 clear per-action conditions: confirm=true is required for restart/terminate/delete, wait=true controls whether lifecycle actions return immediately, and list can be state-filtered. It never names alternative sibling tools to route to, so it stops short of explicit when-not/alternatives 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description adds real behavioral context: delete moves to trash and is recoverable, update uses etag for optimistic concurrency, publish with embed_credentials is SECURITY_SENSITIVE and requires confirm, and created dashboards are tracked in the project manifest. It also clarifies the safety classification varies by action rather than being fixed.

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 resource and then a compact action list with parenthetical arguments, followed by two short standalone notes. Dense but every clause carries information; only the safety-classification restatement is somewhat redundant with annotations.

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 15-parameter, 8-action tool with an output schema and annotations present, the description covers the action surface, the recoverability of delete, the concurrency mechanism, and credential sensitivity. Pagination and the confirmation/dry_run workflow are left to the schema, which is reasonable given full coverage.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema. The description maps parameters to actions (e.g. parent_path and serialized_dashboard for create, etag for update), which adds light orientation but nothing beyond the schema's own descriptions. Baseline 3 is appropriate.

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

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

States a specific verb (Manage) and resource (AI/BI Lakeview dashboards) and enumerates the eight discrete actions with their key arguments. An agent can identify this as the dashboard lifecycle tool and distinguish it from siblings like manage_metric_views or manage_workspace.

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 per-action argument mapping implies what each action does, which aids action selection, but there is no explicit guidance on when to use this tool versus siblings, nor any when-not conditions. Usage is inferable but not spelled out.

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 by classifying each action as READ_ONLY/WRITE/DESTRUCTIVE, disclosing that delete moves to trash, that update's serialized_space is a full replacement, that etag is used for concurrency, that list_conversations requires CAN MANAGE and include_serialized_space requires CAN EDIT, and the two-step confirm flow.

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 resource scope, then uses a tight per-action list plus a safety classification line. Every line carries decision-relevant information; nothing is padding.

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

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

For an 8-action, 10-parameter tool with an output schema and annotations, the description supplies the action semantics, safety tiers, confirmation protocol, and permissions that structured fields alone would not convey. Nothing an agent needs to select or invoke it correctly is missing.

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

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

Schema coverage is already 100%, but the description adds action-to-parameter mapping that the schema does not carry: which spec fields apply to create vs update, that etag belongs to update, and that include_serialized_space is a get-only flag. Useful, though individual parameter meanings largely remain in the schema.

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

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

States a specific verb+resource (manage AI/BI Genie spaces) and immediately scopes it as natural-language-to-SQL over Unity Catalog tables. It enumerates every action, so an agent can tell it apart from ask_genie and the other manage_* siblings without opening a schema.

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

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

Explicitly routes query-asking to ask_genie, tells the agent which actions need confirm, and gives a concrete tip (fetch include_serialized_space=true first to learn the spec format). Usage conditions are stated, not implied.

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 destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so the safety profile is partly covered. The description does add value by pinning destructiveness to specific actions and describing the confirm-after-confirmation_required workflow plus the bounded-poll behavior of wait. However, it does not describe permissions requirements, rate limits, or what state is left behind after a destructive action, so it remains moderate rather than 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 summary sentence is front-loaded, followed by a compact bulleted map of action-to-parameter semantics and a one-line safety note. For a 9-action, 16-parameter tool the length is justified, though the per-action bullets partly restate the schema's own action enum descriptions.

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 an output schema present, return values need not be re-explained, and the description covers action semantics, the confirmation gate, and per-action destructive classification. It is complete enough to call correctly, with only minor gaps such as pagination expectations that the schema already handles.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema and the baseline is 3. The description adds some grouping value by mapping actions to their parameters (e.g., spec fields for submit, repair's rerun options, task_key for get_output), but it does not add format or syntax details beyond what the schema already carries.

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

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

The opening sentence names a specific resource (Databricks job runs) with concrete verbs (start, monitor, inspect, cancel, repair), and the bullet list enumerates every action. It is clear what the tool does, but it never names a sibling such as manage_jobs (job definitions) or manage_pipeline_run to disambiguate runs from job-level management, so it stops short of full sibling differentiation.

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?

Each action is annotated with its intent and required inputs, and destructive actions (cancel, cancel_all, delete_run) are flagged as needing confirmation while repair is flagged EXECUTION, which tells the agent how to proceed. What is missing is explicit routing guidance against alternative tools when a user wants to manage job definitions rather than runs.

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 flag destructiveHint=true, readOnlyHint=false, openWorldHint=true, but the description adds rich operational detail: which actions require confirm, the SECURITY_SENSITIVE confirmation for run_as/access_control_list, partial vs full overwrite semantics, and the wait polling behavior for run_now. This goes well beyond structured data.

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 front-loaded with a clear purpose statement, then uses bullet points to organize action-specific details. It is somewhat long because it enumerates many spec fields, but the structure is efficient 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?

Given the tool's complexity (11 parameters, 7 actions), the description covers all actions, safety confirmations, dry_run, and run_now return behavior. With an output schema present, return values need not be explained, so the definition is complete for an agent to call it correctly.

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

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

The schema has 100% description coverage, so the baseline is 3. However, the description adds significant meaning about the 'spec' object expected fields, task requirements, and update merge semantics, which are not fully captured in the schema's high-level parameter descriptions.

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

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

The description opens with a specific verb list and resource ('Create, inspect, change, delete and trigger Databricks Lakeflow Jobs'), then enumerates every supported action. It does not explicitly name alternative tools for run management, 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?

The action descriptions give clear context for when to use each mode (e.g., create vs update vs reset), and the safety notes explain prerequisites like confirm and dry_run. No explicit when-not-to-use guidance or sibling alternatives are named, so it stops short of the top rubric.

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 give a global destructiveHint=true and openWorldHint=true, which over-warns for the many read actions. The description adds real per-action granularity by classifying each action as READ_ONLY, WRITE, DESTRUCTIVE, EXECUTION+WRITE, or SECURITY_SENSITIVE, and notes that sync_sources re-ingests non-index sources. That is meaningful disclosure beyond the annotations, though it does not describe async timing or failure 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?

Purpose is front-loaded, actions are grouped as scannable bullets, and the safety classification is one consolidated line rather than repeated per action. It is dense and long, but the density is driven by 18 actions and 10 parameters, and nearly every clause carries actionable 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 broad multi-action tool with a rich output schema and fully described parameters, the description supplies the missing pieces: action inventory, per-action payload requirements, safety tiers, and the cross-tool route for querying. Nothing an agent needs to select and invoke an action correctly is absent.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema alone documents confirm, dry_run, page_size, ids, and update_mask. The description goes beyond that by spelling out the spec payload shape per action (display_name/description/instructions; source_type 'files'|'index'|'file_table' with the nested key names for each), which the generic 'spec' schema object does not convey.

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

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

The opening sentence gives a specific verb+resource (manage Knowledge Assistants) and immediately characterizes what they are (Agent Bricks document Q&A agents over UC volumes, tables or vector indexes). The action enumeration then maps every sub-operation, and the sibling it is NOT for (querying an assistant) is explicitly routed to manage_serving_endpoint.

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 plus per-action spec hints tell the agent which operation to pick and what fields each requires. It also names the alternative for the query path (manage_serving_endpoint action=query). However, there is no explicit when-not guidance for overlapping siblings like manage_vs_index or query_vs_index, so it stops short of full routing guidance.

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

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

Beyond the annotations it discloses a full safety taxonomy (READ_ONLY/WRITE/DESTRUCTIVE per action), reversibility of soft delete via undelete, the default-branch refusal, the 'pending' async status and wait_seconds semantics, and the confirm/dry_run flow. This is far richer than what readOnlyHint/destructiveHint already 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?

Dense but tightly organized into branch actions, endpoint actions, and a safety classification line, with the goal statement front-loaded. Every clause carries information an agent needs; there is 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 an 18-parameter multi-action tool with an output schema present, the description covers action scoping, async semantics, confirmation, and destructive guards. Nothing an agent needs to invoke it correctly is missing, and return values need not be explained given the 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 coverage is 100%, so the baseline is 3, but the description adds value by grouping which parameters belong to which action alongside the per-action behaviors they trigger. It does not restate the spec field formats those parameters already document, so it stops at 4 rather than 5.

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

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

The first sentence names the specific resource ('Lakebase autoscaling branches (copy-on-write Postgres branches) and their compute endpoints') and the description then enumerates every action, so an agent knows exactly what the tool covers. It clearly separates itself from siblings like manage_lakebase_database and generate_lakebase_credential by scoping to branch/endpoint lifecycle.

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 maps every action to the parameters it consumes and states the conditions that gate risky actions ('soft unless purge=true; the default branch is refused unless allow_default_branch=true'). What is missing is explicit routing against sibling tools (e.g. when to prefer manage_lakebase_database), so it stops short of the top score.

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?

Beyond the coarse annotations (destructiveHint=true, readOnlyHint=false), the description adds a per-action safety classification (READ_ONLY/WRITE/DESTRUCTIVE), explains that delete is soft unless purge=true, that force removes point-in-time children, and that long-running work returns 'pending' unless wait_seconds is set. This meaningfully deepens the agent's understanding of destructive and async behavior.

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

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

The description is dense but well-structured: it front-loads the purpose, then groups details by kind and catalog actions, and ends with a compact safety table. Every sentence contributes to action/kind mapping, async behavior, or safety, and the length is justified by the tool's 11 actions and 18 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?

Given the rich input schema and an output schema, the description need not document every parameter or return value. It covers the essential conceptual model (kinds, actions, safety, async), but it omits any mention of the dry_run/confirm workflow for destructive actions and does not differentiate from sibling tools.

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

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

The schema already documents all 18 parameters at 100% coverage, so baseline is 3. The description goes further by providing concrete spec examples for both kinds and clarifying how force, purge, and branch interact with specific actions. This adds useful cross-parameter semantics beyond the schema's per-parameter descriptions.

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

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

The description opens with a specific verb+resource ('Manage Lakebase (Postgres) databases') and then scopes the tool by kind ('provisioned' vs 'autoscaling') and catalog actions. It does not name sibling tools (e.g., manage_lakebase_branch), so an agent must infer scope rather than being told 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?

It maps each action to a kind and gives concrete examples for create/update specs, plus notes on soft/hard delete and async wait behavior. However, it never states when to choose this tool over sibling tools like manage_lakebase_branch or generate_lakebase_credential, and gives no explicit exclusions.

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 coarse tool-level flags (destructiveHint=true, openWorldHint=true); the description refines them with a per-action safety classification (READ_ONLY/WRITE/DESTRUCTIVE/EXECUTION) and discloses that purge_data drops the Postgres table and that confirm is required after a 'confirmation_required' status. This is real behavioral context beyond the annotations and does not contradict them.

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 resource and reverse-ETL framing, then breaks actions and safety into scannable segments. Dense but efficient; a few items (scheduling policy names, purge_data) duplicate the schema, costing a point.

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 an output schema present, the description need not describe returns, and it covers the remaining essentials: action prerequisites, the unsupported update, kind branching, destructive scope, and the confirmation/dry-run workflow for a 13-parameter 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 already 100%, so the baseline is 3, but the description adds cross-parameter semantics: which params each action needs, that trigger drives pipelines.start_update, and the SNAPSHOT/TRIGGERED/CONTINUOUS scheduling policies. It largely echoes the schema for individual fields, so it stops short of a 5.

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

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

Names a specific resource (Lakebase synced tables) and clarifies the domain with the parenthetical 'reverse ETL: Unity Catalog Delta table -> Lakebase Postgres table'. The enumerated action list makes it unmistakably distinct from siblings like manage_lakebase_branch and manage_lakebase_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?

Gives per-action selection criteria: list requires instance_name, create requires table_name + spec, trigger is 'not for CONTINUOUS', update 'is not supported by the Databricks API', and kind='autoscaling' has 'no list'. Explicit when-to-use and when-not guidance for every mode.

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 coarse annotations (readOnlyHint=false, destructiveHint=true, openWorldHint=true) by classifying each individual action as READ_ONLY, WRITE, DESTRUCTIVE, or SECURITY_SENSITIVE, so an agent knows exactly which action triggers confirmation. It also discloses the constraint that update_tool can only change the description, a real behavioral limit not present in 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?

Front-loaded with the resource definition, then grouped into action families with terse bullets and a compact safety line. Slightly long for a description, but the density is justified by 17 actions; little 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 composite multi-action tool with an output schema and 100% schema coverage, the description covers action semantics, spec shape, and the confirmation/destructive flow (confirm, dry_run interplay implied). It does not spell out the confirmation workflow in full, but the schema's confirm field carries that.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds concrete spec payload examples (e.g. {'tool_type':'genie_space','genie_space':{'id':'...'}}) that the generic schema field ('Request body fields...') does not provide. It also clarifies that update_mask defaults to spec keys and that unknown fields are rejected.

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?

Starts with a specific verb+resource ('Manage Supervisor Agents') and immediately defines what a Supervisor Agent is (a multi-agent orchestrator routing to Genie spaces, KAs, UC functions/connections, apps, volumes), which sharply distinguishes it from siblings like manage_genie and manage_ka. The per-action breakdown makes the scope unambiguous.

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

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

Enumerates all 17 actions with the spec fields each requires, and routes querying to the sibling 'manage_serving_endpoint action=query', which is genuinely useful cross-tool guidance. It lacks explicit when-not-to-use guidance (e.g. when to pick manage_ka over add_tool), so it falls short of a 5.

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

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

Goes well beyond the aggregate annotations by disambiguating per-action safety: create=WRITE; get/list=READ_ONLY; update/delete=DESTRUCTIVE+WRITE; query=EXECUTION+READ_ONLY. It also discloses that update is CREATE OR REPLACE with a plan showing old vs new, that delete requires confirm, and that DDL/queries execute on a SQL warehouse. This is exactly the added context annotations cannot provide.

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

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

Front-loads the purpose in one line, then uses a tight per-action bullet list, ending with a compact safety classification line. Every sentence carries signal with no repetition of schema 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?

With 14 params, a full output schema, and annotations present, the description fills all remaining gaps: action semantics, per-action safety, confirmation flow, and execution target. Nothing needed to invoke the tool correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds value by mapping parameters to actions (e.g., create(full_name, yaml_definition), query(full_name, dimensions, measures, filters?, limit?)) and noting warehouse_id is optional. This clarifies which params apply to which action beyond the per-param schema text.

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 (managing Unity Catalog metric views / semantic layer) and enumerates every action with its signature, so an agent knows exactly what the tool operates on and which actions exist. It is clearly distinguishable from generic siblings like execute_sql or manage_uc_objects.

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?

Each action is annotated with its intent (create/update/delete from YAML, get returns definition+metadata, list enumerates, query runs SELECT dims + MEASURE). It also states that confirm is required for destructive actions, giving clear per-action context. It stops short of naming when to prefer this over sibling tools like execute_sql, so not a full 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 already flag destructiveHint=true, readOnlyHint=false, and openWorldHint=true, but the description adds substantial behavioral context beyond them: delete is DESTRUCTIVE and needs confirm; tables are deleted by default unless cascade=false; update merges top-level fields and uses expected_last_modified to avoid concurrent edits; run_as specs are SECURITY_SENSITIVE; and safety classification depends on input.

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 front-loaded with the overall purpose, then uses concise action bullets for create/get/list/update/delete/clone, followed by routing and safety notes. Every sentence earns its place for a multi-action, 11-parameter tool with complex semantics.

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

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

Given the tool's complexity—six actions, 11 parameters, a nested spec object, and destructive/security-sensitive behaviors—the description covers action semantics, destructive safeguards, update merging, clone migration, and the manage_pipeline_run alternative. With an output schema present, it need not explain return values, so nothing essential is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: update merges top-level fields onto current settings and setting a field to null removes it; delete's cascade default is true (deletes tables) while false keeps them; clone is HMS-to-UC with clone_mode='MIGRATE_TO_UC'; and spec uses Databricks REST API snake_case names with unknown fields rejected.

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 set and resource: 'Create, inspect, change, clone and delete Lakeflow Spark Declarative Pipelines (DLT).' It then enumerates each action, making clear what the tool does and distinguishing it from manage_pipeline_run, which is explicitly named for run/monitor operations.

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

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

The description gives clear action-level context (e.g., 'get (pipeline_id)', 'list (name_contains or filter; paginated)', 'update (pipeline_id, spec)') and routes run/monitor work to manage_pipeline_run. It does not explicitly state when not to use this tool versus other pipeline-adjacent siblings, so it falls 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?

Adds substantial context beyond the annotations: full refreshes are flagged DESTRUCTIVE because table state is reset, stop halts an active update, failed updates carry ERROR events, and start returns status 'pending' with an update_id. It even notes the safety class varies by input, which the readOnly/destructive annotations cannot express.

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 one-line purpose followed by a tight action list and a safety line, with no repeated filler. It is on the longer side for 16 params, but the structure is scannable and each bullet carries distinct 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?

An output schema exists, so return values need not be described, and the description covers the branchy action semantics and destructive cases that the flat schema cannot. The only gap is the absence of explicit routing guidance against sibling pipeline tools.

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

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

Schema coverage is 100%, so every parameter is already documented, giving the description a baseline of 3. The per-action invocation signatures in the description (e.g., start(...) argument lists) are a mild convenience but do not add syntax or semantics the schema lacks.

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 (Spark Declarative Pipeline updates) and enumerates exactly the operations it covers via per-action bullets. The distinction from siblings like manage_pipeline (configuration) and manage_job_runs (job runs) is implicit in the resource named, and no sibling covers pipeline run lifecycle.

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 bullets give clear context per action and the safety sentence tells the agent when confirmation is required. It stops short of naming an alternative sibling or stating when NOT to use this tool (e.g., vs manage_pipeline for editing), leaving some 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?

Goes well beyond the coarse destructiveHint/readOnlyHint annotations: it assigns a per-action safety classification (READ_ONLY/WRITE/DESTRUCTIVE/EXECUTION), discloses that provider credentials are always stripped on list/get, that delete permanently destroys and needs confirm, that create/update return 'pending' unless wait_seconds is set, and that logs are tailed and size-capped.

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 purpose followed by a dense but well-structured bulleted action list where every line carries operational information; the trailing safety classification is compact and useful. Slightly heavy, but nothing is redundant.

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

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

For a nine-action tool with an output schema present, it covers the create/update/delete lifecycle, the dry_run/confirm confirmation flow, asynchronous completion via wait_seconds, pagination-adjacent caps, and per-action risk. An agent has everything needed to invoke the right action correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value by mapping spec contents to specific actions and clarifying that request is only for query with per-mode shapes. It clarifies role of wait_seconds and max_output_chars beyond raw schema text.

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 ('Manage and query Databricks Model Serving endpoints') and then enumerates all nine actions with concrete semantics, so an agent knows exactly what the tool covers. It is clearly distinguishable from the Vector Search sibling manage_vs_endpoint by the 'Model Serving' framing.

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?

Each action is given a usage-specific meaning, including which spec keys belong to create vs update_config vs update_ai_gateway, that delete requires confirm, and that wait_seconds controls blocking on long-running calls. There is no explicit when-not or sibling routing (e.g., vs manage_vs_endpoint), but the action-level guidance is clear.

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

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

The description usefully discloses per-action safety ('get = READ_ONLY; cancel = EXECUTION'), which is genuinely more granular than the tool-level annotations. However, this conflicts with readOnlyHint=true and destructiveHint=false, which declare the whole tool non-mutating even though cancel stops a running statement — an agent trusting the annotation could treat a state-changing action as safe. The accurate disclosure softens the penalty, but the mismatch with the declared safety profile is a real defect.

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: the action first, then the workflow trigger, then the safety classification. Every sentence earns its place, nothing is repeated, and the most important routing information is front-loaded.

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

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

With an output schema present and 100% parameter coverage, return-value explanation is not needed, and the description covers modes, trigger, and safety. The only thin spot is the confirmation/dry_run path implied by those parameters, which the description never touches and the agent must infer from the schema alone.

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