Skip to main content
Glama

Find the right FinOps guide

find_references
Read-onlyIdempotent

Identify relevant FinOps guidance by asking a cloud or AI spend question, or filter by domain, capability, phase, persona, and maturity to get ranked references and sections.

Instructions

Find which guidance serves a FinOps question - how to commit, size, allocate, charge back, forecast, or govern cloud and AI spend.

Use this with ``query`` for a question in the user's own words rather
than in FinOps Framework terms: "how should we size our first Savings
Plan when usage is seasonal", "we hold SQL Server licences with Software
Assurance, BYOL or licence-included?", "our forecast missed by 20%",
"who should own commitment purchases", "combien s'engager en Savings
Plans". Every guide declares the questions it answers (English and
French); the result is ranked by those, then by title and section
headings, and each entry carries ``matched_question`` and
``suggested_section``, the heading that ``get_reference(name=,
section=)`` takes. The facets narrow the set first; ``query`` ranks what
is left.

Use this with the facets alone for a question already in FinOps
Framework terms (domain, capability, phase, persona, maturity): "what
does a Crawl-stage org tackle first", "the Engineering reading list",
"what should Finance own in chargeback".

All filters are optional and combine with AND semantics. Facet matching
is case-insensitive and exact (not substring). Examples:

- ``find_references(query="our forecast missed by 20%, was it the model or the drivers")``
- ``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:
    query: the user's question or symptom in their own words, up to
        1,000 characters, English or French. Ranks the facet-filtered guides by
        the questions they declare, their title and their headings;
        returns at most five, best first, each with ``match_score``,
        ``matched_question`` and ``suggested_section``.
    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. Useful 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}``. With
``query`` the entries are ranked and capped at five. A facet filter that
matches nothing also returns `hint` and `valid_values`, so a typo is
distinguishable from a genuine gap in coverage; a ``query`` that matches
nothing returns `hint` alone.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "find_references"
  }
}

Input Schema

NameRequiredDescriptionDefault
phaseNo
queryNo
domainNo
personaNo
maturityNo
capabilityNo
persona_primary_onlyNo

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.51.0
    • addedInput schema / properties / query
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Query"
      +}
  2. First observedv0.1.0

TDQS

A4.4/5.0
Behavior3/5

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

Annotations already declare readOnly, idempotent, closed-world and non-destructive, so the safety profile is covered. The description goes well beyond that: ranking order (declared questions, then title and headings), a hard cap of five results, case-insensitive exact rather than substring facet matching, and distinct empty-result behavior (`hint` + `valid_values` for bad facets vs `hint` alone for queries). However, it does not state pagination or ordering guarantees for the unranked facet-only case, so a 3 rather than a 4.

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

Conciseness3/5

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

Front-loading is good — purpose first, then the two usage modes, then call examples, then args, then return shape. But there is real redundancy: the bullet example block largely repeats the inline examples already given in prose, and several sentences run long enough to bury the actionable constraint (e.g. the cap of five is stated twice in different sections).

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

Completeness5/5

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

For a 7-parameter discovery tool with 0% schema coverage, the definition covers everything an agent needs: mode selection, value vocabularies, matching semantics, result cap and ranking, and both empty-result shapes. The output schema makes the return-shape sentence optional rather than required, but its presence is harmless and reinforces the `matched_question`/`suggested_section` handoff to `get_reference`.

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

Parameters5/5

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

Schema coverage is 0% — the input schema carries only titles and defaults — so the description must carry the full burden, and it does: it documents `query` length and language limits plus ranking effects, gives domain/phase/maturity value examples, explains that `capability` matches `fcp_capability` and the secondary list, that `persona` spans primary and collaborating lists, and precisely defines `persona_primary_only` with the rationale that collaboration matching is descriptive rather than discriminating.

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

Purpose5/5

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

Opening sentence gives a specific verb+resource — find guidance that serves a FinOps question — and enumerates the question types it covers (commit, size, allocate, charge back, forecast, govern). It also names the sibling `get_reference(name=, section=)` that consumes the returned `suggested_section`, so the agent can separate discovery from retrieval.

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

Usage Guidelines5/5

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

Explicitly splits two modes: use `query` when the question is in the user's own words (with realistic multi-language examples), use facets alone when the question is already in FinOps Framework terms. It also states the combination rule (all filters optional, AND semantics) and warns that broad personas like Engineering are non-discriminating without `persona_primary_only`.

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