Skip to main content
Glama
anhnguyen0905

codex-mcp

by anhnguyen0905
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
TypeScript
Local

Aggregated Codex run metrics

codex_metrics

Aggregate token usage, duration, and failure counts from Codex metrics logs to analyze run performance. Filter by tool, session, directory, or time range; optionally include archived history.

Instructions

Roll up token/duration/failure counts from the local metrics log (~/.codex-mcp/metrics.jsonl). Set CODEX_MCP_PRICING (JSON: {inputPer1M, cachedInputPer1M, outputPer1M, reasoningOutputPer1M}) to include estCostUsd.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
cwdNoFilter by exact cwd.
toolNoFilter by which tool produced the run.
sinceNoISO 8601 lower bound — only entries at or after this timestamp are aggregated.
untilNoISO 8601 upper bound.
sessionIdNoFilter by session id.
includeHistoryNoAlso aggregate the archived history/*.jsonl files, not just the live + rotated log (default false).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.25.0
    • addedInput schema / properties / includeHistory
      Added value: +{
+  "description": "Also aggregate the archived history/*.jsonl files, not just the live + rotated log (default false).",
+  "type": "boolean"
+}
  2. Addedv0.16.0
  3. Removedv0.15.1
  4. Addedv0.8.0

TDQS

A3.8/5.0
Behavior4/5

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

With no annotations available, the description carries the full behavioral burden and does disclose the data source and the conditional CODEX_MCP_PRICING env var behavior. The read-only nature is reasonably implied by 'roll up ... from the local metrics log.' It could explicitly state side-effect-free behavior or missing-file handling, but the disclosure is solid.

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?

The description is two tight sentences: the first front-loads the action, resource, and source path; the second specifies the exact env var JSON shape. Every sentence earns its place with no filler.

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

Completeness4/5

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

The description covers the core purpose, data source, and optional cost-estimation setup, and the schema already documents all filters. Since there is no output schema, slightly more return-shape detail would improve completeness, but the mentioned 'token/duration/failure counts' and 'estCostUsd' provide a reasonable picture.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents all six parameters and their filter meanings. The description adds no per-parameter detail beyond the schema, though it does provide useful context about the pricing environment variable affecting output.

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?

The description names a specific verb and resource: 'Roll up token/duration/failure counts' from the local metrics log, with an exact file path. This clearly differentiates codex_metrics from the execution/session sibling tools by framing it as an aggregation/reporting tool.

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

Usage Guidelines2/5

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

The description says what the tool does but gives no guidance on when to use it instead of siblings like codex_sessions or codex_health. No exclusions, alternative conditions, or use-case context is provided, so the agent must infer when this tool is the right choice.

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

Install Server

Other Tools