Use this MCP server to discover and retrieve OptimNow’s Cloud FinOps reference guidance and cloud-waste runbooks.
Browse or search FinOps references by domain, capability, phase, persona, or maturity.
Fetch a full reference or just a specific section, with helpful suggestions when a name or section is missed.
Browse or filter waste runbooks by provider/scope, service, waste category, or confidence level.
Read specific runbooks containing symptoms, detection queries, fixes, and anti-patterns.
Answer “which of my resources…” questions by returning detection queries for the user to run in their own cloud account.
Provide read-only, static guidance without reading cloud accounts, bills, or live resource data.
Provides FinOps knowledge and cost optimisation playbooks for Kubernetes, covering allocation, chargeback, anomaly management, and waste detection.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@cloud-finops-mcp Show me the runbook for reducing AWS data transfer costs."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
FinOps knowledge for AI assistants: billing mechanics, commitment decisions and waste runbooks for AWS, Azure, GCP, AI and data platforms. By OptimNow.
Ask your assistant how to reduce a cloud bill, size a commitment, read a term sheet or allocate shared AI costs, and it answers from how billing works, with decision rules and worked examples, instead of general advice. The same files work in Claude, ChatGPT, Gemini, Cursor and any MCP-compatible tool. Open source, written by OptimNow from enterprise FinOps delivery, and aligned with the FinOps Foundation framework.
Each question below is answered by a file that exists in this repository today.
FinOps lead
"Which of our Savings Plans and reservations expire in the next 90 days, and what should we decide before they do?" (aws-expiring-commitment-no-decision, azure-unused-reservation, finops-aws-commitments.md)
"A third of our bill is unallocated. How do we reach a defensible allocation of shared costs?" (finops-allocation-showback.md)
"Who should own commitment purchases, and which meetings do we need to run the practice?" (finops-practice-operations.md)
Finance and procurement
"Our AWS enterprise agreement renews in 6 months. What should we check on the term sheet before signing?" (finops-cloud-contracts.md)
"Finance wants a 12-month cloud forecast with an accuracy target. Which measures do we report, and how tight should the band be at our maturity?" (finops-forecasting.md)
"What has to be true in Finance and in the ERP before we move from showback to chargeback?" (finops-chargeback.md)
Engineering and platform
"Our NAT gateway bill is higher than the compute it serves. Where does it come from and what do we change?" (aws-nat-gateway-endpoint-substitution, aws-zombie-nat-gateway)
"How do we split the cost of a shared Kubernetes cluster between teams?" (finops-kubernetes.md)
"Our Log Analytics ingestion doubled. Which tables and which settings do we check first?" (azure-log-analytics-sprawl, finops-azure.md)
AI product owner
"We spend $40K a month on Bedrock and do not know which features it goes to. Where do we start?" (finops-bedrock.md)
"Should we buy provisioned throughput or stay pay-as-you-go for 500K requests a day?" (finops-genai-capacity.md, finops-azure-openai.md)
"Our AI coding tool spend tripled in 6 months. How do we control it without banning the tools?" (finops-ai-dev-tools.md)
Neither the skill nor the connector can see your cloud account. For a question about your own resources, the answer is a detection query you run yourself, taken from the matching runbook.
Related MCP server: Enterprise MCP Knowledge Platform
The reference library is mapped to the 22 capabilities of the FinOps Foundation framework, grouped in its 4 domains. A filled square means at least one reference owns the capability; a grey square means the capability is covered inside another file; a dashed square is a known gap, listed with its reasoning in docs/ROADMAP.md.
This map is generated from the frontmatter of every reference file, and the CI pipeline fails when the committed map no longer matches the files (fcp-coverage.md).
The matrix reads the library by business need. Every cell comes from a named reference file, listed in the notes under the tables.
Level | Meaning |
● deep | A dedicated reference or section, with decision rules, worked examples or detection queries |
◐ partial | Covered inside a broader file, or mechanics only |
– | Not covered today |
n/a | The combination does not exist |
Hyperscalers
Business need | AWS | Azure | GCP |
Understand and allocate the bill | ● | ● | ● |
Budget and forecast | ● | ● | ● |
Commitments and discounts | ● | ● | ● |
Contract negotiation and renewal | ● | ● | ● |
Reduce waste | ● | ● | ● |
AI and GenAI spend | ● | ● | ● |
Data platforms | ◐ | ● | ◐ |
SaaS and licences | ◐ | ◐ | ◐ |
Carbon footprint | ● | ◐ | ◐ |
Other estates
Business need | OCI | On-prem |
Understand and allocate the bill | ◐ | ● |
Budget and forecast | ◐ | ◐ |
Commitments and discounts | ◐ | ◐ |
Contract negotiation and renewal | – | – |
Reduce waste | ◐ | ◐ |
AI and GenAI spend | – | ◐ |
Data platforms | – | – |
SaaS and licences | – | ◐ |
Carbon footprint | – | – |
Platforms
Business need | AI | Data | SaaS |
Understand and allocate the bill | ● | ● | ◐ |
Budget and forecast | ● | ◐ | ◐ |
Commitments and discounts | ● | ● | ◐ |
Contract negotiation and renewal | – | ◐ | ◐ |
Reduce waste | ● | ● | ● |
AI and GenAI spend | ● | ◐ | ● |
Data platforms | n/a | ● | n/a |
SaaS and licences | ◐ | ◐ | ● |
Carbon footprint | – | – | – |
On-prem covers owned data centres and the hybrid platforms (Outposts, Azure Local, Arc). AI covers the AI platforms: Anthropic, AWS Bedrock, Azure OpenAI, GCP Vertex AI and the open-weight vendor APIs. Data covers Databricks, Snowflake and Microsoft Fabric. SaaS covers SaaS applications, AI coding tools and licences.
All paths are under plugins/cloud-finops/skills/cloud-finops/.
Understand and allocate the bill. AWS: references/finops-aws-billing.md, finops-allocation-showback.md, finops-focus.md, finops-tagging.md. Azure: finops-azure-billing.md, finops-focus.md, finops-tagging.md. GCP: finops-gcp.md (cost data foundation), finops-focus.md, finops-kubernetes.md. OCI, partial: finops-oci.md (cost reports, cost-tracking tags), finops-focus.md. On-prem: finops-on-prem-hybrid.md (internal bill, usage ingestion). AI platforms: the "Cost visibility and allocation" sections of finops-bedrock.md, finops-azure-openai.md, finops-vertexai.md, finops-anthropic.md; finops-for-ai.md. Data platforms: finops-databricks.md (system tables, allocation), finops-fabric.md (shared-capacity allocation), finops-snowflake.md (query attribution). SaaS, partial: finops-sam.md (discovery), finops-focus.md (FOCUS for SaaS vendors), finops-ai-dev-tools.md (attribution patterns).
Budget and forecast. AWS and Azure: finops-forecasting.md, finops-anomaly-management.md, and the Budgets sections of finops-aws-billing.md and finops-azure-billing.md. GCP: finops-gcp.md (budgets, spend caps), finops-anomaly-management.md. OCI, partial: finops-oci.md (Budgets). On-prem, partial: finops-on-prem-hybrid.md (rate setting); capacity planning is on the roadmap. AI platforms: finops-ai-value-management.md (AI investment budgets, stage gates), finops-forecasting.md (AI forecast scenarios), finops-anthropic.md (spend limits). Data platforms, partial: budget controls in finops-snowflake.md, finops-databricks.md, finops-fabric.md. SaaS, partial: finops-sam.md (renewal calendar, metrics), finops-ai-dev-tools.md (spending caps).
Commitments and discounts. AWS: finops-aws-commitments.md, finops-aws-patterns-databases.md (database commitment tree), playbooks/aws-expiring-commitment-no-decision.md. Azure: finops-azure-commitments.md, playbooks/azure-unused-reservation.md. GCP: finops-gcp.md (CUDs, BigQuery commitments), finops-vertexai.md (Flexible Savings Plans), playbooks/gcp-cud-mismatch.md. OCI, partial: finops-oci.md (Universal Credits). On-prem, partial: finops-on-prem-hybrid.md (hybrid platform terms: Outposts, Exadata Cloud@Customer). AI platforms: finops-genai-capacity.md, provisioned capacity in finops-azure-openai.md, finops-bedrock.md, finops-vertexai.md. Data platforms: finops-databricks.md (committed-use bands), finops-snowflake.md (capacity model), finops-fabric.md (reservation). SaaS, partial: finops-ai-dev-tools.md (plan tiers), finops-sam.md (multi-year agreements).
Contract negotiation and renewal. AWS, Azure, GCP: finops-cloud-contracts.md, plus finops-azure-billing.md (EA-to-MCA). Data platforms, partial: the data platform section of finops-cloud-contracts.md, finops-databricks.md, finops-snowflake.md. SaaS, partial: finops-sam.md (renewal governance), finops-itam.md (pre-renewal checkpoint, joint negotiation). OCI, on-prem and AI platforms: no file. See "Contract negotiation and renewal" below.
Reduce waste. AWS: finops-aws.md, the 5 finops-aws-patterns-*.md files, 22 runbooks. Azure: finops-azure.md, finops-azure-patterns.md, 10 runbooks. GCP: the pattern catalogue inside finops-gcp.md, 7 runbooks. OCI, partial: finops-oci.md (6 patterns, no runbook). On-prem, partial: finops-on-prem-hybrid.md (idle capacity line, cost score). AI platforms: finops-for-ai.md (anti-patterns), finops-genai-capacity.md (provisioned-capacity waste), the optimisation sections of the 4 AI platform files, 2 cross-cloud runbooks. Data platforms: the pattern sections of finops-databricks.md, finops-snowflake.md, finops-fabric.md. SaaS: finops-sam.md (sprawl patterns), finops-ai-dev-tools.md (optimisation levers).
AI and GenAI spend. AWS: finops-bedrock.md, finops-aws.md (SageMaker), the GPU and SageMaker runbooks. Azure: finops-azure-openai.md. GCP: finops-vertexai.md. On-prem, partial: finops-ai-self-hosted-vs-managed.md. AI platforms: finops-for-ai.md, finops-agentic.md, finops-ai-value-management.md, finops-genai-capacity.md, finops-anthropic.md, finops-open-weight-vendors.md. Data platforms, partial: Cortex in finops-snowflake.md, model serving in finops-databricks.md. SaaS: finops-ai-dev-tools.md, playbooks/cross-cloud-coding-agent-token-waste.md.
Data platforms. AWS, partial: finops-databricks.md on AWS, Redshift commitments in finops-aws-patterns-databases.md. Azure: finops-fabric.md, finops-databricks.md. GCP, partial: BigQuery in finops-gcp.md. Data platforms: finops-databricks.md, finops-snowflake.md, finops-fabric.md.
SaaS and licences. AWS, Azure, GCP, partial: marketplace channel governance in finops-itam.md, Marketplace private offers in finops-cloud-contracts.md, Azure Hybrid Benefit in finops-azure-commitments.md. On-prem, partial: VMware core licensing in finops-on-prem-hybrid.md, BYOL in finops-itam.md. AI platforms, partial: licensing in finops-open-weight-vendors.md. Data platforms, partial: Pro, PPU and F-SKU licences in finops-fabric.md. SaaS: finops-sam.md, finops-itam.md, finops-ai-dev-tools.md.
Carbon footprint. AWS: greenops-cloud-carbon.md (Sustainability Console, Well-Architected pillar). Azure and GCP, partial: the same file, with the Azure and GCP depth pass on the roadmap; finops-gcp.md (Cloud Carbon Footprint).
The reference finops-cloud-contracts.md covers negotiated spend commitments with the 3 hyperscalers: AWS Private Pricing (EDP and PPA), Azure MACC and the Azure Commitment Discount, and Google Cloud Minimum Commitment. It describes the 12 clauses of an enterprise agreement, where the discount shows in billing data, migration funding (MAP, Azure Accelerate, RaMP), Marketplace private offers as a commitment lever, the reseller channel, 9 intake questions to ask before advising, a 15-point review grid for a term sheet, the usual pitfalls and the timing of a renewal. A closing section covers Databricks and Snowflake commitments inside a cloud contract. Benchmarks come from public sources named in the file; the library carries no observed contract figure.
Also covered: SaaS renewal governance (renewal calendar, auto-renewal review) in finops-sam.md and the pre-renewal checkpoint and marketplace channel governance in finops-itam.md.
Not covered today: negotiation with AI providers (Anthropic, OpenAI and the hosted model vendors; the library covers their reservation mechanics, not their enterprise agreements), OCI Universal Credits beyond their mechanics, and colocation or hosting contracts.
A runbook is a step-by-step procedure for one specific waste pattern: the symptoms, a detection query you run in your own account, the fix in safest-first order, and the mistake to avoid. The library files them by provider and by waste category, and each one carries a confidence level that says whether a single signal is enough to act.
Live prices. The files carry billing mechanics, which stay true for years. Price figures go stale inside a packaged skill within weeks, so they are left out. For a current price the skill points to OptimToken, OptimNow's free comparison of LLM token rates and compute instance rates, each figure with its as-of date.
Your cloud account. Nothing here reads a bill or an API. For "which of my resources" questions, the deliverable is the runbook's detection query.
Legal, tax or accounting advice. The contract and chargeback references describe mechanics and the questions to ask; your counsel, tax adviser and auditors decide.
Topics still open. Accounting for owned capacity (depreciation, lease treatment), AI provider and OCI contract negotiation, and the FinOps Education & Enablement capability. Each is listed in docs/ROADMAP.md with the trigger that would reopen it.
Guaranteed routing. The model decides which file to read. When an answer arrives without a visible file read or tool call, ask for the library by name ("check the playbook library"). See docs/CONCEPTS.md.
Tool | One-step install |
At the Claude Code prompt: | |
Install from the Claude directory (one click, kept current from this repository). Or download the latest release zip, then Settings -> Skills -> Upload zip | |
Self-host: | |
Self-host: | |
| One-liner: |
| |
Nothing to install: | |
|
Full options, troubleshooting, and the model-agnostic API loader: see
INSTALLATION.md. A version-tagged zip
(cloud-finops-vX.Y.Z.zip) is attached to every
GitHub release.
The skill is a folder of markdown files: an entry point that routes a question to the right reference, the reference library and the runbooks. Installed in Claude, Kiro or through the installer for other tools, the guidance sits in the model's context before it answers. No code runs, no data leaves your machine.
The MCP connector serves the same library the other way round, as 6 read-only
tools the model calls when it decides to: list, search by FinOps capability or
waste category, and fetch one reference or runbook. One URL to paste
(https://mcp.optimnow.io/mcp), nothing to install. Tool calls go to a server
OptimNow runs in Paris; see "Data handling" below.
The plugin in the Claude directory is the skill only. The connector is a separate listing, so that the same content is not loaded twice in one session.
Live prices come from OptimToken, queried at answer time, never copied into these files.
The 2 delivery shapes behave differently: a loaded skill grounds advisory and symptom questions without a decision to make, while the connector depends on the model choosing to call a tool. What that means in practice, and when to use both, is in docs/CONCEPTS.md. Using a non-Claude model through an API, add the response contract from INSTALLATION.md to your system prompt so answers stay structured and billing-grounded.
More questions the library is written to answer, beyond the role list above:
"Our monthly bill jumped from $12K to $38K after a developer enabled Fast mode in Claude Code. How do I get this under control?"
"Should we self-host an open-weight model on rented H100s instead of paying per token, and what hidden costs do TCO calculators miss?"
"Our client wants separate AWS invoices per business unit. Their AWS contact suggested Cost Categories. Is that right?"
"We are migrating from EA to MCA. What FinOps work do we need to do before the switch?"
"We need to start reporting our cloud carbon emissions. Where do we begin?"
"Our Snowflake bill doubled in a quarter. Is it the warehouses, storage or Cortex, and what do we check first?"
"We run half our workloads in our own data centres. How do we give app teams a monthly bill for on-prem capacity they will accept?"
Visibility before optimisation. Establish what you spend and what drives it, then act. The skill does not recommend commitments to a team that cannot allocate its bill.
Provider mechanics first, vendor claims second. Guidance is grounded in how billing works (CUR columns, Azure cost-management semantics, BigQuery export, FOCUS conformance), with primary sources cited. Vendor savings and sustainability claims are read critically.
Maturity is contextual. Where cloud is a cost centre, Crawl plus selective Walk is often the right state; where cloud is the product, Run pays for itself in gross margin. The skill assesses maturity before recommending.
Cost connects to business value. Every recommendation answers the CFO question: which business outcome does this protect or create.
Mechanics live here, price figures do not. Any figure a reference quotes carries its date and source; current prices route to OptimToken.
AI cost management is a first-class domain, with a reference per AI platform and a discipline file for agents, capacity and investment governance.
What the skill and the hosted connector run, send and fetch, so you can decide where each is appropriate. Full policy in PRIVACY.md.
The skill is static text. The entry point, the references and the runbooks are markdown files read into the model's context. They run no code, call no network endpoint and carry no credentials. The runbooks contain detection queries (billing export SQL, CLI commands) that you run in your own cloud account; nothing in this repository reads a cloud account.
The hosted MCP connector, if you add it, sends tool calls to mcp.optimnow.io.
When the model calls one of the 7 tools, the tool arguments (a reference or runbook
name, a section phrase, facet filters, a guide slug) travel over HTTPS to that server and the
matching content comes back. The server requires no account and no authentication,
holds no database and no per-user state, and serves the same public files as this
repository. Its application log writes one line per request (method, path, status
and request type, never the arguments); when a lookup matches nothing, it also
writes the tool name and the arguments that missed, which are short strings the
model writes and can include a word copied from your question. The server runs on
Fly.io, primary region Paris, which holds that log stream, possibly with the client
IP address, under its default retention. OptimNow does not sell, share or profile
from it.
Price lookups route to a live tool, not to this repo. Whether the model opens OptimToken is its decision in the conversation.
One tool makes an outbound request. get_live_figures sends one HTTPS GET to
optimtoken.optimnow.io (an OptimNow site) for a guide's figures.json, carrying the
guide slug and a cloud-finops-mcp User-Agent, nothing from the conversation. On the
hosted connector the request leaves the server; with the PyPI package it leaves your
machine. No other tool touches the network.
Nothing else. No telemetry, no analytics beacon, no update check, no package launcher, no credential read from your environment.
The library is updated weekly. Every Saturday an automated scan checks around 35
sources: cloud and AI provider release notes, billing changelogs and pricing pages,
plus FinOps community publications. Each change is confirmed on the provider's own
documentation and reviewed by a practitioner before it is applied. Every merge to
main becomes a new plugin version in the Claude directory, and a version-tagged
release ships the same content to PyPI and the MCP Registry. Watch or star the
repository to be notified.
Practitioner experience is the highest-value contribution. Frameworks and vendor docs are already public; what is rare is "we tried X in production, this is what it billed". Corrections to billing mechanics, new or improved runbooks, real-world counter-examples and adversarial review of the recommendations are all welcome: the repository is opinionated, and it should also be falsifiable.
The full guide, including the repository structure, contribution types, process and conventions, is in CONTRIBUTING.md. If your change names another OptimNow tool (an MCP tool name, an endpoint URL, a provenance field), read DEPENDENCIES.md first.
Fork the repository and customise the reference files for your context: your cloud stack, your internal policies, your tag taxonomy, your negotiated rates. A fork gives you a stable base you can pull upstream updates into at your own pace. Typical customisations:
Adding organisation-specific tag requirements to finops-tagging.md
Replacing illustrative figures with your negotiated rates
Adding reference files for internal tools or platforms not covered here
Adjusting the methodology file to your team's own approach
OptimNow is a boutique FinOps consultancy that helps organisations connect cloud and AI spend to measurable business value. Based in France, with European reach.
Website: optimnow.io
LinkedIn: OptimNow
GitHub: github.com/OptimNow
Open-source tools built by OptimNow:
Tool | What it does |
Compare what 250+ models cost per request, with caching and batch factored in, plus compute instance rates across 7 clouds. Also an MCP connector; this skill routes price questions here | |
Whether an AI project pays for itself: three-layer cost model, payback, break-even, sensitivity. Also an MCP server | |
Where your organisation stands on AI cost management | |
Tag governance automation |
This skill incorporates content derived from the following sources:
FinOps Foundation: framework definitions, capability descriptions and maturity model structure are based on the FinOps Framework.
Point Five: cloud optimisation recommendations informed several provider-specific best practices and quick-win patterns.
Tokenomics Foundation: the token complexity classes in the agentic FinOps reference are adapted from Big-T Notation by Dan Neff (Adobe), published by the Tokenomics Foundation under CC BY 4.0.
All referenced content has been adapted with additional context from OptimNow's consulting delivery experience. Any errors or opinionated interpretations are our own. This skill is independently maintained and is not affiliated with or endorsed by the FinOps Foundation.
Licensed under CC BY-SA 4.0. See LICENSE.md for the full licence text.
You are free to use, adapt and redistribute this skill, including for commercial purposes, as long as you credit OptimNow and share any derivatives under the same licence. When redistributing the material, please include this attribution:
Cloud FinOps Skill by OptimNow - licensed under CC BY-SA 4.0.
Finds the runbook for a specific cloud waste pattern, filtered by provider, service, waste category or detection confidence. Useful before answering a specific waste or cost-fix question: each runbook includes a tested detection query the user can run in their own account, so it also serves questions about the user's own resources.
Use this for questions like "which VMs are running for nothing",
"why is our NAT bill so high", "my NAT gateway processes 10TB to S3",
"should I delete these old snapshots", "which of our RIs are about to
expire", "what waste can we clean up safely without review" - anything
that names a provider, a waste category, or how confident the
detection needs to be before acting. Patterns
covered include NAT gateways and VPC endpoints, expiring Savings
Plans / RIs / reservations, snapshot sprawl, S3 lifecycle gaps, idle
or stopped VMs, orphaned disks / public IPs / EBS volumes, GPU and
SageMaker sizing, Kubernetes idle capacity, and schedule blindness.
All filters are optional and combine with AND semantics. String matching
is case-insensitive and exact. Examples:
- ``find_playbooks(scope="aws")`` - all AWS-specific playbooks
- ``find_playbooks(waste_category="idle")`` - every idle-resource pattern
- ``find_playbooks(scope="cross-cloud", confidence="obvious")``
Args:
scope: ``"aws"``, ``"azure"``, ``"gcp"``, or ``"cross-cloud"``.
service: Provider service exact-match (e.g. ``"AWS NAT Gateway"``).
waste_category: ``"orphaned"``, ``"idle"``, ``"overprovisioned"``,
``"commitment-mismatch"``, ``"schedule-blindness"``,
``"modernization"``, ``"ai-ml-inefficiency"``, or ``"egress"``.
confidence: ``"obvious"`` (single signal is enough),
``"likely"`` (two signals required), or ``"possible"``
(needs human review). From the OptimNow three-tier confidence
model in `finops-waste-detection-playbooks`.
Returns ``{"filters": {...}, "playbooks": [...], "total": N}``. A query
that matches nothing also returns `hint` and `valid_values`, so a typo is
distinguishable from a genuine gap in coverage.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | ||
| service | No | ||
| confidence | No | ||
| waste_category | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
Find which guidance serves a FinOps question - how to commit, size, allocate, charge back, forecast, or govern cloud and AI spend.
Use this for questions like "how should we size Savings Plans",
"what should Finance own in chargeback", "what does a Crawl-stage org
tackle first" - anything that maps to FinOps Framework facets (domain,
capability, phase, persona, maturity) - and you want only the
references that serve it, instead of scanning the full list.
All filters are optional and combine with AND semantics. String matching
is case-insensitive and exact (not substring). Examples:
- ``find_references(domain="Optimize Usage & Cost")``
- ``find_references(phase="Optimize", persona="Engineering")``
- ``find_references(persona="Engineering", persona_primary_only=True)``
- ``find_references(capability="Rate Optimization")``
- ``find_references(maturity="Crawl")``
Args:
domain: FinOps Framework domain (e.g. ``"Optimize Usage & Cost"``,
``"Quantify Business Value"``, ``"Manage the FinOps Practice"``).
capability: FinOps capability (matches ``fcp_capability`` and
``fcp_capabilities_secondary``).
phase: FinOps phase (``"Inform"``, ``"Optimize"``, ``"Operate"``).
persona: Persona (matches ``fcp_personas_primary`` and
``fcp_personas_collaborating``).
maturity: Entry maturity level (``"Crawl"``, ``"Walk"``, ``"Run"``).
persona_primary_only: when True, ``persona`` matches only the primary
list. Use it when the default match barely narrows the set -
broad personas like Engineering collaborate on nearly every file,
so filtering on collaboration is descriptive, not discriminating.
``persona="Engineering", persona_primary_only=True`` is the
engineering reading list; the default is the everything-they-touch
view.
Returns ``{"filters": {...}, "references": [...], "total": N}``. A query
that matches nothing also returns `hint` and `valid_values`, so a typo is
distinguishable from a genuine gap in coverage.
| Name | Required | Description | Default |
|---|---|---|---|
| phase | No | ||
| domain | No | ||
| persona | No | ||
| maturity | No | ||
| capability | No | ||
| persona_primary_only | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
Fetch the step-by-step runbook for one specific waste pattern: symptoms, the detection queries to run, the fix, and the anti-pattern to avoid.
Use this when the user asks how to detect, confirm, or fix one specific
named waste pattern (zombie NAT gateway, snapshot sprawl, idle SageMaker
endpoint, ...). It also serves questions about the user's own resources
("which of my X..."): the runbook's detection query is written to be run
in the user's account, so the answer does not depend on access to that
account.
Args:
name: Playbook slug as returned by ``list_playbooks`` (e.g.
``"aws-zombie-nat-gateway"``, ``"azure-orphan-disks"``,
``"cross-cloud-untagged-spend-drift"``).
Returns ``{"name": ..., "title": ..., "content": "...", "lines": N}``.
On miss, returns ``{"error": ..., "suggestions": [...]}`` with up to
three string-distance matches so the caller can self-correct.
A host with MCP Apps (SEP-1865) support may render this result via the
linked ``ui://cloud-finops/playbook-viewer`` resource instead of showing
the raw markdown.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
Fetch the guidance on one FinOps topic - the billing mechanics, decision rules and worked examples behind a defensible answer - either whole or one section at a time.
Use this when you need the actual content of one known reference,
after ``list_references`` or ``find_references`` told you which one
serves the question. Advisory questions (commitment sizing, chargeback
design, allocation methodology) are served by the reference's decision
rules and worked examples, which a summary does not carry.
Pass ``section`` when the question is narrower than the file. The
``approx_tokens`` hint in the listing tells you when this matters: the
largest references run to about 15,000 tokens and the Azure pattern catalogue
is an enumerated list, so a question about storage lifecycle wants one
section of ``finops-azure-patterns``, not all of it. Omit ``section`` for the whole
file when you need the cross-cutting reasoning.
Args:
name: Reference name as returned by ``list_references`` (e.g.
``"finops-aws"``, ``"finops-genai-capacity"``,
``"optimnow-methodology"``).
section: Optional H2 or H3 heading to return on its own. Matched
case-insensitively and partially against the headings, so a
natural phrase works - ``"storage"``, ``"commitment decision
tree"``. A heading's trailing count is ignored, so
``"storage optimization patterns"`` matches
``"Storage Optimization Patterns (28)"``. If it matches nothing
you get the list of available headings back, not the whole file.
Without ``section``, returns ``{"name": ..., "content": "...",
"lines": N}`` where ``content`` is the file verbatim. With ``section``,
returns ``{"name", "title", "section", "section_level", "partial": true,
"content", "lines", "full_lines"}`` where ``content`` is that section
prefixed by the reference's title, plus ``other_matching_sections`` when
the phrase matched more than one heading.
On a miss, returns ``{"error": ..., "suggestions": [...]}``. An unknown
name gives up to three string-distance matches; an unmatched ``section``
gives ``available_sections`` - every heading in the file - so the retry
is exact.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| section | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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 adds what they cannot: partial-return semantics with 'partial': true, the fact that a section result is prefixed by the reference title, and precise miss behavior (unknown name → up to three distance matches; unmatched section → available_sections). That is exactly the error/retry context an agent 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-loaded with purpose, then usage, then params — good ordering with no filler sentences. It is somewhat long, and the paragraph spelling out both return shapes partially duplicates the existing output schema, which is the only trimming opportunity.
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?
Two-parameter read with rich annotations and an output schema; the description still adds the routing decision, section-selection heuristic tied to approx_tokens, and the miss/retry contract. Nothing an agent needs to call this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description fully compensates: it gives concrete name examples, then defines section matching rules (H2 or H3, case-insensitive, partial, trailing count ignored) with a natural-phrase example and the 'storage optimization patterns' → 'Storage Optimization Patterns (28)' case, plus the fallback when nothing matches.
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 ('Fetch the guidance on one FinOps topic') with the exact resource, and immediately scopes it to a *known* reference, which distinguishes it from the discovery siblings find_references and list_references.
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 sequences itself after list_references/find_references ('after ... told you which one serves the question'), names the class of questions it serves (advisory: commitment sizing, chargeback design, allocation methodology), and gives a concrete rule for section vs. whole file with a worked example (storage lifecycle vs. finops-azure-patterns).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
See every ready-made runbook for finding and fixing cloud waste: idle, orphaned and overprovisioned resources, egress surprises, schedule blindness and AI/ML inefficiency across AWS, Azure and GCP.
Use this to discover which waste patterns have a runbook. When the
question already names a provider, waste category, or confidence tier,
call ``find_playbooks`` instead.
Each playbook is a small (~90-170 line) runbook scoped to one waste
pattern (e.g. ``aws-zombie-nat-gateway``, ``azure-orphan-disks``). Returns
``{"playbooks": [...], "total": N}`` where each entry includes ``name``,
``title``, ``scope`` (aws/azure/gcp/cross-cloud), ``service``,
``waste_category``, ``confidence`` (obvious/likely/possible), and
``approx_tokens`` - the same size hint the reference listing carries, so a
multi-playbook answer can be budgeted before fetching.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
See what FinOps guidance is available: billing mechanics, commitment strategy, allocation and chargeback, AI cost management, and per-provider cost handbooks (AWS, Azure, GCP, OCI, Databricks, Snowflake, ...).
Use this to discover what the library covers before deciding what to
fetch. When the question already names a FinOps domain, phase, persona
or maturity, call ``find_references`` instead of scanning this full
list.
Returns a dict shaped ``{"references": [...], "total": N}`` where each
entry includes ``name``, ``title``, a one-line ``description``, the
discriminating FCP facets (``fcp_domain``, ``fcp_capability``,
``fcp_phases``, ``fcp_personas_primary``, ``fcp_maturity_entry``) and
``approx_tokens``.
Read ``approx_tokens`` before fetching: the library runs from about 2,000
to about 15,000 tokens per file. Above roughly 10,000, prefer
``get_reference(name, section=...)`` and pull the part you need.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new operational context: the token size range per file (~2,000–15,000), the ~10,000 threshold where fetching becomes expensive, and the section-scoped workaround. That is exactly the cost/behavior information an agent cannot get from structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose and the sibling routing are front-loaded in the first two paragraphs, which is the right ordering. The third paragraph spells out the response dict field-by-field even though an output schema already exists, which is slightly redundant bulk, though the approx_tokens advice that follows does earn 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 no-argument discovery tool this leaves nothing an agent needs unanswered: scope, alternative tool, response shape, per-item facets, and the token-cost decision rule. The output schema exists, so the extra return-value prose is redundant rather than required, but completeness is not lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. The description does usefully explain which fields appear in each returned entry, but that is return-value detail rather than 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?
Opens with a specific verb+resource ('See what FinOps guidance is available') and enumerates the concrete domains and providers covered, so an agent knows exactly what is in the library. It is clearly distinguishable from find_references, get_reference, and the playbook siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States the intended use ('discover what the library covers before deciding what to fetch') and an explicit exclusion with the alternative: when a FinOps domain, phase, persona or maturity is already named, call find_references instead. It also routes oversized files to get_reference(name, section=...).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0find_playbooksfind_referencesget_playbookget_referencelist_playbookslist_referencesScored across 6 tools
The six tools form two clean triplets (references and playbooks), each split into list/find/get with distinct roles, and the descriptions explicitly steer callers between list_* and find_* based on whether filters are known. The only residual overlap is that list_references and find_references return the same payload shape and find with no filters behaves like list, but the guidance on when to use each is unusually clear.
All six tools follow a strict verb_noun pattern (list_references, find_references, get_reference, list_playbooks, find_playbooks, get_playbook), and the verb choice is semantically consistent across both resource families. Plural for collection operations and singular for single-item fetches is applied uniformly.
Six tools is well-scoped for a read-only guidance library: two resources times three access patterns, with no redundant or speculative endpoints. Every tool has a clear, earned place in the workflow.
Discovery (list), faceted search (find) and retrieval with section-level granularity (get) cover the read-only lifecycle for both references and playbooks, including miss-recovery via suggestions and available_sections. Minor gaps: no cross-corpus search spanning references and playbooks at once, and no standalone way to enumerate a reference's headings without triggering a section miss.
FinOps agent MCP: one allocated view of cloud, AI and data costs for your team. Starter $300/mo
Read-only AI/LLM cost tools with current MCP discovery and attributable Registry transport.
Connect MCP clients to 2,000+ AI models without managing provider API keys.
MCP-Native LLM Orchestration Agent
