Costory: Your Finops MCP

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

Annotations only declare destructiveHint=true/readOnlyHint=false generically; the description adds per-kind semantics that matter operationally – report/alert/event/virtualDimension perform soft deletes via archivedAt/deletedAt while dashboard 'permanently deletes the dashboard row'. It also discloses that no MCP restore exists, which is exactly the kind of irreversibility detail annotations cannot express.

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

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

Front-loaded with the core definition and routing before the kind-specific lines. The line-by-line enumeration of archivedAt/deletedAt is slightly repetitive but each line carries distinct per-kind behavior, so it earns its space.

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

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

For a no-output-schema, 4-parameter object with a tricky dependent parameter (alertType), the description covers purpose, routing to alternatives, per-kind side effects, and the alertType coupling – everything an agent needs to call it correctly.

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

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

Schema coverage is low (25%), so the description must compensate and largely does: it defines alertType as 'the type field from list_alerts' and constrains it to resourceKind=costAlert, and notes a budget alert isn't its own kind. resourceId itself gets no added meaning, so it falls just short of full compensation.

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 ('Archive (soft-delete / hide) one saved Costory object') and immediately demarcates scope ('it does not create or edit objects'). The specific resourceKinds enumerated make it trivially distinguishable from siblings like archive_report and delete_tag.

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 ('archive, remove, or delete a report, cost alert, event, virtual dimension, or dashboard'), explicit exclusions ('Do not use this to hard-delete an alert', 'No bulk'), and named alternatives for the two lookalike cases (discard_virtual_dimension_draft, delete_tag). Nothing 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 destructiveHint=true, readOnlyHint=false, and openWorldHint=false. The description adds genuinely non-redundant context: the deletion is a soft delete and there is no restore path via MCP, which materially changes how an agent should weigh the call.

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

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

Three short, waste-free clauses covering redirect, deprecation date, and semantics. Slightly awkward ordering, since the redirect precedes the statement of what the tool does, but nothing is 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?

For a two-parameter mutation with full schema coverage, safety annotations, and no output schema, the description covers the essentials plus the undo limitation. Only missing nicety is explicit permission requirements for archiving a report.

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 both parameters (reportId, slug) are documented in-schema, including the auto-detect caveat for slug. The description adds no parameter-level detail, 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 ('Archive a report') and names the replacement sibling archive_object, so the agent can distinguish it from the other 50+ tools. It is not a tautology, but the purpose sentence is pushed to third position behind the redirect and deprecation notice.

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 archive_object and gives a concrete temporal condition ('Deprecated on 1 October 2026'), which effectively says when not to use this tool. No other exclusions or prerequisites are stated, but the alternative 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds substantial non-obvious behavior: new alerts are creator-only with implied Admin, tag side-effects (create-if-missing, default color), the scopeId-stored-but-not-merged quirk, daily BigQuery evaluation of window math, and the mandated URL in the response.

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

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

Front-loaded purpose followed by dense, mostly non-redundant guidance plus a concrete end-to-end example. It is long but proportionate to a 17-parameter nested tool; a few passages (dedup, condition) restate schema text, which keeps it from a 5.

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

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

For a complex 17-param tool with nested objects and no output schema, the description covers cross-parameter relationships, side effects, and even the return value (the URL to surface). Nothing an agent needs to call it correctly appears missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by giving worked condition expressions, explaining the dedup re-notification model relative to the evaluation window, and clarifying that scopeId is stored rather than merged into filters and that tagIds of `[]` vs omitted are equivalent.

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

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

Opens with a specific verb+resource+scope: 'Create a cost alert that monitors one or more queries and notifies when a condition fires.' An agent can distinguish this from update_alert, list_alerts, and preview_alert without opening any schema.

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

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

Explicitly routes to siblings for sub-steps: set_object_permissions to share, list_available_destinations for SLACK/TEAMS IDs, list_tags for tag IDs, and the `query` tool config format. It clarifies the datePreset-vs-from/to preference and when to omit scopeId. It stops short of an explicit when-to-use-this-vs-update_alert/preview_alert statement, so a 4 rather than 5.

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

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

Annotations only cover the safety profile (readOnly=false, destructive=false, openWorld=false); the description adds substantial behavior beyond that: creator-only ownership/Admin grant, sharing flow, the deprecated `context` alias, auto-creation of missing tags, grid auto-packing, inheritance defaults, and the required URL return value.

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 long dense block, but every sentence carries a concrete rule and the core purpose is front-loaded in the first clause. The single-paragraph format is harder to scan than bullets would be for the volume of rules, but little is wasted.

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

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

For a complex nested tool with no output schema, the description covers the return value ('Returns a URL — you MUST include it in your response'), the widget model, inheritance semantics, and a worked example pointing to the skill. Nothing essential to correct invocation is missing.

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

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

Schema coverage is 100%, so the schema already documents every parameter (baseline 3). The description still adds practical semantics not obvious from the schema: never send both context and dashboardContext, don't repeat matching date fields, hide formula inputs with visible:false, and budget groupBy explicitly does not inherit.

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

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

Opens with a specific verb+resource ('Create a dashboard with one or more widgets') and immediately distinguishes itself from update_dashboard through sequencing guidance ('call set_object_permissions after create'). An agent can identify the tool's role 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?

Explicit when-to-use rules throughout: call get_skill skillId 'dashboards' first, use set_object_permissions to share, prefer datePreset over dates, omit from/to when matching dashboardContext, use suggest_usage_metrics for usage metricId. Names concrete alternatives and conditions.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=false, and destructiveHint=false, but the description adds substantial behavioral context: events appear as chart annotations, widget definitions create visual annotations, widget is a full replacement on update, source is server-set, deprecated aliases are ignored, and list_tags should be used before creating tags. No annotation contradiction.

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 long but well-structured and front-loads the purpose and primary usage guidance before parameter details and the example. The example is useful for a nested widget object, though some widget and metadata guidance is repeated from the schema.

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

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

For a complex create tool with nine parameters, nested widget objects, and no output schema, the description is thorough about creation semantics, annotation behavior, tag discovery, metadata handling, and example usage. It does not describe the return value, error behavior, or permission requirements, but those gaps are relatively minor given the schema coverage.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by emphasizing that widget is STRONGLY RECOMMENDED, explaining when to omit it, noting that null is equivalent to omit for scopeId on create, and providing a complete example invocation. Some of this overlaps with schema descriptions, but it meaningfully improves parameter understanding.

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: 'Create a new event to annotate a cost change.' It explains the event's role as a chart annotation, which distinguishes this create/annotation tool from list_events and update_event without opening either schema.

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

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

Gives clear when-to-use context ('when the user wants to document why costs changed') and instructions for the widget parameter, including when to omit it. It also points to list_tags before inventing new tag values. It does not explicitly say when to use update_event instead for existing events, so it falls short of full alternative routing.

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

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

The annotations say only that this writes (readOnlyHint false) to an open world without being destructive. The description adds what the annotations cannot: the report is creator-only immediately after creation, the NOW and SCHEDULED modes are flagged DANGER ZONE and demand a summarised confirmation before calling, the legacy `context` alias is deprecated, and the return payload is spelled out (URL and nextRunAt, plus execution URLs and per-destination status for NOW).

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 safety warnings are front-loaded, and almost every sentence covers a distinct rule. It is long, however, and three full JSON examples plus repeated restatements of the DIGEST hierarchy and the deprecation notice cost some density.

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 9-parameter tool with polymorphic widgets, schedules and destinations and no output schema, the description supplies the confirmation requirements, the inheritance rules, the destination formats, the WEEKLY weekday constraint and worked examples. An agent would not need anything else in order to call this 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 already 100%, so the baseline is 3, but the description carries inheritance semantics the schema only states piecemeal: widgets inherit from `reportContext` and should only carry overrides, and the description ties the period requirement to the presence of query widgets. It also resolves per-widget ambiguities, such as `useDashboardGroupBy: false` making the first `additionalGroupBy` item the root and requiring at least one dimension, and the DIGEST `aggBy` restriction to Week or Month.

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

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

It opens with a specific verb and resource: 'Create a report with shared `reportContext` and one or more `widgets` plus destinations.' That is enough for an agent to distinguish this from update_report, preview_report_widget or run_report_now 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 names the alternatives and the conditions that select them throughout: call get_skill skillId 'reports' first, use set_object_permissions after create rather than sending PRIVATE/PUBLIC, resolve tags via list_tags, resolve channels via list_available_destinations. The NOW/UNSCHEDULED/SCHEDULED modes are each given an explicit use case.

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

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

Annotations only indicate readOnlyHint false / destructiveHint false, so the description carries the burden and delivers extensively: 'Rejects invalid payloads — nothing persisted unless validation passes', success includes 'draftPersisted: true' and 'draftValidation: { ok: true }', rule ids are 'generated on save', leftoverRule is 'auto-added', and 'bqName … is immutable'. Side effects and validation behavior are fully disclosed.

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

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

The prose is front-loaded with the core purpose, then organized into lifecycle guidance, allocation details, constraints, response shape, and an example before the schema. However, it is extremely dense and contains redundancy — the BigQuery/S3 dateColumn/metricColumn/gapFillingMethod requirement is stated twice ('For BigQuery/S3, also set…' and 'For BigQuery/S3, dateColumn, metricColumn, and gapFillingMethod are required…').

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?

