io.github.Craig-Horton/aibvf-mcp

Assemble a valid AI BVF v1.0 portfolio document from loose inputs, deterministically. Agents arrive with initiative names, plain-language functions and half the pillar scores, then hand-build the portfolio JSON and get the shape wrong; this tool builds it right. Give it the organisation (name plus industry in canonical or everyday language) and one entry per initiative (name, function, ai_tier, plus whatever pillar scores you actually have as bare numbers) and it returns the finished document: aliases resolved through the same mapping as map_to_taxonomy, ids generated from names and deduplicated, missing pillars estimated from readiness, tier, function and the published benchmarks with the estimation reported per initiative in estimated_pillars, and the whole document validated before it is returned. CALL THIS when the user lists several AI initiatives in conversation and you need a portfolio document for validate_portfolio, score_portfolio or sequence_portfolio, instead of composing the JSON by hand. Do NOT invent pillar scores to fill it: pass only the numbers the user gave you and let the estimation carry the rest honestly, the estimated pillars carry low confidence and scoring haircuts accordingly. Unresolvable inputs come back as issues with suggestions; ask the user to choose rather than guessing. Every default the assembler applies is named in plain language in assumptions: surface them to the user, the assembler structures inputs and never makes hidden business judgements. This tool creates a document in the response only: nothing is stored, nothing is edited, no state exists between calls. Pure deterministic calculation, no network, auth, or side effects.

The front door for one AI investment decision. CALL THIS FIRST when the user describes an AI idea in ordinary language or asks whether it should proceed. It resolves industry, revenue, business function, AI tier and organisational readiness, then returns the next missing question or an Accelerate, Fix or Stop verdict. Use work_architecture to test whether the end-to-end workflow, affected roles, human decision rights and performance measures have been redesigned. Any explicit work architecture gap blocks Accelerate and stays visible in the audit trail. Pillar scores and work architecture evidence remain optional, and unresolved values are never guessed. Use score_initiative when the canonical fields are already known, score_portfolio for several initiatives, and diagnose_process for measured waste in a running process. Pure deterministic calculation, no network, auth or side effects.

Quantify the annual EUR cost of an AI ambition outrunning the operating model: queues, hand-offs and slow decisions that prevent the organisation capturing the value already assumed in the case. CALL THIS when the user needs the cost of waiting for the organisation to change, or when a Fix plan needs a cost-of-waiting figure. Do not use it to score an AI initiative, estimate the implementation cost, or calculate a process saving: use score_initiative for the investment verdict, diagnose_process for a running process, and recommend_improvements for the change plan. revenue_eur sets the absolute EUR range; ai_tier and readiness together set the drag rate and pace_gap, so gen3 in a siloed organisation costs more than gen1 in an agile one. industry is accepted for a consistent interface and defaults to universal, but does not change this calculation yet. Returns a low/high EUR range, drag rate, pace-gap severity, drivers and source. Pure deterministic calculation — no network, auth, or side effects.

Diagnose a single existing business process from operational evidence and return the intervention, modelled net EUR saving, efficiency gain, verdict and confidence. CALL THIS when the user can describe a process already running, including volume, touch time, waiting, hand-offs, rework, automation and cost. instances_per_year × fte_hours_per_instance × loaded_hourly_rate_eur builds the labour baseline, direct_spend_eur adds the non-labour baseline, and readiness caps the saving that the organisation can realise. The friction signals select the intervention: low automation points to Automate, many hand-offs or wait to Consolidate & re-sequence, rework to Quality controls, low-volume heavy work to Eliminate / insource. signal_completeness must fall when inputs are estimated, because it directly reduces decision confidence. Use score_initiative for a proposed AI investment and infer_readiness when the question is the organisation’s change capacity. Effectiveness bands are benchmark-cited and figures are directional, not audited. Pure deterministic calculation — no network, auth, or side effects.

Look up the published raw benchmark rates behind the value model for one business function and industry. CALL THIS when the user wants to inspect the revenue-uplift and cost-takeout assumptions before scoring, or to compare the value drivers across functions. function selects the base rate range and named drivers; industry applies the multiplier, while universal returns the unadjusted base rate. The output is a rate, expressed as a fraction of revenue, not an initiative verdict or EUR business case. Use score_initiative for an Accelerate/Fix/Stop decision, score_portfolio for several initiatives and diagnose_process for measured operational waste. Pure deterministic lookup — no network, auth, or side effects.

Measure organisational readiness from process data, so the investment case does not depend on an untested maturity claim. CALL THIS before score_initiative, score_portfolio or calculate_pace_layer_drag when the user can provide at least two of five signals: hand-offs, rework, touch ratio, automation level and cycle time. function selects the comparison medians for hand-offs and cycle time; more signals increase confidence and disagreement between them reduces it. claimed_readiness is optional, but pass it when the organisation has declared itself agile, traditional or siloed, because the returned gap exposes where its self-image runs ahead of the process data. Fewer than two signals produces a refusal, not a guess. Pass the measured readiness into the downstream tool, then use diagnose_process when the next question is what to change in that process. Pure deterministic calculation, no network, auth, or side effects.

