Cloud FinOps Skill & MCP

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

Annotations already declare readOnlyHint/idempotentHint/closed-world, so the safety profile is covered; the description goes further with a genuinely load-bearing constraint — "This connector has no access to the user's accounts" — which prevents the agent from promising live inspection. It also discloses the AND-combination of filters, case-insensitive exact string matching, the return envelope, and that a zero-match result carries hint and valid_values so a typo is distinguishable from a coverage 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?

Front-loaded and well organized: purpose, then usage triggers, then filter semantics, then return shape. It is longer than needed — the example-questions list and the "patterns covered" inventory partially overlap, since the categories and services are already enumerated under Args, and the closing Returns paragraph repeats information that the output schema already encodes.

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-optional-filter search tool with a 0%-covered schema, everything an agent needs is present: valid values for every parameter, AND semantics, matching rules, the response envelope, and the empty-result contract. The output schema exists, so the brief return-value note is sufficient rather than redundant padding.

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

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

Schema coverage is 0% and the schema is bare nullable strings with no enums, so the description carries the entire burden — and does: scope enumerates aws/azure/gcp/cross-cloud, waste_category lists all eight canonical values, service is flagged as exact-match with a quoted example, and confidence explains the semantics of each tier (one signal vs two vs human review). Without this text the parameters would be unusable.

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

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

Opens with a specific verb and resource ("Finds runbooks") plus the filterable dimensions (provider, service, waste category, detection confidence), which is exactly what separates it from list_playbooks (unfiltered enumeration) and get_playbook (single fetch). The added note that each runbook contains a detection query the user runs in their own account pins down what the returned resource actually is.

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 rich when-to-use guidance, including five concrete user utterances ("why is our NAT bill so high", "which of our RIs are about to expire") and the general rule "anything that names a provider, a waste category, or how confident the detection needs to be." It never names a sibling as the alternative for the adjacent case (e.g. use list_playbooks to browse everything, get_playbook to fetch one by id), so the routing is inferable rather than explicit.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so safety is covered; the description adds genuinely non-obvious behavior: optional filters combine with AND, string matching is case-insensitive and exact rather than substring, and a zero-match query returns `hint` and `valid_values` so a typo is distinguishable from a coverage gap. It also explains why `persona_primary_only` exists (broad personas like Engineering collaborate on nearly every file). Minor deduction because the stated return shape largely restates the existing output schema.

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

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

Front-loaded with purpose, then usage triggers, then matching semantics, then per-parameter detail, then return shape — a logical order for an agent reading top-down. The five worked call examples are efficient illustrations, though the Args section slightly duplicates the schema property names and the return-shape sentence could be trimmed given the output schema.

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

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

For a six-parameter, all-optional filter tool with an output schema, everything an agent needs is present: which facet values are legal, how filters combine, how strings are matched, how to disambiguate the one non-obvious boolean, and what an empty result looks like. No open questions remain before calling it.

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

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

Schema description coverage is 0%, so the description carries the full burden and does: each of the six parameters is defined with accepted vocabulary (phase = Inform/Optimize/Operate, maturity = Crawl/Walk/Run, sample domain strings) and match targets (capability hits both fcp_capability and fcp_capabilities_secondary; persona hits primary and collaborating). The `persona_primary_only` semantics are spelled out precisely, including the default-vs-strict contrast.

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

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

Opens with a specific verb and resource ("Find which guidance serves a FinOps question") and enumerates the question space it covers (commit, size, allocate, charge back, forecast, govern). The closing contrast — "only the references that serve it, instead of scanning the full list" — separates it from list_references and get_reference without the agent needing to open those schemas.

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

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

Gives concrete trigger utterances ("how should we size Savings Plans", "what does a Crawl-stage org tackle first") plus the general rule that the question maps to a FinOps Framework facet. It explicitly routes away from the sibling bulk-listing behavior by stating this returns only matching references rather than the full list.

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 say read-only, idempotent and open-world; the description adds the daily rebuild cadence, the six-hour cache and the resulting 'source'/'cache_age_seconds' fields, plus both failure shapes (unknown slug with suggestions, other errors with fallback). That is real behavior an agent cannot get from the annotations.

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

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

Front-loaded with the purpose and use case, then Args/Returns/errors in a clean order. Slightly long — the parenthetical catalogue example is repeated and the figure-category list could be tighter — but every section adds 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?

Covers the one parameter, the return document's fields and units (discounts as fractions, keys naming medians/ranges/counts), snapshot dating, cache semantics, and both error branches. Nothing needed to call it or interpret the result is missing, even though an output schema exists.

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

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

Schema coverage is 0% and the schema only declares a bare string, so the description carries the full burden: it specifies the slug format (lowercase letters, digits, hyphens), lists the currently valid slugs, and documents the error payload returned for an unknown slug.

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 ('Get the current value of a figure a reference quotes with a date') and makes the live-vs-dated distinction explicit, which separates it from the sibling reference and playbook lookup 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?

Gives a concrete trigger condition (a reference quotes a figure like 'measured on the 2026-10-25 OptimToken catalogue' and the answer needs the current value), enumerates the kinds of figures covered, and states what to do when the call fails (keep the dated figure with its date).

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

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

Annotations already declare this as a read-only, idempotent, non-destructive, closed-world read, so the safety profile is covered; the description adds genuinely new behavior. It discloses that the connector has no access to the user's cloud accounts and that runbooks merely supply a detection query the user runs themselves, which is a critical expectation-setting detail. It also documents the success payload shape, the miss behavior with up to three string-distance suggestions for self-correction, and the optional MCP Apps rendering path.

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

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