Despite having no separate output schema, the description enumerates the full success response ('virtualDimensionId, bqName, name, description, tags, values, rules with generated ids, leftoverRule, draftValidation: { ok: true }, draftPersisted: true'), covers failure behavior, advanced allocation semantics, required prerequisite skill, following tool, and a worked example — complete for a tool with this much nested logic and many relevant siblings.

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

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

While the schema already covers all 5 parameters, the description adds substantial meaning beyond it: 'virtualDimensionId in inputs equals id from list/get/search', 'bqName … is set once from name at create', rules must not send 'id (generated on save) or values (derived)', the four allocation types are spelled out, and BigQuery/S3 requirements (dateColumn/metricColumn from list_metrics schema, default gapFillingMethod FORWARD_FILL) go far beyond the bare property definitions.

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?

Opening phrase 'Create a new virtual dimension draft without publishing' names a specific verb, resource, and lifecycle state, distinguishing it from the sibling publish_virtual_dimension_draft. The embedded EXAMPLE ('Draft an Environment VDIM with a prod rule') makes the intent unmistakable.

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 instructs prerequisites ('Call get_skill with skillId: "virtual-dimensions" first'), next steps ('Use preview_virtual_dimension_draft next'), and exclusions ('Do not set datasource on new reallocations', 'Do not include catch-all/leftover in rules', 'Does not publish or refresh BigQuery'). It also explains the relationship to query after publish ('Use returned bqName for groupBy/filterCel in query after publish').

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 mark the operation as destructive (destructiveHint=true). The description adds valuable behavioral context beyond the annotations by specifying the zero-usage requirement, the error condition, and the need to check list_tags first. This clarifies the operational constraints without contradicting the annotations.

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

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

The description is concise, with the main purpose in the first sentence and additional context in a second sentence. The example is helpful but slightly redundant, though it does not inflate the text excessively. Overall it is well-structured and front-loaded.

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

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

For a destructive delete operation with only two parameters and no output schema, the description covers the essential conditions, error behavior, and prerequisite. It does not mention authentication or success response details, but these are less critical given the annotations and the tool's simplicity.

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

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

The input schema covers both parameters (slug and tagId) with clear descriptions, achieving 100% schema description coverage. The description includes an example that illustrates tagId usage but does not add semantic meaning beyond what the schema provides, so the baseline score 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 description uses a specific verb ('Delete') and resource ('tag') with organizational scope, clearly distinguishing this tool from sibling tools like list_tags or update_dashboard. It explicitly states the purpose and the key constraint of deleting only unused 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?

The description gives explicit usage guidance: call list_tags first to check usage counts, and notes that an error occurs if the tag is still in use. This tells the agent when to use the tool and what prerequisite steps are needed, effectively differentiating it from non-delete alternatives.

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

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

Annotations already declare destructiveHint=true, but the description adds valuable context: it does not delete published virtual dimensions, returns 'draftDiscarded: true' on success, and errors when no draft exists. This clarifies the exact scope of destruction and the outcome, exceeding what annotations alone 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 description is well-structured and front-loaded with the main purpose. It includes necessary details (return value, error case, non-destructive scope, example) without fluff. It is slightly longer than the bare minimum but every sentence adds value, making it appropriately sized for a tool with multiple behavioral caveats.

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 moderate complexity, the description covers the key aspects: what it does, when to use it, parameter mapping, success/error behavior, and scope. There is no output schema, but the return value is mentioned. The description is sufficient for an agent to invoke 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?

The schema already provides descriptions for both parameters at 100% coverage, but the description adds crucial mapping: 'virtualDimensionId in inputs equals id from list/get/search.' The example also demonstrates how to fill the parameter, which is helpful beyond the schema's minLength constraint.

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

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

The description clearly states the action: 'Discard the pending draft for an existing virtual dimension without publishing.' The verb 'discard' and specific resource 'pending draft' are unambiguous, and 'without publishing' distinguishes it from the publish tool. This completely separates it from sibling tools like create/update/publish.

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 explicit when-to-use guidance: 'Use when a draft is corrupt/unreadable or you want to abandon in-progress edits.' It also notes the error condition when no draft exists. However, it doesn't explicitly compare with update_virtual_dimension_draft or other alternatives, though the 'without publishing' phrase implies a contrast.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is known Stephen. The description adds substantial behavioral detail beyond annotations: compare is required, `{}` auto-derives the previous window, filterCel omitted or "" is unfiltered (not AWS-only), and nestingEdges warns against summing hierarchical contributors. This addresses a subtle and likely accidental misuse (double-counting) that the schema would not reveal. No contradiction with annotations.

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

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

The description is dense but every sentence serves a distinct purpose: purpose, prerequisite, constraint, a behavioral warning, a default preference, and two examples. There is no redundancy or filler. The structure naturally front-loads the core purpose and then progressively adds nuance, making it easy for an agent to scan.

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 8 parameters Prix, no output schema, and a non-trivial analysis workflow, the description covers everything an agent needs to invoke it correctly: required fields, ordering of discovery calls, column selection rules, filter semantics, aggregation defaults, and sample invocations. It even includes a hierarchical aggregation caveat that would otherwise be an easy to make error. The only thing missing is an explicit return format, but given the complexity handled and the annotations covering safety, this is complete enough.

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 ~88%, but the description goes beyond the schema to explain critical semantics: compare's `{}` shorthand, filterCel's unfiltered default, aggregationMethod's preference to omit, and the recommended 2–4 column range (with max 8). The examples demonstrate the exact structure for columns, including the { column, contains } object form. This is high-value practical context that the schema alone does not provide.

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 and resource: 'Find which dimension values drove a cost change between two periods.' This clearly distinguishes the tool from siblings like query (raw data) or suggest_groupby (suggest dimensions), and it explicitly frames the tool as a before/after analysis. The name and description are aligned, and the purpose is immediately actionable.

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 explicit usage direction: 'Prefer suggest_groupby / search / get_context first, then pass 2–4 columns (max 8).' It tells the agent the prerequisite discovery tools Series and the recommended column count. It also provides a clear exclusion ('Do not invent columns') and clarifies filterCel semantics. The two concrete examples further illustrate both datePreset and from/to usage, leaving little ambiguity about when to call 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 declare a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description adds substantial behavior beyond that: Postgres caching with a guaranteed second-call cache hit for BigQuery jobs, what is deliberately omitted (timing histograms, column lists), that returned `queries` are a read-only internal shape lacking the scope filter and must not be echoed back, and that `values` on virtual dimensions is derived/output-only. This is unusually rich disclosure for a read 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?

Front-loaded with the discriminator and ID-discovery guidance, then cleanly partitioned by resource type, so an agent can jump to the relevant paragraph. It is nevertheless very long and enumerates return payload fields (costMetricId, filterCelRestrictToIncludedLines, etc.) that read as spec-dump; with no output schema most of that detail earns its place, but the volume is close to the limit of what a selector can absorb.

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 full burden of return-value semantics, and it does: per-type payload contents, the `type` discriminator, BigQuery stage/children behavior, and the alert `queries` shape. For a six-way polymorphic getter sitting among dozens of get_/search/list siblings, nothing an agent needs to invoke or interpret this correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3 and much here (BigQuery id shape, budget parent/version id, the type enum) is already in the schema. The description still adds operating meaning: BigQuery ids are auto-detected from their shape and location is case-insensitive, omitting `type` tries every type, and slug auto-detection fails for multi-org accounts. That is above the baseline, though not a full compensation 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?

Opens with a specific verb + resource list ('Fetch a V2 dashboard, budget, cost alert, report, virtual dimension, or BigQuery job by ID') and immediately explains the `type` discriminator used to branch. Despite the generic name 'get', an agent can distinguish this polymorphic fetcher from get_report_execution, get_dashboard_widget_data, and the search/list siblings without opening any schema.

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

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

Explicitly routes the agent: 'Use "search" (or list tools) first to discover IDs', plus named hand-offs to get_report_execution for delivery content, get_dashboard_widget_data/get_dashboard_widget_image after a dashboard fetch, get_skill with skillId 'dashboards'/'virtual-dimensions' before mutations, and update_alert for alert rewrites. Both the when-to-use and the when-to-use-something-else conditions are stated.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that — the name-vs-label distinction, the 10-minute propagation delay for published dimensions, the dryRun/confirm publish flow, and polling computeStatus until COMPLETED. Much of this, however, describes side effects of other tools rather than this read call, so it is context rather than disclosure about get_context itself.

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 'call first' directive are correctly front-loaded, but the body sprawls into operating instructions for at least five other tools (search, list_dimension_candidates, publish_label_dimensions, list_metrics, virtual-dimension publishing) plus column/gap-filling guidance. Those sentences do not earn their place in this tool's definition and bury the actual contract.

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 describe returns — and it does, naming dimensions with name/label, recent dashboards, externalMetricIntegrations, and a per-integration schema with DATE/NUMERIC columns. For a single-optional-param read tool the core is complete, though the parameter's auto-detection behavior is left entirely to the 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?

