Skip to main content
Glama

record_actual

Submit actual hours for a previous estimate to improve future accuracy and reduce estimation bias through automatic correction factors.

Instructions

Submit actual hours for a previous estimate to improve future accuracy.

Pairs with any estimation tool. The estimate_id comes from the estimate response. Actuals feed into the self-improvement loop — after enough samples, correction factors update automatically to reduce estimation bias.

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": {
      "estimate_id": "<estimate_id>",
      "actual_hours": "<actual_hours>"
    },
    "name": "record_actual"
  }
}

Input Schema

NameRequiredDescriptionDefault
unitNoUnit 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.
notesNoOptional context.
estimate_idYesID of the estimate to update.
actual_hoursYesActual hours spent.
calibration_provenanceNoOptional 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.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.8.0
    • removedInput schema / additionalProperties
      Removed value: -false
    • addedInput schema / 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 / 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.6/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the write-profile is known. The description adds genuine downstream behavior — actuals feed a self-improvement loop and correction factors update after enough samples — which is useful context. However, it does not warn that non-idempotent resubmission creates additional records, nor what the call returns; with annotations covering safety, this lands at a 3.

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?

Three short sentences, front-loaded with the action and followed by the pairing and feedback-loop mechanics; nothing is padding. It is slightly loose in the middle ('Pairs with any estimation tool') but overall efficient.

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

Completeness3/5

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

For a write tool with no output schema, the description explains the calibration side effect but omits what the caller gets back and whether repeat submissions are additive. With 5 parameters and rich schema coverage, the remaining gap is modest but real.

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%, with detailed per-parameter text including unit normalization conventions and the full calibration_provenance taxonomy. The description only adds the provenance of estimate_id, so the schema does the heavy lifting and the baseline of 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 — 'Submit actual hours for a previous estimate' — and adds the downstream purpose (improving estimation accuracy). It clearly differs from the batch sibling in shape, though it never names that sibling or any alternative, so differentiation is implied rather than explicit.

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 clear usage context: use it after an estimation tool has produced an estimate, and 'the estimate_id comes from the estimate response.' That is a concrete prerequisite. It stops short of naming when not to use it (e.g., bulk entry via batch_record_actuals) or how duplicates are handled.

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