Plutus

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

Annotations already establish a read-only, idempotent, non-destructive profile, and the description goes well beyond them: it discloses the confidence cap (0.60), the absence of a 'high' tier, the meaning of tier:'unknown', the mutual exclusivity of p_cause/p_unknown, and the no-causation reporting discipline. The only gap is it doesn't describe pagination or response envelope shape, though it does cover the semantic 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?

Purpose is front-loaded in the first sentence. The body is dense and every paragraph carries a distinct semantic payload (render discipline, the three numbers, tier semantics, request shape). It runs long, but with no output schema the verbosity is largely load-bearing 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?

With no output schema, the description must carry the full return-value burden — and it does, defining change_evidence, attribution_completeness, p_cause/p_unknown, tier, explained_day, and explanation.sentences, plus the API endpoint it mirrors. Nothing an agent needs to call or interpret this 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?

Schema coverage is 100%, so a 3 is the floor, but the description adds real meaning: 'dimension + value name the slice, optional cost_source_id narrows it, and exactly one of day or range says when' — the mutual-exclusivity constraint is not stated in the schema. It also explains the range→explained_day narrowing behavior, which the schema only hints at.

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 specific cost change') and immediately enumerates the three things it returns: which timeline events line up, how strongly, and how much Plutus could account for. It also distinguishes itself from the sibling list_anomalies by scope ('any point on a cost chart — not limited to anomalies the detector flagged').

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 when to use it ('ask this about any point on a cost chart') and names the alternative for the flagged-anomaly case ('use list_anomalies for those; each already carries the same explanation'). It even governs downstream behavior with 'RENDER explanation.sentences AS WRITTEN', which is strong usage guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description goes well beyond them: it discloses the USD unit convention, the top-level currency field, the native_cost/native_currency reconciliation exception, an explicit prohibition on summing or comparing native_cost across rows, and the absence of a cost_metric parameter (cost is always billed, never amortized). This is unusually rich behavioral context.

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

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

Front-loaded with purpose, then alternative routing, then unit conventions — a sensible order with no filler sentences. It is on the long side for a two-parameter read tool, and the currency rules could be tightened, but every clause carries information.

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

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

With no output schema, the description helpfully describes the return shape (per-row cost, top-level currency, native_cost/native_currency). The main gap is the date parameter format; otherwise an agent has enough to call and interpret the tool correctly.

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

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

Schema description coverage is 0% for both startDate and endDate, so the description must compensate. It conveys that the pair forms a 'date range' but never states the expected format, inclusivity, or defaults, so the agent still has to guess the string syntax. Partial compensation only.

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 ('Fetch raw per-service cost entries ... unaggregated') and immediately distinguishes itself from the sibling query_costs by scope (individual rows vs. bucketed/aggregated spend). An agent can route between the two 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?

Explicit when-to-use and when-not-to-use: 'Prefer query_costs for time-bucketed/aggregated spend — this is for inspecting individual rows.' It names the alternative and the condition that selects it, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral context beyond annotations: that widgets reference a preset catalog_id while custom metrics/charts carry inline config, and the replacement semantics of the downstream set_dashboard_widgets. It does not cover output shape, but no output schema exists so this is a modest gap.

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

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

Three sentences, front-loaded with what is fetched, then content structure, then the when-to-use rule. Every sentence earns its place with no filler.

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

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