There is one optional parameter (slug) with 100% schema description coverage, so the schema already carries the meaning, including the multi-org failure mode. The description adds nothing about slug, which is acceptable under the baseline-3 rule but earns no uplift.

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 with concrete scope: 'Get workspace context: popular groupBy dimensions, recent dashboards, and connected external-metric integrations (e.g. Tsuga, BigQuery, Datadog, CloudWatch).' An agent can immediately distinguish this from siblings like search, list_metrics, or list_dimension_candidates because the description names those as separate destinations.

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 'Call this FIRST at the start of every conversation,' which is an unambiguous trigger. It also routes the agent onward with conditions: use search with type:["dimensions"] for CEL field discovery, list_dimension_candidates for unmodeled billing keys, and list_metrics with includeExternal:true when externalMetricIntegrations is non-empty.

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 read-only, non-destructive behavior. The description adds meaningful context beyond annotations: conditionsCel application logic, the extendDashboardConditions override, and that hidden series with visible: false are omitted from display.

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

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

Front-loads the core action and scope, followed by behavioral detail and an example. Dense but appropriate for the tool's nuance; every sentence earns its place.

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

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

Covers purpose, preconditions, the conditionsCel behavior, and a concrete example. No output schema exists, so it notes what is returned (series/timeSeries or comparison breakdown). Complete enough 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 baseline is 3. The description references widgetId and dashboardId in the example, but adds no semantics beyond what the schema descriptions already provide for slug, widgetId, and dashboardId.

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: 'Run a saved widget by id and return its cost data.' Clearly distinguishes itself from the query tool and the sibling get by explaining that no query config re-specification is needed.

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

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

Explicitly says 'Use after get to get data for a specific widgetId,' and provides an example workflow. It does not name alternatives or exclusions (e.g., when to use query directly instead), so not a full 5.

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

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

Beyond the annotations, the description discloses the GCS upload side effect, the default inclusion of base64 PNG bytes, the option to skip binary for large payloads, the condition merge behavior, and the UNSUPPORTED_WIDGET failure case. This is rich behavioral context that annotations alone don't provide. The readOnlyHint=false annotation aligns with the stated upload side effect, showing no contradiction.

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 appropriately sized for the tool's complexity. Every sentence contributes meaningful information: purpose, when to use, condition merge, return format, binary option, no-share-URL note, unsupported types, and a working example. Despite its length, it remains structured and front-loaded, with the core action stated first.

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 stating the return values (imageUrl, base64 image block). It also covers failure modes, parameter interplay, and usage context. The example provides a complete scenario from widgetId to call, making the tool's behavior fully understandable for an agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the purpose of includeBinaryImage (skip binary for large payloads), clarifying widgetId comes from a get call, and providing a concrete example with parameter values. However, the schema already thoroughly documents each parameter, so the description doesn't need to compensate heavily.

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

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

The description opens with a specific verb and resource: 'Render a saved widget as a PNG chart, upload to GCS, and optionally return the binary image inline.' It clearly distinguishes from sibling tools like get_dashboard_widget_data by focusing on the visual image output rather than data.

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

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

Explicitly states when to use: 'Use when the user wants to see a visual snapshot or embed an image in a chat reply.' It also provides an exclusion ('Does NOT work for text or table-only widgets') and suggests an alternative (link to the dashboard for the live chart), making the usage guidance very actionable.

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

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

Despite readOnlyHint=true in annotations, the description adds valuable behavioral context: the response format ('Response starts with `Url: ...`') and a specific citation instruction using that exact URL as markdown href. This goes beyond the annotation safety profile.

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

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

The description is two concise sentences plus a formatted example. Every sentence earns its place: first states the purpose, second gives usage sequence and response details, then a labeled example. No redundancy.

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

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

For a simple read tool with one parameter and no output schema, the description covers all necessary aspects: what it does, when to use it, what the response looks like, and how to handle the response correctly. The example completes the context.

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

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

Schema coverage is 100%, so the parameter is fully documented. The description reinforces meaning with a concrete example ('Show me the full page about cost explorer' → { page: ... }), adding usage context beyond the schema but not new parameter semantics.

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 specifies a clear verb ('Retrieve'), resource ('full content of a specific Costory documentation page'), and input method ('by its public docs URL or page path'). It distinguishes itself from sibling tool search_documentation by explicitly stating this is the follow-up retrieval step.

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

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

Provides explicit usage context: 'Use this after search_documentation returns results.' This clearly indicates when to use the tool in relation to its sibling. The example also demonstrates a natural-language-to-parameter mapping.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'Read-only.' It adds meaningful behavioral context beyond annotations: the special case for budget alerts (use parent budget id), the fact that templates have no ordinary grants, and the semantic detail that canManage is true only for Admin. It does not describe pagination or error behavior, but for a read-only listing tool this is a minor 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?

The description is compact and front-loaded: the core purpose appears in the first sentence, followed by return-value summary, special cases, and examples. Every sentence earns its place, and the examples are illustrative without being verbose.

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

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

For a read-only tool with full schema coverage and safety annotations, the description covers the essential invocation details: resource kinds, id provenance, return contents, and edge cases (budget alerts, templates). It lacks an output schema and does not describe pagination or error conditions, but those are not critical for a permissions-listing tool with this level of guidance.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds value by explaining the relationship between resourceKind and resourceId ('pass resourceKind plus the object id from search / get / create'), clarifying the budget-alert special case, and providing concrete example values. It slightly exceeds the baseline 3 by enriching the enum semantics with usage context.

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') and resource ('direct Reader/Editor/Admin grants on a dashboard, report, budget, or cost alert'), and explicitly distinguishes itself from the sibling set by covering all four resource kinds in one tool. It also clarifies what it returns (grants, caller's effective role, capabilities), making the tool's purpose unmistakable.

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 explicit when-to-use guidance: 'One tool for all four kinds — pass resourceKind plus the object id from search / get / create.' It also provides exclusions ('Templates have no ordinary grants') and two concrete examples mapping natural-language questions to parameter values. This is strong routing guidance relative to siblings like set_object_permissions and get.

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

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

Beyond the readOnlyHint/destructiveHint annotations, the description discloses the condensed behavior, the omission of raw time-series and full DIGEST trees, and the ability to expand widget drillDowns. This is exactly the kind of behavioral context that annotations alone do not provide.

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

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

The description is compact and front-loaded, using three sentences plus a short example. Each sentence adds necessary information: what the tool returns, what it omits, and which sibling to use for more 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?

Even without an output schema, the description enumerates the key returned fields (status, destination, per-widget summaries, URLs) and explicitly lists what is not included. This is sufficient for an agent to contract on a read-only summary call.

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

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

Schema description coverage is 100%, so the baseline is 3. The description includes a concrete example with executionId, but it does not add significant meaning beyond what the schema already provides for either parameter.

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 begins with a specific verb-resource pair ('Get a condensed execution summary') and lists concrete contents (status, destination, per-widget summaries, URLs). It also distinguishes itself from get_report_execution_widget by explicitly pointing to that sibling for expanded widget details.

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 states what the tool omits (raw time-series, full DIGEST trees) and names get_report_execution_widget as the alternative for drillDown widgets. It also instructs the agent to mention DIGEST tree/node investigations are available, which is practical guidance for when to use this tool vs. other investigation paths.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'Read-only; never starts new investigations', adding the specific safeguard against triggering investigations. It also explains behavior for the `tree` view ('returns the full formatted tree'), which is context beyond the schema. Slightly more could be said about error cases or response format, but the annotation coverage lowers the burden.

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

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

The description is two sentences plus an example, with zero filler. It front-loads the core purpose first, then provides invocation detail, and closes with a concrete example. Every sentence contributes 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?

Given the tool has no output schema, the description covers the main usage flow and highlights a key behavior (full tree). The annotations cover safety. However, it does not describe what each enum value (`series`, `investigations`) returns or what happens if the provided view is not in the drillDown list. Still, the tool is relatively simple and the example helps fill gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful value by explaining that `widgetId` and `view` come from a drillDown list and by specifying that the `tree` view returns a full formatted tree. This goes beyond the schema's bare enum descriptions. The example also shows real-world usage. No param-specific info is missing that would require a higher score.

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 ('Fetch') and clearly identifies the resource ('advanced view for one widget from get_report_execution'). It also distinguishes this from the sibling `get_report_execution` by focusing on drill-down views per widget. The example and mention of 'DIGEST tree' further clarify scope.

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 instructs the agent to 'Pass widgetId and a view from its drillDown list', giving explicit invocation guidance and a concrete example. It also notes the read-only nature, which prevents misuse. However, it does not explicitly contrast with alternatives like `preview_report_widget` or state when this is preferable to `get_report_execution`.

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 mark the tool as read-only and non-destructive. The description adds valuable behavioral context beyond the annotations: it returns markdown, must be called after get_context, and enforces path constraints ('relative, end in .md, and cannot traverse (..)'). It doesn't detail error behavior or auth requirements, but the safety profile is already covered by annotations.

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

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

The description is well-structured, starting with purpose and timing, then offering examples. The numbered input options and bulleted examples improve scannability. It is somewhat repetitive (the same skill IDs appear in the prose and examples), but the extra length is justified by the tool's need to disambiguate between two input modes.

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

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

The description covers the core contextual needs: what the tool loads, the return format (markdown), sequencing relative to get_context, the two accepted input forms, and path constraints. For a read-only, single-parameter tool with no output schema, this is largely sufficient. It stops short of explaining failure modes or listing all possible skill IDs, but those are discoverable via list_skills.

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 100%, the description adds substantial meaning beyond the schema: it maps user intents to concrete skillId values, provides representative examples for both catalog IDs and repo-relative paths, and introduces path validation rules not present in the schema. This exceeds the baseline expected for fully covered schemas.

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

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

