Skip to main content
Glama

analyze_modal_costs

Read-onlyIdempotent

Break down Modal workspace billing costs by app, resource, or timeline to see ranked totals, period-over-period changes, and peak-day causes.

Instructions

Break down what the workspace is spending (`modal billing`). Costs are fetched once
and aggregated locally, so you get ranked totals and period-over-period changes
rather than hundreds of raw rows.

Answering common questions:
  "what is my costliest app?"     -> view="by_app", period="this month"
  "why was Monday expensive?"     -> view="timeline", period="last week" (the
                                     `explanation` field diffs the peak day against
                                     the day before and ranks which apps grew)
  "what did that day cost hourly?" -> view="timeline", start="2026-08-31",
                                      end="2026-09-01", resolution="h"
  "where does the money go?"      -> view="by_resource" (CPU / GPU / memory / ...)
  "what is the bill this cycle?"  -> view="summary"

Billing is workspace-wide, so this reports across every environment; use
`environment` to narrow it after the fact.

Args:
    view: "by_app" (default), "timeline" (per interval, with an explanation of the
        peak), "by_environment", "by_resource", "summary" (billed vs metered for a
        month cycle), or "rates" (current unit prices).
    period: Convenience range — "today", "yesterday", "this week", "last week",
        "this month", "last month". For "summary" also accepts "YYYY-MM".
    start / end: Explicit range instead of `period` — ISO dates ("2026-08-31") or
        relative ("3 days ago"). Start is inclusive, end exclusive; end defaults to now.
    resolution: "d" (daily, default) or "h" (hourly). Hourly is what you want when
        drilling into a single day.
    timezone: Timezone for interpreting dates — "local", an offset ("+05:30"), or an
        IANA name. Requires resolution="h".
    app: Only include apps whose name or ID contains this string (case-insensitive).
    environment: Only include rows from this Modal environment.
    top_n: How many groups/movers to return. Default 10.
    tag_names: Comma-separated cost-attribution tag names to include.
    profile: Modal profile for this call only. Defaults to the active profile.

Returns: {total_cost, groups | intervals, explanation (for timeline), row_count}.
    Costs are strings of US dollars with 4 decimals. `total_cost` always covers every
    row in range, even when `groups` is cut to top_n.

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": "analyze_modal_costs"
  }
}

Input Schema

NameRequiredDescriptionDefault
appNo
endNo
viewNoby_app
startNo
top_nNo
periodNo
profileNo
timezoneNo
tag_namesNo
resolutionNod
environmentNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.0.1
    • addedInput schema / properties / profile
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Profile"
      +}
  2. Addedv0.2.2

TDQS

A4.7/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds genuinely new behavior: local aggregation instead of raw rows, `total_cost` always covering every row even when `groups` is truncated to top_n, currency formatting to 4 decimals, and the timeline `explanation` field diffing peak day against the prior day. It does not mention auth scope or practical limits on range size, which keeps it below 5.

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

Conciseness4/5

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

Front-loaded with the core purpose, then organized into worked examples and an Args list, which is the right order for a complex tool. A few lines restate schema defaults verbatim (top_n default 10, view default by_app), which is minor waste given the otherwise dense content.

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 an 11-parameter, all-optional analytics tool with 0% schema documentation, the description supplies the argument semantics, the return shape, and the scope caveats needed to call it correctly. An output schema exists, so the extra Returns summary is a bonus rather than a necessity.

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 description coverage is 0%, so the description carries the full burden and does so: it enumerates all view values with their semantics, lists accepted period keywords plus the YYYY-MM exception for summary, defines start/end inclusivity and the end-defaults-to-now rule, gives the timezone constraint (requires resolution="h"), and explains app, environment, top_n, tag_names and profile. This is meaning well beyond bare schema titles.

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?

States a specific verb and resource ("Break down what the workspace is spending") and immediately clarifies a non-obvious property: costs are fetched once and aggregated locally. No sibling tool in the catalog deals with billing, so an agent can route here unambiguously.

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?

Provides explicit question-to-parameters mappings ("what is my costliest app?" -> view="by_app", period="this month") and states which resolution to pick when drilling into a day. It also flags the scope caveat that billing is workspace-wide and `environment` narrows it after the fact, so the agent knows the alternative reading of a filtered query.

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