Itential MCP Server

Official

by itential

Overview Schema Source Related Servers Discussions Admin

Python

Remote

Get Agent Token Usage

get_agent_token_usage

Read-onlyIdempotent

Aggregate agent token usage by agent name, calculating input and output token sums, averages, and min/max per agent from completed sessions. Filter by agent, date range, or include failed sessions.

Instructions

Aggregate agent session token usage grouped by agent name.

Fetches agent sessions and groups them by agent name, computing token consumption statistics (sum, average, min, max) for both input and output tokens per agent. Sessions with missing or null token values are still counted toward session_count but contribute 0 to sum, average, and min/max calculations. Sessions with no agent name are grouped under a None-keyed entry rather than dropped. Only COMPLETE sessions are included by default — see include_failed to also include FAILED sessions. Sessions that failed before an execution-engine session ID was assigned are not included.

Input Schema

Name	Required	Description
`agent_name`	No	Filter to agent names containing this substring (case-insensitive)
`started_after`	No	ISO 8601 timestamp — only include sessions started at or after this time
`include_failed`	No	By default only COMPLETE sessions count toward usage (finished, billable work). Set true to also include FAILED sessions, which can still have consumed real tokens. Non-terminal statuses (PENDING, RUNNING, PAUSED, ...) are always excluded either way, since their totals aren't final.
`started_before`	No	ISO 8601 timestamp — only include sessions started at or before this time

Output Schema

Name	Required	Description	Default
`result`	Yes	Response model for the agent token usage aggregation endpoint. Wraps a list of AgentTokenUsageStats objects, one per distinct agent name (including a None-keyed entry for sessions with no agent name), sorted by total_tokens descending. Attributes: root: List of AgentTokenUsageStats objects with aggregated token usage metrics per agent.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.13.3Aug 7, 2026

TDQS

A4/5.0

Behavior5/5

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

Annotations already establish readOnly, idempotent, and closed-world behavior, so the bar for added behavioral context is lower. The description goes well beyond that by disclosing aggregation logic, handling of missing or null token values, None-keyed groups for sessions without an agent name, default exclusion of FAILED and non-terminal sessions, and the omission of sessions that failed before receiving an execution-engine session ID.

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?

The description is front-loaded with the core aggregation purpose and then efficiently covers important edge cases. It is somewhat long and the second sentence partially restates the first by explaining the grouping and statistics again, but every remaining sentence adds meaningful behavioral detail.

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?

Given a moderate-complexity aggregation tool with an output schema, complete parameter descriptions, and strong annotations, the description supplies everything needed to invoke it correctly. It covers aggregation scope, filtering defaults, session-status handling, and edge cases without needing to explain return values.

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 itself already documents all four parameters thoroughly, including include_failed. The description reinforces the include_failed semantics but adds little parameter-level information beyond what the schema already provides, so the baseline 3 is appropriate.

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

Purpose4/5

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

The description states a specific verb and resource: aggregate agent session token usage grouped by agent name, with per-agent statistics for input and output tokens. That distinguishes it from generic session-listing tools, but it does not explicitly name or contrast with the close sibling get_agent_session_token_usage, so it falls 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.

Usage Guidelines3/5

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

It explains the default inclusion rule for COMPLETE sessions and directs the agent to include_failed for FAILED sessions, which is useful behavioral context. However, it gives no explicit guidance on when to choose this tool over alternatives such as get_agent_session_token_usage or describe_session_token_usage, leaving tool selection implied rather than stated.

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

Deploy Server