Epoch is a time estimation MCP server that gives AI agents grounded, data-driven scheduling capabilities across 25 tools, replacing guesswork with established estimation methods.
Time & Calendar Operations
Get current time in any IANA timezone, convert timestamps, and parse human-readable durations (e.g., 2h30m, 1w3d)
Add or count business days with public holiday support for US, UK, FR, DE, and JP
Estimation Methods
PERT three-point estimation with confidence intervals and urgency scoring
COCOMO II LLM-adapted software sizing returning nominal and AI-adjusted person-months
Sprint velocity forecasting from historical sprint data
Critical Path Method (CPM) with slack per task and merge-bias adjustment
Monte Carlo simulation for probabilistic schedule risk (P10/P50/P80/P95)
Analytics & Reference Class Forecasting
Data-driven estimates from 126,223+ real task data points with planning fallacy correction
Classify free-text task descriptions and auto-delegate to reference class forecasting
Compute team-specific correction factors from historical estimated vs. actual data
Map LLM token budgets to wall-clock time for 12 model families
Cost & Risk Analysis
Estimate token costs and wall-clock time for LLM API calls by model
Side-by-side model comparison by cost, speed, and quality
Schedule risk scoring with confidence intervals (P50/P80/P95)
Validate COCOMO estimates against 195–240 real historical projects (NASA93, COCOMO81, etc.)
Feedback & Self-Improvement
Record actual hours against previous estimates to calibrate future accuracy
Batch-record up to 500 actuals at once
Track accuracy trends over time (sliding-window MAPE by tool/task type)
Monitor feedback loop health and self-improvement readiness
All self-improvement data stored locally and privately, with optional opt-in for anonymized community sharing
Epoch is a time estimation MCP server that helps engineering leads, agents, and planners who need calibrated duration estimates produce PERT/reference-class estimates and record actuals.
TL;DR: Epoch — time estimation MCP server. Best for engineering leads, agents, and planners who need calibrated duration estimates.
Epoch helps AI agents understand time.
AI can write code, analyze data, and build apps -- but it can't tell you how long something will take, what it'll cost, or whether a deadline is realistic. Epoch fixes that.
You: "How long will a 15,000 line project take with a small team?"
Claude (using Epoch):
COCOMO II nominal: 100 person-months (traditional team)
AI-adjusted: 9 person-months (LLM-assisted workflow)
Schedule risk: medium (MAPE 15%, based on 28 historical features)
Cost estimate (Claude Sonnet): ~$340 in API tokensYou: "How many working days between now and launch?"
Claude (using Epoch):
Start: May 1, 2026
End: July 15, 2026
Business days: 54
Weekend days: 16
Holidays: 1 (Independence Day)
Total calendar days: 75You: "Which AI model should we use for a 50k-token job?"
Claude (using Epoch):
gemini-2.0-flash: $0.02 -- fast, budget-friendly
gpt-4o-mini: $0.02 -- fast, budget-friendly
gemini-2.5-pro: $0.37 -- standard, high quality
claude-sonnet-5: $0.57 -- standard, high quality
Recommendation: gemini-2.0-flash for cost, claude-sonnet-5 for qualityRelated MCP server: @isteamhq/mcp
Every AI agent hallucinates timelines. "This should take about 2 hours" becomes 2 days. Epoch gives AI grounded, data-driven estimates instead of guesses. It packages established estimation methods (PERT, COCOMO II, Monte Carlo, reference class forecasting) into 25 tools any AI can call -- so your assistant stops guessing and starts calculating.
Works out of the box. Epoch ships with a bundled reference database built from 117,791 real data points across task types, complexity levels, and estimation tools. You get accurate estimates from day one — no data collection or account setup required. If you choose to record your actuals, Epoch's self-improvement engine learns your patterns and gets even more precise over time.
MCP (Model Context Protocol) is how AI assistants like Claude connect to external tools. Think of it like a plugin system -- you add Epoch with one command, and suddenly your AI assistant can estimate timelines, calculate business days, compare model costs, and predict whether your project will finish on time.
30-second setup -- works in Claude Code, Cursor, VS Code, and Windsurf:
claude mcp add epoch -- npx @kyanitelabs/epochThat's it. Your AI assistant now has 25 time estimation tools.
Or add it to your project's .mcp.json:
{
"mcpServers": {
"epoch": {
"command": "npx",
"args": ["@kyanitelabs/epoch"]
}
}
}Epoch also ships a public agent skill at skills/epoch/SKILL.md. Use $epoch in compatible agent hosts when you want the agent to choose the right Epoch MCP or CLI workflow for time estimates, business-day math, model-cost comparison, schedule risk, and estimate-vs-actual feedback.
What you want | What Epoch does | No jargon |
"How long will this take?" | Gives you a realistic estimate with best/worst case ranges | Estimates |
"Can we hit this deadline?" | Tells you if your timeline is realistic or risky | Schedule risk |
"How much will the AI calls cost?" | Calculates token costs across 16 AI models side-by-side | Cost comparison |
"How many business days between now and launch?" | Counts days excluding weekends and holidays (5 countries) | Calendar math |
"Are our estimates getting better?" | Tracks your accuracy over time and auto-corrects | Self-improving |
"What model should we use?" | Compares speed, cost, and quality across all major AI models | Model comparison |
Everything below is for developers who want to understand the internals, use the CLI or REST API, or contribute to Epoch.
Six-layer design with 25 tools for time estimation, scheduling, cost analysis, and feedback:
Layer | Purpose | Tools |
1. Core Temporal | Time, timezones, duration, date math |
|
2. Calendar Math | Business days, holidays (US/UK/FR/DE/JP) |
|
3. Estimation | PERT, COCOMO II, sprint, CPM, Monte Carlo |
|
4. Analytics | Reference class, context classification, calibration, token-time bridge |
|
5. Cost & Risk | Token cost, model comparison, accuracy trends, risk, COCOMO validation |
|
6. Feedback | Record actuals, track pending estimates, batch operations, health checks |
|
get_current_time -- Current wall-clock time in any IANA timezone
Input: { timezone: "America/New_York" }
Output: {
iso: "2026-05-01T08:30:00.000-04:00",
humanReadable: "Fri, May 1, 2026, 8:30 AM EDT",
timezone: "America/New_York",
utcOffset: "-04:00"
}convert_timezone -- Convert a timestamp between IANA timezones
Input: { timestamp: "2026-05-01T12:00:00Z", target_tz: "Asia/Tokyo" }
Output: {
iso: "2026-05-01T21:00:00.000+09:00",
timezone: "Asia/Tokyo",
utcOffset: "+09:00",
humanReadable: "Fri, May 1, 2026, 9:00 PM JST"
}parse_duration -- Parse human-readable duration strings
Input: { duration_string: "2h30m" }
Output: {
input: "2h30m",
totalSeconds: 9000,
humanReadable: "2 hours 30 minutes"
}time_math -- Date arithmetic operations
Input: { operation: "add_days", date: "2026-05-01", value: 7 }
Output: {
result: "2026-05-08T00:00:00.000Z",
operation: "add_days",
input: "2026-05-01"
}Supported operations: add_days, add_business_days, diff, convert_tz, parse_nl, format_duration
add_business_days -- Add N business days with holiday awareness (US, UK, FR, DE, JP)
Input: { start_date: "2026-05-01", days: 5, country: "US" }
Output: {
startDate: "2026-05-01",
endDate: "2026-05-08",
businessDays: 5,
countryCode: "US",
holidaySupport: "holiday_calendar",
humanReadable: "5 business days from 2026-05-01 to 2026-05-08 (US)."
}count_business_days -- Count business days between two dates
Input: { start_date: "2026-05-01", end_date: "2026-05-15", country: "US" }
Output: {
startDate: "2026-05-01",
endDate: "2026-05-15",
businessDays: 10,
countryCode: "US",
holidaySupport: "holiday_calendar",
humanReadable: "10 business days between 2026-05-01 and 2026-05-15 (US)."
}Both tools always include holidaySupport ("holiday_calendar" when the country has a bundled holiday set — US/UK/FR/DE/JP — otherwise "weekends_only") in successful output; country must match ^[A-Za-z]{2}$ — "USA"-style codes are rejected with a readable error.
pert_estimate -- PERT three-point estimation with confidence intervals and urgency scoring
Input: {
optimistic: 2,
most_likely: 4,
pessimistic: 12,
unit: "hours"
}
Output: {
expected: 5,
variance: 2.78,
stdDeviation: 1.67,
confidence95: [1.67, 8.33],
confidence99: [0, 10],
unit: "hours",
urgencyCategory: "medium",
riskLevel: "high",
humanReadable: "Expected 2.86–7.14 hours (80% confidence interval); point estimate 5 hours (ledger-recorded basis; adjustedEstimate 5 applies the correction factor). No task_type was supplied, so this interval is derived from the PERT variance (optimistic/most_likely/pessimistic spread) instead of empirical data.",
developerProfile: { mode: "ai_native", correctionFactor: 1 },
adjustedEstimate: 5,
rawEstimate: 5,
correctionFactor: 1,
n: 0,
interval: { p50: { lower: 3.87, upper: 6.13 }, p80: { lower: 2.86, upper: 7.14 }, p90: { lower: 2.25, upper: 7.75 }, source: "pert_variance" },
intervalNote: "No task_type was supplied, so this interval is derived from the PERT variance (optimistic/most_likely/pessimistic spread) instead of empirical data.",
basisNote: "Interval and point estimate are on the ledger-recorded basis (raw PERT expected × unit factor). adjustedEstimate (5 hours) additionally applies the correction factor (1) and is display-only — it is never recorded or calibrated against."
}(Example from a fresh install with no accumulated feedback; with ≥5 exclusion-filtered matched pairs for the task type, interval.source becomes "empirical_ratio_quantile", n reports the sample size, and intervalPopulation names the ratio population used.)
cocomo_estimate -- COCOMO II software sizing with LLM-adapted cost drivers
Input: {
kloc: 15,
reasoning_complexity: 1.2,
context_completeness: 1.0,
transformation_impact: 0.8,
iterative_cycles: 1.5,
human_oversight: 1.2
}
Output: {
kloc: 15,
personMonthsNominal: 99.9,
personMonthsLlmAdjusted: 8.9,
effortMultipliers: {
reasoning_complexity: 1.2,
context_completeness: 1.0,
transformation_impact: 0.8,
iterative_cycles: 1.5,
human_oversight: 1.2,
product: 1.728
},
developerProfile: { mode: "ai_native", correctionFactor: 1.45 }
}LLM-adapted cost drivers include reasoning complexity, context completeness, transformation impact, iterative cycles, and human oversight requirements.
sprint_forecast -- Sprint velocity forecasting from historical data
Input: {
backlog_points: 100,
velocity_history: [20, 25, 22, 23],
sprint_length_days: 14,
hours_per_sprint: 80
}
Output: {
backlogPoints: 100,
averageVelocity: 22.5,
requiredSprints: 4.4,
pessimisticSprints: 4.9,
hoursPerPoint: 3.56,
totalHours: 355.6,
completionDays: 62,
sprintLengthDays: 14,
developerProfile: { mode: "ai_native", sprintVelocityPoints: 80, correctionFactor: 1.45 }
}critical_path -- Critical Path Method with merge-bias adjustment for parallel tasks
Input: {
tasks: [
{ name: "A", duration: 5, predecessors: [] },
{ name: "B", duration: 3, predecessors: ["A"] },
{ name: "C", duration: 4, predecessors: ["A"] }
]
}
Output: {
critical_path: ["A", "C"],
total_duration: 9,
slack_per_task: { A: 0, B: 1, C: 0 },
merge_bias_adjustment: 0
}monte_carlo_schedule -- Monte Carlo simulation with seeded PRNG for deterministic, reproducible results
Input: {
tasks: [
{ name: "A", optimistic: 2, most_likely: 4, pessimistic: 8 },
{ name: "B", optimistic: 1, most_likely: 3, pessimistic: 6 }
],
iterations: 10000
}
Output: {
p10: "5.9",
p50: "7.91",
p80: "9.39",
p95: "10.75",
riskEvents: [
{ description: "Task \"A\" exceeded 1.5x PERT expected in 10% of simulations", probability: 0.1, impactDays: 0.05 },
{ description: "Task \"B\" exceeded 1.5x PERT expected in 10% of simulations", probability: 0.1, impactDays: 0.04 }
],
criticalPathProbability: null
}(criticalPathProbability is null unless a target_hours deadline is supplied — then it is the real P(total ≤ target); riskEvents[].impactDays is per-task expected overrun, sorted by impact.)
reference_class_estimate -- Reference class forecasting with planning fallacy correction
Input: {
task_type: "feature",
complexity: 3
}
Output: {
rawEstimate: 2,
correctedEstimate: 2,
correctionFactor: 1,
sampleSize: 0,
baselineSource: "inferred_scope_medium_real_tasks",
scopeUsed: "medium",
scopeInferred: true,
confidence: "pessimistic",
developerProfile: { mode: "ai_native", estimationMape: 15, underestimationBias: 0.2, correctionFactor: 1 },
adjustedEstimate: 2,
basisNote: "correctedEstimate (2 hours) is the ledger-recorded and displayed basis (rawEstimate × correctionFactor). adjustedEstimate (2 hours) additionally applies the developerProfile factor (1) and is display-only — it is never recorded or calibrated against.",
intervalNote: "Fewer than 5 exclusion-filtered historical \"feature\" reference_class_estimate pairs are available yet, so no empirical confidence interval could be computed."
}(Fresh-install output; with accumulated feedback the correction factor and sample size come from your own matched pairs and the empirical interval is populated — correctedEstimate is always the recorded basis.)
Valid task_type values: feature, bugfix, refactor, migration, infrastructure, documentation, testing, design.
estimate_from_context -- Classify a free-text task description and delegate to reference class estimation
Input: {
context: "Add OAuth2 login support to the API, including refresh token rotation and a new /auth/callback endpoint"
}
Output: {
tool: "estimate_from_context",
rawEstimate: 2,
correctedEstimate: 2,
correctionFactor: 1,
sampleSize: 0,
baselineSource: "inferred_scope_medium_real_tasks",
scopeUsed: "medium",
scopeGuide: "For feature tasks: small=~2.3h, medium=~6h, large=~10.6h, xl=~17h",
classification: {
classified_task_type: "feature",
classified_complexity: 3,
confidence: "medium",
signals: ["task_type_matched:feature"],
task_type_from_hint: false,
complexity_from_hint: false
},
note: "Using reference database correction factors. Submit actuals via record_actual to improve accuracy."
}Classifies task_type and complexity from free text (an issue body, PR/diff description, or task summary) using a local, deterministic keyword/signal heuristic -- no LLM call is made. Caller-supplied task_type/complexity hints always override the classification. The resolved inputs are then delegated to the same reference-class-forecasting path used by reference_class_estimate, so the response carries the same estimate fields plus a classification provenance block explaining how the tool read the context. When classification confidence is low, an additional lowConfidenceNote field is returned rather than silently guessing.
calibrate_estimates -- Team-specific accuracy calibration from historical estimated vs actual data
Input: {
task_type: "feature",
team_id: "backend"
}
Output: {
correctionFactor: 1.45,
accuracyTrend: "stable",
velocityTrend: "stable",
recommendations: [
"Using reference database correction factor (1.45x) — personalized from 117,791 samples.",
"Record actuals via POST /v1/feedback/record-actual to refine for your team's patterns."
]
}token_time_bridge -- Map LLM token budgets to wall-clock time for 16 model families
Input: {
tokens: 50000,
model: "claude-sonnet-4-20250514",
tool_calls: 10,
reasoning_depth: "deep"
}
Output: {
estimatedSeconds: 697,
estimatedMinutes: 11.6,
confidence: "likely",
urgency: "short",
breakdown: {
promptTokens: 15000,
completionTokens: 35000,
toolOverheadSeconds: 2
}
}token_cost_estimate -- Token cost estimation for LLM API calls
Input: {
tokens: 50000,
model: "claude-sonnet-5"
}
Output: {
tokens: 50000,
model: "claude-sonnet-5",
estimatedSeconds: 695,
estimatedMinutes: 11.6,
estimatedCost: 0.57,
costBreakdown: { inputCost: 0.045, outputCost: 0.525, toolCallOverheadCost: 0 },
confidence: "likely"
}compare_models -- Side-by-side cost and capability comparison across LLM models
Input: {
tokens: 50000,
sort_by: "cost"
}
Output: {
tokens: 50000,
models: [
{ model: "gemini-2.0-flash", estimatedCost: 0.0155, qualityTier: "fast", tokensPerSecond: 230 },
{ model: "deepseek-v3", estimatedCost: 0.0189, qualityTier: "standard", tokensPerSecond: 97 },
{ model: "gpt-4o-mini", estimatedCost: 0.0233, qualityTier: "fast", tokensPerSecond: 180 }
],
sortBy: "cost"
}accuracy_trend -- Track estimation accuracy over time from recorded feedback data
Input: { team_id: "backend", window_size: 50 }
Output: {
overallTrend: "improving",
currentMape: 26.5,
industryBaselineMape: 25,
totalEstimates: 1049,
totalWithActuals: 1049,
windows: [{ period: "Window 1 (estimates 1-50)", mape: 32, bias: 5.3, sampleSize: 50 }]
}schedule_risk -- Schedule risk scoring for project timelines
Input: {
estimated_hours: 40,
task_type: "feature"
}
Output: {
estimatedHours: 40,
riskLevel: "low",
confidenceIntervals: { p50: 40, p80: 45.1, p95: 49.9 },
historicalAccuracy: { mape: 15, sampleSize: 117791 },
recommendation: "Low risk. Estimate is within normal variance.",
humanReadable: "Schedule risk: low. MAPE: 15% (based on 0 historical records). Confidence intervals: p50=40h, p80=45.1h, p95=49.9h."
}cocomo_validate -- Validate COCOMO II estimates against reference data
Input: {}
Output: {
projectsEvaluated: 182,
mape: 85.55,
bias: 53.5,
byProjectType: {
organic: { mape: 86.57, count: 22 },
semidetached: { mape: 84.75, count: 106 },
embedded: { mape: 86.71, count: 54 }
},
recommendedAdjustments: []
}cocomo_ground_truth -- Benchmark all COCOMO variants (Basic, COCOMO II nominal, AI 12x speedup, AI + developer-profile gradients) against the same real historical projects, with per-dataset and per-type breakdowns
Input: {}
Output: {
projectsEvaluated: 182,
models: [
{ name: "COCOMO Basic", mape: 85.55, mmre: 0.856, pred25: 0.313, pred50: 0.544, bias: 53.5, count: 182 },
...
],
byDataset: { ... },
byType: { ... },
winner: "AI + Profile (human)",
conclusion: "Best model: AI + Profile (human) (MAPE=79.66%). ...",
humanReadable: "..."
}Epoch tools support dual estimation modes to account for the fundamentally different velocity of AI-assisted vs human-only development.
When ai_native=true (default), tools use Epoch's reference database with tool-aware correction factors. These baselines reflect AI agent workflows: faster iteration, higher output volume, and different error profiles.
When ai_native=false, tools apply human developer baselines:
Parameter | Human Baseline | AI-Native Baseline |
Feature development | 14 calendar days (industry data) | 5.7h median (126K+ real tasks) |
Bug fix turnaround | 72 hours (industry data) | 6.2h median (139 matched estimate-actual pairs; source: |
Sprint velocity | 35 story points (industry data) | 80 story points |
Estimation accuracy (MAPE) | 25% (Jorgensen 2004) | 15% (from AI-native profiles) |
Correction factor | 1.8x (industry standard) | 1.07-1.45x (from reference DB) |
Tools that support ai_native: pert_estimate, cocomo_estimate, sprint_forecast, reference_class_estimate, schedule_risk.
Hybrid workflows: ai_native accepts a float from 0.0 (fully human) to 1.0 (fully AI-native). Values like 0.5 produce interpolated profiles for mixed AI/human workflows. Boolean values (true/false) remain supported for backward compatibility.
Epoch learns your patterns the more you use it. The bundled reference database already contains 117,791 data points with correction factors tuned from real estimate-vs-actual pairs across 8 task types — it works accurately on day one.
If you record your actuals, Epoch personalizes further:
Estimate -- Generate an initial estimate with any estimation tool
Record -- Track the actual outcome (record_actual)
Learn -- Self-improvement computes personalized correction factors from your data
Improve -- Future estimates apply your team's actual patterns
Trend -- accuracy_trend tracks whether your accuracy is improving over time
Your estimates + your actuals -> Your correction factors -> Better estimates -> RepeatThe loop can close itself. Recording actuals is the step everyone forgets, so Epoch can do it for you: epoch auto-actuals --session <id> records wall-clock-derived actuals for a session's unfinished estimates (agent hosts can wire it into a session-end hook). Auto-recorded actuals are sanity-bounded (0.05–12h, <10x the estimate), provenance-labeled auto_wallclock, never overwrite a real actual, and feedback_health reports them separately (byProvenance) so automated data can't silently skew your calibration.
Estimates lead with honest ranges. When at least 5 matched pairs exist for a task type, pert_estimate and reference_class_estimate open with a calibrated 80% interval ("Expected 1.6–4.2 hours (80% confidence interval); point estimate 2.5 hours") derived from your own historical estimate-vs-actual ratios — and say plainly when there isn't enough data yet.
The engine detects systematic biases (chronic under-estimation, accuracy degradation) and surfaces actionable recommendations.
You do not need to share data with anyone for this to work. Self-improvement runs entirely locally using your own ~/.epoch/ data.
The self-improvement claim above isn't marketing copy -- it's backed by a runnable receipt. scripts/backtest-pert-correction.mjs makes a read-only temp copy of your ~/.epoch ledger, chronologically splits matched pert_estimate (estimate, actual) pairs 80/20, trains the learned per-(tool, task_type) correction factor on the training split only, and reports MdAPE on the held-out test split it never trained on:
npx tsx scripts/backtest-pert-correction.mjsMeasured on the maintainers' production ledger (697 held-out matched pairs at time of writing): MdAPE improved from 105.2% (uncorrected) to 80.5% (learned correction) on data the correction factor never saw during training. This is the mechanism EPOCH_PERT_LEARNED_CORRECTION gates behind before it's recommended on by default -- the script also checks that the corrected median actual/predicted ratio lands in [0.7, 1.3], and reports HOLD (not recommended yet) when that second guard hasn't cleared, so the flag doesn't ship as "on" until both hold. Run the script against your own ledger for your own numbers; they move as more actuals get recorded, which is the point.
reference_class_estimate's correction factors are the same learned mechanism applied to a different tool. Track its current calibration with epoch data status or feedback_health (per-tool MAPE/MdAPE, bias, and trend), or generate a full calibration decision-surface report with node scripts/build-calibration-dashboard.mjs -- also strictly read-only against your ledger.
Epoch uses a three-layer data strategy so it's accurate from the start and gets better over time:
1. Bundled reference database (works immediately, no setup): Epoch ships with a pre-built reference database containing 117,791 data points across 8 task types and 5 complexity levels. Correction factors are computed from real estimate-vs-actual pairs. You get accurate estimates the moment you install it.
2. Local self-improvement (automatic, private):
As you use Epoch and record actuals, the self-improvement engine recalibrates correction factors from your data. This runs entirely locally in ~/.epoch/ — nothing leaves your machine. The engine triggers automatically every 100 tool calls or 24 hours.
Auto-recording: Use scripts/auto-record-actual.mjs to automatically record actual time against pending estimates.
Source tagging: Set EPOCH_SOURCE=<project-name> to tag estimates by project.
Inspect your data: epoch data where and epoch data status show what's stored locally.
3. Community contributions (optional, opt-in): You can optionally share anonymized data to help improve baselines for all users. Community data is stripped of all identifying information — only task type, complexity, estimated hours, actual hours, and date remain. See CONTRIBUTING-data.md for format and privacy requirements.
epoch share-data --validate --description "My anonymized estimation data"This is completely optional. Epoch works great without it.
Epoch exposes the same 25 tools through three interfaces:
Surface | Transport | Use Case |
MCP Server | stdio | Claude Code, Cursor, VS Code, Windsurf |
CLI | Direct invocation | Scripts, CI/CD, quick lookups |
REST API | HTTP (Hono) | Web apps, AI agents, integrations |
Default behavior: running epoch with no arguments starts the MCP stdio server.
# PERT estimate
epoch pert-estimate --optimistic 2 --most-likely 4 --pessimistic 12 --unit hours
# Token-to-time bridge
epoch token-time-bridge --tokens 50000 --model claude-sonnet-4-20250514
# Monte Carlo simulation
epoch monte-carlo-schedule --tasks '[{"name":"A","optimistic":2,"most_likely":4,"pessimistic":8}]'
# COCOMO II estimate
epoch cocomo-estimate --kloc 15 --project-type organic
# Schedule risk score
epoch schedule-risk --tasks '[{"name":"A","duration":5,"risk_level":"high"},{"name":"B","duration":3,"risk_level":"low"}]'
# List all tools
epoch list-tools
# Pretty table output
epoch pert-estimate --optimistic 2 --most-likely 4 --pessimistic 12 --pretty# Start the server
epoch serve --port 3099
# or: EPOCH_TRANSPORT=http EPOCH_PORT=3099 epoch
# Call any tool
curl -X POST http://localhost:3099/v1/tools/pert_estimate \
-H "Content-Type: application/json" \
-d '{"optimistic": 2, "most_likely": 4, "pessimistic": 12, "unit": "hours"}'
# Health check
curl http://localhost:3099/health
# OpenAPI spec
curl http://localhost:3099/openapi.jsonEpoch is built for agents as first-class callers, not humans typing in a terminal as an afterthought.
Why agents need time-sense. An LLM has no grounded sense of duration or cost -- it will say "quick fix" for a two-day migration and "big project" for a two-hour config change with equal confidence, because it has no feedback loop telling it otherwise. That's fine for a chat answer; it breaks down the moment an agent is planning multi-step work, sequencing a sprint, or deciding whether a deadline is realistic. Epoch gives the agent a calculator instead of a guess: PERT/COCOMO/Monte Carlo math, a reference-class baseline built from real task data, and a feedback loop that corrects itself as the agent (or its operator) records actuals.
EPOCH_TELEMETRY=1 for headless/agent operators. Telemetry is off by default and requires informed consent. For a human at a terminal, that consent is epoch telemetry enable, which shows the data and asks for confirmation. An agent should never be the one clicking "yes" to that prompt on its own behalf -- there is deliberately no MCP tool that enables telemetry, so an agent cannot self-consent. For headless or agent-operated deployments, the operator opts in out-of-band by setting EPOCH_TELEMETRY=1 in the server's environment (for example, the env block of the MCP server config) before the agent ever starts. Consent stays with the human who configures the deployment, not the agent that runs inside it.
MCP client qualification. Epoch's telemetry schema (v2) records client_name/client_version from the MCP clientInfo your host reports at connection time, plus transport (stdio/http). This is agent qualification, not agent identification: it lets aggregate accuracy stats count "5.7h median across N agent-driven feature estimates" as first-class agent data rather than lumping it in with anonymous CLI usage, without adding any new per-user identifying signal. MCP clients that report clientInfo (Claude Code, Cursor, and most current hosts do) get this for free; clients that don't are still fully functional, they just show up as client_name: null.
Epoch also provides built-in discoverability endpoints so agents can find and use the HTTP API without prior configuration:
Endpoint | Description |
| OpenAI plugin manifest |
| LLM-consumable documentation |
| OpenAPI 3.1 specification |
| Service health and version |
git clone https://github.com/KyaniteLabs/Epoch.git
cd Epoch
pnpm install
pnpm run buildpnpm test # Run the Vitest suite
pnpm run build # Build with tsup
pnpm run typecheck # TypeScript strict mode check
pnpm run dev # Run development server
pnpm run inspector # Open MCP Inspector for interactive testingRuntime: Node.js 22+ (ESM; engines.node >=22 — Node 20 reached EOL April 2026)
Language: TypeScript 6 (strict mode, noUncheckedIndexedAccess, verbatimModuleSyntax)
Validation: Zod 4 with .describe() on every field
MCP SDK: @modelcontextprotocol/sdk 1.12+
HTTP: Hono (lightweight, multi-runtime)
CLI: Commander.js
Date Handling: date-fns 4.x + date-fns-tz 3.x
Build: tsup (ESM output)
Testing: vitest 4.x with v8 coverage (97% statements, 88% branches)
Variable | Default | Description |
|
| Transport mode: |
|
| HTTP server port |
|
| HTTP server bind address |
|
| Data directory for feedback and self-improvement |
|
| Community data directory |
|
| Max requests per minute per client (HTTP only). |
|
| Set to |
| (none) | Comma-separated origins allowed by the HTTP API's CORS handling (e.g. |
| (none) | Project/source tag attached to estimate records |
|
| Set to |
| (none) | Override the configured telemetry receiver endpoint for status/submission. |
Epoch can share anonymized estimate/actual pairs to improve accuracy for all users. This is off by default and requires explicit opt-in.
Agent-operator consent model: there is deliberately no MCP tool that enables telemetry -- an agent must not be able to self-consent on a human's behalf. Humans opt in interactively with epoch telemetry enable. Agent/headless operators opt in out-of-band by setting EPOCH_TELEMETRY=1 in the server's environment before the agent starts (see Agent-First). Either way, consent belongs to the person who configures the deployment.
epoch telemetry enable # Opt in (shows exactly what will be shared)
epoch telemetry preview # Preview anonymized data before enabling
epoch telemetry status # Show current settings
epoch telemetry set-endpoint --endpoint https://your-server.example.com/v1/telemetry
epoch telemetry submit # Submit queued anonymized records to the configured endpoint
epoch telemetry disable # Opt out
epoch telemetry export # Export all local data as anonymized JSONWhat is shared: task type, complexity, tool name, estimated hours, actual hours, ratio, date (YYYY-MM-DD only).
What is NEVER shared: project names, notes, team IDs, IP addresses, timestamps with time-of-day, source code, descriptions.
See Privacy Policy and Telemetry Documentation for full details.
By default, Epoch stores local data under ~/.epoch/ or EPOCH_DATA_DIR. Your local usage data is not automatically committed to GitHub and is not automatically submitted anywhere.
epoch data where # Show local data file locations
epoch data status # Show data file counts, feedback health, telemetry configUse epoch share-data --validate to create a community-data JSON file suitable for data/community/. Review the file before opening a PR.
epoch share-data --description "Anonymized Epoch usage export" --validateFleet host inventories are not published in this repository. docs/ops/machines.md documents the schema used to track machines internally; actual hostnames, addresses, and SSH users are supplied at runtime via environment variables (see scripts/ and docs/ops/epoch-fleet-audit.md). windows-receiver is a historical label only.
Apache License 2.0. See LICENSE for full terms.
More from KyaniteLabs. Related projects:
mcp-video — guardrailed video-editing MCP server for AI agents
DialectOS — Spanish dialect localization MCP server & CLI
checkyourself — local-first production-readiness checks for AI-built code
→ More at kyanitelabs.tech
Epoch is a time estimation MCP server that helps engineering leads, agents, and planners who need calibrated duration estimates produce PERT/reference-class estimates and record actuals.
Product | Epoch |
Category | time estimation MCP server |
Best for | engineering leads, agents, and planners who need calibrated duration estimates |
Not | a calendar or project tracker |
Source | |
Keywords | time estimation MCP, PERT, reference class forecasting |
Primary: engineering leads, agents, and planners who need calibrated duration estimates
Use when you need to produce PERT/reference-class estimates and record actuals
Skip if you need a calendar or project tracker
Epoch is a time estimation MCP server. It helps engineering leads, agents, and planners who need calibrated duration estimates produce PERT/reference-class estimates and record actuals.
engineering leads, agents, and planners who need calibrated duration estimates.
Unlike vibes-based hour guesses, Epoch forces structured estimate + actual feedback.
Treat the README status and release tags as source of truth for maturity. Validate against your own requirements before production use.
Maintained as of 2026 on the default branch
Prefer release tags when pinning dependencies
Report issues on the canonical remote listed above
Coding agents: read this README first, then repo docs/AGENTS.md if present
Prefer machine-readable briefs (llms.txt) when the repo ships one
MCP or skill entrypoints are documented in-repo when applicable
Issues and PRs welcome on the canonical remote. Keep public docs free of secrets and machine-local paths.
See LICENSE in this repository (or package metadata if license is package-only).
Track estimation accuracy improvement over time.
Computes sliding-window MAPE and compares against industry baseline (25%). Shows whether your estimates are improving, degrading, or stable. Industry research shows estimation accuracy does NOT improve with experience (Cao 2022) — self-correcting systems like Epoch can buck this trend.
| Name | Required | Description | Default |
|---|---|---|---|
| team_id | No | Optional team identifier to scope historical data. | |
| window_size | No | Number of records per sliding window. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate read-only and idempotent; description adds behavioral context about sliding-window computation and baseline comparison, enhancing transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Sufficient for a read-only analytical tool with two optional parameters; describes output concept (MAPE, baseline, trend) though lacks exact return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3 is appropriate. Description does not add parameter-specific details beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool tracks estimation accuracy over time using MAPE and compares to a baseline. It distinguishes from siblings like compare_models and feedback_health by focusing on trend analysis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context about industry research but no explicit when-to-use or when-not-to-use guidance. No alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Adds N business (working) days to a start date, skipping weekends and country-specific public holidays. Supports US, UK, FR, DE, and JP holidays.
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | Yes | ISO date string for the start date. | |
| days | Yes | Number of business days to add (negative to subtract). | |
| country | No | ISO-3166-1-alpha-2 country code for holiday calendar. | US |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, non-destructive, and idempotent behavior. The description adds context about skipping weekends and specific country holidays, which is useful beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two succinct sentences that front-load the core purpose and then provide additional detail on supported countries. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers functionality, countries, and parameter hints. It omits error handling or return format, but is sufficient for a simple date calculation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description reiterates parameter meanings (ISO date, number for days, country code). It adds no significant new semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it adds business days to a start date, skipping weekends and country-specific holidays. It specifies supported countries, distinguishing it from sibling tools like count_business_days or time_math.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for computing future/past dates excluding weekends/holidays but does not explicitly state when not to use it or mention alternatives. Usage is implied from the purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| entries | Yes | Array of actual-hour records (1–500 entries). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only indicate non-read-only and non-destructive, so the description carries the burden of behavioral disclosure. It mentions the batch size limit and that it's a single call, but does not address partial failures, idempotency (explicitly marked non-idempotent), or error responses.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action and scope, and contains no filler. Every word contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a batch mutation tool with no output schema, the description adequately covers purpose, input format, and size limits. It could be improved by mentioning potential error handling or response behavior, but the core context is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description adds little beyond the schema. It rephrases the entry structure but does not provide additional context or constraints not already present in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'record actual hours', the scope 'multiple estimates in a single call', and the data format 'pairs an estimate ID with the actual hours spent'. It effectively distinguishes from the singular sibling tool 'record_actual' by emphasizing bulk submission.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (for bulk feedback submission) and specifies the valid batch size (1–500 entries). However, it does not explicitly recommend the singular tool for single entries, which would be a helpful alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recalculate team-specific correction factors from historical estimation data.
Compares estimated vs actual hours to compute a correction multiplier. Requires PM system integration for best results. Returns recommendations for improving estimation accuracy.
| Name | Required | Description | Default |
|---|---|---|---|
| team_id | Yes | Team identifier whose historical accuracy data should be analysed. | |
| period_days | No | Lookback window in calendar days for calibration data. | |
| minimum_samples | No | Minimum number of completed tasks required before producing a calibration factor. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds that the tool returns recommendations and requires PM integration, providing additional behavioral context beyond the safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three lines covering purpose, mechanism, requirement, and output. No extraneous information, every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema, the description mentions it 'returns recommendations,' which is helpful. It could be more specific about the output format, but for a calculation tool it is largely adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter already has a description. The tool description does not add extra meaning beyond what the schema provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool recalculates team-specific correction factors from historical estimation data, comparing estimated vs actual hours. It distinguishes itself from siblings like 'accuracy_trend' and 'cocomo_estimate' by focusing on calibration of correction factors.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'Requires PM system integration for best results,' implying a prerequisite but does not explicitly state when to use this tool versus siblings or provide alternatives. Usage context is somewhat implied but not clearly defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
LLM-adapted COCOMO II parametric effort estimation.
Replaces traditional 17 human-labor cost drivers with 5 LLM-specific factors: reasoning complexity, context completeness, transformation impact, iterative cycles, and human oversight. Returns both nominal and LLM-adjusted person-months.
| Name | Required | Description | Default |
|---|---|---|---|
| kloc | Yes | Estimated thousands of lines of code. Count actual code, not comments/blank lines. | |
| reasoning_complexity | No | Multiplier for reasoning complexity of the codebase. 0.5 = trivial CRUD, 1.0 = average, 2.0 = novel algorithm/R&D. | |
| context_completeness | No | How complete is the context provided to the LLM? 0.5 = exhaustive specs, 1.0 = typical, 2.0 = vague requirements. | |
| transformation_impact | No | Scale of transformation relative to existing code. 0.5 = small patch, 1.0 = new module, 2.0 = architectural rewrite. | |
| iterative_cycles | No | Iteration overhead multiplier or literal cycle count. Multiplier scale: 0.5 = one-shot, 1.0 = typical debug loop, 2.0 = heavy back-and-forth. Values above 2.0 are accepted as literal cycle counts and normalized internally. | |
| human_oversight | No | Human review overhead multiplier. 0.5 = auto-merged, 1.0 = standard PR review, 2.0 = compliance/security review. | |
| task_type | No | Optional task type for feedback matching. | |
| ai_native | No | Degree of AI assistance: 0.0 = fully human, 1.0 = fully AI-native, 0.5 = hybrid. Accepts boolean for backward compatibility (true=1.0, false=0.0). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds that the tool returns nominal and LLM-adjusted person-months but does not elaborate on side effects, authorization needs, or other behavioral traits beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two concise sentences. The first sentence immediately states the tool's purpose, and the second provides key adaptation details and outputs. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 8 parameters and no output schema, the description only vaguely mentions returning 'person-months' without specifying the exact output structure (e.g., object with fields, single float). This is a significant gap for a complex estimation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 8 parameters have descriptions in the input schema (100% coverage), so the tool description adds no additional semantic value. The schema already explains each parameter's purpose, range, and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is an 'LLM-adapted COCOMO II parametric effort estimation' tool, replacing traditional cost drivers with LLM-specific factors. It specifies the output (nominal and adjusted person-months) and distinguishes itself from sibling estimation tools like cocomo_ground_truth and pert_estimate by its focus on LLM adaptation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for estimating LLM development effort but does not explicitly state when to use this tool versus alternatives like pert_estimate or token_cost_estimate. No exclusion criteria or prerequisite conditions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate all COCOMO estimation models against 240 real historical projects with known effort.
Runs 6 models in parallel: COCOMO Basic, COCOMO II Nominal, COCOMO II + AI 12x speedup, and AI + developer profile at human/hybrid/ai_native gradients. Reports MAPE, MMRE, PRED(25), PRED(50), bias per model, with breakdowns by dataset and project type.
| Name | Required | Description | Default |
|---|---|---|---|
| dataset_filter | No | Optional filter to validate against specific datasets only. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint; description adds details about parallel execution of 6 models and specific metrics reported, providing context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with purpose, no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, description lists all key metrics and model breakdowns; could clarify if output is summary or detailed, but overall sufficient for complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one optional parameter; description does not add additional meaning beyond what the schema provides, meeting baseline expectations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool validates COCOMO models against 240 historical projects, lists the specific models and metrics, and distinguishes it from siblings like cocomo_estimate and cocomo_validate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies use for validation/ground truth but does not explicitly state when to use this over sibling tools like cocomo_validate or compare_models, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate COCOMO estimation model against 195 real historical projects.
Runs the COCOMO Basic formula against projects from NASA93, COCOMO81, Albrecht, and Kemerer datasets. Reports overall MAPE, bias, per-type accuracy, and recommended coefficient adjustments.
| Name | Required | Description | Default |
|---|---|---|---|
| dataset_filter | No | Optional filter to validate against specific datasets only. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds context by detailing what the tool reports (MAPE, bias, per-type accuracy, coefficient adjustments) and the datasets it runs against (NASA93, COCOMO81, Albrecht, Kemerer). This provides useful behavioral information beyond annotations, though it does not describe potential output structure or edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of three sentences with no redundant information. It is front-loaded with the core purpose in the first sentence, and each subsequent sentence adds specific value (datasets, reported outputs).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one optional parameter and no output schema, the description covers the essential aspects: what it validates, against which datasets, and what it reports. It mentions coefficient adjustments, implying actionable output. However, it does not clarify how the COCOMO model is specified (e.g., from a prior estimate) or explain the output structure in detail, leaving minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description mentions the datasets in the tool's body but does not add meaning to the 'dataset_filter' parameter beyond what the schema already provides ('Optional filter to validate against specific datasets only'). No extra semantics are given for the parameter's usage or format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the tool's purpose: validating the COCOMO estimation model against a set of 195 historical projects. It lists the datasets used and the metrics reported (MAPE, bias, per-type accuracy, coefficient adjustments). This differentiates it from siblings like 'cocomo_estimate' (which would produce estimates) and 'cocomo_ground_truth' (which might provide ground truth), though explicit contrast is absent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for validation, but it does not explicitly state when to use it versus alternatives (e.g., 'Use this to assess model accuracy; for new estimates, use cocomo_estimate'). It lacks when-not-to-use guidance and does not mention any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare all LLM models side-by-side for a given token budget.
Ranks models by estimated cost or time. Shows quality tier for each model. Use when choosing which model to use for a task.
| Name | Required | Description | Default |
|---|---|---|---|
| tokens | Yes | Total number of tokens to estimate across all models. | |
| tool_calls | No | Number of tool calls expected. | |
| reasoning_depth | No | Expected depth of chain-of-thought reasoning. | moderate |
| sort_by | No | Sort models by cost (default) or estimated time. | cost |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate safe read-only behavior. The description adds that it ranks by cost/time and shows quality tiers, providing useful behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus a usage line, no fluff, front-loaded with the main action. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main purpose, ranking criteria, and quality tiers. Without an output schema, it provides enough context for an agent, though terms like 'quality tier' could be elaborated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good parameter descriptions. The description aligns with parameters (e.g., 'token budget' maps to tokens) but does not add extra meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool compares LLM models side-by-side for a given token budget, differentiating it from siblings like token_cost_estimate or token_time_bridge. The verb 'compare' and resource 'LLM models' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when choosing which model to use for a task,' providing clear context. However, it does not mention when not to use or point to alternatives, which would strengthen guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Converts an ISO-8601 timestamp to a target IANA timezone. The input timestamp must include timezone information or be in UTC. Returns the localised time, UTC offset, and human-readable format.
| Name | Required | Description | Default |
|---|---|---|---|
| timestamp | Yes | ISO-8601 timestamp to convert. | |
| target_tz | Yes | Target IANA timezone identifier. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations confirm safety; description adds output details (localised time, UTC offset, human-readable). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with action, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Rich annotations and full schema coverage; description explains output structure. No gaps given tool complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters with descriptions; description adds timestamp constraint but no extra semantic depth beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'converts', resource 'ISO-8601 timestamp', and target 'target IANA timezone'. Prerequisites are noted, distinguishing it from sibling time tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Specifies input requirement (must include timezone or be UTC) but lacks explicit when-to-use vs alternatives among 23 siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Counts the number of business (working) days between two dates, excluding weekends and country-specific public holidays. The count is exclusive of the start date and inclusive of the end date.
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | Yes | ISO date string for the start date. | |
| end_date | Yes | ISO date string for the end date. | |
| country | No | ISO-3166-1-alpha-2 country code for holiday calendar. | US |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, indicating safe read operation. The description adds value by disclosing the date boundary behavior (exclusive start, inclusive end) and the use of country-specific holiday calendars, which are not evident from annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two clear, well-structured sentences covering all essential aspects without redundancy. Every sentence provides distinct value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description sufficiently explains the return semantics (count of business days). It covers date handling, holidays, and country-specific behavior, making it complete for an agent to understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes each parameter. The description adds context about the counting logic (exclusive start, inclusive end) and the country parameter defaulting to US, enhancing understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'counts the number of business (working) days between two dates', which is a specific verb+resource. It distinguishes itself from sibling tools like add_business_days (which adds days) and time_math (general time operations) by clearly focusing on counting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (to count working days) and provides details on date counting semantics (exclusive of start, inclusive of end). It does not explicitly mention when not to use it or name alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compute critical path with merge-bias adjustment for project schedules.
Performs forward/backward pass to identify critical tasks and slack. Applies merge bias: tasks with >2 predecessors get 5% duration increase per extra predecessor.
| Name | Required | Description | Default |
|---|---|---|---|
| tasks | Yes | All tasks in the project graph. Each task must have a unique name. | |
| task_type | No | Optional task type for feedback matching. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description adds significant behavioral context by explaining the merge-bias adjustment algorithm (5% duration increase per extra predecessor beyond 2), which goes beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise with two short paragraphs (4 sentences). The key purpose is front-loaded in the first sentence, and every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the algorithm well but does not describe the output format or return value. Since there is no output schema, more detail on what the tool returns (e.g., critical tasks, slack) would improve completeness. It also omits error conditions like cycles.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not mention the parameters or add any meaning beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool computes critical path with merge-bias adjustment, distinguishing it from sibling tools like monte_carlo_schedule or pert_estimate. It specifies the verb 'compute' and resource 'critical path', and mentions the unique merge-bias feature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for project schedule analysis but does not explicitly state when to use this tool versus alternatives or when not to use it. It lacks guidance on prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a health report on the estimation feedback loop.
Shows total estimates, actuals, match rate, MAPE by tool and task type, and self-improvement readiness (which types have enough data for auto-calibration).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds information about the report content (metrics) but does not detail behavior like auth requirements or data freshness. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with a bullet list, front-loaded with the purpose. Every sentence adds value without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description lists key metrics. For a simple zero-parameter tool, this is sufficient. Could mention aggregation scope, but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters, the baseline is 4. The description adds value by explaining what the report contains, but the schema already covers all parameters (none).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a health report on the estimation feedback loop' with specific metrics listed (total estimates, actuals, match rate, MAPE, self-improvement readiness). It distinguishes itself from siblings like 'accuracy_trend' and 'calibrate_estimates' by focusing on a broad health overview.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly suggests usage for checking feedback health but lacks explicit when-to-use or when-not-to-use guidance. No alternatives are mentioned, making it adequate but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the current date and time in the specified IANA timezone. Useful for grounding the LLM in the user's local time. Example timezones: 'UTC', 'America/New_York', 'Europe/London', 'Asia/Tokyo'.
| Name | Required | Description | Default |
|---|---|---|---|
| timezone | No | IANA timezone identifier. Defaults to "UTC". | UTC |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, non-destructive, and idempotent behavior. The description adds no further behavioral details (e.g., precision, format), so it meets the baseline but does not exceed it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a single sentence stating the purpose followed by examples. It is front-loaded and efficient, though it could be slightly more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter, no output schema), the description fully covers what is needed: purpose, usage context, and parameter examples.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter 'timezone' has a clear description and default. The description adds example timezones, which is helpful but not essential, so the score is at the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'returns' and the resource 'current date and time', and distinguishes from sibling tools like convert_timezone or count_business_days by focusing on a simple time retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear use case ('grounding the LLM in the user's local time') but does not explicitly state when not to use this tool or mention alternatives among the many time-related siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recent estimates that have not yet received actual-hour feedback.
Returns estimates awaiting actuals so you can submit feedback via record_actual. Use this to close the estimation feedback loop and improve accuracy over time.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max estimates to return. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds that it returns 'estimates awaiting actuals' and explains the feedback loop purpose. This adds non-obvious behavioral context beyond annotations, such as the intent of improving accuracy over time. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place. The first sentence immediately states the main action, the second links to a related tool, and the third explains the purpose. No fluff or redundancy. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains what the tool returns and its role in the feedback loop, but it does not specify ordering, date range, or pagination behavior. Since there is no output schema, the description could be more complete about the returned data structure. Adequate for a simple list tool but with gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the one parameter (limit), which already has a description. The tool description does not add any additional parameter semantics beyond what the schema provides. Baseline 3 is appropriate since the schema covers the parameter well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it 'List recent estimates that have not yet received actual-hour feedback.' This is a specific verb-resource pair that distinguishes it from siblings like record_actual (which submits feedback) and accuracy_trend (which shows trends). It exactly tells what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Use this to close the estimation feedback loop and improve accuracy over time' and suggests pairing with record_actual. This gives clear context for when to use it, though it doesn't explicitly state when not to use it or mention alternatives. The guidance is strong but could be more complete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run Monte Carlo simulation for probabilistic schedule risk analysis.
Samples task durations from triangular distributions and returns P10/P50/P80/P95 completion estimates with identified risk events. Use seed for reproducible results.
| Name | Required | Description | Default |
|---|---|---|---|
| tasks | Yes | Task list with PERT-style three-point estimates and dependency edges. | |
| iterations | No | Number of Monte Carlo simulation iterations (1–100,000). Higher = more stable percentiles. | |
| seed | No | Optional seed for reproducible results. | |
| task_type | No | Optional task type for feedback matching. Enables per-task-type accuracy tracking. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnly, non-destructive, idempotent. Description adds that it samples from triangular distributions and returns percentiles with risk events, providing useful behavioral detail beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states purpose, second details methodology and key parameters. Every word adds value, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description specifies return values (P10/P50/P80/P95 estimates, risk events). Could clarify what constitutes risk events, but overall sufficient given input schema richness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions. Description reinforces seed usage and explains that durations are sampled from triangular distributions, adding context that the three-point estimates are used to generate output percentiles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool runs Monte Carlo simulation for probabilistic schedule risk analysis, specifies inputs (triangular distributions) and outputs (P10/P50/P80/P95 estimates with risk events), and distinguishes from sibling tools like pert_estimate and critical_path.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description mentions using seed for reproducibility but gives no explicit guidance on when to choose Monte Carlo over alternatives like pert_estimate or schedule_risk. Usage context is implied but not formally stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Parses a human-readable duration string into structured seconds. Supports combinations of y (years), mo (months), w (weeks), d (days), h (hours), m (minutes), s (seconds). Examples: '2h30m', '1d6h', '1w3d', '45m'.
| Name | Required | Description | Default |
|---|---|---|---|
| duration_string | Yes | Duration string like "2h30m", "1d6h", "45m". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only, non-destructive, and idempotent. The description adds supported units and examples, which supplements but does not extend behavioral transparency beyond what annotations imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states purpose and supported units, second provides examples. Every sentence is informative with no redundancy. Front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one required parameter with full schema coverage, no output schema, and complete annotations, the description sufficiently explains the tool's behavior and input format. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so schema explains the parameter. The description adds meaning with allowed units and examples, helping the agent understand valid input formats beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool parses human-readable duration strings into seconds, lists supported units (y, mo, w, d, h, m, s), and provides concrete examples. The unique function stands out among siblings like convert_timezone or time_math.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for converting duration strings but does not explicitly contrast with siblings (e.g., when to parse vs. compute time differences). No when-not-to-use or alternative tool guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate PERT expected duration from three-point estimates using Beta distribution.
Formula: E = (O + 4M + P) / 6. Returns expected value, variance, standard deviation, and 95%/99% confidence bounds with urgency categorization. Use when estimating task duration with uncertain outcomes.
| Name | Required | Description | Default |
|---|---|---|---|
| optimistic | Yes | Best-case duration. Do NOT use your initial optimistic guess — this should be the absolute minimum if everything goes perfectly. | |
| most_likely | Yes | Mode of the distribution — the single most probable outcome. | |
| pessimistic | Yes | Worst-case duration accounting for known risks and unknown unknowns. | |
| unit | No | Time unit for all three PERT estimates. | hours |
| task_type | No | Optional task type for feedback matching. Enables per-task-type accuracy tracking. | |
| ai_native | No | Degree of AI assistance: 0.0 = fully human, 1.0 = fully AI-native, 0.5 = hybrid. Accepts boolean for backward compatibility (true=1.0, false=0.0). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) are consistent. The description adds details about outputs (confidence bounds, urgency categorization) beyond annotations, fully disclosing behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: two sentences, formula, and output list. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description enumerates all outputs (expected value, variance, etc.). With good annotations and parameter descriptions, the tool is fully understandable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds practical guidance for parameters (e.g., 'Do NOT use your initial optimistic guess'), improving clarity beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool calculates PERT expected duration from three-point estimates using Beta distribution. It specifies the formula and outputs (expected value, variance, etc.), and distinguishes from sibling estimation tools like cocomo_estimate or monte_carlo_schedule.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use when estimating task duration with uncertain outcomes,' providing clear context. While it doesn't list when not to use, the sibling tools cover alternative methods, making the usage guidance adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| estimate_id | Yes | ID of the estimate to update. | |
| actual_hours | Yes | Actual hours spent. | |
| notes | No | Optional context. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation (readOnlyHint false). The description adds behavioral context: actuals feed into a self-improvement loop for automatic correction factor updates. No annotation contradictions. Lacks details on return value or side effects, but sufficient for a straightforward write tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences. The first sentence states the main action and purpose. The second provides pairing context. The third explains the system behavior. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (3 parameters, no output schema), the description covers the essential workflow: obtaining estimate_id, submitting actuals, and the resulting improvement loop. It does not mention the batch sibling alternative or potential errors, but it is adequate for a single-record submission tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value beyond the schema by explaining the purpose of the inputs (e.g., actual_hours for hours spent, estimate_id from estimate response) and the system effect. This helps the agent understand the workflow.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Submit actual hours'), the target resource ('a previous estimate'), and the purpose ('improve future accuracy'). It distinguishes from sibling estimation tools by highlighting the pairing with any estimation tool and the self-improvement loop.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance on when to use: after obtaining an estimate and to feed into self-improvement. Mentions estimate_id origin from estimate response. However, it does not explicitly contrast with the sibling batch_record_actuals tool or state when not to use it. Still, it gives clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Data-driven estimate using reference class forecasting.
Applies historical correction factors based on actual-vs-estimated ratios. When no historical data exists, uses industry averages (1.3-2.2x for software tasks). Prioritize this over algorithmic models when historical data is available.
| Name | Required | Description | Default |
|---|---|---|---|
| task_type | Yes | Category of work being estimated for reference-class lookup. | |
| scope | No | Rough size of the task: small=tiny fix/tweak, medium=typical task, large=significant effort, xl=epic-scale. When omitted, inferred from complexity (1-2=small, 3=medium, 4=large, 5=xl). | |
| complexity | No | Fine-tuning complexity from 1 (trivial) to 5 (extreme). Adjusts within the scope band: low complexity shortens, high complexity lengthens the estimate. | |
| team_id | No | Optional team identifier to scope historical data to a specific team. | |
| ai_native | No | Degree of AI assistance: 0.0 = fully human, 1.0 = fully AI-native, 0.5 = hybrid. Accepts boolean for backward compatibility (true=1.0, false=0.0). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true, idempotentHint=true, so the tool is safe and idempotent. Description adds value by explaining the estimation method (historical correction factors, industry averages) without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two paragraphs, four sentences total. Critical information is front-loaded, with no extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Explains the core estimation approach and usage context well. Lacks description of the output format, but given the tool's nature (estimates), the description is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 100% of parameters with descriptions. Description provides context about the estimation logic but does not add significant detail beyond the schema for individual parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it provides data-driven estimates using reference class forecasting with historical correction factors. Distinguishes itself from siblings like cocomo_estimate and pert_estimate by emphasizing historical data prioritization.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use ('Prioritize this over algorithmic models when historical data is available') and implies when not to (use industry averages when no historical data). Lacks explicit naming of alternatives but provides solid guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Assess schedule risk for an estimate using historical accuracy data.
Computes confidence intervals (p50/p80/p95) based on your team's MAPE. Returns risk level and actionable recommendations. Uses industry baseline (25% MAPE) when no historical data is available.
| Name | Required | Description | Default |
|---|---|---|---|
| estimated_hours | Yes | The estimated effort in hours to assess risk for. | |
| task_type | No | Optional task type to refine historical accuracy lookup. | |
| team_id | No | Optional team identifier to scope historical data. | |
| complexity | No | Task complexity from 1 (trivial) to 5 (extreme). Higher complexity widens confidence intervals. | |
| ai_native | No | Degree of AI assistance: 0.0 = fully human, 1.0 = fully AI-native, 0.5 = hybrid. Accepts boolean for backward compatibility (true=1.0, false=0.0). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly and idempotent behavior. The description adds valuable context: it computes confidence intervals (p50/p80/p95) based on MAPE, returns risk level and recommendations, and uses an industry baseline when historical data is absent. This provides behavioral insight beyond structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at three sentences, front-loaded with the primary purpose. Each sentence adds distinct information (purpose, outputs, fallback behavior). No redundancy or wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description sufficiently explains what is returned (confidence intervals, risk level, recommendations). It mentions fallback behavior. However, it could be more complete by hinting at the output structure or when to use this over sibling tools like 'monte_carlo_schedule'. Overall, it equips the agent adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all parameters described. The description adds marginal value by explaining that the tool uses historical accuracy data and MAPE (related to team_id and task_type), but does not elaborate on how individual parameters affect the computation. Baseline 3 is appropriate since the schema already does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Assess schedule risk for an estimate using historical accuracy data.' It specifies the resource (estimate) and action (assess risk). However, it does not explicitly differentiate from siblings like 'monte_carlo_schedule' or 'pert_estimate', which may also assess risk or uncertainty.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have an estimate and want confidence intervals based on historical data, but lacks explicit guidance on when to use this tool versus alternatives (e.g., 'monte_carlo_schedule', 'pert_estimate'). There is no mention of prerequisites, exclusion criteria, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Forecast sprint completion date from backlog size and historical velocity.
Computes average velocity from sprint history, converts story points to hours, and returns required sprints with pessimistic estimate based on velocity variance.
| Name | Required | Description | Default |
|---|---|---|---|
| backlog_points | Yes | Total story points or effort units remaining in the backlog. | |
| velocity_history | Yes | Historical velocities from completed sprints. Minimum 1 data point; 3+ recommended for meaningful forecasts. | |
| sprint_length_days | No | Calendar days in a single sprint cycle. | |
| hours_per_sprint | No | Total productive engineering hours available per sprint (accounts for meetings, overhead). | |
| task_type | No | Optional task type for feedback matching. | |
| ai_native | No | Degree of AI assistance: 0.0 = fully human, 1.0 = fully AI-native, 0.5 = hybrid. Accepts boolean for backward compatibility (true=1.0, false=0.0). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, idempotentHint), the description explains the computation: average velocity from history, conversion of story points to hours, and a pessimistic estimate based on variance. This adds meaningful behavioral context without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences totaling 25 words. The first sentence front-loads the core purpose, and the second adds necessary detail without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 6 parameters and no output schema, the description covers the essential algorithmic logic but omits details about the return format (e.g., what fields the forecast result contains). This is a minor gap given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full descriptions for all 6 parameters (100% coverage). The description reiterates some and adds the conversion concept, but does not significantly enhance understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: forecasting sprint completion date from backlog size and historical velocity. It explicitly mentions the verb 'forecast' and the resources 'backlog size' and 'historical velocity', distinguishing it from sibling tools like cocomo_estimate or pert_estimate that use different methodologies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. Sibling tools such as cocomo_estimate, pert_estimate, and monte_carlo_schedule offer different estimation approaches, but the description does not explain scenarios where sprint_forecast is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Performs compound time-math operations. Dispatches to the appropriate sub-operation based on the 'operation' parameter. Operations: add_days, add_business_days, diff, convert_tz, parse_nl, format_duration.
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | The time arithmetic operation to perform. Each operation expects specific operands. | |
| operands | Yes | Key-value pairs matching the chosen operation's expected fields. See operation documentation for required keys. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds the dispatch behavior, which is useful but not extensive. There is no contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences that front-load the main purpose and list the operations. No redundant words; every sentence serves a clear purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of multiple sub-operations and the absence of an output schema, the description lacks details about expected return values, operand structures for each operation, and examples. It is minimally viable but not richly informative.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters described. The description lists the operation enum values but does not add new information beyond the schema. It does not specify the required keys for the 'operands' object per operation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it performs compound time-math operations and dispatches to sub-operations, listing the six operations. However, it does not differentiate when to use this tool versus standalone sibling tools like add_business_days or convert_timezone, which overlap with the sub-operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use time_math vs. the separate sibling tools that perform overlapping sub-operations. The agent receives no criteria for choosing between the two paths, leading to potential confusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Estimate wall-clock time AND dollar cost for LLM token usage.
Combines token-to-time mapping with model-specific pricing data. Returns cost breakdown (input/output/overhead) alongside the time estimate.
| Name | Required | Description | Default |
|---|---|---|---|
| tokens | Yes | Total number of tokens in the LLM request (prompt + completion). | |
| model | Yes | LLM model identifier. Unknown models fall back to generic estimates. | |
| tool_calls | No | Number of tool calls expected in the agentic loop. | |
| reasoning_depth | No | Expected depth of chain-of-thought reasoning. | moderate |
| task_type | No | Optional task type for feedback matching. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description adds value by explaining the estimation approach (combines token-to-time mapping with pricing) and the output structure (cost breakdown and time estimate). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. The first sentence states the purpose clearly, the second explains the mechanics and output. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters and no output schema, the description adequately covers the output and basic behavior. Missing details like handling of unknown models or edge cases, but overall sufficient for a straightforward estimation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add parameter-level meaning beyond the schema; it mainly focuses on output. No extra semantics for tokens, model, or other fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool estimates 'wall-clock time AND dollar cost' for LLM token usage, with a specific verb and resource. It distinguishes itself from sibling tools like cocomo_estimate (software cost) and token_time_bridge (likely just time) by clearly targeting LLM token scenarios.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for LLM token cost/time estimation but provides no explicit guidance on when to use this tool versus alternatives like token_time_bridge or cocomo_estimate. No when-not-to-use or exclusion criteria are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Map LLM token budgets to estimated wall-clock time.
Uses model-specific calibration data (tokens/second, reasoning overhead, tool-call latency) to estimate how long a task will actually take. Bridges the gap between token-space (how agents reason) and time-space (what humans need).
| Name | Required | Description | Default |
|---|---|---|---|
| tokens | Yes | Total number of tokens in the LLM request (prompt + completion). | |
| model | Yes | LLM model identifier. Unknown models fall back to generic estimates. | |
| tool_calls | No | Number of tool calls expected in the agentic loop. Each adds overhead latency. | |
| reasoning_depth | No | Expected depth of chain-of-thought reasoning. Deep reasoning adds significant per-token latency. | moderate |
| task_type | No | Optional task type for feedback matching. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the annotations, explaining that it uses model-specific calibration data and accounts for reasoning depth, tool-call latency, and token count. This helps the agent understand the estimation process, though it does not mention limitations or accuracy bounds.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each adding value: core purpose, mechanism, and motivation. It is front-loaded and contains no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, but the description does not mention the return format (e.g., seconds, minutes). It also omits the role of the optional 'task_type' parameter. While the input behavior is well-covered, the lack of output description is a gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all parameters, so the baseline is 3. The description does not elaborate on each parameter beyond what the schema already provides, but the overall context of how parameters contribute to the estimation is helpful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool maps token budgets to wall-clock time using calibration data. It uses a specific verb ('Map') and identifies the resource ('LLM token budgets'). However, it does not explicitly differentiate from siblings like calibrate_estimates or token_cost_estimate, though the purpose is specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no exclusions, and no context about prerequisites or typical use cases. It simply states what it does without any when-to-use or when-not-to-use information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0accuracy_trendadd_business_daysbatch_record_actualscalibrate_estimatescocomo_estimatecocomo_ground_truthcocomo_validatecompare_modelsconvert_timezonecount_business_dayscritical_pathfeedback_healthget_current_timeget_pending_estimatesmonte_carlo_scheduleparse_durationpert_estimaterecord_actualreference_class_estimateschedule_risksprint_forecasttime_mathtoken_cost_estimatetoken_time_bridgeMost tools have distinct purposes, but the high number of estimation-related tools (e.g., cocomo_estimate, cocomo_ground_truth, pert_estimate, reference_class_estimate) could cause confusion for an agent. The time utilities and scheduling tools are clearly separated, but the similar prefix 'cocomo_' and overlapping functionality among estimation methods reduce clarity.
Tool names follow a mix of patterns: many use verb_noun (e.g., add_business_days, get_current_time), but others use noun_noun or descriptive names without verbs (e.g., cocomo_estimate, monte_carlo_schedule, reference_class_estimate). This inconsistency makes it harder for an agent to predict tool names based on a pattern.
24 tools is at the higher end of reasonable for a domain covering estimation, scheduling, time utilities, and token cost analysis. Each tool serves a specific purpose, though some (e.g., time_math) could be broken down further. The count is appropriate for the breadth of functionality offered.
The server covers a wide range of estimation methods (COCOMO, PERT, reference class), scheduling (critical path, Monte Carlo, sprint forecast), and time utilities. However, there are noticeable gaps: no tools for updating or deleting estimates, no team or project management integration, and the token cost tools feel like an add-on rather than core. Some workflows have dead ends.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Hosted MCP server for LLM cost estimation, model comparison, and budget-aware routing.
MCP server for generating rough-draft project plans from natural-language prompts.
MCP server for aerospace calculations: orbital mechanics, ephemeris, DSN operations, ...
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/KyaniteLabs/Epoch'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