The description clearly states the tool's action: 'Load a workflow guide or any markdown file from the Costory skills GitHub repo' and notes it 'Returns markdown.' It distinguishes itself from siblings by specifying its timing ('call BEFORE starting the task, AFTER get_context') and by saying 'Call this instead of guessing the tool sequence.'

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 explicit guidance on when to use the tool: before starting a task, after get_context, and for build tasks it recommends specific mechanics skills. It also explains the recipe workflow and the two valid input forms. However, it doesn't explicitly state when not to use the tool versus alternatives like get_documentation_page, so it falls short of full exclusionary 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?

The description adds valuable behavioral details beyond the readOnlyHint annotation: it explains that cost alerts return a firing condition expression and dedup config, while legacy alerts return thresholds. This clarifies response shape and handling of legacy 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?

Two concise sentences front-load the core purpose and then add necessary detail on return formats and usage constraint. No wasted words.

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

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

With no output schema, the description adequately conveys what the tool returns and differentiates legacy vs. current alerts. It could mention pagination or statuses, but the core context is well covered for a read-only list operation.

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

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

Schema coverage is 100% with both parameters (slug and type) already described in the schema. The description does not add further parameter semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool lists all cost and budget alerts for an organization with their current status, using a specific verb and resource. This distinguishes it from sibling tools like create_alert and preview_alert.

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 explicitly says 'Only call this when the user explicitly asks about their current cost monitors or alerts,' providing strong when-to-use guidance. It does not name alternatives explicitly, but the purpose is distinct from creating or previewing alerts.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description adds valuable behavioral context: it explains the return structure (object keyed by provider), the 'connected' boolean for telling users about unset integrations, and the special ALL_ACTIVE_USERS literal. It doesn't contradict annotations. It could mention that the tool may fail if the user belongs to multiple orgs and slug is omitted, but that's covered in the parameter description. The description goes beyond annotations by explaining the shape and semantics of the response.

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

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

The description is well-structured and front-loaded with the core purpose. It includes a concrete example that illustrates the expected usage pattern. It's a bit long but every sentence earns its place: the return structure, the connected boolean, the email special cases, and the example all add necessary information. The example is particularly helpful for an agent to understand how to map user requests to channelId values.

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 one optional parameter and no output schema, the description is quite complete. It explains the return shape, the special email cases, and the relationship to sibling tools. It doesn't describe pagination or rate limits, but for a destination-listing tool that's likely not a concern. The description covers what an agent needs to know to call it correctly and 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?

Schema description coverage is 100%, so the schema already documents the slug parameter. The description adds context by explaining when slug matters (omit to auto-detect, fails if multiple orgs) and how it relates to the tool's behavior. It doesn't repeat the schema but adds a small amount of value. Baseline 3 is exceeded slightly because the description clarifies the failure mode and the auto-detection 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?

The description clearly states the tool's purpose: listing every destination the organization can deliver reports or alerts to. It specifies the resource (destinations) and the verb (list), and distinguishes it from sibling tools like create_report and create_alert by explicitly saying to call it before those to resolve channelId values. The example further clarifies the intended use.

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 explicit when-to-use guidance: 'Call this before create_report or create_alert to resolve channelId values.' It also gives specific instructions for handling email recipients, including using destinations.email.self for 'email me' and asking the user for any other explicit recipient. This is clear, actionable guidance that an agent can follow without ambiguity.

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

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

Annotations already declare readOnlyHint/openWorldHint/destructiveHint, and the description adds substantial context on top: default behavior drops already-published keys, the result row shape including 'topValues (top 8, Others omitted)', and the ~10-minute propagation delay before changes appear in Explorer. These are non-obvious operational traits not derivable from the schema.

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

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

Front-loads purpose and return shape, then packs workflow guidance into tight sentences, ending with a concrete example call. It is dense and slightly redundant with schema defaults (limit, offset, default sort), which costs a point but the density is information-bearing rather than 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?

Despite having no output schema, the description enumerates the returned columns and the topValues truncation rule, covers filtering/sorting/paging, and describes the full publish loop with preview and confirmation semantics. An agent can invoke this correctly and understand its downstream workflow without further context.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by naming the sort enum values and explaining why includeImported matters (keeping keys already used in a published label) rather than merely restating the type. Some entries (limit cap 50, offset) duplicate the schema, which holds it below 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?

Opens with a precise verb+resource ('List native billing label keys that can be imported as label dimensions') and immediately disambiguates scope with '(not virtual dimensions)', separating it from list_virtual_dimensions and list_label_dimensions. It also enumerates the returned row fields, so the agent knows exactly what it 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?

Explicitly routes to siblings and states the workflow: use publish_label_dimensions to add/change, call list_label_dimension_usages before rename/delete, and notes there is 'No suggestion engine — pick merges and value maps from topValues yourself.' It also gives the dryRun-then-commit sequence, which is exactly the guidance an agent needs.

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

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

Annotations already cover the read-only safety profile, but the description adds real value by disclosing the return shape (sorted date-descending, metadata like link/owner/source, widgetEvents and scopeId). With no output schema this is the only place that return behavior is described, though pagination/limits are still unaddressed.

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

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

Purpose is front-loaded and the examples are genuinely useful. The sentence 'After query you may optionally call this to check if any events happened around that time' is somewhat meandering and slightly redundant, but overall the text is efficient.

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 four-parameter read tool with no output schema, the description covers purpose, filtering, and return contents adequately. Minor gaps remain around pagination or result limits, but nothing essential for correct invocation 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 examples add meaning by showing how from/to bracket a spike window and how tags filter (e.g. ['deployment']), clarifying intended usage beyond the field descriptions.

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

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

States a specific verb (List) plus resource (events), clarifies the event types (deployments, business changes, provider updates), and scopes to an organization within a date range. It does not explicitly distinguish itself from sibling list/create/update tools, but the verb+resource combination is unambiguous.

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

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

'Use this to correlate cost changes with real-world events' gives a clear use context, and the two examples show concrete invocations. It does not, however, name when-not to use it or route to alternatives like search or find_cost_change_factors, so exclusions are missing.

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

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

With readOnlyHint/destructiveHint/openWorldHint already declaring the safety profile, the description still adds real value: it specifies the return payload ('Compact rows only: id, name, sourceKeys, maps') in the absence of an output schema, and states pagination behavior ('No pagination — orgs do not have enough labels to page'). The remaining text about dryRun/confirm and the ~10 minute Explorer delay describes the publish workflow rather than this tool, so it is context rather than this tool's own behavior.

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

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

Purpose and scope are front-loaded in the first sentence, but roughly half the text is instructions for a different tool (publish_label_dimensions dryRun/confirm flow, merge semantics, 'do not resend the full list'). That material is useful workflow context yet dilutes a listing tool's description.

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

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

Covers what an agent needs to call this correctly: the returned fields (substituting for a missing output schema), the absence of pagination, and the correct sibling tools for filtered/related operations. No material gap remains.

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 there is a single optional slug parameter already fully documented in the schema ('Omit to auto-detect from your account (fails if you belong to multiple orgs)'). The description adds no additional parameter semantics, which is the expected baseline when the schema carries the burden.

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

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

States a specific verb and resource ('List all published engineered label dimensions') and immediately defines the returned concept ('merge + value map'). It also names the sibling it is not ('Not virtual dimensions — those use list_virtual_dimensions'), so an agent can disambiguate from list_virtual_dimensions and list_label_dimension_usages 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 routing: use list_label_dimension_usages before rename or delete, use publish_label_dimensions operations for edits, use list_virtual_dimensions for virtual dimensions. The read-only scope of this tool is clearly bounded against the mutation path.

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 is a safe read, but the description adds material behavioral facts: hits are static JSON/CEL scans of specific fields rather than live BigQuery, an empty result is success/safe-to-delete, and results are capped at 100 with a truncated flag.

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

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

Purpose and scoping are front-loaded, and every clause carries information (semantics, caveats, cap). It is dense with em-dash asides rather than wasteful, though slightly packed for a single paragraph.

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

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

No output schema exists, yet the description pre-empts the questions an agent would have about results: what empty means, what is scanned, and the truncation behavior. Nothing needed to call it correctly or interpret the response 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 schema already documents the id-wins rule, but the description adds non-schema meaning: 'Native cos_* names work with name alone,' clarifying the name parameter's accepted domain.

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 stored objects that reference a label dimension column') and enumerates the object types, so an agent distinguishes it from list_label_dimensions (which returns dimensions, not usages) 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 frames the use case ('before rename or delete') and names the complementary tool to source ids from ('Pass id (from list_label_dimensions)'). The condition that selects the parameter path is spelled out, 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 cover read-only and non-destructive behavior, so the description does not need to re-establish safety. It adds useful behavioral context: external catalogs can be large and will ask for a search term, externalLimit is capped at 50, gapFillingMethod defaults to FORWARD_FILL, and the tool returns metadata only, not actual 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?

The description is long but dense, and nearly every sentence carries provider-specific behavior an agent needs. It front-loads the core purpose, then details edge cases and ends with examples. It is not as compact as the best definitions, but it contains little filler and uses examples to illustrate the main parameter modes.

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

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

There is no output schema, so the description carries the full burden of explaining return shapes, and it does: saved metric id/name/type, externalMetrics fields, BigQuery/S3 schema, datasourceId special mode, gapFilling default, and required fields for query or reallocations. For a tool with this many provider-specific modes, the coverage is comprehensive.

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?

