Cloud FinOps Skill & MCP

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new behavior: filters combine with AND, string matching is case-insensitive and exact, and a no-match query returns hint/valid_values so a typo is distinguishable from a coverage gap. It does not discuss rate limits or result size, which is the only shortfall.

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 argument semantics, then return shape — a sensible order. The battery of example questions is long, but each maps to a filter dimension and earns its place as disambiguation; only marginal 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?

For a four-filter lookup tool with annotations covering safety, the description covers purpose, routing, filter semantics, enum values, matching rules, and even the no-match return behavior. Although an output schema exists, the description supplements it usefully with the hint/valid_values edge case rather than redundantly restating 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 description coverage is 0%, so the description carries the full burden — and it does: it enumerates all four scope values, all eight waste_category values, the three confidence tiers with their signal requirements, and specifies exact-match semantics for service with an example. This is materially more than the bare 'string' schema types.

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 ('finds') and resource ('runbook for a cloud waste pattern') plus the filter dimensions that define the lookup. The filter-based semantics clearly separate it from list_playbooks (unfiltered enumeration) and get_playbook (single fetch by identifier), so an agent can route without opening the schema.

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

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

Explicitly frames when to use it ('before answering a specific waste or cost-fix question') and supplies a long list of concrete triggering questions, including the insight that it also answers questions about the user's own resources. The condition for each filter is spelled out, 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.

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

Beyond annotations, it discloses AND semantics across filters, case-insensitive exact string matching, persona_primary_only behavior, and the return shape including a no-match hint/valid_values. This is substantial behavioral context not available in structured data.

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

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

The description is front-loaded with purpose and usage, then moves to filter semantics, examples, args, and return shape. Despite its length, every section carries needed information for a 6-parameter search tool and the examples are illustrative 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?

Given the schema has no property descriptions and no enums, the description covers all call-relevant details: optionality, AND combination, string-matching behavior, field matching semantics, return object, and the no-match hint. The presence of an output schema further reduces the burden, so nothing needed 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?

With 0% schema description coverage, the description fully compensates: it documents each of the six parameters, gives examples for four of them, explains matching semantics, and even clarifies the nuanced persona_primary_only behavior. This is far beyond the bare 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?

Description states a specific verb and resource: 'Find which guidance serves a FinOps question' and returns references filtered by FinOps facets. It differentiates from list_references with 'instead of scanning the full list', but it does not explicitly contrast with the sibling find_playbooks, so it stops short of full sibling differentiation.

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 usage context with examples ('how should we size Savings Plans', 'what should Finance own in chargeback') and an explicit alternative ('instead of scanning the full list'). It lacks an explicit when-not or routing to other siblings like get_reference or find_playbooks, so it earns a 4 rather than a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc., but the description adds valuable behavioral details beyond those: it describes the response format, the miss behavior with suggestions for self-correction, and notes optional MCP Apps rendering. This is rich, transparent 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?

The description is well-structured with a clear purpose statement, usage guidelines, parameter explanation, and return details. It is slightly verbose but each part serves a purpose; no major 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 complexity (single parameter, output schema) the description covers all necessary aspects: purpose, when to use, parameter semantics, return format, error handling, and rendering context. Nothing missing 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 0% and the parameter has no description, so the description fully compensates by explaining that 'name' is a playbook slug as returned by list_playbooks and provides concrete examples. This adds crucial meaning beyond the bare 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 clearly states the verb 'Fetch' and the resource 'step-by-step runbook for one specific waste pattern', and it enumerates the contents (symptoms, detection queries, fix, anti-pattern). It is distinct from siblings like list_playbooks or find_playbooks.

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 when-to-use guidance: 'when the user asks how to detect, confirm, or fix one specific named waste pattern' and notes it serves questions about the user's own resources. It distinguishes itself from list/find tools by focusing on a single named pattern.

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

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