For a single-param read tool with full annotation coverage and no output schema, the description supplies the key context: what the layout contains, how references are shaped, and the ordering constraint relative to set_dashboard_widgets. It is complete enough for correct invocation; the only minor gap is return-shape detail, which is acceptable without an 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% and the dashboard_id parameter is already documented as 'a shared dashboard id from list_dashboards'. The description reinforces the scoping ('one org-shared dashboard') which clarifies that list_dashboards is the source of valid ids, but adds no syntax the schema lacks. A 4 reflects the marginal reinforcement without introducing new parameter detail.

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 ('Fetch one org-shared dashboard's full layout') and enumerates what the layout contains — placed widgets, custom metrics, custom charts, grid positions. This clearly distinguishes it from list_dashboards (enumeration) and from list_dashboard_widget_catalog (the preset catalog).

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

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

Gives explicit when-to-use guidance: call before set_dashboard_widgets if you want to preserve existing widgets, because that tool always replaces the whole set. It also points to list_dashboard_widget_catalog for resolving catalog_id references, routing the agent to the right sibling.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds real value beyond them: it discloses the return shape (id/type/name/enabled) and an important security constraint that credentials/URL are never returned.

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

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

A single tight sentence-pair that front-loads what is listed and follows with the rationale and the return/security caveat. No filler, every clause earns its place.

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

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

With no output schema and no parameters, the description carries the entire burden and does so: it names the resource, the useful fields returned, the deliberately omitted sensitive fields, and the reason to call it. Nothing needed to 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool is 4. The schema is empty and fully consistent with the description's account-scoped behavior.

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

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

States a specific verb (List) and resource (this account's alert notification channels), enumerates the channel types, and ties the result to a concrete downstream action (create_alert_subscription). An agent can distinguish it from siblings like list_alert_subscriptions/list_alert_deliveries 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?

Gives clear context for when to reach for it — you need a channel id before calling create_alert_subscription. It does not, however, explicitly contrast itself with list_alert_subscriptions or list_alert_deliveries, so the routing between the alert-related siblings is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so safety is covered. The description adds genuine behavioral context beyond them: the underlying REST endpoint, the fact that error text is deliberately excluded, and that results are a delivery log rather than configuration. It does not state the retention window behind 'recent', which is the main remaining gap.

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

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

Two sentences, no filler. The core purpose and the heatmap anchor are front-loaded, and the exclusion and endpoint mapping follow as supporting detail.

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 read-only single-parameter list tool with no output schema, the description covers purpose, data provenance, and an explicit content exclusion. It is slightly incomplete in not hinting at the returned fields or the retention window, but nothing needed to 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 100% and the single 'limit' parameter is fully documented (default 100, max 500, most-recent-first ordering), so the schema carries the burden. The description adds nothing parameter-specific, which is the expected baseline 3 when the schema is 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?

Specific verb+resource ('list alert delivery history') with an unusual amount of semantic disambiguation: it explains the data is about whether an alert fired and whether the send succeeded, and pins it to the Alerts page heatmap. This clearly separates it from siblings like list_alert_channels and list_alert_subscriptions, which cover configuration rather than delivery outcomes.

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 frames when the data is relevant (the Alerts page heatmap) and notes a scope boundary ('does not include the delivery error text'), but it never states when to prefer this tool over the alert-config siblings or what to do if error detail is needed. Usage is implied rather than routed.

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 read-only, idempotent, closed-world, and non-destructive behavior, so the safety profile is covered. The description adds useful behavioral context by defining what a subscription maps (alert channel to trigger) and enumerating the supported trigger types, though it does not discuss auth, pagination, or 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?

Two sentences, front-loaded with the core action and scope, followed by a concise API mirror note. Every sentence contributes useful information without redundancy.

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

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

For a parameterless list tool with rich annotations and no output schema, the description supplies sufficient context: it defines the resource, the trigger taxonomy, and the API endpoint it mirrors. An agent can call and interpret it without further description-level detail.

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

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

The tool has zero parameters, and the schema is empty with 100% coverage. Per the baseline for parameterless tools, the description does not need to compensate for missing parameter semantics, so a 4 is appropriate.

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

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

The description states a specific verb and resource: listing alert-channel subscriptions to triggers. It further distinguishes the mapping from sibling tools by naming the trigger categories (budget spend_threshold vs account-wide event_overage/cost_anomaly/commitment_expiring/sync_failure).

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

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

The description implies when to use the tool by explaining the subscription mapping and trigger scope, but it does not explicitly say when to choose this tool over siblings like list_alert_channels or list_alert_deliveries. No exclusions or alternatives are named.

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 far beyond the readOnly/idempotent annotations. It discloses the 200-row cap, most-recent-first ordering, the default/max of the lookback window, the semantics of suppressed rows, and — critically — the null-vs-[] distinction for driven_by and correlated_events, plus what null vs [] means for notified-withheld rows. It also explicitly disclaims causation for correlated_events, which prevents a likely agent error.

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 and front-loaded, but it is a wall of text with many field-level notes packed into a single block. The information is valuable, yet the structure is a run-on rather than crisply partitioned; a bulleted breakdown of the response fields would be easier to parse. It earns most of its length but could be tightened.

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 list tool with no output schema, the description lays out the shape of the result (severity, baseline vs. current, drivers, correlated events) and all the subtle field semantics an agent needs in order to report results correctly. Account-scoping, ordering, and the cap are all present. Nothing material 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% and the single 'days' parameter is documented in the schema, so the baseline is 3. The description does add the default (30) and max (90) in prose, but that duplicates schema information rather than extending it.

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

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

The description states a specific verb+resource ('List detected cost anomalies') and immediately distinguishes itself from a sibling ('Prefer this over eyeballing query_costs'). It also clarifies the data source ('the real output of Plutus's nightly anomaly detector ... not something recomputed here from raw spend'), leaving no ambiguity about what a caller gets.

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 guidance: use this over query_costs when asking 'did anything spike', with the reason (day-of-week baselines and an absolute-dollar noise floor). It also tells the agent what to do with edge-case rows ('mention it but do not lead with it as a live problem' for suppressed, and 'report it as a decomposition of the same service anomaly, never as a separate anomaly of its own' for resource-shaped drivers).

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 cover the safety profile (readOnly, idempotent, non-destructive). The description adds genuine value beyond them: it explains that anomalies marked 'expected' are hidden from the detector (the behavior that matters), notes expires_at semantics (null = indefinite), and discloses the MCP limitation on create/delete. Return format and pagination are not addressed.

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 tightly packed sentences with no filler: purpose, key data attribute (expires_at), API mirror, and a limitation note. Front-loaded with the verb and resource.

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?

Comprehensive for a zero-param, read-only list tool: explains the domain model, a notable field, and discloses what is not supported. Without an output schema, a brief note on the shape of returned items would help, but the essence is captured.

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?

Zero parameters, so the baseline is 4. The description correctly indicates a simple account-scoped list with no filtering inputs, matching the empty schema.

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

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

States a specific verb (list) and resource (anomaly suppressions) and defines the domain concept precisely: signatures of provider+service or tag_key+tag_value that a human marked expected. This clearly distinguishes it from siblings like list_anomalies, which surfaces anomalies rather than the suppressions that hide them.

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?

Clarifies scope (this account's active suppressions) and the key constraint that creating/deleting a suppression is not available over MCP, which directly tells the agent not to look for mutation tools. Lacks explicit routing to a related sibling for anomaly review, but the domain is narrow enough that 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?

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered; the description goes well beyond that by disclosing data provenance (figures are only meaningful when you check both `currency` and `status_currency`), the rollup-time semantics of `spend_cents`/`projected_cents`, and an explicit warning never to quote the values as dollars blindly. That is exactly the behavioral context an agent cannot get 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?

Three sentences, front-loaded with what the tool returns before the caveats. The long currency sentence is dense but every clause carries a distinct, non-redundant constraint (denomination, base-currency divergence, rollup provenance), and no sentence 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?

There is no output schema, so the description carries the full burden of describing the return payload, and it does so by naming the status fields, the two currency fields, and the rollup caveat that governs their interpretation. For a zero-parameter, read-only list tool this leaves nothing material 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?

The schema has zero parameters, which sets a baseline of 4. The description's discussion of `currency`, `amount_cents`, `spend_cents`, and `projected_cents` concerns response fields rather than inputs, so it adds nothing to parameter semantics but loses nothing either.

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 this account's spend budgets) and enumerates the scope of the payload (current-cycle status: spend so far, projected total, ok/warning/exceeded, forecast). It also anchors the tool to a concrete upstream endpoint (GET /api/accounts/:accountId/budgets), so the agent knows exactly what domain object is being returned.

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 contrasts this tool with the sibling cost tools by warning that budget figures are NOT converted to the USD base those tools return, which gives the agent a selection signal. However, it never states a positive 'use this when...' condition or names a competing sibling tool for a specific budget question, so the routing guidance is implicit rather than explicit.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds rare, decision-critical behavior: days are computed server-side against current UTC, expired rows are not pruned so the sign must be checked, and utilization is a TYPE-level monthly aggregate rather than per-commitment. That disclosure prevents an agent from misreporting a commitment as unused.

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 and ordering before the caveats, and every sentence carries non-redundant information about either data provenance or correct interpretation. It is dense but not padded, though the final threshold sentence is slightly long-winded.

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 input schema, no output schema, and a zero-parameter signature, the description must carry the entire interpretation burden — and it does, covering ordering, sign semantics, staleness of expired rows, and the true granularity of the utilization figure.

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?

Zero parameters, so the baseline is 4. The description spends its space on return-field semantics (days_until_expiration, latest_utilization_percentage) instead, which is the correct use of the budget here.

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 this account's Reserved Instance / Savings Plan / Azure Reservation commitments'), scopes it to one account, names the key field returned, and specifies ordering ('soonest-first'). An agent can distinguish this from get_cost_entries or list_commitment_utilization 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?

Gives clear context for acting on results: the 30/14/7/1-day thresholds and 80% cutoff are the right flags 'for consistency with what a subscribed channel already receives', and it points at list_commitment_utilization as the source of utilization data. It stops short of an explicit when-not or a stated alternative tool for the same question.

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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the data is sourced from specific Cost Explorer APIs, and the granularity is one snapshot per commitment type per month, plus net-savings content.

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

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

Two sentences, front-loaded with the verb and resource; the API-mirroring note is tacked on but short. No filler, though the first sentence is dense with parentheticals.

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

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

With no output schema, the description carries the burden of telling the agent what comes back, and it does: per-commitment-type monthly utilization/coverage plus net savings vs on-demand. Only pagination or response envelope details are 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?

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate at the parameter level.

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

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

States a specific verb (List) and resource (Reservation/Savings Plan utilization and coverage snapshots) and pins the source to AWS Cost Explorer's GetReservationUtilization/GetSavingsPlansUtilization. It is clearly distinguishable from cost-query siblings on inspection, though it never names its closest neighbor list_commitment_expirations to sharpen the boundary.

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 the data is and where it comes from, but gives no when-to-use vs when-not guidance and does not route the agent to an alternative sibling (e.g., query_costs or list_commitment_expirations) for related commitment questions.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description goes well beyond them by disclosing the provenance semantics of the cost_basis column, including why two providers differ (no historical billing API, negotiated vs list rates) and the accuracy caveat for static-rate figures. That is precisely the behavioral context an agent needs to avoid misreporting numbers.

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

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

Three sentences, entirely front-loaded: purpose first, then the cost_basis enum semantics, then the reporting directive. The enumeration is dense but every clause conveys a distinct distinction the agent must preserve when summarizing results.

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

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

There is no output schema, yet the description compensates by explaining the returned fields' meaning and their reliability implications. For a zero-parameter read tool with full annotation coverage, nothing material 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, for which a 4 is the baseline. The description instead spends its budget documenting the shape and meaning of returned rows, which is the more relevant semantic content here.

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 the cost-source providers ... enabled for this account') and immediately enumerates examples (AWS, GCP, Anthropic), so the agent knows exactly what a call returns. It is cleanly distinguished from siblings like list_cost_source_tag_keys or list_cost_tags, which operate on different 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?

It gives clear interpretive guidance — 'Qualify any total that includes an estimated source rather than reporting it as billed spend' — which tells the agent how to use the output downstream. It stops short of naming when-not-to-use conditions or sibling alternatives, but the calling context is unambiguous.

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 readOnly, idempotent, non-destructive, and closed-world hints. The description adds critical behavioral context: 'Only ever populated on grain='service' rows' and that omitting cost_source_id searches across every enabled provider. However, it doesn't explain what happens if the account lacks permissions or how results are ordered/paginated, leaving some gaps. With annotations covering the safety profile, a 3 is appropriate.

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

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

A single, dense sentence packed with necessary information: what the tool lists, its purpose relative to cost-tag-rule creation, a grain constraint, and the effect of omitting the only parameter. 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?

Given the tool's simplicity (one optional parameter, read-only annotations, no output schema), the description covers what an agent needs: the returned keys and when they are populated. It could go slightly further by clarifying that it returns only keys, not values (distinguishing from list_cost_source_tag_values), but it is sufficiently complete.

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

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

The schema already documents the sole parameter (cost_source_id) at 100% coverage, but the description adds meaning beyond it: omitting cost_source_id triggers a cross-provider search. This extra nuance about the parameter's behavior when absent is valuable and not present in the schema description.

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

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

The description states a specific verb (List), resource (distinct provider-native tag/label keys), and scope (actually present in this account's cost data). It distinguishes itself from siblings by explaining that it reveals what a 'tags.<key>' cost-tag-rule match could reference before creating one.

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 clearly explains the purpose (discovering available tag keys for cost-tag-rule matching) and gives a condition (before creating a rule), but does not explicitly compare to siblings like list_cost_source_tag_values, list_cost_tags, or list_tag_recommendations. The usage context is clear though not exclusionary.

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, idempotentHint, non-destructive and closed-world, so the safety profile needs no restating. The description adds the account-scoping constraint and 'distinct values' semantics, but says nothing about pagination, result limits, or what happens when a key has no values.

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

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

A single front-loaded sentence that names the output ('distinct values') before the qualifier. Nothing is redundant or padding.

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

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

For a two-parameter, read-only list tool with full schema coverage and no output schema, the description is nearly complete: purpose, scope, and the key-source prerequisite are all covered. Only pagination/empty-result behavior is left unaddressed, which is minor.

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 both parameters (tag_name, cost_source_id) are already documented with examples in the schema. The description therefore does not need to compensate, and adds no syntax or format detail beyond what the schema already supplies.

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), resource (distinct values for a tag/label key), and scope (this account's cost data). It explicitly distinguishes itself from list_cost_source_tag_keys by naming that sibling as the source of keys, so an agent can tell keys from values 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?

The parenthetical '(see list_cost_source_tag_keys)' encodes the prerequisite workflow: get a key first, then list its values. That is clear usage context, but there is no explicit when-not guidance or mention of the other tag-related siblings such as list_cost_tags.

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 cover the read-only/idempotent safety profile, but the description goes well beyond them: it explains ascending priority evaluation, first-match-wins semantics, the 'Untagged' fallback, and critically the non-obvious split-rule behavior where spend is divided by weight and tag_value is only a display label. It even warns against a common misinterpretation.

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 purpose, then layers necessary caveats. It is somewhat long, but the IMPORTANT section on split rules and the reallocation pointer earn their space by preventing a costly misinterpretation. Minor redundancy around tag_value labeling slightly inflates length.

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

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

With no output schema, the description carries the full burden of explaining return semantics and does so thoroughly: rule structure, priority order, split arrays with weights summing to 1, and post-rule reallocation via redistribute_bucket. Nothing an agent needs to interpret results 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% and the single tag_key parameter is already documented in the schema as 'One of the tag_keys returned by list_cost_tags'. The description repeats this same guidance, adding no new syntax or format detail beyond what the schema provides, 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 and resource ('List the actual match rules') scoped to one cost-allocation tag_key, and clarifies it retrieves rule definitions rather than the tags themselves. The mention of priority order and dimension-value mapping makes the purpose unmistakable and distinguishable from list_cost_tags.

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 the agent to list_cost_tags to obtain the required tag_key, establishing a clear prerequisite. It doesn't spell out when NOT to use it versus other siblings, but the context ('see list_cost_tags') is clear enough for selection.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive). The description goes further by explaining the non-obvious behavior of redistribute_bucket—how it dissolves a bucket's spend into other tag values and when it reappears—which is valuable context not captured elsewhere.

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 core purpose and structured logically, but the third sentence detailing redistribute_bucket is lengthy and could potentially be trimmed. Overall, every sentence contributes to understanding the tool's output.

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 zero parameters, the description fully equips an agent to call this tool correctly: it explains what is returned (tag_keys, grains, rule counts, redistribute_bucket), and the annotations cover safety. No critical gaps remain.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify. The baseline score of 4 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 description states a specific verb and resource: 'List the virtual cost-allocation tag_keys defined for this account', and elaborates on the payload (grain, rule counts). It doesn't explicitly name a sibling tool it might be confused with (e.g., list_cost_tag_rules), so it misses the top-tier differentiation criterion.

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 sentence 'Use a tag_key with query_costs (breakdown_by: "tag") to see spend broken down by it' implies the tool's purpose is to discover tag keys for later querying, but it does not state when to choose this tool over alternatives like list_cost_tag_rules or list_cost_source_tag_keys.

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 readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely non-redundant context: the org-versus-personal visibility boundary and the fact that personal dashboards have no id an account-level MCP key can address, which explains why they are absent rather than silently filtered.

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

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

Three sentences, each earning its place: scope, exclusion-with-reason, and downstream routing. The most decision-relevant fact (org-shared) is front-loaded in the first clause.

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, no parameters and rich annotations, the description carries the remaining burden well — it hints at the returned 'id' field and explains the omission of personal dashboards. It stops short of noting result ordering or pagination, a minor gap for an unfiltered list endpoint.

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

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

The tool takes zero parameters, so the schema imposes no semantic burden and the baseline is 4. The description correctly spends no space on parameter prose.

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

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

States a specific verb (List) and resource (org-shared dashboards) with an explicit scope qualifier — 'visible to every account member'. It immediately distinguishes itself from the personal-dashboard surface, so an agent can tell it apart from get_dashboard and the widget catalog sibling 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?

Gives a clear exclusion ('Does not include any member's PERSONAL dashboard') and routes the agent forward by naming get_dashboard, set_dashboard_widgets and delete_dashboard as consumers of the returned id. It does not, however, say when to prefer this over sibling listers like list_dashboard_widget_catalog, so it falls short of the explicit when/when-not bar.

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/idempotentHint/non-destructive/non-open-world, so the safety profile is covered. The description adds genuine behavioral detail beyond that: the response carries grid_cols and size_bounds, and the crucial nuance that size_bounds are keyed by widget TYPE (kpi/chart/widget) rather than by individual catalog_id. It stops short of describing pagination or catalog size, keeping it at a 4.

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 and the key routing fact (no preset chart), and every sentence carries information. The second paragraph is dense with inline JSON fragments and backticked field names, which slows reading slightly, but 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?

There is no output schema, so the description has to carry the return contract itself — and it does: grid_cols, size_bounds, and the catalog_id/id semantics of entries. Combined with the explicit chart alternative, an agent has everything needed to call this and consume the result correctly.

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

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

The tool takes zero parameters, so the baseline is 4. The description does add meaning to the surrounding call contract (catalog_id values feed a {"kind": "preset", "catalog_id": ...} spec), but there are no input parameters for it to clarify.

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 precise verb+resource (list built-in 'preset' dashboard widgets) and immediately scopes it to the two tools that consume the result (create_dashboard/set_dashboard_widgets). It also names what the catalog does NOT contain (no preset chart), which lets an agent distinguish it from any chart-related sibling at a glance.

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 when to call it and what to do instead when the requested artifact is absent: for a trend chart, build an inline {"kind": "custom_chart", ...} spec rather than looking for a catalog_id, with a pointer to create_dashboard's description. It also gives the precondition for using grid_cols/size_bounds before passing an explicit w/h.

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 cover safety (readOnly, idempotent), but the description adds substantial domain semantics beyond them: it defines how is_overdue is computed, clarifies that partial_failure counts as failed for recent_failure_count, and warns that status does NOT reflect partial failures or the gap between failure and recovery. This is high-value behavioral context that 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 core purpose in the first clause, then layers definitions and usage guidance. It's dense but every sentence earns its place by clarifying non-obvious semantics (is_overdue, recent_failure_count, status). Slightly long, but justified by the complexity of the health signals.

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

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

With no output schema, the description fully explains the key return fields (last synced, next scheduled, outcome, is_overdue, recent_failure_count, status) and their edge cases. It also provides the critical caveat about relying on is_overdue and recent_failure_count over status. Complete for a zero-parameter list 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?

Zero parameters, so baseline is 4 per the rubric. The description doesn't need to document parameters, and it appropriately focuses on output fields instead.

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 the exact resource ('sync health for every cost/event/usage connection') and lists the specific fields returned (last synced time, next scheduled sync, outcome, is_overdue), which is far more specific than the name alone. An agent can distinguish this from siblings like list_cost_sources or list_anomalies 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 usage: 'Check this before asserting that recent cost or usage data is complete, especially right before calling query_costs or query_usage for a very recent date range.' Names the condition and the downstream tools, which is exactly the when-to-use guidance needed.

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, openWorldHint=false, idempotentHint, and destructiveHint=false, carrying the safety profile. The description adds the scoping fact that values are per-provider, which is useful, but doesn't mention date-range effects or whether results are paginated/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?

One efficient sentence, front-loading the action and the key dimensions, then adding the routing hint. No filler.

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

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

For a read-only discovery tool with annotations covering safety and no output schema, the description is adequate but incomplete: it doesn't clarify the date-range parameters' role, the provider-id requirement (beyond schema), or returns. The partial dimension list is a notable gap for an enum-driven 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 25%, low enough that the description should compensate. It names the dimension parameter and gives example values, but the parameter list is incomplete versus the enum (missing identity, namespace, workload, cluster, resource_id). start_date/end_date and cost_source_id receive no semantic help from the description beyond what the schema says.

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

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

Clear verb+resource: 'List the distinct values seen for a given dimension ... for one provider.' However, it only lists 5 of the 10 enum dimensions, potentially misleading about scope. It does distinguish from query_costs by noting it's for discovery beforehand.

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 states 'useful for discovering filter values before calling query_costs', which gives a clear when-to-use and names the alternative. No when-not-to-use or exclusions, but strong context.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, and openWorldHint, covering the safety profile. The description adds useful domain semantics (values are repos with at least one event, mirrors GET /api/events/facets) but says nothing about result size, pagination, or how the date-range filter affects the returned set.

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 purpose, followed by scope and the routing hint. Three compact clauses with no filler, though the REST-endpoint note is slightly redundant for an agent that cannot call the endpoint directly.

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 read-only enumeration tool with no output schema and rich annotations, the description conveys purpose, scope, and intended workflow well. The main gap is undocumented parameter semantics (source_id) and any notion of result cardinality.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains attr (the facet, currently only 'repo') and implies the date-range params, but source_id is never explained in either the schema or the description, and no date format is given.

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 the distinct values of a faceted event metadata field. It immediately scopes the operation ('currently just "repo"') and ties it to a known surface (the Event Explorer repo picker), letting an agent distinguish it from query_events 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?

Explicitly names the alternative and the condition that selects it: use this to discover query_events' meta_repo filter values before calling query_events. The relationship between the two sibling tools and the ordering of calls is left to no inference.

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

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

Annotations already cover the read-only/idempotent/non-destructive profile, and the description adds substantial context beyond them: data provenance (AWS Cost Explorer, Azure Advisor, GCP Recommender), that commitment rows omit instance-type fields, that only one term/payment/lookback variant is surfaced (AWS 30-day, 1-year, no upfront default), and the currency split between per-recommendation figures and the USD total.

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 purpose in the first clause, and nearly every sentence carries non-obvious information. The middle section on commitment variants and provider defaults is dense and longer than needed, but the content is load-bearing 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?

With no output schema, the description must carry the return-shape burden and does: it explains the `type` values, the commitment-row field differences, where term/payment/lookback live, and how currency is reported. An agent can interpret and report results correctly without further documentation.

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?

Zero input parameters, so the baseline is 4 regardless of schema coverage. The description goes further by documenting the returned `type` enumeration and the presence of `detail`, `currency` and absent instance-type fields, which meaningfully describes the payload an agent will receive.

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 active cost-reduction recommendations') and immediately bounds the scope: 'for this account', sourced from provider engines rather than computed by Plutus. It is clearly distinguishable from siblings like list_tag_recommendations and list_commitment_expirations.

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 context for interpretation — the four `type` values, what commitment rows represent, and an explicit caution not to report the single surfaced commitment variant as the only option. It does not, however, name when to prefer this tool over overlapping siblings such as list_commitment_expirations or list_commitment_utilization.

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, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuinely useful behavior context beyond that: it explains the `next_period_label` field semantics, the three possible scopes, and that it mirrors a specific REST endpoint — details an agent could not derive from the annotations.

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

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

Two sentences, front-loaded with the verb and resource, followed by the endpoint mapping. Dense but every clause carries information; the backtick-quoted field name is a minor readability cost but acceptable.

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

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

With no output schema, the description carries the burden of describing returns and does so adequately by naming the fields each digest exposes. It omits pagination/ordering and exact response format, which are minor gaps for an account-scoped list.

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

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

The tool takes zero parameters, so the schema baseline of 4 applies. The description adds no parameter meaning (there is none to add) but does describe the shape of the result records, which is the relevant substitute here.

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?

Specific verb+resource ('List this account's scheduled cost digests') with an explicit enumeration of what each entry contains (cadence, scope, destination, next due date). No sibling tool covers scheduled reports, so no collision risk, and the description preempts confusion by noting that create/edit are unavailable over MCP.

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 scope ('this account's') and the note that creating/editing scheduled reports is not available over MCP give clear boundaries for when this tool applies and when the agent must stop. There is no alternative sibling to route to, so no when-vs-alternative clause is needed.

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, idempotentHint, and destructiveHint=false, so safety is covered. The description adds real context beyond that: the USD-base `estimated_monthly_spend_cents` each item carries, the REST endpoint it mirrors, and the crucial constraint that no MCP-side accept/dismiss exists — which prevents a wasted write attempt. Return volume and pagination behavior are not addressed.

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 purpose is front-loaded and every sentence earns its place — the second explains item content, the third the endpoint mapping, the fourth the action limitation. The opening sentence is dense with parentheticals but still readable; no filler or restated boilerplate.

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

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

With no output schema and no parameters, the description carries the full burden and meets it: it says what a recommendation is, what fields each carries, that values are USD base, and that acting on results is out of scope for MCP. Nothing an agent needs 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?

The tool takes zero parameters, which is the baseline-4 case; there is no parameter surface for the description to compensate for. The description correctly avoids inventing filtering arguments.

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

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

Opens with a specific verb and resource — 'List suggested cost-allocation tag rules this account doesn't have yet' — and immediately defines the two recommendation categories (high-spend values falling through to Untagged for an existing tag_key, or a provider-native tag worth promoting). It also names list_cost_tags as the related sibling, so an agent can place it among the tag tools 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?

The description gives a clear condition for use (surfacing tag rules the account lacks) and explicitly excludes an action the agent might otherwise attempt: 'Accepting or dismissing a recommendation is a UI/REST-only action, not available over MCP.' It cross-references list_cost_tags but does not distinguish itself from list_savings_recommendations or list_cost_tag_rules directly, so it stops just 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds genuine context beyond that: the return payload includes members and the reserved cost-tag tag_value, which is not derivable from the annotations. It omits pagination or auth requirements, but for a bounded read-only listing this is solid.

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

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

A single front-loaded sentence opens with the core action and then layers scope and integration detail via an em-dash. Slightly dense with parentheticals, but every clause (members, tag_value, scope_ref linkage, API mirror) earns its place.

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

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

With no output schema, the description partially compensates by naming the returned fields (members, reserved tag_value) and the endpoint mirrored. Combined with full annotation coverage, an agent has enough to invoke and interpret it correctly, though return shape remains only loosely sketched.

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 coverage is 100%, so there is nothing to document; baseline 4 applies. The description adds no parameter surface, which is correct here.

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 this account's teams') and further specifies scope by naming what is returned: members and the cost-tag tag_value each team is reserved under. An agent can distinguish it from sibling list_* tools 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?

Explicitly connects to the downstream use case: team-scoped budgets created via create_budget with scope_type 'team' reference a team's id as scope_ref. This tells the agent why it would call this tool, though it stops short of stating when not to use it or naming an alternative listing.

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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description adds real value beyond that by explaining the semantics of the returned item fields (numerator_scope's three possible slices, denominator_metric, denominator_scale values), which compensates for the absent output schema.

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 dense sentences with the core purpose front-loaded; the ratio definition, field semantics, and the follow-up tool are packed without filler. Every clause earns its place given there is no output schema to lean on.

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

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

For a zero-argument list tool with no output schema, the description covers purpose, item field semantics, and the natural next step (query_unit_costs). It only omits secondary details such as volume, ordering, or pagination behavior, which are minor here.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The field descriptions in the text refer to response items rather than inputs, so there is no parameter ambiguity to resolve.

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 this account's saved unit-economics metrics") and immediately defines the resource with concrete examples ("cost per 1k API requests", "infra cost per order"). It distinguishes itself from query_unit_costs, which computes a single metric, by positioning this tool as the catalog of saved definitions.

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 context: use this to enumerate saved metrics, then "Pass an id to query_unit_costs to compute one over a date range," and points to list_cost_tags for tag_value scope values. It does not state explicit exclusions or why to choose this over, say, list_cost_sources, 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 already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered; the description adds real value by disclosing the return shape (value/label pairs) and the label fallback logic from account_customers to raw id. It also notes the REST endpoint it mirrors. No rate limits or auth notes, so not a full 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?

Two sentences, front-loaded with the core action and scope, followed by return-shape detail. Every clause adds information (purpose, follow-up tool, output semantics, endpoint) with no filler.

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

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

With no output schema, the description usefully explains the returned value/label entries, which is exactly what an agent needs without a schema. The main remaining gap is date-range parameter format/semantics, which is left undocumented.

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 only partly does. It clarifies the allowed dimension values ('metric' or 'external_customer_id'), but those are already constrained by the schema enum, and it says nothing about start_date/end_date format or whether they are optional.

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 the distinct values seen for a usage dimension') and scopes it over a date range, directly distinguishing it from the query tools. An agent can tell this discovery/list tool apart from siblings like query_usage 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?

Explicitly frames the use case: 'useful for discovering filter values before calling query_usage', which routes the agent to the right follow-up tool. It lacks explicit when-not-to-use guidance or naming of the alternative list_dimensions sibling, keeping it 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 only cover the read-only/idempotent safety profile, so the description carries real weight here and delivers: estimated vs invoiced `cost_basis` (and the instruction to qualify estimates), USD conversion at the charge-day rate, `cost_per_unit` scale caveats, `coverage.complete_through` lag behavior, and `lagging_sources` under-counting. This is exactly the kind of context the agent needs to interpret results correctly and cannot get 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?

Front-loads the core purpose and then devotes one paragraph each to cost-basis semantics, quantity/unit fields, and coverage caveats — a structure that maps to distinct behaviors rather than rambling. It is long and occasionally verbose (e.g., the collapsing-unit explanation), but the length is largely justified by the absence of an output schema.

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

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

With no output schema, the description must explain returns, and it does: row shape, `cost`, `cost_basis`, `quantity`/`unit`/`cost_per_unit`/`cost_per_unit_label`, `currency`, and `coverage.complete_through` / `lagging_sources`. For an 18-parameter analytics tool, the interpretation guidance is complete enough to call and read the result correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks — notably what the `identity` breakdown actually represents (per-actor spend such as an api_key_id, not populated by every provider) and that tagging requires a tag_key from list_cost_tags. It stops short of explaining most filters or the secondary-breakdown pairing rules beyond what the schema already states.

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

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

Opens with a specific verb+resource+scope: 'Query time-bucketed spend for this account,' then enumerates the breakdown dimensions and filters. It also cites the underlying endpoint (GET /api/analytics) and explicitly contrasts its behavior with query_unit_costs, so an agent can separate it from that sibling 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?

Usage is implied rather than prescribed: it points to list_cost_tags for tag keys and distinguishes its row-truncation behavior from query_unit_costs, but never states when to choose this tool over query_usage, query_unit_costs, or get_cost_entries for a given question. The alternative references are contextual, not routing rules.

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 read-only/idempotent/non-destructive, and the description adds substantial non-obvious behavior: no pagination, oldest-first ordering, a hard 5000-row cap with silent truncation, and that results carry no cost figure. These are exactly the runtime traits an agent needs beyond the safety hints.

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 purpose and the critical scoping warning; the long parenthetical source list is informative rather than filler. Dense but every clause carries signal, so only marginally verbose.

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

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

With no output schema, the description compensates by disclosing the result cap, row ordering, and the absence of cost figures, and by noting the underlying REST endpoint. It does not describe the returned event fields, but the coverage is strong for a read-only timeline query.

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 semantics the schema lacks: it explains that start_date/end_date are effectively mandatory for correctness rather than optional filters. That elevates it above the schema-only baseline.

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 (query) and resource (business-event timeline) and enumerates the concrete event sources (GitHub, PagerDuty, Jira, Stripe, etc.) so it is unmistakably distinct from sibling cost/usage tools like query_costs and query_usage. It also clarifies the resource is 'the same events overlaid on the Cost/Event Explorer charts'.

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 clear directive — 'Always scope with start_date/end_date' — plus the reason (no pagination, 5000-row cap, silent truncation on long histories). It does not name an explicit alternative sibling (e.g. when to prefer query_costs), so it stops short of full 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 read-only/idempotent/non-destructive, and the description adds substantial behavioral context on top: null `unit_cost` is not zero, series truncation at `coverage.complete_through`, `lagging_sources` meaning, empty rows from removed cost sources, billed-not-amortized semantics, and tag redistribution effects. This is exactly the beyond-annotations disclosure the dimension rewards.

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 operation is front-loaded in the first sentence and each subsequent paragraph addresses a distinct failure mode (nulls, truncation, removed sources, per-customer splits). It is long, but the volume is largely justified by the absence of an output schema; a few caveats could be tightened.

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 a read-only annotation profile, the description carries the return-value burden itself and does so thoroughly — row fields, `coverage`, `numerator_status`, `customers` block, and `denominator_label`. An agent has everything needed to call and correctly 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 coverage is 100% and already documents `start_date`, `end_date`, `group_by`, and `unit_metric_id`, so the baseline is 3. The description adds interpretation context around the date range (coverage stopping early) but nothing about parameter syntax or defaults 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 and resource — computing a saved unit-economics metric (cost numerator ÷ business-unit denominator) over a date range — and explicitly ties it to `list_unit_metrics` for metric selection, which separates it from `query_costs` and `query_usage`.

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?

Clear context for use: the metric must come from `list_unit_metrics`, the date range is bucketed by `group_by`, and it explains when results are legitimately short (cost lag) versus broken (`numerator_status.available=false`). It never explicitly names when to prefer `query_costs`/`query_usage` instead, so it stops short of full alternative 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 readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds substantive context: the data source ('this account's own backend has pushed or synced in') and the warning that quantity is a unitless raw count, not currency. It does not describe pagination or result-size behavior, but adds clear value beyond the annotations.

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

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

Purpose and the raw-vs-ratio distinction are front-loaded, and each clause carries information. It is a dense run-on sentence, slightly harder to parse than a cleanly split version, but not padded.

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

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

With no output schema, the description does the work of explaining what comes back (time-bucketed usage with a unitless quantity) and disambiguates the key confusion (usage = counts, not money). It omits return shape details like bucket structure, which is a minor gap given the query tool's simplicity.

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

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

Schema coverage is 71%, so descriptions carry meaningful weight. The description explains breakdown_by ('optionally broken down by external_customer_id when the pushed rows carry one'), whose schema entry has an enum but no description, and clarifies the nature of returned quantities. It stops short of explaining filters or grouping semantics, but adds real meaning over 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 and resource ('Query time-bucketed usage telemetry') and immediately scopes it as raw pushed/synced telemetry rather than a computed ratio. It explicitly distinguishes itself from the unit-cost siblings (list_unit_metrics/query_unit_costs) it sits beside in the tool list.

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 clarifies the choice between inspecting raw data here versus a pre-defined ratio via list_unit_metrics/query_unit_costs, which is real alternative guidance. It does not explicitly address where it stops relative to query_costs or query_events, so the guidance is clear but not exhaustive.

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