Even though schema coverage is 100%, the description substantially enriches the parameters: search is required when includeExternal is true, datasourceId has a special list mode with exact id-suffix handling, includeExternal selects a specific return shape, and externalLimit has documented defaults and caps. It also explains how returned fields map to downstream query and externalMetric construction.

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

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

The description opens with a specific verb and resource: list saved Costory business metrics and optionally matching live external metrics. It clearly separates this tool from query by stating it does not return values, which helps an agent pick it correctly among the sibling tools.

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

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

The description gives explicit usage rules: use includeExternal only with a search term, pass datasourceId only for inspecting leftover datasource groupByDimensions, and call query afterwards to inspect values. The examples map natural-language requests to concrete parameter objects, which is strong when-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful context about slug auto-detection and scoping results to accessible orgs, going beyond the annotations.

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

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

Three concise sentences with front-loaded purpose. The usage note and slug clarification are valuable with no redundant content.

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

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

For a simple zero-parameter list tool with no output schema, the description covers purpose, usage, and a relevant behavioral note. It lacks explicit return format, but this is manageable for such a straightforward operation.

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

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

There are zero parameters, so baseline is 4. The description adds no parameter-specific info, but none is needed.

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

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

The description clearly states 'List organizations you have access to' with a specific verb and resource. It distinguishes itself from other list tools by focusing on organizations and adding context about discovering orgs.

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

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

Explicitly states when to use: 'to discover available orgs or when a user needs to choose between multiple organizations.' It does not mention alternatives or when-not, but the guidance is clear and contextually relevant.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description goes beyond by specifying the returned fields (id, name, kind, status, nextRunDate, destination counts, lastRunHealth), confirming on-demand reports are included, and documenting the includeArchived default. It does not address pagination or permission requirements, but given the strong annotations this is sufficient.

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

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

The description is compact and front-loaded with the essential purpose, followed by a field list, filters, a short read-only note, and an example. Every sentence contributes; there is no filler.

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

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

For a list operation with no required parameters and no output schema, the description covers the return fields and filters. It does not mention pagination or potential size limits, but the tool's simplicity and the provided field list make it complete enough for an agent to use 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 input schema has 100% coverage with descriptions for all four parameters, so the baseline is 3. The description adds a concrete usage example ({ kind: 'SCHEDULED' }) and restates filter semantics, which slightly enhances the parameter understanding beyond the schema.

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

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

The description opens with a specific verb+resource: 'List compact report summaries.' It defines the output fields and states the scope ('for the organization'), clearly distinguishing it from sibling report-execution tools like get_report_execution, run_report_now, and update_report. It also clarifies inclusion of on-demand reports.

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 implicitly establishes when to use this tool (when you need a compact overview of reports) and lists available filters, but it does not explicitly mention when not to use it or point to alternatives (e.g., use get_report_execution for full details). The read-only hint is clear context.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false. The description adds that the catalog is remote and lists the returned fields, providing useful context beyond the annotations, though it doesn't cover other behaviors like pagination.

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

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

The description is compact, front-loads the primary purpose, and includes usage guidance and an example without any redundant filler. Every sentence earns its place.

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

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

For a simple zero-parameter read-only listing tool, the description fully covers what it does, when to use it, what it returns, and the relationship to get_skill. There are no significant gaps.

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

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

The tool has zero parameters, so schema coverage is trivially complete. The description includes an example invocation with {}, satisfying the baseline for the zero-param 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 uses a specific verb ('List') with a clear resource ('Costory MCP workflow skills') and enumerates the returned fields (skillId, name, description), making it distinct from the sibling get_skill tool.

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

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

The description explicitly states when to call this tool ('when you are unsure which skillId to load') and when to skip it in favor of get_skill ('If already known... call get_skill directly'), naming the alternative.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description goes beyond that by disclosing org-level scope and the composition of the returned data (per-type counts), which an agent cannot infer from the annotations alone. It stops short of describing pagination or whether empty orgs return an empty list.

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

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

Front-loaded with the core action and return shape, then the usage guidance. The enumeration of eight downstream tools is long but each entry earns its place by naming a real integration point; only minor trimming is 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?

There is no output schema, so the description usefully compensates by describing the return contents (tags with resource counts). Combined with a fully documented single parameter and read-only annotations, an agent has what it needs, though ordering and pagination behavior remain unstated.

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

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

Schema coverage is 100% and the single slug parameter is fully documented in the schema (including auto-detect behavior and the multi-org failure case). The description adds nothing about the parameter, so the baseline 3 applies.

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

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

Specific verb+resource ("List all tags in the organization") plus a precise statement of what each entry contains (counts of tagged dashboards, views, explorers, alerts). This clearly distinguishes it from siblings like delete_tag or the various list_* tools by stating both scope and payload.

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

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

Explicitly states when to call it ("discover available tag values before passing them to...") and enumerates the concrete downstream tools that consume tags (create_event, update_event, create_alert, update_dashboard, etc.). This is a textbook when-to-use routing instruction with named alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: it includes non-member teams, explains that 'role' is omitted when the caller isn't a member, and details how the returned 'id' and scope 'id'/'filterCel' should be used in other calls. This goes beyond the annotation basics.

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 moderately long but every sentence carries functional information: resource scope, field meanings, how to repurpose IDs, and usage triggers. It is front-loaded with the core purpose and organized logically, though it could be tightened by merging the scope/filterCel details into a more compact phrasing.

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?

Since there is no output schema, the description appropriately explains the return structure (id, visibility, role, scope id, filterCel) and how to consume those fields in other tools. It omits pagination or ordering, but those are not critical for a list operation, and the provided information is sufficient for correct invocation and interpretation.

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 input schema already documents both parameters fully (slug auto-detection behavior, and query as optional team-name search) with 100% coverage. The description reiterates the query filtering but adds no new parameter-level meaning. Per the rubric, high schema coverage yields a baseline of 3, which is appropriate 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?

The description states a precise verb and resource ('List all non-archived teams') and clearly distinguishes itself by noting it includes teams the user is not a member of, which sets it apart from other list_* tools. It also specifies the data returned per team, removing any ambiguity about what the tool outputs.

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 explicitly lists three concrete use cases: when the user asks about team costs, wants to filter by team scope, or needs a teamId for sharing dashboards/reports/budgets/alerts. It does not mention when not to use it or name alternative tools, though the listed scenarios are sufficiently specific to guide 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 mark this as read-only, and the description adds that it returns id, name, and email, lists up to 100 members by default, and filters by name/email. The extra note that sharing does not require sharing a team is useful behavioral context beyond the annotations.

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

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

Four focused sentences cover purpose, return fields, query behavior, and the downstream use of the returned id. Every sentence earns its place and no filler is present.

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

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

For a simple, read-only, zero-required-parameter tool with complete schema coverage, the description is complete. It explains results, filtering, limits, and how to use the output, so an agent has enough to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds the first-name/last-name/email detail and reinforces the omit-query behavior, but does not materially expand on the slug parameter beyond what the schema already says.

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

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

States the specific verb 'List' and resource 'organization members', plus the purpose of sharing dashboards/reports/budgets/alerts. Clearly distinguishes from siblings like list_teams and list_alerts by focusing on people rather than resources.

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

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

Provides clear when-to-use context: when you need a person's id to share something with them or to set object permissions. It explains the optional query behavior and the no-team-sharing prerequisite, though it does not explicitly name an alternative like list_teams for team-related queries.

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 indicate readOnlyHint=true and destructiveHint=false; the description adds substantial behavioral context: bqName is immutable and set once at creation, status semantics for drafts vs published VDIMs, and the exact return fields. It also specifies that virtualDimensionId equals id, which is a non-obvious data model behavior. No contradiction with annotations.

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

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

The description is long but every sentence is purposeful. It front-loads the core purpose, then explains field relationships, usage rules, and ends with a concrete example. There is no fluff or repetition of schema content; the structure is logical and scannable.

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 takes full responsibility for explaining return values, which it does explicitly (id, virtualDimensionId, name, bqName, description, status, computeStatus, tags, hasPendingDraft, draftValidation.ok). It also covers edge cases like draft vs published status, pagination behavior, and the bqName immutability pitfall. This is complete for an agent to invoke correctly.

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

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

The schema already covers all parameter descriptions at 100% (baseline 3). The description adds meaningful context beyond the schema, notably the immutability of bqName and the interpretation of status values (DRAFT vs COMPLETED). It also reiterates the limit cap of 100 and shows an example query, but does not deeply enhance every parameter; hence a 4 rather than 5.

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

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

The description opens with a specific verb+resource: 'List virtual dimensions (custom cost axes) in the organization.' It clearly differentiates from the 'get' sibling by stating 'Call this before get when the user refers to a VDIM by name rather than id.' The example further anchors the purpose.

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 explicit when-to-use guidance against the sibling 'get' tool. It also explains how to use query filters, status filters (DRAFT vs COMPLETED), pagination, and the critical rule to always use bqName (not name) for groupBy/filterCel. This is actionable direction beyond generic 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 flag this as read-only, and the description adds behavior well beyond that: it replays a condition, reports firing days/rows, applies dedup semantics per groupBy value, and describes the notification count computation. It also discloses the default lookback window and returns a sample of firing dates with state, giving the agent a clear model of what execution will do.

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

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

The description is front-loaded with the core purpose and is organized clearly: what it does, what it takes, what it returns, and when to use it. It is somewhat long and repeats dedup details that also appear in the schema, but the example and return-field listing earn their place for such a complex tool.

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

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