Annotations already cover the read-only/idempotent safety profile, and the description adds substantial behavior beyond them: a section miss returns the available heading list rather than the whole file, multiple heading matches surface other_matching_sections, and an unknown name yields up to three string-distance suggestions. That is exactly the kind of retry-relevant context 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 purpose, then usage, then args, then return shapes — a clean order. It is on the long side and the return-shape paragraph partly restates what the output schema already encodes, though the miss/partial semantics are not obvious from the schema alone.

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

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

For a two-parameter read tool with an output schema, nothing an agent needs is missing: input provenance, matching semantics, degradation path on a miss, and the difference between whole-file and sectioned responses are all stated. The remaining detail is carried by the output schema.

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

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

Schema description coverage is 0%, so the description carries the full burden and does: 'name' is documented as coming from list_references with three concrete examples, and 'section' is documented as case-insensitive partial H2/H3 matching with trailing-count tolerance ('storage optimization patterns' → 'Storage Optimization Patterns (28)'). This is meaning well beyond the bare string types 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') and immediately scopes the payload ('billing mechanics, decision rules and worked examples'). It also names the sibling tools that precede it (list_references, find_references), so an agent can place it in the workflow 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 conditions use on having already identified the reference via list_references or find_references, and explicitly recommends section vs whole-file based on question breadth and the approx_tokens hint. It even gives a concrete counter-example (finops-aws-patterns / S3 lifecycle) for when to pass section.

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/idempotent/non-destructive, so safety is covered. The description adds real behavioral context beyond that: each playbook is a small (~90-170 line) runbook, entries carry a confidence tier and an approx_tokens size hint explicitly framed for budgeting a multi-playbook answer before fetching. That is useful operational detail not present in 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 purpose, then routing, then return shape - a sensible order with no filler. It is slightly longer than strictly necessary given an output schema exists, but every section carries substance.

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-param, read-only enumeration tool with annotations and an output schema, the description supplies everything an agent needs: what is listed, when to prefer the sibling, entry granularity, and the size hint for budgeting. 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 per the baseline this is a 4. No argument syntax needs explaining and the description correctly spends no space on inputs.

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

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

States a specific verb and resource ('See every ready-made runbook for finding and fixing cloud waste') and enumerates the concrete scope (idle, orphaned, overprovisioned, egress, schedule blindness, AI/ML across AWS/Azure/GCP). It explicitly contrasts itself with the sibling find_playbooks, so an agent can pick it apart 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 an explicit when-to-use ('discover which waste patterns have a runbook') and an explicit when-not plus the alternative ('When the question already names a provider, waste category, or confidence tier, call find_playbooks instead'). The routing condition is precise and 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description goes beyond that with genuinely useful operational context: per-file token sizes (2,000-25,000), the ~10,000 threshold, and the recommendation to switch to get_reference(name, section=...) above it. It stops short of describing pagination or whether the list is exhaustive for very large libraries, which keeps it at a 4 rather than a 5.

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

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

Front-loaded with the coverage list, then the usage rule, then the return shape and token guidance; every block is doing work. The return-shape paragraph ('Returns a dict shaped ... where each entry includes name, title, ...') partially restates what the output schema already declares, which is the one place a sentence could be trimmed.

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?

An output schema exists, so return-value documentation is not strictly required, yet the description still tells the agent which fields discriminate entries and how to budget tokens before fetching. Combined with the named alternative and the no-parameter contract, an agent has everything needed to call this correctly on the first try.

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 there is no schema semantics to compensate for. The description's discussion of section= on the sibling get_reference is routing help rather than parameter documentation for this tool.

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

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

The description states a specific verb and resource ('See what FinOps guidance is available') and enumerates the actual coverage areas, so an agent knows exactly what this returns. It also names the sibling it is not ('find_references') and the condition that separates them, which is more than most definitions manage.

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 ('discover what the library covers before deciding what to fetch') and explicit when-not-to-use ('When the question already names a FinOps domain, phase, persona or maturity, call find_references instead of scanning this full list'). The alternative is named and the selecting condition is unambiguous.

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