Skip to main content
Glama

Report computation

report_computation
Destructive

Say how a computation an issue rests on stands — a GAP run, a batch of work units, a Lean build that ran somewhere else; the tracker runs nothing. Call it when the job is submitted, as it progresses and when it ends, with the same 'source' + 'externalId' every time: that is one job, updated, never a second. Send only what you know now — a field left out keeps what an earlier report said, so a progress report need not repeat the commit. 'state' is queued, running, done, failed, cancelled or lost (a job whose runner stopped answering); 'starting' reads as running. Report the commit it ran at and the repository's web address: that is what makes a [computer] result checkable, and the answer's 'commitUrl' links it where the host is GitHub or GitLab. 'result' is what came of it, in a sentence — Markdown and $…$ formulas work. Say what it spent when you know it — 'machine', 'cores', 'cpuSeconds' (processor time so far, all cores together; send the running total each time, it is not added up), 'wallSeconds', 'gpuSeconds' — and always on the last report, a failed or cancelled job's included: that is what the issue's and the project's machine-hours and costs are counted from. A job on a service billed by the second (Modal: machine 'modal') also says 'memoryGiB' and 'gpuType' beside 'gpuSeconds', which its tariff prices; where you know what the service billed for the job, send 'costUsd' — it wins over the cost worked out from the price list. Answers with 'created' and 'stateBefore'. A name already reported on another issue is refused with that issue's key. Requires permission to edit the issue.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "key": "<key>",
      "source": "<source>",
      "externalId": "<externalId>"
    },
    "name": "report_computation"
  }
}

Input Schema

NameRequiredDescriptionDefault
keyYesThe issue the computation answers, e.g. 'MATH-74'.
urlNoThe job's own page on its runner (http/https).
coresNoCores allocated to it, e.g. 8 (or 0.5).
stateNoqueued, running, done, failed, cancelled or lost.
titleNoWhat it computes, in words, e.g. 'rank 5, order 2^11, stage C'.
commitNoThe commit it ran at.
resultNoWhat came of it, a sentence or two. Markdown, $...$ formulas.
sourceYesWho runs it, e.g. 'tm' or 'boinc'. The job's name is unique within it.
commandNoHow it was run: the command line or the job's description.
costUsdNoWhat the service itself billed for the job, in US dollars, where you know it (Modal's billing report). It wins over the cost worked out from the price list.
gpuTypeNoThe GPU's type, e.g. 'H100', 'A100-80GB', 'L4' — what a tariff prices a GPU-second by.
machineNoThe machine it ran on, e.g. 'kimmy', 'ax42', 'modal'.
memoryGiBNoMemory allocated to it in GiB — billed by a tariff such as Modal's.
outputUrlNoWhere its output can be fetched (http/https).
startedAtNoWhen it started (ISO 8601). Left out, a move to running stamps now.
cpuSecondsNoProcessor time used so far, all cores together, in seconds — the running total, not an increment.
externalIdYesThe job's own name there, e.g. 'kimmy/gap/m74r5u'. The same name again updates the job.
finishedAtNoWhen it ended (ISO 8601). Left out, a move to a finished state stamps now.
gpuSecondsNoGPU time in seconds, where there was one.
repositoryNoThe repository's web address, e.g. 'https://github.com/org/repo'.
wallSecondsNoIts wall clock in seconds, where the runner counts it otherwise than end minus start.
progressDoneNoHow much is done, as the runner counts, e.g. 812.
progressTotalNoOut of how much, e.g. 1695.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • addedInput schema / properties / costUsd
      Added value: +{
      +  "default": null,
      +  "description": "What the service itself billed for the job, in US dollars, where you know it (Modal's billing report). It wins over the cost worked out from the price list.",
      +  "type": [
      +    "number",
      +    "null"
      +  ]
      +}
    • addedInput schema / properties / gpuType
      Added value: +{
      +  "default": null,
      +  "description": "The GPU's type, e.g. 'H100', 'A100-80GB', 'L4' — what a tariff prices a GPU-second by.",
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
    • addedInput schema / properties / memoryGiB
      Added value: +{
      +  "default": null,
      +  "description": "Memory allocated to it in GiB — billed by a tariff such as Modal's.",
      +  "type": [
      +    "number",
      +    "null"
      +  ]
      +}
  2. Changed5 schema fields changed
    • addedInput schema / properties / cores
      Added value: +{
      +  "default": null,
      +  "description": "Cores allocated to it, e.g. 8 (or 0.5).",
      +  "type": [
      +    "number",
      +    "null"
      +  ]
      +}
    • addedInput schema / properties / cpuSeconds
      Added value: +{
      +  "default": null,
      +  "description": "Processor time used so far, all cores together, in seconds — the running total, not an increment.",
      +  "type": [
      +    "number",
      +    "null"
      +  ]
      +}
    • addedInput schema / properties / gpuSeconds
      Added value: +{
      +  "default": null,
      +  "description": "GPU time in seconds, where there was one.",
      +  "type": [
      +    "number",
      +    "null"
      +  ]
      +}
    • addedInput schema / properties / machine
      Added value: +{
      +  "default": null,
      +  "description": "The machine it ran on, e.g. 'kimmy', 'ax42', 'modal'.",
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
    • addedInput schema / properties / wallSeconds
      Added value: +{
      +  "default": null,
      +  "description": "Its wall clock in seconds, where the runner counts it otherwise than end minus start.",
      +  "type": [
      +    "number",
      +    "null"
      +  ]
      +}
  3. Added

TDQS

A4.5/5.0
Behavior5/5

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

With annotations already declaring non-read-only and destructive, the description still adds substantial behavior: merge semantics ("a field left out keeps what an earlier report said"), cross-issue name-uniqueness refusal, the permission requirement, the 'created' / 'stateBefore' response fields, the meaning of 'lost' ("a job whose runner stopped answering"), and the 'starting'-reads-as-running alias. It also discloses derived behavior — commitUrl linking for GitHub/GitLab hosts, machine-hours and costs computed from the last report, and costUsd overriding the price list.

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

Conciseness3/5

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

The purpose is front-loaded and there is almost no filler, but the body is a single dense run-on of em-dash clauses where idempotency, state vocabulary, billing rules and permissions blur together. For a 23-parameter tool some length is justified, yet splitting identity/merge semantics from the billing rules would make it far more scannable.

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 a destructive, 23-parameter, no-output-schema tool, the description covers what an agent needs: the upsert identity contract, partial-update behavior, required permission, the conflict error case, and the response fields. Nothing essential to calling it correctly is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-field rules the schema cannot express: the Modal case requires 'memoryGiB' and 'gpuType' alongside 'gpuSeconds', costUsd wins over the computed tariff, and cpuSeconds is a running total to be resent rather than added up. It also ties 'source' + 'externalId' to job identity, which gives those two required parameters meaning beyond their individual definitions.

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?

"Say how a computation an issue rests on stands — a GAP run, a batch of work units, a Lean build that ran somewhere else; the tracker runs nothing" names a specific verb (report status) and resource (computation attached to an issue), and explicitly rules out the misreading that it executes anything. The examples (GAP, work units, Lean build) make it distinguishable from siblings like list_computations, delete_computation and report_lean_audit.

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

Usage Guidelines4/5

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

Gives concrete when-to-use guidance: "Call it when the job is submitted, as it progresses and when it ends, with the same 'source' + 'externalId' every time: that is one job, updated, never a second." That covers the full lifecycle and the idempotency contract. It stops short of naming alternatives (e.g. delete_computation for removal, list_computations for reading back), so it is not a full 5.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources