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

With no annotations, the description carries the full load and does well: it discloses read-only semantics, that proposals are never applied, that three parameters are forwarded to find_waste, and the exact return keys. It omits the operational cost of fanning out to three underlying tools and any permission prerequisites.

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 deliverable and window, then composition, then safety, then return shape. Dense but every clause carries information; 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?

No output schema, so it correctly inlines the return keys {days, markdown, measured_saving_usd, projected_30d_usd}. All four parameters are optional with defaults, lowering the cost of underspecification, but the forwarded parameters' meanings remain unexplained.

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 documents `days` (range 1..365) and says the other three are forwarded to find_waste, but never explains what max_rows limits or what the idle-percentage/autotermination thresholds mean operationally.

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 artifact (a markdown cost-review report), the window, and explicitly the three sibling tools it composes (cost_summary, top_cost_drivers, find_waste). An agent can tell immediately that this is the aggregated one-shot report versus the individual primitives.

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 composition statement plus 'Read-only; proposals only — nothing is applied' gives a clear usage context: use this when you want the combined report and aren't applying changes. It stops short of explicit exclusions (e.g. when to call cost_summary alone or whether to call propose_fix afterwards).

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

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

No annotations are provided, yet the description carries the full behavioral burden: it declares read-only status, clarifies the pricing basis (list price, not discount), and explains the completeness caveat (usd_complete=false with unpriced_skus). That is exactly the context an agent needs to interpret partial results.

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 purpose, then pricing caveats, then the usage routing — three sentences plus a directive, none of which are filler. Every clause adds decision-relevant 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?

With no output schema and no annotations, the description compensates fully by naming the returned fields (per-product, per-day, usd_complete, unpriced_skus) and the read-only/list-price semantics. An agent can interpret results without opening anything else.

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 `days` param has no schema description, but the description supplies its semantic range (integer 1..365) and ties it to the reporting window. It doesn't note the 30-day default, keeping it just under 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?

States a specific verb ('Orient on spend') plus the exact resource dimensions returned: total list-price cost, cost per product, and per day. The closing clause ('overall bill shape') distinguishes it from the analytic siblings like find_waste and explain_cost_spike.

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 says 'Use before find_waste when you need the overall bill shape', giving a concrete placement in the workflow and an alternative it precedes. It doesn't exclude scenarios for the other four siblings (top_cost_drivers, cost_review_report), so it falls short of a full when/when-not map.

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

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

With no annotations, the description carries the full burden and does disclose "Read-only" plus the analytical method (single day vs prior 7-day daily average, list-price basis). It does not say what happens when fewer than 7 days of history exist, whether the result is truncated to top-N drivers, or anything about response shape.

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, each doing distinct work: scope, semantics, routing. The parenthetical date clarification is placed inline where it is needed and nothing is repeated from the name.

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, read-only analytical tool with no output schema, this is nearly complete — scope, comparison baseline, and date semantics are all covered. The only gap is the shape/granularity of the returned attribution (e.g. ranked list vs full breakdown).

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 schema only declares a bare string, so the description must compensate — and it does, pinning the format (YYYY-MM-DD), the timezone/billing-day semantics (UTC billing day), and the underlying field (system.billing.usage.usage_date).

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 (explain a one-day cost spike) and immediately names the attribution dimensions (jobs/warehouses/clusters) plus the comparison basis (prior 7-day daily average). This is clearly distinct from cost_summary (aggregate) and top_cost_drivers (ranking) without opening either schema.

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

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

Gives a concrete trigger ("why did Tuesday cost more?") and an explicit sequencing rule — use after cost_summary — which routes the agent relative to a sibling. It stops short of stating when NOT to use it (e.g. multi-day trend questions that belong to cost_summary or cost_review_report).

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

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

