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 readOnly/idempotent/non-destructive, and the description adds genuinely new behavioral facts: a hard 90-day retention window, the fact that skipped deliveries (cooldown, hourly cap, no data) are included rather than filtered out, the delivery_key linkage between an alert and its attached report, and that errors are truncated. These are exactly the traits that change how an agent interprets rows it retrieves.

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

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

It is front-loaded with the identifying phrase and every clause carries information (content types, 90-day window, returned fields, skipped rows, key linkage, endpoint mirror). It is dense and slightly run-on as one long sentence, but there is no filler to cut.

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 describing return values, and it does: the row types, the identifying fields, the grouping key, and the fact that error text is truncated. Combined with the stated 90-day scope and default/max limit, an agent has enough to call this correctly and interpret results.

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?

There is a single parameter with 100% schema description coverage ('Max rows, most recent first, default 500, max 1000'), so the schema already does the work. The description adds no ordering, pagination, or limit guidance beyond what the schema states, which is the baseline-3 case.

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

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

The description names a specific resource and enumerates precisely what it contains: alert sends, scheduled reports, reports attached to alerts, and test sends over a fixed 90-day window, along with the fields returned (channel, recipients, trigger_key, window, status, truncated error). That is far beyond a restatement of the name. It loses the top score only because it never contrasts itself with the close sibling list_alert_deliveries, leaving the agent to infer 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?

Usage is implied: this is the endpoint behind the Alerts page table, so an agent can infer it is for reviewing what was sent or skipped. But there is no explicit 'use this when…' statement, no exclusion of list_alert_deliveries or list_scheduled_reports, and the final sentence about mirroring GET /api/... is developer provenance rather than selection 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, and non-destructive, so the safety profile is covered. The description adds the backing REST endpoint and the trigger taxonomy, but says nothing about result volume, ordering, or pagination for a list endpoint.

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

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

A single front-loaded sentence with no filler, and the endpoint reference is compact. The long parenthetical enumeration of trigger types is dense but earns its place by defining scope.

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

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

For a zero-parameter, read-only list tool with full annotation coverage, the description conveys the resource, the trigger taxonomy, and the analogous REST call. The lack of any return-shape hint (no output schema exists) is the only meaningful omission.

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 of 4 applies; there is nothing for the description to clarify beyond the empty schema. The enumerated trigger kinds instead inform what the returned objects contain.

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 which alert channels are subscribed to which trigger') and enumerates the trigger types covered, which distinguishes it from list_alert_channels. It does not explicitly name the sibling it differs from, so it falls just short of a 5.

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

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

The mapping framing implies this is the tool for answering 'what is wired to what', but the description never says when to prefer it over list_alert_channels, list_alert_history, or list_alert_deliveries. No exclusions or prerequisites are given.

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 cover the read-only/idempotent/non-destructive profile, so the description clears the lower bar easily. It adds substantial context beyond them: the meaning of projected_cents (trend-based, weekday/weekend aware, not a run rate), the two distinct currency fields, and a concrete warning not to quote figures as dollars without checking currency 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-loaded with the core purpose and status fields in the first sentence, then details. The middle sentences on projected_cents and currency are dense but each earns its place; the API-endpoint line ('Mirrors GET /api/...') is the least load-bearing element but is minor overhead.

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 return-value burden and does so: it names the status fields, explains the projection methodology, and disambiguates the two currency fields. Nothing an agent needs to interpret the response correctly appears to be 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 per the rubric the baseline is 4. There is no parameter surface to add semantics to, and the description correctly spends its words on return-value semantics 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?

