Skip to main content
Glama

batch_record_actuals

Record actual hours for up to 500 estimates in one call, pairing estimate IDs with real time spent. Use it to close the feedback loop and submit bulk actuals from pending estimates.

Instructions

Record actual hours for multiple estimates in a single call.

Efficient for bulk feedback submission — accepts 1 to 500 entries at once. Each entry pairs an estimate ID with the actual hours spent. Returns total/succeeded/failed counts. Use when closing the feedback loop for many estimates at once; pass estimate_id values from get_pending_estimates.

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": {
      "entries": "<entries>"
    },
    "name": "batch_record_actuals"
  }
}

Input Schema

NameRequiredDescriptionDefault
entriesYesArray of actual-hour records (1–500 entries).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.8.0
    • removedInput schema / additionalProperties
      Removed value: -false
    • removedInput schema / properties / entries / items / additionalProperties
      Removed value: -false
    • addedInput schema / properties / entries / items / properties / calibration_provenance
      Added value: +{
      +  "description": "Optional explicit provenance classification for this actual, consumed by the shared exclusion predicate (synthetic/smoke are excluded from calibration math). auto_wallclock marks a wall-clock-derived actual auto-recorded at session end (never focused-effort-verified) — included in correction training by default but subject to a dedicated sanity gate and segmented separately in feedback_health. git_derived marks a cycle-time actual mined from git history by `epoch mine-git` (first-commit→merge dev window); git_derived_review_inclusive marks the open→merge window — both are sanity-gated and segmented separately, never blended with verified actuals.",
      +  "enum": [
      +    "prospective",
      +    "backfilled_real_session",
      +    "backfilled_calibration",
      +    "synthetic",
      +    "smoke",
      +    "unknown",
      +    "auto_wallclock",
      +    "git_derived",
      +    "git_derived_review_inclusive"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / entries / items / properties / unit
      Added value: +{
      +  "description": "Unit actual_hours is expressed in. Normalized to hours at ingest (days=8h, weeks=40h workday convention, matching estimation.ts's toHours()). Defaults to hours when omitted.",
      +  "enum": [
      +    "minutes",
      +    "hours",
      +    "days",
      +    "weeks"
      +  ],
      +  "type": "string"
      +}
  2. First observedv0.1.0

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already declare the mutation/non-idempotent/non-destructive profile, and the description adds useful context on top: the 1–500 entry ceiling and the total/succeeded/failed return shape, which tells the agent partial failures are possible. It does not address retry semantics or what happens to already-recorded entries in a partially failed batch, which matters given idempotentHint=false.

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?

Four short sentences, front-loaded with the core action and batch scope, with the guidance sentence last. The '1 to 500 entries' claim duplicates the schema's minItems/maxItems, a minor redundancy, but nothing is bloated.

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?

With no output schema, the description compensates by naming the return fields (total/succeeded/failed), and it explains the bulk boundary and where estimate IDs come from. For a single-parameter mutation tool this covers what an agent needs, with only retry/duplicate-handling left unstated.

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 coverage is 100% and the nested entries object already documents estimate_id, actual_hours, unit normalization, notes, and the provenance enum in detail. The description only restates the estimate-ID/actual-hours pairing, adding no meaning beyond the schema — baseline 3 applies.

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?

States a specific verb and resource (record actual hours) plus an explicit scope qualifier: 'for multiple estimates in a single call.' That bulk scope implicitly separates it from the singular record_actual sibling, though the description never names that alternative outright.

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 a concrete usage condition ('when closing the feedback loop for many estimates at once') and points to a sibling source for inputs ('pass estimate_id values from get_pending_estimates'). It stops short of an explicit exclusion such as 'use record_actual for a single estimate,' so the when-not side is left to inference.

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