With no annotations, the description carries the full burden and does: it declares read-only/'never changes the workspace', documents projection withholding below 3 days and low_confidence below 7 days, explains that USD is None when unknown, and specifies that failed checks surface under `errors` with the table and required GRANT rather than being silently counted as $0.

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 purpose and the read-only guarantee, then return semantics, then check families — a sensible order. It is dense and the check enumeration is long, but each clause carries scope or threshold information rather than 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 names the return fields (measured_saving_usd, measured_waste_dbu, observation_days, projected_30d_usd/_dbu, low_confidence, errors) and their caveats. For a read-only, zero-required-parameter analysis tool, an agent has everything needed to call and interpret 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 must compensate, and it does for all four parameters: `days` (1..365), `max_rows` (1..1000 per check), `warehouse_idle_pct` (idle_pct ≥ threshold, default 80), and `max_autotermination_minutes` (clusters off or above threshold, default 60). Ranges and comparison semantics are exactly what the bare integer 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?

States a specific verb and resource ('Find wasted DBUs') with an explicit time scope, then enumerates the three check families (Classic, Serverless, Delta) it covers. That enumeration separates it cleanly from cost_summary and top_cost_drivers, which report spend rather than waste findings.

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 by the scope ('wasted DBUs', 'proposals only' for Delta), but the description never says when to pick this over cost_summary, top_cost_drivers, or cost_review_report, nor when to follow up with propose_fix. The agent must infer routing from sibling names 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?

With no annotations, the description carries the full burden and delivers the key traits: output is a diff/SQL proposal, 'never applied' (non-mutating), and deleted clusters are refused. It omits permission/rate-limit details, but for a proposal-only tool the core safety profile is 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 opening sentence front-loads purpose and the non-applied nature; the dense subsequent text earns its place by mapping issue values to behaviors and parameter quirks. It's information-dense rather than padded, though the nested parenthetical structure is heavy.

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 output is a proposal (diff/SQL) and an output schema exists, so return values needn't be explained. The description covers the tricky parameters and safety behavior, leaving only a few auxiliary params (path, num_workers, spark_version) 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?

At 0% schema coverage, the description compensates well: it explains the issue enum, tells that delta_zorder overloads node_type_id as column list, that delta_vacuum uses minutes (default 168/min 7 days), resource_key as catalog.schema.table, and that bundle_yaml may be empty. It leaves path, num_workers, and spark_version undocumented, so not fully complete.

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 ('Propose a fix as a unified diff ... or reviewable SQL') plus a critical behavioral qualifier ('never applied'). This clearly distinguishes it from siblings like find_waste, cost_summary, and top_cost_drivers, which are analysis/reporting tools rather than fix generation.

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 issue types with their intent, tells the agent to pass cluster_id 'from find_waste' for cluster fixes, and notes a deleted cluster is refused. It establishes the routing from find_waste and the delta-issue path, but doesn't explicitly say when NOT to use it or name every alternative.

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

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

No annotations are provided, so the description must carry the burden, and it does: it declares read-only behavior, states the exact result shape (rows, usd_complete, unpriced_skus), and flags the list-price-vs-applied-discount caveat. The unpriced_skus/usd_complete flags are valuable partial-data disclosure; only auth/permission requirements are unaddressed.

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 the resource and window, then safety/return contract, then the routing hint. No filler and each sentence 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?

For a one-parameter, no-output-schema analytics tool, everything an agent needs to call it correctly is present: scope, time window, read-only status, price basis, and the shape of the returned object including partial-pricing flags.

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 must compensate, and it adds the key constraint the schema lacks: the valid range 1..365 for `days`. It omits how out-of-range values behave, but the default (30) is already in the schema, so the critical semantics are covered.

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

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

States a concrete resource (top 20 jobs, warehouses and clusters ranked by list-price cost) plus the time window, which is a specific ranking query rather than a generic summary. It distinguishes itself from find_waste but does not clarify how it differs from cost_summary or cost_review_report, which appear to cover adjacent ground.

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 use case ("answer 'what spent the most?'") and sequences it before find_waste ("before drilling into waste"). It provides clear context but no exclusion of when cost_summary or cost_review_report would be the better pick.

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