Modal MCP

Overview Schema Source Related Servers Discussions Admin

analyze_modal_costs

Read-onlyIdempotent

Analyze Modal workspace billing to identify cost drivers, with ranked totals and period-over-period changes by app, resource, or environment.

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.

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.

Input Schema

TableJSON Schema

Name	Required	Default
`app`	No
`end`	No
`view`	No	by_app
`start`	No
`top_n`	No
`period`	No
`timezone`	No
`tag_names`	No
`resolution`	No	d
`environment`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.2.2Sep 3, 2026

TDQS

A5/5.0

Behavior5/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description adds meaningful behavior beyond that: 'Costs are fetched once and aggregated locally', 'total_cost always covers every row in range, even when groups is cut to top_n', and costs are strings with 4 decimals. 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.

Conciseness5/5

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

Long but tightly organized: purpose, example-driven usage, workspace-wide caveat, Args list, and Returns. For a tool with 10 parameters, the length is justified and every sentence adds operational value; no filler or repetition.

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?

Covers all 10 optional parameters, return shape, cost formatting, date-range edge cases, and view-specific explanation behavior. The description is complete enough for an agent to invoke this tool correctly without external documentation, even with an output schema present.

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%, but the description documents every parameter: view values, period named ranges, start/end inclusivity, resolution alternatives, timezone requirements, app filtering, environment scoping, top_n default, and tag_names format. This fully compensates for the schema's lack of property descriptions.

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 ... modal billing') and enumerates distinct views. It is unambiguous and clearly differentiated from sibling tools like deploy, run, logs, and resource management, none of which cover cost analytics.

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 common-question mappings ('what is my costliest app?' -> view="by_app", period="this month"') and explains scope ('Billing is workspace-wide... use environment to narrow it after the fact'). This gives an agent concrete decision rules for selecting the right view and parameters.

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

Deploy Server