It is front-loaded with purpose and usage before the Args/Returns blocks, so an agent can decide quickly. The Args and Returns sections duplicate some information already conveyed by the schema and output schema, and the MCP Apps rendering note is marginally useful, but nothing is genuinely wasteful.

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

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

For a one-parameter read tool, the description covers purpose, selection criteria, parameter format and provenance, success payload, failure payload with recovery hints, and the no-account-access constraint. Despite an output schema existing, the explicit miss-with-suggestions behavior is worth stating and closes the only real ambiguity an agent would face.

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

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

Schema description coverage is 0%, so the description carries the full burden for the single required parameter, and it does: it defines the argument as a playbook slug sourced from list_playbooks and supplies three concrete example values across AWS, Azure, and cross-cloud patterns. That is more meaning than the bare string type 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 names a specific verb ("Fetch") and a precisely scoped resource ("the step-by-step runbook for one specific waste pattern") and enumerates the contents: symptoms, detection queries, the fix, and the anti-pattern. It is clearly distinguishable from siblings like list_playbooks and find_playbooks, which operate on collections rather than a single named runbook.

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 states exactly when to reach for this tool: the user asks how to detect, confirm, or fix one specific named waste pattern, with concrete examples (zombie NAT gateway, snapshot sprawl, idle SageMaker endpoint). It also covers the ambiguous case of "which of my X..." questions and implicitly routes slug discovery to list_playbooks, leaving little to infer.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description reasonably spends its budget elsewhere: it discloses exact return shapes for both modes, the title-prefixing of section content, the "other_matching_sections" case, and the distinct error shapes on a miss. The failure behavior (suggestions vs. available_sections, never silently returning the whole file) is the kind of context annotations cannot carry.

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

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

Front-loaded with purpose, then usage, then parameters, then return shapes — a logical escalation with no filler sentences. It runs long and the "Args:" block partially restates schema property names, which keeps it just short of 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?

Despite the existence of an output schema, the description explains branch-dependent return shapes and error recovery, which the agent needs to plan a retry strategy. For a two-parameter read tool with sibling routing, nothing material is missing.

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

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

Schema coverage is 0%, so the description must compensate, and it does: `name` is tied to list_references output with example values, and `section` is fully specified as case-insensitive, partially matched, trailing-count-insensitive, with worked examples ("storage" matching "Storage Optimization Patterns (28)"). This is meaning well beyond the bare string type in the schema.

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

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

States a specific verb and resource ("Fetch the guidance on one FinOps topic") plus the scope of what is returned ("billing mechanics, decision rules and worked examples"), and separates itself from list_references/find_references by naming them as the discovery step. An agent can distinguish this from every sibling without opening a schema.

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

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

Gives an explicit trigger ("after list_references or find_references told you which one serves the question") and an explicit condition for the section variant ("when the question is narrower than the file"), including a concrete example of storage lifecycle in finops-azure-patterns. It also carves out advisory question types where this tool beats a summary.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuine context beyond that: entry size (~90-170 lines), the exact response envelope `{"playbooks": [...], "total": N}`, and the purpose of `approx_tokens` as a pre-fetch budgeting hint. It doesn't mention catalogue scale or pagination, but since all results appear to be returned in one listing, little is missing.

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

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

Front-loaded with purpose, then the alternative, then the return shape — a logical order for an agent. The waste-pattern enumeration in the first sentence is somewhat long but earns its place by letting the agent judge coverage; minor redundancy between 'scope (aws/azure/gcp/cross-cloud)' and the provider list above.

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

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

For a zero-parameter, read-only catalogue tool with annotations and an output schema, this is complete: it covers what it returns, the field semantics, the sibling split, and the token-budgeting use of approx_tokens. An agent can call it and interpret results without further information.

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

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

With zero parameters the baseline is 4; the description correctly signals the tool is unfiltered and redirects filtering intent to find_playbooks rather than implying hidden parameters. It also documents the meaning of each returned field, which goes beyond the input schema's obligations.

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 ('See every ready-made runbook for finding and fixing cloud waste') and enumerates the waste patterns and providers covered, which distinguishes it from the sibling catalog tools (list_references, find_references) and from the retrieval tools (get_playbook).

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 states explicitly when to use this (broad discovery of what runbooks exist) and names `find_playbooks` as the alternative with the exact trigger condition: 'When the question already names a provider, waste category, or confidence tier'. That is a full use/don't-use rule with the sibling named.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed-world scope, so the safety profile is covered. The description adds genuinely new behavioral context: approximate per-file size (2,000-15,000 tokens) and the fact that get_reference(name, section=...) fetches just one section of a large file, which is real cost-planning information. It is slightly redundant in spelling out the return shape given an output schema exists.

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

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

Three short paragraphs, front-loaded with purpose, then routing, then return shape and cost guidance — well ordered and easy to scan. The detailed field enumeration overlaps with the output schema and could be trimmed without loss.

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

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

For a zero-parameter, read-only browse tool this covers everything an agent needs: what is listed, when to prefer find_references, what comes back, and how big the payloads are before fetching. Nothing material is missing.

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

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

The tool takes zero parameters, so the baseline is 4 and nothing needs compensating for. The description instead documents the shape of the returned entries (name, title, description, fcp_* facets, approx_tokens), which helps an agent interpret results even though it is not strictly 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 opens with a specific verb-plus-resource ('See what FinOps guidance is available') and enumerates the actual coverage areas (billing mechanics, commitment strategy, allocation/chargeback, AI cost, per-provider handbooks). It also names the sibling it is NOT (find_references), so an agent can distinguish the two 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: 'Use this to discover what the library covers.' Explicit alternative and its selection condition: when the question already names a domain, phase, persona or maturity, find_references returns only matches. This is a clean routing rule with no inference required.

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