States a specific verb+resource ('List this account's spend budgets') and enumerates the status fields returned (spend, projected total, ok/warning/exceeded, forecast). It explicitly distinguishes itself from the cost tools, which lack the budget currency semantics, so an agent can tell it apart from siblings without opening a schema.

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

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

It contrasts budget currency with 'the USD base the cost tools return,' which gives implicit context on when this tool is the right one. However, there is no explicit when-to-use, prerequisites, or named alternative routing (e.g., vs. query_costs or list_anomalies), so usage is implied rather than stated.

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

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

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 declare readOnlyHint, idempotentHint, destructiveHint: false, and openWorldHint: false. The description adds substantial behavior beyond that, explaining the redistribution semantics, when an "Untagged" bucket disappears from query_costs results, and how redistribute_basis selects the proportional split. That is exactly the kind of non-obvious behavioral detail annotations cannot convey.

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

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

The purpose is front-loaded in the first sentence, and every sentence carries useful information. The later sentences are dense, especially the explanation of redistribute_bucket and redistribute_basis, but that complexity reflects non-obvious return semantics rather than filler. It could be formatted more cleanly, but it is 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?

There is no output schema, so the description must explain the returned structure, and it does: tag_keys, the cost_entries grain, rule counts, redistribute_bucket behavior, redistribute_basis, and redistribute_usage_metric. For a zero-parameter, read-only list tool with no output schema, this covers the details an agent needs to interpret results 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 has zero input parameters, and the schema is empty, so there is no parameter meaning for the description to add. The description instead focuses on the returned data, which is appropriate. A baseline of 4 is correct for a parameterless tool.

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

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

The description uses a specific verb and resource: "List the virtual cost-allocation tag_keys defined for this account." It also clarifies the returned fields (cost_entries grain, rule count), which helps distinguish it from list_cost_tag_rules. However, it does not explicitly name that sibling or state that it is not the rules-listing endpoint, so identification still requires some inference.

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

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

It gives a clear downstream use case: pass a returned tag_key to query_costs with breakdown_by: "tag" to see spend broken down by that tag. That is useful context for when the result matters. It stops short of explicitly contrasting this tool with list_cost_tag_rules or list_cost_source_tag_keys, 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.

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 this as a safe read-only, idempotent, closed-world operation, but the description adds substantial behavioral context: `grid_cols`, `size_bounds`, `window_mode`, `report_scopes`, and the important caveat that widgets with `names_people` are not visible to viewers. This goes well beyond what annotations provide.

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

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

The purpose and the key 'no preset chart' caveat are front-loaded, and the response-field explanations are relevant. It is still noticeably long for a one-parameter list tool and repeats `create_dashboard`/`set_dashboard_widgets` several times, so it is not maximally tight.

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, but the description enumerates the important return fields — `grid_cols`, `size_bounds`, `data_version`, `report_scopes`, `window_mode`, `names_people`, and `data_schemas` — so an agent has the context needed to use the results correctly.

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

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

Schema coverage is 100% and the only parameter, `data_schema_for`, is already documented in the schema. The description largely repeats that limit and adds only the output location (`data_schemas`), so the baseline of 3 is appropriate.

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

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

The first sentence states a specific verb and resource — listing built-in preset dashboard widgets — and immediately distinguishes the two preset types (`kpi` tiles vs `widget` cards) plus the absence of preset charts. That is enough for an agent to tell this apart from `list_dashboards` or `get_dashboard`.

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

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

It explicitly says to use the catalog before calling `create_dashboard`/`set_dashboard_widgets` with an explicit `w`/`h`, and it names the alternative path for charts: build a `custom_chart` inline instead of using a `catalog_id`. It also explains when to pass `data_schema_for`.

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 a safe read (readOnly, idempotent, non-destructive), yet the description adds substantial semantics beyond them: how is_overdue is derived, when status flips to error (and when it does not), and that is_overdue/recent_failure_count are the true staleness signals. It also flags UNTRUSTED agent-reported text and instructs treating it strictly as data — critical behavioral context absent from 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 is front-loaded in the first clause, and the dense middle section is all load-bearing schema semantics (partial_failure, status behavior, push-agent states). It is long and reads as a wall of clauses, but almost every sentence earns its place; minor tightening possible.

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

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

No output schema exists, so the description carries the return-value burden and does so thoroughly — covering standard connections, push-agent connections with their collector and health states, and null cases. An agent has everything needed to interpret the response.

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. The description instead invests in output-field semantics, which is appropriate for a no-arg tool.

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

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

States a specific verb and resource ('List sync health for every cost/event/usage connection this account has') and enumerates the exact fields returned. Clearly distinguishable from siblings like query_costs or query_usage, which it is framed as a precondition for.

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

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

Explicitly says when to use it: '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 alternatives and the condition that selects this tool.

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

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

Annotations already declare readOnlyHint/true, idempotentHint/true, and destructiveHint/false, so safety is covered. The description adds the data-driven nature ('values seen') and the workflow placement ahead of query_costs, but says nothing about whether results are paginated, capped, or scoped to the date range, which matters for a listing tool.

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

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

A single front-loaded sentence with the purpose first and the workflow hint second; no filler. The inline dimension list is slightly redundant with the schema enum, but the sentence is otherwise tight.

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 two undocumented optional params and no output schema, the description should clarify the effect of start_date/end_date on which distinct values are returned and roughly what the result looks like (list of strings vs objects). It covers the conceptual purpose but leaves the temporal scoping of results completely unexplained.

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

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

Schema coverage is only 25% (just cost_source_id documented), so the description carries the burden and does not meet it. Its parenthetical enumerates only 5 of the 11 enum values (omitting identity, namespace, workload, cluster, resource_id, model), which can mislead an agent into thinking the list is exhaustive, and start_date/end_date are never mentioned.

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

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

States a specific verb+resource ('List the distinct values seen for a given dimension') and scopes it to one provider, so the agent knows it is a discovery/enumeration read, not an aggregation. It does not, however, differentiate itself from the similarly named sibling list_usage_dimensions, which an agent may not distinguish on name alone.

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

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

Explicitly frames the use case: 'useful for discovering filter values before calling query_costs,' naming the downstream tool and the intent. There is no when-not-to-use guidance or mention of the near-identical list_usage_dimensions sibling, so it falls short of a full 5.

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

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

Annotations already 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 declare read-only, idempotent, non-destructive behavior. The description adds useful behavioral context beyond annotations: it discloses the categories of returned data, which widgets are renderable versus not, why charts and heatmaps are excluded, and that it mirrors a specific API endpoint. It does not mention pagination or response shape details.

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 definition is front-loaded and two sentences with no wasted text. The parenthetical examples and caveats are dense but each clause contributes to understanding what the tool returns or how to use its 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 no parameters, the description carries the burden of explaining the return contents. It does so adequately by describing presets, renderable widgets, supported cost-scope types, excluded widgets, reasons, and the `catalog_id` usage needed for downstream report creation.

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?

This tool has zero input parameters, so the baseline is 4. The description mentions downstream use of `catalog_id`s, but there are no parameters whose semantics need additional explanation.

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 what a scheduled report's layout can be made of. It enumerates presets, renderable dashboard widgets with supported cost-scope types, and non-renderable widgets with reasons, which distinguishes it from generic dashboard widget catalog tools.

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

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

It gives clear usage context by saying the returned `catalog_id`s are used with create_scheduled_report / update_scheduled_report's `layout`. However, it does not explicitly name alternatives or when-not-to-use guidance, such as when list_dashboard_widget_catalog would be more appropriate.

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 profile, yet the description adds substantial non-obvious behavior: which rows come from provider engines vs. Plutus, that commitment rows are purchases lacking instance-type fields, that only one term/payment variant is surfaced by design, and that `total_estimated_monthly_savings_cents` excludes `upper_bound` findings. It also spells out unit/currency semantics (per-provider currency vs. USD total). This is exactly the context annotations cannot convey.

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

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

Purpose is front-loaded, but the body is a dense wall of unbroken prose in which `misconfiguration` and `source = plutus` are explained twice, and spending-reporting rules are interleaved with data-model facts. Content earns its place, but the structure makes it harder to scan than it needs to be.

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 single optional parameter, the description carries the full disclosure burden and does so: return shape, per-type field semantics, currency/total math, and interpretation caveats (`impact_unknown`, `upper_bound`). An agent has everything needed to call it and report results correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the schema's `type` param has no enum and only a one-line description; the description supplies the full value vocabulary and flags that `misconfiguration` is the value returning Plutus findings. That is real added meaning beyond the structured field.

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 for this account") and then enumerates the exact row taxonomy (`terminate`, `modify`, commitment types, `misconfiguration`) plus their provenance. An agent can tell this apart from `list_tag_recommendations` or `list_commitment_expirations` by the explicit source/type inventory.

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

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

There is useful in-tool usage guidance ("for the findings, use type=misconfiguration") and downstream handling ("Triage them like any recommendation: dismiss, mark acted-on, or ticket"), but no explicit when-to-use-this-vs-sibling routing, even though `list_tag_recommendations` and `list_commitment_expirations` sit right next to it. Usage is implied by the content rather than declared.

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 structurally. The description adds real behavioral context beyond that: schedules are all evaluated in UTC, the layout field may be null (meaning the standard digest), each destination carries the outcome of its last delivery, and next_period_label names the concrete covered range. It does not mention pagination or ordering, which keeps it off a 5.

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

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

Purpose is front-loaded in the first clause, with the API mirror and sibling routing at the end where they belong. The middle enumeration of cadences is long, but each item adds real information about what values the schedule field can hold.

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 return shape, and it does so field-by-field (schedule, scope, destinations plus last delivery outcome, widget layout, next due, next_period_label). Only pagination/size limits and sorting are unaddressed.

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

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

The tool takes zero parameters, so the baseline is 4; the description correctly avoids inventing arguments and instead spends its words describing the return content. The enumerated schedule cadences are helpful output semantics even though they are not inputs.

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

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

Specific verb (list) + specific resource (this account's scheduled cost digests), and it immediately enumerates what a digest consists of (schedule, scope, destinations, layout, next due). It also names the sibling create/update tools so an agent can route correctly.

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 closing sentence explicitly separates this read tool from create_scheduled_report / update_scheduled_report, giving an alternative. It does not state preconditions or when-not-to-use (e.g. versus list_report_layouts when only widget layouts are needed), so it falls just 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, 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 declare readOnly, idempotent, closed-world, so the safety bar is lower; the description adds real value by defining all five status values, including the non-obvious 'orphaned' (ticket not found) and 'closed_unresolved' (Won't Do/Duplicate/Declined), and by naming the returned attributes and the REST endpoint it mirrors. It stops short of disclosing pagination, result limits, or behavior when no tracker is connected.

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: what is listed, the status vocabulary, then the endpoint mapping last. The resource description is front-loaded and the enum glossary is compact rather than 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 compensates by enumerating the returned attributes and decoding status values, which is enough to call and interpret the tool. Remaining gaps are secondary: pagination behavior, an empty-result story, and clarity on whether owner_user_id is a filter.

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

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

Schema description coverage is 0%, so the description carries the burden: it thoroughly explains the status enum, which is the parameter most in need of definition. However, item_type and owner_user_id receive no explanation beyond the generic phrase 'Plutus-side owner', and it's unclear whether owner_user_id filters results or is merely a returned field.

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: lists tickets linked to savings recommendations and anomalies, plus the fields returned (tracker status, resolution, owner). That distinguishes it from list_savings_recommendations and list_anomalies, which return the underlying items rather than their tracker links, though the description never names those siblings explicitly.

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

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

Usage is only implied: an agent can infer this is the tool for cross-referencing tickets against recommendations/anomalies, and the status glossary hints at valid filter intents. There is no explicit when-to-use versus the recommendation/anomaly listing tools, and no note on prerequisites such as needing a synced tracker connection.

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 the safety profile is covered. The description adds real context beyond them: these are pre-saved, account-scoped definitions whose fields are interpreted (numerator_scope, denominator_metric, denominator_scale, revenue_source_ids). It does not mention result count or pagination, which keeps it below a 5.

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

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

Three dense sentences, front-loaded with the core definition before field semantics and routing. Every clause carries information, though the stacked parentheticals make it slightly harder to scan than a strictly minimal version would be.

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 job of explaining return values and does so for the key item fields, plus it links to query_unit_costs for computation. Remaining gaps — list shape, whether an empty set is possible, ordering — are minor but real.

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

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

With zero input parameters the baseline is 4, and the description goes further by explaining the semantics of the fields returned on each item — notably that denominator_scale is a readability factor limited to 1/1000/1000000 and that revenue_source_ids names revenue streams. That compensates for the absence of an output 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 ('List this account's saved unit-economics metrics') and immediately defines what such a metric is ('a cost ÷ business-unit ratio'). It also implicitly separates itself from the sibling query_unit_costs, which computes values rather than listing 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?

Routes the agent to two alternatives with conditions: 'see list_cost_tags' for tag_value scoping and 'Pass an id to query_unit_costs to compute one over a date range'. The guidance is clear but framed as follow-on actions rather than an explicit 'use this when you want definitions, use query_unit_costs when you want numbers' exclusion.

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

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

Annotations already carry readOnly/idempotent/non-destructive, so the bar is lower; the description still adds real behavior: it discloses the value/label pairing and the account_customers name fallback, which an agent cannot infer from the schema. It also maps to a concrete REST endpoint for orientation.

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

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

Two compact sentences, both front-loaded (purpose and scope first, output shape second). The parenthetical label explanation is dense but earns its place; nothing is padding.

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

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

With no output schema, explaining the value/label shape and the fallback to raw id is exactly the missing information an agent needs. Minor incompleteness remains around date conventions and the dimension_key variants, but nothing critical is absent.

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

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

Schema coverage is only 33%, and the description mentions just two of the four accepted dimension forms, omitting 'dimension_key' and 'dimension:<key>'. It adds useful meaning for external_customer_id labels but says nothing about start_date/end_date format, leaving a real coverage gap only partly compensated.

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 pins the scope with a date range. It is immediately distinguishable from query_usage, which it explicitly positions itself upstream of.

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 when-to-use: 'discovering filter values before calling query_usage', which routes the agent to the correct sibling. It stops short of stating when not to use it (e.g. when filter values are already known, just call query_usage).

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?

Far exceeds annotations: it discloses cost_basis estimation semantics and the duty to qualify estimates, currency conversion basis, cost_per_unit scale pitfalls, coverage.complete_through latency, and lagging_sources under-counting. This is exactly the behavioral context an agent needs for a read-only analytics tool.

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, but the description runs several dense paragraphs that mix invocation guidance with output-field semantics, including lengthy asides (token vs 1k-token quoting, cost_basis). Some of this could be tightened even given the 32-param complexity.

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

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

No output schema exists, so the description carries the return-value burden and does so thoroughly (currency, cost_basis, quantity/unit/cost_per_unit, coverage fields). For a broad analytics query tool, an agent has enough to interpret results and caveats 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?

With 100% schema coverage the baseline is 3, but the description adds real meaning beyond the schema: it explains that 'identity' is per-actor spend not always populated, and that 'category' folds sources into series and cannot combine with secondary_breakdown_by. Other params are left to the schema.

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

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

The opening sentence states a specific verb (Query) and resource (time-bucketed spend), lists the breakdown dimensions, and notes the tag path via list_cost_tags. It distinguishes from query_unit_costs behaviorally, though it does not fully contrast with get_cost_entries or query_usage siblings.

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

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

Usage context is implied ('Mirrors the GET /api/analytics endpoint') and one sibling (list_cost_tags) is referenced for tags, plus a contrast with query_unit_costs. But there is no explicit when-to-use-this-vs-get_cost_entries/query_usage guidance, so selection still requires 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 establish read-only, idempotent, non-destructive behavior, but the description adds critical operational traits: no pagination, a 5000-row cap, oldest-first ordering, and silent truncation on unscoped long-range queries. It also clarifies that results carry no cost figure and that the tool mirrors GET /api/events.

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 purpose, then constraints and distinctions. The long source enumeration is useful for identification but makes the first sentence dense; the final API-mirror line is mildly extraneous for an agent. Overall it is efficient but not maximally tight.

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

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

For an eight-parameter, no-output-schema query tool, the description covers purpose, scoping requirements, truncation risk, and cost-data exclusion well. It does not describe the returned event object shape, but the annotation and schema context make the definition largely complete for correct invocation.

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

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

Schema coverage is 100%, so the schema already documents all eight parameters in detail, including the meta_repo caveat. The description still adds useful meaning by making date scoping effectively mandatory and explaining the truncation consequence of unscoped start_date/end_date usage.

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 the account's business-event timeline. It enumerates concrete event sources (GitHub, PagerDuty, Jira, etc.) and explicitly distinguishes the tool from cost tools by saying it carries no cost figure. An agent can tell exactly what this tool returns and how it differs from query_costs/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?

Gives clear operational guidance: always scope with start_date/end_date because there is no pagination and results are capped at 5000 oldest-first rows, with silent truncation risk. It does not name a sibling alternative for event-facet discovery, but the core when-to-use constraint is 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?

Far beyond the readOnly/idempotent annotations, the description discloses null-vs-zero semantics, truncation at coverage.complete_through, lagging_sources, numerator_status.available meaning a removed source with empty rows, per-customer split blocks, and null revenue/margin semantics. These are exactly the traps an agent would otherwise misreport, and none of it is available in 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?

The purpose and the critical null/coverage warnings are front-loaded, and each subsequent paragraph maps to a distinct output condition. It is long, but with no output schema the density is largely earned; a few sentences (e.g. the restatement of 'null does NOT mean zero') 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 five parameters, no output schema, and non-obvious failure modes (telemetry gaps, lagging cost sources, removed sources, per-customer mismatches, revenue joins), the description covers every case an agent must handle to report results honestly. 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 coverage is 100%, so baseline is 3, but the description genuinely adds meaning for cost_metric by explaining that amortized spreads prepaid commitments across the term while budgets and target_unit_cost alerts stay billed, and warns that a tag-scoped metric's numerator may include redistributed shared spend. It adds nothing for group_by or the dates, keeping it short of a 5.

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

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

The opening sentence gives a specific verb ('Compute'), a specific resource ('saved unit-economics metrics'), and the actual arithmetic definition (cost of a slice of spend divided by business units produced). It names list_unit_metrics as the source of the id, so an agent can distinguish this from query_costs or query_usage 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?

Usage context is clear and alternatives are referenced explicitly: list_unit_metrics for obtaining unit_metric_id, query_costs for amortized detail, list_cost_tags for redistribution policy. It does not spell out a negative case (e.g. 'use query_costs instead when you want raw spend'), but the routing is unambiguous for the intended task.

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?

It adds critical behavioral traits beyond the annotations, specifically the warning: 'quantity is a raw count with no currency — never treat it as money.' This is crucial operational context for the AI agent interpreting the returned data.

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

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

The description is dense but efficient. It front-loads the primary function, followed by technical details, the vital currency warning, and the scope, making every sentence serve a structural purpose.

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

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

Given the high parameter count (12) and schema coverage, the description successfully handles the contextual 'why' and 'how to interpret' the results. It covers the units, the data source, and critical limitations, making it highly complete for this complexity.

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

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

Although schema coverage is high, the description adds vital semantic meaning, such as explaining that the metrics are for 'unit-economics divide cost by' and detailing the breakdown constraint ('at most 50 values are returned, the rest folded into "Other"').

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 purpose is extremely clear: 'Query time-bucketed usage telemetry.' It specifies the type of data (raw metrics like API counts, tokens processed) and explicitly differentiates itself by stating it provides raw unit-economics metrics, distinct from pre-defined ratios.

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

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

The description provides strong guidance on *how* to use the data by advising the agent to inspect raw units directly rather than using cost ratios. It also notes an optional breakdown by external_customer_id when applicable.

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