With no output schema, the description compensates by enumerating the return values (`firingDays`, `firingRows`, `notificationsCount`, sample dates with `state`), which is essential for the agent to interpret results. The schema handles parameter syntax fully, the annotations handle safety, and the description provides workflow context and a realistic invocation example. Nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining how parameters combine with a concrete example ('alert if 7-day AWS spend tops $50k') and by tying queries/condition/dedup to create_alert semantics. It also clarifies that dedup affects the returned notification counts, which is not explicit in the schema.

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

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

The description opens with a specific verb and resource ('Backtest a cost-alert condition') and explicitly distinguishes itself from create_alert by saying it runs BEFORE creation and needs no notification channel. This makes the tool's role unmistakable even among many sibling tools.

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

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

It explicitly says to use this to 'sanity-check a condition/threshold (and tune dedup) before calling create_alert,' naming the closely related sibling and the intended workflow. It also communicates that notification-channel setup is not needed here, reinforcing the boundary between previewing and creating.

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

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

Goes well beyond the annotations: 'read-only and in-memory', no persisted report, no Costory object mutation, no Slack/Teams/email delivery, and 'Returns a token-bounded, per-type result'. It also flags slower opt-in paths (display: "summary", enableAiInvestigation via async analysis_agent_run) and the deprecation of the `context` alias — disclosure an agent cannot get from the schema.

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

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

Front-loaded with the core claim and safety profile, then organized by concern (inheritance, hierarchy, thresholds, AI options) and closed with worked examples. It is long and some clauses restate schema descriptions, but for a five-variant discriminated-union payload the density is largely earned.

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-shape burden — and it does, listing per-type results (DIGEST resolvedPeriod/comparison totals/root nodes; TOP_FLOP bounded rows; GRAPH_SNAPSHOT series sample + explorerUrl; DASHBOARD_PDF/TEXT validity pointer). Combined with the inheritance and override rules, an agent can call this correctly without further context.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds cross-field semantics the schema cannot express cleanly: widgets omit matching fields to inherit from reportContext, never send both `context` and `reportContext`, and the DIGEST hierarchy rules plus threshold defaults (100/5%/20). Slight redundancy with the per-parameter schema text keeps it off 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?

Opens with a specific verb+resource+scope: 'Dry-run preview of ONE report widget', which immediately separates it from create_report (persist), preview_alert and query. The per-type return breakdown further pins down exactly what the tool produces for each widget type.

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?

States the lifecycle relationship explicitly: 'Pass the same reportContext + widget object you will later hand to create_report', which tells the agent this is the validation step before persistence. It also gives when-to-use guidance per widget type (DIGEST vs TOP_FLOP vs GRAPH_SNAPSHOT). It stops short of naming exclusion conditions such as when to skip preview and call create_report directly.

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 only the read-only safety profile, but the description adds substantial behavioral context beyond them: it operates on the latest pending draft when one exists (draftPersisted: true) and otherwise previews published rules in memory without creating a draft (draftPersisted: false, not publishable). It also clarifies both modes share the same time window and that datePreset/from-to are mutually exclusive.

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 mode behavior, and most sentences carry distinct information (draft persistence, rule targeting, return fields, currency). It is nonetheless very long and dense, with some overlapping restatement of from/to and costMetric between description and schema, 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?

With no output schema, the description carries the return-value burden and does so: it names totals.namedRulesSharePercent/totals.leftoverSharePercent, conditionCel, allocatesTo, howToRead, and breakdown's period/scope.explanation/topValues/dailyTotals. Combined with mode, targeting, and window semantics, an agent has what it needs to invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description meaningfully enriches semantics: ruleId is preferred over ruleIndex, how to target leftover via the leftoverRule id or ruleIndex: rules.length, the shared 0-based ordinal between position and ruleIndex, currency alignment with query, and the costMetric valid-id list. This is real added meaning over the schema.

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

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

States a specific verb (Preview) and resource (virtual dimension draft) with the two operating modes named explicitly ('per-rule costs or a groupBy breakdown (read-only BigQuery)'). An agent can distinguish this from update_virtual_dimension_draft and create_virtual_dimension_draft without opening any schema.

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

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

Explicitly says when to call ('After a successful create/update') and draws the line against alternatives: 'preview alone does not persist', routing to update_virtual_dimension_draft or create_virtual_dimension_draft to publish. Mode selection (costs vs breakdown) and how to discover valid groupBy values are also spelled out.

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

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

Annotations mark it destructive and non-read-only, and the description adds substantial context beyond them: a ~10 minute feature-engineering refresh, sibling labels not mentioned are preserved, duplicate sourceKeys and name collisions reject the whole array, delete-then-re-add is permitted in either order, and an auth/route constraint (admin-only, Clerk-only writes). This is far more than the annotations 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 and the dryRun-first workflow are front-loaded, and given the merge/collision/ordering complexity few sentences are wasted. It is a dense single paragraph rather than a structured list, which makes the many constraints harder to scan, 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?

Despite no output schema, the description covers what dryRun returns (the full next labels document, preview only) versus what the real write does, plus ordering, collision, and auth constraints. An agent has everything needed to construct a correct call for this high-risk mutation.

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 baseline is 3, but the description adds array-level semantics the schema cannot express: ids are generated for add, update/delete target an id from list_label_dimensions or an earlier add in the same array, default name is a sanitized sourceKeys[0], and moving a key with update on the owner in the same array. It largely restates but usefully frames the per-item fields in operation terms.

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 and resource: 'Merge add/update/delete operations onto published label dimensions, then replace the stored document.' It immediately distinguishes itself from read-only siblings (list_label_dimensions, list_label_dimension_usages) and from the virtual-dimension publish path, so an agent can route correctly 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?

Explicit when-to-use and when-not-to: dryRun defaults true for preview, persist once with dryRun:false and confirm:true, check list_label_dimension_usages before rename/delete, demo orgs are read-only, dimensionsAdminOnly requires an org admin, and real writes happen through Clerk MCP only (the service route is dry-run only). It also warns not to call publish twice.

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 destructiveHint; description adds substantial beyond that — rejects invalid drafts with draftValidation errors, deletes the pending draft version, does not wait for refresh job, discloses computeStatus semantics (REFRESHING async vs TO_REFRESH on queue failure), bqName immutability, and Clerk MCP only restriction. No contradiction with 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?

Dense but front-loaded and organized: action → prerequisite → error semantics → return fields → follow-up. Some long run-on clauses about computeStatus and bqName could be tightened, but every sentence carries operational value.

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

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

Complete for a mutation tool that both deletes a draft and triggers async work. Covers prerequisites, error path, async polling, immutable identifier for downstream query, and environment restriction (Clerk MCP only). No output schema exists, and the description appropriately describes return fields.

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 3. Description adds meaning: virtualDimensionId equals id from list/get/search, and success returns bqName used for query groupBy/filterCel, with example showing virtualDimensionId sourced from create/list.

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 multi-step action: validate persisted draft, promote to published, kick off BigQuery refresh. Distinguishes from siblings by naming update_virtual_dimension_draft, create_virtual_dimension_draft, and preview_virtual_dimension_draft as prerequisites/alternatives.

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: requires a pending draft row; tells agent to call update/create draft first, and that preview alone does not create a draft. Also gives post-publish polling guidance (poll get/list until COMPLETED) and retry guidance on TO_REFRESH.

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

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

Annotations only declare readOnlyHint/openWorldHint/destructiveHint, so the description carries the real behavioral burden and does so richly: limit defaults to 100 groups and must be raised for long tails, the response includes resolved period dates, computeStatus must be polled until COMPLETED, and BigQuery/S3/Snowflake conditions reject separators, comments, and unbalanced quotes. These are concrete operational traits not present 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?

Strongly front-loaded: the minimum valid call and naming convention precede the long provider-specific detail, and worked examples follow. However, the prose duplicates a substantial amount of the externalMetric provider detail already present in the schema, making it very long. It is well-organized but not maximally economical.

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 11-parameter tool with nested oneOf query variants and no output schema, the description covers the naming contract, every query type, period/comparison semantics, dimension discovery, and the budget-ID pitfall. It even notes what the response contains (resolved period dates) and suggests follow-up tools. 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 description coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: it warns that budgetId must be the budget version ID despite the field name, distinguishes groupBy (SPLIT) from filterCel (SCOPE), explains rollingAggregation for running totals, and clarifies unitOverride/currency behavior. Some overlap with the schema remains, keeping it from 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?

Opens with 'Unified query tool for cost data, custom metrics, usage metrics, external (live integration) metrics, period comparisons, formulas, and budgets' — a specific verb (query) plus an exhaustive enumeration of resources. It also leads with a MINIMUM VALID CALL block, so an agent knows both what the tool does and the smallest valid invocation. It is clearly distinguishable from siblings like get_dashboard_widget_data or list_metrics.

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 routing rules: call suggest_usage_metrics before usage queries, use list_metrics with includeExternal: true to discover external metric fields, call search with type: ['dimensions'] before guessing CEL names, and call get to obtain budgetVersionId. It states when to prefer saved { type: 'metric' } over externalMetric and names exclusions (analyze.changePoint incompatible with compare, datePreset mutually exclusive with from/to).

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

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

The description discloses that the operation has a side effect, is a 'DANGER ZONE', and should only be used after confirmation. This adds meaningful behavioral context beyond the annotations (readOnlyHint=false, destructiveHint=false). It also clarifies the scope ('one failed delivery only'), which is not apparent from the schema. No contradiction with annotations.

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

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