Return the exact industry, function, AI-tier and readiness values every AI BVF calculation accepts. CALL THIS when the caller needs the complete allowed list or when a free-text value is not obvious. It returns taxonomy only, no score, verdict or language mapping. Use map_to_taxonomy when the user has said customer service, banking, RPA or bureaucratic and you need the one canonical value; use this tool when they need the whole menu of values to choose from. Takes no parameters. Pure deterministic lookup — no network, auth, or side effects.

Map everyday business language to the canonical AI BVF values required by the scoring tools. CALL THIS when the user says customer service, procurement, banking, GenAI copilot or bureaucratic and the matching enum is not certain. Pass only the fields written in free text; each returns the canonical value, what it matched on, or null with suggestions. A null result requires the user to choose from the suggestions, because a plausible guess would change the score. Use list_taxonomy when the user needs every permitted value, then pass the mapped values into score_initiative, diagnose_process, get_benchmark or the portfolio tools. Pure deterministic lookup, no network, auth, or side effects.

Turn a Fix or Stop verdict into the change plan that could earn a re-score, with pillar targets, named plays, owners, stop conditions, cost of waiting and a deadline. CALL THIS after score_initiative returns Fix or Stop. Pass work_architecture when the workflow, roles, decision rights or measures have been tested; any explicit gap adds a work-architecture-redesign play and enters the re-score gate. resistance_type selects the will or skill route, and risk_type selects the regulatory, reputational or operational route. Omitted diagnostics remain provisional and return the question needed to test them. Lead with binding_constraint, surface honest_stop when present, and use rescore_gate to decide whether this remains Fix or becomes Stop. Pure deterministic calculation, no network, auth or side effects.

Canonical-field scorer for one AI initiative. CALL THIS when industry, revenue_eur, function, ai_tier and readiness are already known, or when re-scoring with measured pillar evidence. For a proposal written in ordinary business language, call assess_ai_initiative first; it resolves these fields and asks for anything missing. Pillar scores remain optional: missing pillars are estimated deterministically, reported through pillar_basis, and reduce decision confidence, while a fully estimated pass can never return Accelerate. Returns Accelerate, Fix or Stop, modelled gross and net EUR ranges, decision confidence, sensitivity, assumptions and an audit trail. Use score_portfolio for several initiatives and diagnose_process for measured waste in an existing process. Pure deterministic calculation, no network, auth or side effects.

Score several AI initiatives as one AI BVF v1.0 portfolio and return the board-level position: counts of Accelerate / Fix / Stop, aggregate modelled EUR value range, mean decision confidence, the highest-value initiative, the highest-risk initiative, and every individual result. CALL THIS when the user has a portfolio document and needs to know what it contains before deciding funding or order, instead of looping score_initiative one initiative at a time. The single readiness value applies across every initiative: it changes capture rates and the pace-layer drag, so measure it with infer_readiness first when process data exists. The portfolio must carry organization.revenue_eur for EUR values; initiatives with missing revenue or invalid taxonomy are reported as skipped, never silently counted. Run validate_portfolio first only when the document shape is uncertain, then call sequence_portfolio when the verdicts need turning into a 90-day order. Pure deterministic calculation — no network, auth, or side effects.

Turn a scored AI portfolio into three waves with gates over a configurable horizon, so the roadmap respects the change capacity of each business function. CALL THIS after score_portfolio when the user asks what to stop, fund first, defer or fit into the next 90 days. It does not change any verdict or re-score the business case. Stops enter wave 1 to reclaim budget and attention, quicker Accelerates enter wave 2, complex Accelerates and Fixes enter wave 3 behind their re-score gates. Pass the portfolio returned by score_portfolio directly through portfolio, or pass organization plus initiatives; both score shapes are accepted and nested values are flattened. readiness sets capture rates and pacing, max_parallel_per_function caps simultaneous change in one function per wave, and horizon_days divides the plan into three equal windows. Capacity overflow is reported as a conflict or a deferral beyond the horizon, never hidden. Run recommend_improvements for a Fix before treating its wave placement as permission to proceed. Pure deterministic calculation, no network, auth, or side effects.

Check whether a supplied AI BVF v1.0 portfolio document has the shape the portfolio tools require, before scoring, sequencing, storing or sharing it. CALL THIS when the document came from a file, another system or hand-built JSON and its structure is uncertain. It checks required fields, taxonomy values and 0–100 pillar ranges only; it does not judge the evidence or calculate a verdict. Pillars may be bare numbers or { value, confidence } objects, both are valid. Use assemble_portfolio when the user has a list of initiatives in conversation and needs the document built for them, score_portfolio when the document is already ready for verdicts, and sequence_portfolio only after its initiatives are scoreable. Returns valid=true or one error per failing JSON path. Pure deterministic validation — no network, auth, or side effects.