Cloud FinOps Skill & MCP

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

Beyond the readOnly/idempotent annotations, the description discloses matching semantics (filters combine with AND, case-insensitive and exact), return shape, and the no-match behavior with hint and valid_values to distinguish typos from coverage gaps. It also communicates the important behavioral rule that the runbook itself is the answer.

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 section earns its place: critical usage rules, param semantics, examples, and return handling. It is front-loaded with the most important instruction ('ALWAYS call this before...') and uses structured examples to make the content 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?

For a tool with 4 optional filter params, an output schema, and a strategic role in workflow routing, the description covers everything needed: parameter values, filter semantics, matching behavior, return structure, and when to prefer this over knowledge or asking the user. The presence of an output schema reduces the need to describe return values, but the description still usefully documents the no-match response.

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

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

The schema provides no descriptions or enums (0% coverage), so the description carries full responsibility, and it delivers: each parameter is documented with allowed values, examples, and meaning. The confidence parameter even explains the three-tier model, and waste_category lists all valid categories.

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 identifies a specific verb and resource: 'Find the tested runbook for a waste suspicion' with filtering by provider, service, category, or confidence. It is distinct from list_playbooks because it is a search/find operation for a specific answer, not a browse/list behavior.

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 instructions: ALWAYS call before answering any cloud-waste question or requesting account data, even when the agent thinks it knows the answer. It also provides concrete when-not-to behavior, instructing the agent not to claim lack of account access and not to request data exports, which makes the intended usage 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?

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description still adds substantial behavior beyond them: the exact success return shape, the miss behavior returning error plus up to three string-distance suggestions for self-correction, and the optional ui://cloud-finops/playbook-viewer rendering path. This is genuinely useful runtime behavior an agent could not infer from annotations alone.

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?

Despite its length, every sentence earns its place: purpose, content inventory, when-to-use plus a behavioral guardrail, parameter semantics, success/error return formats, and an optional rendering note. The tool's job is front-loaded in the first two sentences, and the rest is organized into clear labeled sections rather than a wall of prose.

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

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

For a single-parameter, read-only tool with rich annotations and an existing output schema, the description covers everything needed for correct invocation: what the tool does, what the param means and where it comes from, what a successful call returns, what a miss returns (with self-correction suggestions), and a rendering alternative. There is no meaningful gap an agent would have to guess about.

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 carries the full burden for the 'name' parameter — and it succeeds completely. It defines name as a playbook slug, gives its provenance ('as returned by list_playbooks'), and provides three concrete examples (aws-zombie-nat-gateway, azure-orphan-disks, cross-cloud-untagged-spend-drift). An agent could correctly populate this parameter from the description 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 opens with a specific verb and resource — 'Fetch the step-by-step runbook for one specific waste pattern' — and enumerates the runbook's contents (symptoms, detection queries, fix, anti-pattern). It clearly distinguishes from siblings like list_playbooks by emphasizing 'one specific' named pattern with concrete slug examples, so an agent can route correctly without inspecting 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?

It explicitly states when to use the tool ('Use this when the user asks how to detect, confirm, or fix one specific named waste pattern') and adds a strong behavioral rule for the user's-own-resources case: fetch the runbook and hand over its detection query, never claim lack of access or ask for data export. It doesn't explicitly name alternatives (e.g., list_playbooks for browsing all runbooks), so it stops short of full when-not 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?

Beyond the readOnlyHint and idempotentHint annotations, the description discloses important behaviors: partial-match section resolution, trailing-count ignoring, the error response shape with suggestions, and the fact that an unmatched section returns available headings rather than the whole file. These are non-obvious behaviors an agent needs to predict output correctly.

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 part earns its place: purpose, when-to-use, parameter semantics, return shapes, and error handling. It is front-loaded with purpose and usage before diving into arguments, and uses structured sections (Args, return descriptions) that make scanning easy.

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 tool of this complexity. It covers selection guidance, section granularity decisions, matching behavior, exact return shapes with and without section, and miss/error handling. There is no important caller-relevant behavior left undocumented.

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

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

Schema description coverage is 0%, so the description must fully document parameters, and it does. It explains that name must be a value as returned by list_references, gives concrete examples, and describes section matching semantics with natural-phrase examples and edge-case behavior. Both parameters are thoroughly specified.

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: 'Fetch the guidance on one FinOps topic ... either whole or one section at a time.' It explicitly differentiates from siblings by stating it is for 'the actual content of one known reference' after list_references or find_references, which makes the tool's role in the workflow 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: use it after list_references or find_references has identified the reference, and ALWAYS before answering an advisory question. It also gives a clear rule for when to pass section versus omit it, using the approx_tokens hint from the listing. This is strong routing guidance 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 and idempotentHint, so the agent knows this is a safe read. The description adds value by disclosing the return structure (playbooks array with total), the fields per entry, and the approx_tokens budget hint, which is useful for planning multi-playbook answers. 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 well-structured, front-loading the core purpose before detailing the return format. It is longer than a single sentence but every part earns its place, explaining scope, alternatives, and output fields without fluff.

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

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

Given the tool's simplicity (no parameters), the presence of an output schema, and rich annotations, the description covers all necessary aspects: what it does, when to use it, what it returns, and how to budget for it. 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?

The tool has zero parameters, so schema coverage is 100% and there is nothing to document. The description correctly omits parameter details, and the baseline for 0-parameter tools is 4, 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 clearly states the tool lists all ready-made runbooks for cloud waste across AWS, Azure, and GCP, covering specific waste patterns. It distinguishes itself from find_playbooks by naming the alternative and the condition that triggers it, making the purpose 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?

Explicitly states when to use this tool (to discover which waste patterns have a runbook) and when to use the sibling find_playbooks instead (when the question already names a provider, waste category, or confidence tier). This leaves no ambiguity about routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds valuable behavioral context: it returns a dict with 'references' and 'total', each entry containing specific fields, and includes approx_tokens with token ranges from ~3,000 to 25,000+. This goes beyond the annotations without contradicting them.

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 at ~120 words and structured logically: purpose, usage guidance, return format, and token advice. It front-loads the core purpose and each sentence adds value without redundancy. The formatting is clean 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?

The description covers all essential aspects: what it returns, how to use it appropriately, and how it relates to sibling tools. The output schema exists, so the description doesn't need to enumerate every field, but it mentions key ones. The only minor omission is pagination behavior, but the 'total' field suggests a complete list. Overall, it's sufficient for an agent to use 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 tool has zero parameters, so the schema requires no explanation. According to the rubric, a tool with 0 parameters gets a baseline of 4. The description correctly focuses on return format and usage rather than parameter details, which 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 purpose: to list available FinOps guidance across specified domains and providers. It explicitly differentiates itself from find_references, which targets specific domains/phases/personas, and mentions get_reference for fetching. The verb 'see what FinOps guidance is available' is specific and the resource is well-defined.

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 direct guidance: use this for discovery before fetching, and switch to find_references when the query already specifies a domain/phase/persona/maturity. It also advises using get_reference with a section parameter for files over ~10,000 tokens. These are explicit when-to-use and when-not-to-use statements, leaving no ambiguity.

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