The description is extremely concise, with a clear front-loaded warning ('Side effect', 'DANGER ZONE') followed by actionable instructions. All sentences earn their place, and there is no redundancy or filler.

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

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

The description is complete for a side-effectful tool: it states the trigger condition, the required preliminary step, and the need for user confirmation. It does not describe the return value, but no output schema exists and the description does not need to. Slight gap: it does not mention what happens on success or failure, but the core context is sufficiently covered.

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 input schema already provides full descriptions for both parameters (slug and executionId), so schema description coverage is 100%. The description does not add further parameter-level detail, but the schema suffices. Baseline score 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 description clearly states the tool's function: it retries one failed delivery only. This specifies the verb (retry), the resource (failed delivery), and the scope (one only), distinguishing it from sibling tools like run_report_now or transfer_report_execution. The purpose is unambiguous.

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

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

The description provides explicit when-to-use guidance ('Use after partial failure') and a required precondition (state the failed execution and its destination from get_report_execution, then ask the user to confirm). It does not explicitly name alternatives, but the instructions are clear enough for safe invocation. Slight deduction for lacking explicit when-not-to-use alternatives.

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

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

The description goes beyond the annotations (readOnlyHint=false, destructiveHint=false) by disclosing the real side effect of sending messages and labeling it a 'DANGER ZONE.' It also reveals the return behavior (canonical execution URLs and statuses) and the need for user confirmation. No contradiction with annotations exists; the description adds crucial 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?

The description is highly concise with three purposeful sentences: it states the core side effect, the safety step, and the return value/exclusion. There is zero filler and the 'DANGER ZONE' warning is front-loaded for immediate visibility.

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?

Despite having no output schema, the description clearly states what is returned (canonical execution URLs and statuses) and covers prerequisites, confirmation, and exclusions. For a two-parameter tool with no nested objects, this is complete and actionable for an agent.

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 input schema already provides 100% description coverage for all parameters (slug and reportId), so the baseline is 3. The description does not add extra parameter-level semantics beyond the schema; it focuses on usage context rather than parameter syntax.

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 explicitly states the tool 'sends real messages now to every configured destination,' which clearly identifies the action (sends) and resource (report destinations). It distinguishes itself from siblings by noting 'Never use this to recover only failed destinations,' pointing to retry_report_execution as an alternative.

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 explicit when-to-use and when-not-to-use guidance: it instructs to 'show the report name and complete destination list from get, then ask the user to confirm before calling' and explicitly warns against using it to recover only failed destinations. This gives clear operational context and an implicit alternative (retry_report_execution).

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/safe, but the description adds substantial behavior beyond them: non-imported keys are invisible in results, keyword queries filter to matching values, each dashboard carries a conditionsCel string usable to decide extendDashboardConditions, virtual-dimension hits expose bqName as immutable, and budget results expose only id/name/year, requiring get for budgetVersionId.

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

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

Front-loads the core purpose and then organizes guidance into scoping, filtering, return shapes, and follow-ups. It is long (~300 words) and the entity list is restated once with camelCase result keys, but that restatement doubles as return-shape documentation for a tool with no output schema, so most sentences earn their place.

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

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

For a 5-param, no-output-schema tool spanning seven entity types, the description covers return shapes per bucket, special-case fields (conditionsCel, bqName, budgetVersionId), and the full follow-up chain. An agent has everything needed to call it and act on 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?

Schema coverage is 100%, so baseline is 3, but the description adds real semantics: query+"type: [\"dimensions\"]" returns the full field catalog, empty query semantics, and the IMPORTANT guidance to use short terms rather than full phrases. It does not mention from/to/slug, so it stops short of a 5.

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

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

Opens with a specific verb+resource ("Unified search across your entire Costory workspace") and enumerates every entity bucket it spans. It clearly distinguishes itself from siblings by explicitly routing non-imported keys to list_dimension_candidates and full-detail fetches to get.

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 ("PRIMARY tool for discovering CEL field names", "when a user mentions a product, team, project, or service name"), named alternatives (list_dimension_candidates), and step-by-step follow-up routing (get for dashboards/budgets/reports, query for dimension values, update_dashboard with the dashboards id). Nothing 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 mark this as read-only and non-destructive; the description adds substantial context beyond that: parallel search behavior, Mintlify as source of truth, KB as complementary, conflict-resolution priority, return format specifics, and the critical instruction to use the full URL verbatim when citing. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place: purpose, synthesis rule, return structure, limit nuance, alternative tool, citation guidance, and examples. It is well-organized, front-loaded with the core behavior, and uses examples to clarify usage without unnecessary filler.

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

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

There is no output schema, so the description appropriately explains return values: Mintlify matches with titles, snippets, and full URLs, and KB articles with title, summary, and markdown. It also covers the limit behavior, conflict resolution, and citation format. For a search tool with this level of nuance, nothing essential is missing.

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

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

Schema coverage is 100%, so query and limit are documented. The description enhances this by clarifying that the limit applies only to KB results (not Mintlify matches) and by providing concrete query examples. This adds meaning beyond the schema's generic descriptions, though the schema already carries most of the parameter burden.

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

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

Description uses specific verb 'Search' with clear resources: Costory product docs (Mintlify) and knowledge base. It states the search runs in parallel and describes the output, distinguishing it from the sibling get_documentation_page by explicitly naming it for full-page retrieval. This gives an agent a precise understanding of what the tool does.

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

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

Provides explicit guidance: use get_documentation_page for a full Mintlify page, includes query-to-parameter examples, and explains how to handle conflicts between sources. It lacks a broader comparison to other search-like siblings (e.g., search, query), but the key alternatives are addressed and the intended context is clear.

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

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

Annotations already declare destructiveHint=true, and the description reinforces and enriches this: omitted principals lose access, empty grants[] is invalid, every replacement must retain at least one Admin grant, and new objects start as creator-only Admin. It also documents role restrictions (ORGANIZATION never Admin, CLERK_ADMIN org-admin only).

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 operation, then rules, then two worked examples. Dense but almost every sentence carries a constraint or routing instruction; slightly long, with some rules that 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 destructive mutation with no output schema, the description covers prerequisites, replacement semantics, role validity, and a full workflow, plus examples. It does not describe the response or error behavior on invalid input, which is the only notable gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic constraints the schema cannot express: ORGANIZATION may only be Reader/Editor, CLERK_ADMIN applies only to Clerk org admins and means No access when omitted, and resourceKind maps to the four object types. It stops short of explaining the slug parameter, which the schema covers.

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 ('Replace the full grant list on a dashboard, report, budget, or cost alert') and enumerates the four supported resource kinds. It is immediately distinguishable from the sibling get_object_permissions, which reads rather than replaces.

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 to call get_object_permissions first and send the full list including retained grants, tells the agent not to use PRIVATE/PUBLIC or teamId on create/update tools, and routes people/teams resolution to list_users and list_teams. When-to-use and prerequisites are fully covered.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context by showing how the input flags (hasEvents, hasDiff) affect the suggestions, using examples. It also implies that the tool is context-dependent, which is beyond the annotations.

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

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

The description is appropriately concise and well-structured. The first sentence states the purpose, the second gives usage timing, and examples are presented in a clear bullet list. Every sentence contributes information without redundancy.

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

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

Given the simple tool with two boolean parameters and no output schema, the description covers purpose, usage timing, and parameter semantics. A minor gap is that it does not explicitly describe the return format (e.g., list of action objects), but the examples and phrase 'present follow-up options' make it sufficiently clear. Overall, it is complete enough for an agent to invoke correctly.

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

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

The schema description coverage is 100%, giving baseline 3. The description adds semantic value by providing concrete example parameter combinations (e.g., { hasEvents: false, hasDiff: false } for standard post-query, { hasEvents: true, hasDiff: true } for events+difference), which clarifies how the flags map to real investigation flows.

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

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

The description clearly states the tool 'Suggests interesting actions the user can perform next' with specific examples (save a view, set up an alert, share to Slack, drill down, compare periods). It also distinguishes itself from siblings like suggest_groupby and suggest_usage_metrics by focusing on follow-up actions rather than metrics or group-by suggestions.

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 explicit when-to-use guidance: 'Call this after investigation flows (after query or get) to present follow-up options to the user.' It gives concrete usage scenarios with the parameter examples, but does not explicitly mention when not to use it or contrast with alternatives, so it falls short of a 5.

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

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

The annotations already cover read-only and non-destructive behavior. The description adds meaningful behavioral context: return shape ({ column } or { column, contains } plus metrics), a 'do not invent columns' constraint, clarification that an omitted filter is unfiltered and not AWS-only, and support for == null on unlabelled dimension values. This is substantial beyond the structured fields.

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

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

The description is long but dense and front-loaded with the core purpose and usage trigger. It earns most of its length with concrete examples and downstream routing, but some compare/filterCel guidance is duplicated from the schema descriptions and 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 tool with six parameters, one nested object, and no output schema, the description is remarkably complete: it covers parameter selection, return shape, filter semantics, examples, and how the result feeds into find_cost_change_factors. An agent has enough context to call it correctly without further inference.

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 high at 83%, but the description still adds value beyond it: it explains when to pass compare, what {} auto-derives, why to prefer datePreset over from/to, and what filterCel null/unfiltered means. The examples further clarify realistic parameter combinations, especially the CEL syntax for service filtering.

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: 'Suggest the best dimensions to group costs by.' It distinguishes itself from siblings by explicitly tying its output to query and find_cost_change_factors, and by framing the tool as the one to call when the user asks 'what should I look at?'.

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 explicit trigger conditions: 'Call this when the user asks "what should I look at?" or when you need columns for query or find_cost_change_factors.' It also provides conditional guidance for compare, datePreset vs from/to, and downstream use, so an agent knows exactly when and how to invoke it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool is known to be safe. The description adds behavioral context: the warning that broad queries return unhelpful results and the detail that filterCel supports == null for unlabelled dimension values, which goes beyond the schema.

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

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

