Reference
MCP tools
The tools your assistant gets when you add IA4AI as an MCP connector, what each answers, and the endpoint behind it.
Every tool is a read of your own workspace, except ingest_trace, which sends one run for investigation. Each one
calls a REST endpoint with your key, so it returns exactly what the API returns, scoped the
same way. To add the connector, see Ask IA4AI from your AI tool.
The descriptions below are the ones your assistant is given when it chooses a tool. They tell it to relay numbers as given, and to state a saving only where one was verified.
| Tool | What it answers |
|---|---|
my_ai_overview |
The answer to "what is my AI doing?": usage and spend, agents, live connections, what is wrong and what to do next. |
agents_report |
Per agent (each app or bot that sent model calls): how many calls, what they cost, which models and tools it used, its tool failures, and when it was last seen. |
agent_work |
Per agent and per kind of job: where its money goes and what would cost less (a smaller context, a cheaper model of the same provider, off-peak hours), from call metadata only, never the prompts. |
run_report |
The run-by-run view, summarised for an assistant: the findings, each agent's totals, and the 10 costliest runs. |
context_events |
Why an agent pays full price for input it already sent: the calls where the provider's cache missed, the context resets, and the dollars each cost, from token counts only. |
job_review |
Not a list of runs: only the jobs where something real could change, each summarised, the rest in one line. |
job_report |
Read one job without reading its 200 steps. |
model_tests |
The proof in progress: a sample of your real calls also ran on a cheaper model and the two answers were compared. |
local_box |
The buy-a-box answer from your own calls: which agents' calls a 128 GB local box could run (context size), how slow they would be (measured box speeds, sources dated), and the box's price against what those calls cost now. |
alternative_plan |
Your bill against running open models yourself: each call placed at the lowest tier that could take it (from its difficulty and length), the servers that volume needs (sourced, dated prices), what each mix costs a month against what the calls cost now, and unused chat seats. |
spend_report |
Where the money goes: total spend and tokens, broken down by model, by task type and by day, plus the calls whose model has no known price yet. |
list_cases |
Returns every investigation this key is allowed to see as a compact table — case id, job, finding count, verdict count, and cost. |
list_investigations |
Every investigation of this workspace's spend over a period: when it was opened, the period it covers, whether it is published, and how many findings it has. |
investigation_conclusions |
What a person reads first: the conclusions written from the investigation's measured findings (every number checked against them), the single most useful next step, and the chart's data. |
get_case |
Opens a single case file in full: the findings, policy verdicts, cost rollup, root-cause analysis, and the reasons behind each decision. |
cost_cuts |
Names cheaper models that meet the job's needs as candidates to test, and the savings only of swaps a golden-set run verified, so nobody switches on a price list alone. |
ingest_trace |
Hands one agent run (its job description plus the raw trace/spans) to the system for investigation, and returns the new case id. |
verify_evidence |
Re-checks the hash-chained, signed evidence log and reports whether any record has been tampered with since it was written. |
#Ask about your AI
#my_ai_overview
The answer to "what is my AI doing?": usage and spend, agents, live connections, what is wrong and what to do next. The same figures as the dashboard's Overview and Connect screens.
What your assistant is told: Start here for any question about this company's AI use. Returns, for the workspace this key belongs to: a one-line headline, model calls and spend, when the last call arrived, which agents and models, which connections are live, the problems found (each with its fix) and the next step.
| Calls | Needs | Arguments |
|---|---|---|
GET /workspace/summary |
viewer |
none |
#agents_report
Per agent (each app or bot that sent model calls): how many calls, what they cost, which models and tools it used, its tool failures, and when it was last seen.
What your assistant is told: Each agent seen in this workspace: model calls, cost, models, tools used, failures, last seen.
| Calls | Needs | Arguments |
|---|---|---|
GET /report/agents |
viewer |
none |
#agent_work
Per agent and per kind of job: where its money goes and what would cost less (a smaller context, a cheaper model of the same provider, off-peak hours), from call metadata only, never the prompts.
What your assistant is told: What each agent does and why it costs what it does: cost split (uncached input, cached input, output), context size per call and its growth per task, cache share, cost per task run, peak vs off-peak spend, the tools it asks for, calls stopped mid-answer, and advice (each marked measured or estimated).
| Calls | Needs | Arguments |
|---|---|---|
GET /report/agent-work |
viewer |
none |
#run_report
The run-by-run view, summarised for an assistant: the findings, each agent's totals, and the 10 costliest runs. Pass a run_id (from top_runs) to expand one run into its numbered steps. From call metadata only.
What your assistant is told: Each agent's runs and the candidate findings, summarised: the findings, a per-agent roll-up, and the 10 costliest runs. Pass run_id to expand one run into its numbered steps.
| Calls | Needs | Arguments |
|---|---|---|
GET /report/runs |
viewer |
run_id |
#context_events
Why an agent pays full price for input it already sent: the calls where the provider's cache missed, the context resets, and the dollars each cost, from token counts only.
What your assistant is told: Where each agent's uncached input (the expensive part) comes from: new content, task starts, context resets (compaction), and cache misses, after a pause longer than the cache lasts or without one, with what the misses cost and what a cache hit would have saved. The latest events, call by call.
| Calls | Needs | Arguments |
|---|---|---|
GET /report/context-events |
viewer |
none |
#job_review
Not a list of runs: only the jobs where something real could change, each summarised, the rest in one line.
What your assistant is told: Jobs worth a look: short summaries of the few agent jobs whose junior or waiting steps cost enough to change, or that reached a production server or looked for secrets; every other job in one line. Each summary: what was asked, how it ended, the senior/junior/waiting split with dollars, what would cost less, and flags. No saving is stated.
| Calls | Needs | Arguments |
|---|---|---|
GET /report/job-review |
viewer |
none |
#job_report
Read one job without reading its 200 steps.
What your assistant is told: One job written up: the story in plain words (what was asked, how long, what it cost, how it ended), where the money went (senior / junior / waiting), whether it did only what it was asked, the options for its junior and waiting steps, and every step grouped into pieces of work. Pass a run_id from job_review.
| Calls | Needs | Arguments |
|---|---|---|
GET /report/job/{run_id} |
viewer |
run_id |
#model_tests
The proof in progress: a sample of your real calls also ran on a cheaper model and the two answers were compared. Shows matches per pair, and says plainly if your key's scope blocks a test.
What your assistant is told: Cheaper-model tests on live calls: for each pair (current model → cheaper candidate), how many real calls the side-by-side test sampled, how many the candidate matched, the match rate it is sure of, what the samples cost, and whether a stored key's model scope blocks the test. No saving is stated.
| Calls | Needs | Arguments |
|---|---|---|
GET /report/model-tests |
viewer |
none |
#local_box
The buy-a-box answer from your own calls: which agents' calls a 128 GB local box could run (context size), how slow they would be (measured box speeds, sources dated), and the box's price against what those calls cost now. From call metadata only, never the prompts.
What your assistant is told: Should this company buy a local AI box (Mac Studio M5 Max, DGX Spark, Ryzen AI Max+ 395)? Which calls would fit one, how many seconds each would take on it, what those calls cost now, and each box's price in months of that cost. Never a saving: quality needs a replay of the calls on the local model first.
| Calls | Needs | Arguments |
|---|---|---|
GET /report/local-box |
viewer |
none |
#alternative_plan
Your bill against running open models yourself: each call placed at the lowest tier that could take it (from its difficulty and length), the servers that volume needs (sourced, dated prices), what each mix costs a month against what the calls cost now, and unused chat seats. From call metadata only.
What your assistant is told: The alternative plan: this company's AI bill (API calls and chat seats) against open models on its own hardware, in three tiers (Good: one 96 GB card; Pro: an 8-GPU H200 server; Premium: 16 B200 GPUs). Which work each tier could take, the hardware that volume needs, each mix's monthly cost rented or bought, and the company's privacy choice. Never a saving: quality needs a replay of the calls on the open model first.
| Calls | Needs | Arguments |
|---|---|---|
GET /report/alternative-plan |
viewer |
none |
#spend_report
Where the money goes: total spend and tokens, broken down by model, by task type and by day, plus the calls whose model has no known price yet.
What your assistant is told: Spend in detail: totals, per model, per task type, per day, and calls with no known price.
| Calls | Needs | Arguments |
|---|---|---|
GET /report/spend |
viewer |
none |
#list_cases
Returns every investigation this key is allowed to see as a compact table — case id, job, finding count, verdict count, and cost.
What your assistant is told: List investigation case files (one per analysed agent run: findings, cost). Often empty while usage exists; for usage, spend and agents use my_ai_overview.
| Calls | Needs | Arguments |
|---|---|---|
GET /cases |
viewer |
none |
#list_investigations
Every investigation of this workspace's spend over a period: when it was opened, the period it covers, whether it is published, and how many findings it has.
What your assistant is told: List this workspace's investigations (one per period the client asked about): case id, period, state and finding count. Use investigation_conclusions on a case id for its answer.
| Calls | Needs | Arguments |
|---|---|---|
GET /workspace/client-cases |
viewer |
none |
#investigation_conclusions
What a person reads first: the conclusions written from the investigation's measured findings (every number checked against them), the single most useful next step, and the chart's data.
What your assistant is told: An investigation's answer in brief: up to five conclusions with what to do, the next step, the data of its one chart, and the findings they rest on. Relay the numbers as given; do not recompute them.
| Calls | Needs | Arguments |
|---|---|---|
GET /workspace/client-cases/{case_id}/conclusions |
viewer |
case_id |
#get_case
Opens a single case file in full: the findings, policy verdicts, cost rollup, root-cause analysis, and the reasons behind each decision.
What your assistant is told: Fetch one full case file: findings, verdicts, cost, root cause.
| Calls | Needs | Arguments |
|---|---|---|
GET /case/{case_id} |
viewer |
case_id |
#cost_cuts
Names cheaper models that meet the job's needs as candidates to test, and the savings only of swaps a golden-set run verified, so nobody switches on a price list alone.
What your assistant is told: Cheaper models to test for a case. A saving is stated only for a swap a verification run on the client's own calls showed does the work; untested candidates carry no saving.
| Calls | Needs | Arguments |
|---|---|---|
GET /case/{case_id}/cost-cuts |
viewer |
case_id |
#Send a run
#ingest_trace
Hands one agent run (its job description plus the raw trace/spans) to the system for investigation, and returns the new case id.
What your assistant is told: Send one agent run (job + trace) to be investigated. Returns the case id.
| Calls | Needs | Arguments |
|---|---|---|
POST /ingest/trace |
investigator |
job, trace |
#Check the records
#verify_evidence
Re-checks the hash-chained, signed evidence log and reports whether any record has been tampered with since it was written.
What your assistant is told: Prove the tamper-evident evidence log has not been altered.
| Calls | Needs | Arguments |
|---|---|---|
GET /audit/evidence-log/verify |
viewer |
none |