The description is compact: two sentences plus an example. It is front-loaded with the core purpose, followed by usage guidance and a clarifying example. No wasted words.

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

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

The tool has no output schema, but the description covers what it does, when to use it, and includes an example. It does not detail the return format, but for a suggestion tool with no output schema this is acceptable. The annotations and sibling context provide enough completeness.

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%, but the description adds meaningful value by providing an example filterCel value ("cos_provider in [\"GCP\"]") and explaining the == null syntax for unlabelled dimension values. This enriches the parameter semantics beyond the schema alone.

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 'Suggest' and resource 'usage metric units' with concrete examples (k8s_cpu_hours, network_bytes_out) to analyze in the current billing context. It clearly differentiates from sibling tools like suggest_actions or suggest_groupby by focusing on metric units in billing context.

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 explicitly states when to use ('Only use when a specific filterCel scope is provided') and warns against broad queries ('broad queries will return unhelpful results'). It does not name alternatives, but the condition is clear and actionable, with an example.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description explicitly states 'Side effect: sends real messages now' and includes a DANGER ZONE warning to list and confirm destinations. This adds crucial behavioral context about real-world impact and safety, going 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 description is extremely concise and front-loaded, leading with the side-effect warning, then the core action, destination format, and a clear safety directive. Every sentence contributes operational value without waste.

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

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

Given the tool's mutation nature and no output schema, the description is complete: it covers the action, side effect, destination format, a necessary prerequisite (list_available_destinations), and a mandatory user confirmation step. It leaves no significant gaps for safe 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?

The schema already has 100% coverage with detailed descriptions for all parameters. The description adds complementary value by noting the destination shape matches create_report and that channel ids must be resolved via list_available_destinations, reinforcing the schema's explainer and providing cross-tool guidance.

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

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

The description clearly states the tool's function: 'Re-delivers an already-rendered successful execution without recomputing widgets.' This is a specific verb+resource pair that distinguishes it from sibling tools like retry_report_execution or run_report_now. The mention of 'sends real messages' also clarifies the real-world side effect, leaving no ambiguity about its purpose.

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 solid usage context: it is for re-delivering successful executions, references the destination shape from create_report, and instructs resolving channel ids via list_available_destinations. However, it does not explicitly mention alternatives or when not to use it, so it falls short of a 5.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, but the description adds genuinely non-obvious behavior: `tagIds` replaces the whole list (`[]` clears), `scopeId` cannot be sent alone and null clears it, `aggBy` must never be sent because stored grain is always Day, and a legacy alert edit can succeed while emitting a `warning` about per-firing notifications.

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 long, but appropriately so for a 16-parameter destructive mutation tool. It is front-loaded with purpose and the alertId lookup, then rules, then four concrete call examples — only mild redundancy with the schema's own field descriptions prevents a 5.

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

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

For a complex, destructive, annotation-covered mutation with no output schema, the description closes the gaps an agent needs: how to source alertId, which sibling handles sharing, group-atomicity rules, the Day grain constraint, and the `warning` that can appear in 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?

Schema coverage is 100% so the baseline is 3, but the description adds cross-field rules the schema cannot express: the wholesale-group rule for queries+period, the omit-vs-null distinction for scopeId, the ban on `aggBy`, and that `condition` references query `name`s. Some prose (e.g. tagIds, condition examples) duplicates the schema text, so it is not fully additive, but the field-interaction guidance is valuable.

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

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

Opens with a specific verb+resource ("Update an existing cost alert") and immediately routes the agent on how to obtain the required alertId (search / list_alerts / get / create_alert). This clearly separates it from sibling create_alert, list_alerts, and get without the agent opening any schema.

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

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

Explicitly states the omit-to-keep default semantics, which edits need no other fields, that Explorer and notification-destination are wholesale groups requiring a full write from scratch, and that the stored `queries` from get are not valid input. It also names the correct alternative for sharing (get_object_permissions then set_object_permissions) and warns about the legacy-threshold `warning` requiring `dedup`.

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

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

Annotations already declare destructiveHint=true, and the description reinforces that with concrete destructive semantics (remove deletes a widget, tags replaces the full list, [] clears, empty description clears). It also adds non-annotation behavior: atomic operation application, the 'at least one field required' constraint (not in schema), and 'Returns a URL — you MUST include it in your response'. It does not cover auth/permission requirements, which tempers the score.

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

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

Purpose and required-field guidance are reasonably front-loaded, but the body is a single dense paragraph of ~300 words mixing invocation rules, inheritance logic, and widget guidance. Most sentences earn their place, yet the lack of structure makes a complex spec 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?

For a heavily nested 8-parameter mutation tool with no output schema, the description covers invocation, inheritance/override semantics, destructive side effects, the response URL obligation, and cross-references (get_skill, search, permissions siblings). Nothing an agent needs to call it 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?

Schema description coverage is 100%, so the baseline is 3. The description still adds real meaning beyond the schema: inheritance rules for dashboardContext vs widget queries, the deprecated `context` alias and 'never send both', budget groupBy being explicit rather than inherited, and extendDashboardConditions opt-out 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?

Opens with a specific verb+resource and enumerates the mutable fields ('Update an existing dashboard's name, description, shared dashboardContext, widgets, and/or tags'). This clearly distinguishes it from siblings (create_dashboard, update_report, update_alert) without needing to name 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?

Explicitly routes the agent: 'Call get_skill with skillId: "dashboards" first', 'Look up the dashboard id via search', and names a when-NOT with a concrete alternative ('Sharing is not an update_dashboard field — use get_object_permissions / set_object_permissions'). It also states the minimum required combination of fields, so the agent knows how to invoke it correctly.

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

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

Annotations only declare destructiveHint=true and readOnlyHint=false; the description goes far beyond that by disclosing overwrite semantics per field, merge-vs-replace behavior (metadata merged, tags replace the full list, source preserved), omission meaning 'keep stored value', and the wholesale-replacement nature of the widget. This is exactly the extra behavioral context a mutation tool needs.

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

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

Purpose and write-vs-preview caveat are front-loaded, and the worked examples make intent concrete. It is long, though justified by 12 parameters and nested objects, with some overlap between the top-level scopeId precedence sentence and the later widget/scopeId discussion that could be consolidated.

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 complex 12-parameter mutation tool with a nested widget object and no output schema, the description covers defaults, replacement vs merge semantics, precedence rules, and cross-tool lookups (list_events, list_teams). Nothing an agent needs to call it correctly is missing.

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

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

Although schema coverage is 100% (baseline 3), the description adds semantics the schema does not: scopeId precedence over widget.scopeId, null-clears vs id-replaces behavior, the full-replacement requirement for widget including mandatory chartType on every series, and the requirement to pass widgetEventId for multi-chart events. These rules materially change how an agent fills the fields.

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 ('Persist changes to an existing cost-chart annotation event'), and immediately disambiguates from siblings by declaring it is a write, not a preview, and does not create a new event (create_event), send notifications, or archive/delete (archive_object). An agent can route to it correctly without opening a schema.

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

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

Explicitly names prerequisites ('Use list_events to find the event id first') and enumerates when-not conditions: it does not create events, does not notify Slack/Teams/email, and does not archive or delete. It also names list_teams as the source of scope ids, giving concrete routing context.

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

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

Goes well beyond the destructiveHint/openWorldHint annotations: declares replace-vs-preserve semantics for tagIds, destinations, widgets, that omitted fields are preserved, that empty conditionsCel clears the filter, that schedule.mode NOW sends immediately, that archived restore is forbidden in MCP, and that a singular `widget` key is silently ignored. This is exactly the behavioral context a destructive mutation tool needs.

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

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

Front-loads the verb and resource, then prerequisites, then the DANGER ZONE, then worked examples at the end. It is dense and some sentences run together, but for an 11-parameter destructive patch tool nearly every clause earns its place.

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

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

For a destructive mutation with nested widget/destination objects and no output schema, the description covers mutation semantics, safety/confirmation flow, deprecations, and example payloads. An agent has what it needs to call it correctly without opening the 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 already 100%, yet the description adds meaning the schema doesn't carry: reportContext as a partial patch (omit to keep, empty conditionsCel clears), tagIds replaces the full list with color default #6366F1 and auto-creation, destinations must be non-empty, widgets replace wholesale with type inside each widget, and the legacy `context` alias must never be co-sent. Genuine value beyond structured fields.

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 ("Apply declarative partial changes to one non-archived report") and scopes it (non-archived). It is immediately distinguishable from create_report, archive_report, and update_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?

Explicitly names the prerequisite (call get_skill with skillId: "reports" before changing DIGEST/schedule/destinations/reportContext) and gives conditional routing (DANGER ZONE operations require user confirmation, pure pause + metadata edits apply immediately). It also names supporting reads like list_tags and list_teams, leaving little to inference.

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