MCP Tools Reference

VoLCA exposes 35 tools via MCP. All tools return JSON as a text content block.

Quick reference

Tool	Required parameters	Purpose
list_databases	–	LCA / ACV: list all loaded LCA databases (Agribalyse, ecoinvent, …)
load_database	database	LCA / ACV: load a configured database into memory so it can be queried
unload_database	database	LCA / ACV: unload a database from memory to free RAM
derive_database	database, new_name	LCA / ACV: read a database's source files again under another allocation key, and register the result under a new name
list_presets	–	LCA / ACV: list named classification filter presets configured in this instance
search_activities	database, name	LCA / ACV: search for activities (processes) by name, geography, product, classification, or preset
search_flows	database, query	LCA / ACV: search flows by name
get_activity	database, process_id	LCA / ACV: get detailed information about an activity: name, location, exchanges, reference product, metadata
aggregate	database, process_id, scope	LCA / ACV: aggregate exchanges, supply chain entries, or biosphere flows with SQL group-by-style filters
get_supply_chain	database, process_id	LCA / ACV: get a flat list of all upstream activities in the supply chain (chaîne amont, filière, intrants)
get_inventory	database, process_id	LCA / ACV: compute the Life Cycle Inventory (LCI): biosphere flows (emissions and resource extractions) for an activity's full supply chain
get_impacts	database, process_id, method_id	LCA / ACV: compute Life Cycle Impact Assessment (LCIA) scores for an activity
compute_sensitivity	database, process_id, method_id, perturbations	LCA / ACV: sensitivity analysis: sweep relative perturbations of technosphere coefficients A_ij and report the resulting impact for each
list_methods	–	LCA / ACV: list all loaded LCIA methods (impact assessment methods like climate change, acidification, eutrophication, land use, water scarcity)
get_flow_mapping	database, method_id	LCA / ACV: get the mapping between a method's characterization factors and database flows, showing match coverage
get_characterization	database, method_id	LCA / ACV: look up characterization factors for a method matched against database flows
explain_cf	database, method_id, flow_id	LCA / ACV: explain why one elementary flow scores with the characterization factor it does
get_contributing_flows	database, process_id, method_id	LCA / ACV: identify which elementary flows (emissions/resources) contribute most to a specific impact category
get_contributing_activities	database, process_id, method_id	LCA / ACV: identify which upstream activities contribute most to a specific impact category
list_geographies	database	LCA / ACV: list all geography codes present in a database, with display names and parent regions
list_classifications	database	LCA / ACV: list classification systems in a database
get_path_to	database, process_id, target	LCA / ACV: find the shortest supply chain path from a process to the first upstream activity whose name matches a pattern
get_consumers	database, process_id	LCA / ACV: find all activities that transitively consume (depend on) a given supplier
count_search_matches	database, query	LCA / ACV: how many processes, products and flows one query matches in a database, in a single call
compare_impacts	database_a, process_id_a, method_id_a, database_b, process_id_b, method_id_b	LCA / ACV audit: score the same logical activity on two (database, method) pairs and return the per-impact-category delta plus a per-flow drill-down
compare_activities	database, process_id, other_process_id	LCA / ACV: compare two activities exchange by exchange: the lines one has and the other does not, and the lines whose amount or unit differ
compare_databases	database, other_database	LCA / ACV: compare two loaded databases, typically two versions of one: the activities added, removed and changed, each changed one with the exchange-level detail compare_activities gives
score_activity	database, process_id, collection	LCA / ACV: compute the full LCIA panel + every configured scoring set for an activity in one call
score_activities	database, collection, process_ids	LCA / ACV: rank N activities against one scoring set in one call
list_scoring_sets	–	LCA / ACV: list formula-based scoring sets defined in loaded method collections
get_gap_report	database	LCA / ACV: supplier-gap report of a database: every input demand still unsupplied after internal resolution and cross-database linking, aggregated per (product, supplier activity the input named, location, unit) and ranked by demanding edges
get_quality_report	database	LCA / ACV: dataset-soundness report of a database, for the people who build or repair one: the structural defects a score cannot reveal
get_computed_quality_report	database	LCA / ACV: computed-checks report of a LOADED database: what the data computes, judged against the catalogue's own norms
get_characterization_coverage	database	LCA / ACV: characterization-coverage report of a database against the loaded LCIA method collections, for the people who maintain databases
edit_exchanges	database, process_id	LCA / ACV: change what one activity consumes and emits, keeping the activity itself

Tool details

list_databases

LCA / ACV: list all loaded LCA databases (Agribalyse, ecoinvent, …). Call this first to discover which databases are available before searching.

load_database

LCA / ACV: load a configured database into memory so it can be queried. Its declared dependencies are loaded first (needed for cross-database flow linking). A database must be loaded before search/score/impact tools can target it; use list_databases to see which are configured. No effect if it is already loaded.

Parameter	Type	Required	Description
database	string	✓	Database name

unload_database

LCA / ACV: unload a database from memory to free RAM. The on-disk data is kept and the database can be reloaded later with load_database. Refuses if another loaded database still depends on it: unload the dependents first.

Parameter	Type	Required	Description
database	string	✓	Database name

derive_database

LCA / ACV: read a database's source files again under another allocation key, and register the result under a new name. Use it to ask what a study would look like with the multi-output blocks divided by a physical property instead of the shares the source declares: 'wet mass' divides a block by the mass of each product, 'dry mass' by its dry matter, 'declared' keeps the source's own shares. The source is untouched and both stay usable side by side. This is a full load, not a copy: seconds to minutes on a large database. Refused when the key divides no block, when it is the key the source already reads under, when the products carry no such property, and on a read-only instance.

Parameter	Type	Required	Description
allocation	string		The key its multi-output blocks are divided by: declared (the source's own shares, the default) | dry mass | wet mass.
database	string	✓	Database name
new_name	string	✓	Name to register the re-keyed database under. Must not already exist.

list_presets

LCA / ACV: list named classification filter presets configured in this instance. Each preset bundles multiple (system, value, mode) classification filters under a human-readable label. Use the filter values from a preset as inputs to search_activities classification parameters.

search_activities

LCA / ACV: search for activities (processes) by name, geography, product, classification, or preset. Returns a paginated list of matching activities with their process IDs. Entry point for any LCA/ACV question about a specific product or process: food (yaourt, steak, pain, lait, fromage), packaging (PET, verre, carton), matériaux, énergie, transport. Accepts non-technical synonyms: empreinte carbone, empreinte environnementale, impact environnemental, occupation des sols, surface agricole, prairie, pâturage, intrants, filière, chaîne amont.

Parameter	Type	Required	Description
classification	string		Classification system name to filter by (e.g. 'ISIC rev.4 ecoinvent', 'CPC'). Use list_classifications to see available systems.
classification_match	string		Match mode: "equals" (case-insensitive equality) or "contains" (substring, default)
classification_value	string		Value within the classification system to match
database	string	✓	Database name
exact	boolean		If true, the name must match exactly (case-insensitive equality) rather than as a substring, and the geography must be the location itself rather than that location plus every location inside it
geo	string		Geography/location filter (e.g. 'FR', 'DE', 'GLO'). Matches that location, plus every location inside it ('US' also matches 'US-WECC', 'RER' matches 'FR'). Which place sits inside which comes from the engine's location table, never from how a code is spelled, so 'GL' does not match 'GLO'.
limit	integer		Max results (default 20)
name	string	✓	Name substring to search for (or exact name if exact=true). The identifier a source file gave a dataset (a SimaPro 'Process identifier'), whole or the four or more characters that tell it apart, brings that dataset's products to the top of the results.
preset	string		Name of a classification preset (from list_presets): expands to its bundled filters. Can be combined with explicit classification filters.
product	string		Product name filter

search_flows

LCA / ACV: search flows by name. Three kinds of flow answer, and each result says which it is in its 'kind' field: a biosphere flow, meaning a substance exchanged with nature (CO2, CH4, water, land occupation); a technosphere flow, meaning a product one activity makes and another consumes; or a waste flow. Pass kind=biosphere to look for a substance alone, which is what a question about characterization factors or inventory contributions is usually after. A biosphere flow also reports the medium it is exchanged with in 'category' (air, water, soil, resource), which is how a resource taken from nature is told apart from an emission released to it; the other two kinds have no medium.

Parameter	Type	Required	Description
database	string	✓	Database name
kind	string		Keep only these kinds of flow: technosphere | biosphere | waste. Name several separated by commas, as in "biosphere,waste". Omit for all three.
limit	integer		Max results (default 20)
query	string	✓	Flow name to search for

get_activity

LCA / ACV: get detailed information about an activity: name, location, exchanges, reference product, metadata. Use exchange_type / is_input / flow to filter exchanges and reduce response size.

Parameter	Type	Required	Description
database	string	✓	Database name
exchange_type	string		Filter exchanges by kind: "technosphere" (product/input flows), "biosphere" (emissions/resources), "waste" (third flow kind: residuals routed to treatment), or "all" (default)
flow	string		Filter exchanges by flow name or synonym, the way search_flows reads a query: every word must appear, case-blind, in any order, punctuation optional
is_input	boolean		If true, return only inputs; if false, only outputs; omit for both. Combines with exchange_type.
process_id	string	✓	Process ID (activityUUID_productUUID format)

aggregate

LCA / ACV: aggregate exchanges, supply chain entries, or biosphere flows with SQL group-by-style filters. One primitive replaces ad-hoc decomposition tools: express any 'how much X is in Y' question as one call. Also the right tool for 'combien de surface agricole / d'eau / d'énergie dans un produit ?' style questions via scope=biosphere or scope=supply_chain. Examples: - Total electricity in direct inputs: scope=direct, is_input=true, filter_name=Electricity, filter_unit=kWh - Mass breakdown of direct inputs: scope=direct, is_input=true, filter_unit=kg, group_by=name - Total energy across the supply chain: scope=supply_chain, max_depth=2, filter_classification=["Category type=energy:exact"] - Largest pasture occupation flow: scope=biosphere, filter_name=Occupation, pasture, group_by=name - Total upstream electricity without double counting: scope=consumption, filter_name=electricity, filter_consumer_not=electricity - Grass eaten by cattle across the whole chain: scope=consumption, filter_name=grass, filter_consumer=cattle scope=supply_chain rows are cumulative productions: when a filtered product feeds another filtered product (electricity high→medium→low voltage), their sum double-counts the chain. scope=consumption has one row per scaled technosphere edge (product, supplier, consumer), so its sums are actual consumption events; the default total is gross throughput; exclude intra-family edges with filter_consumer_not to get the amount delivered outside the filtered family. Byproduct edges keep their negative sign. The filter_classification parameter accepts a list of strings in "System=Value[:exact]" form (default mode is 'contains').

Parameter	Type	Required	Description
aggregate	string		sum_quantity | count | share (default: sum_quantity)
database	string	✓	Database name
filter_classification	string[]		List of "System=Value[:exact]" strings; defaults to 'contains' mode
filter_consumer	string		Only for scope=consumption: case-insensitive substring on the consuming activity's name
filter_consumer_not	string		Only for scope=consumption: comma-separated consumer-name exclude list (each item is a substring; a name containing a comma cannot be expressed)
filter_is_reference	boolean		Filter by reference-product flag (typically for outputs)
filter_name	string		Case-insensitive substring on flow/activity name
filter_name_not	string		Comma-separated substring exclude list
filter_target_name	string		Only for scope=direct technosphere or scope=consumption: filter by supplier activity name
filter_unit	string		Whole unit name, case-insensitive: "MJ" and "mj" are the same unit, "kg" does not match "kgm"
group_by	string		name | flow_id | name_prefix | unit | classification.<system> | location | target_name | consumer_name
is_input	boolean		Only for scope=direct: true=inputs only, false=outputs only
max_depth	integer		Only for scope=supply_chain: max hops from the root activity
preset	string		Name of a classification preset (from list_presets): expanded and merged into filter_classification.
process_id	string	✓	Process ID (activityUUID_productUUID format)
scope	string	✓	direct | supply_chain | biosphere | consumption

get_supply_chain

LCA / ACV: get a flat list of all upstream activities in the supply chain (chaîne amont, filière, intrants). The 'quantity' field is the cumulative scaled amount relative to the functional unit (scaling_factor × root reference product amount). To get the per-step yield ratio between two connected entries, divide the supplier's scaling_factor by the consumer's scaling_factor. Summing quantities across entries that feed each other (electricity high→medium→low voltage) double-counts the chain, so use aggregate with scope=consumption for upstream totals. Every entry states its own 'unit': the producing activity's reference product unit, which a SimaPro or Brightway Excel import records in the canonical unit of its dimension (kg, mj, m3). It is not always the unit written on the exchange that consumes it, so an input of 0.22 kWh appears here in mj (1 kWh = 3.6 MJ). Read the unit off the entry, never assume it.

Parameter	Type	Required	Description
classification	string		Classification system name (e.g. 'Category', 'Category type')
classification_match	string		Match mode: "exact" (case-insensitive equality) or "contains" (substring, default)
classification_value	string		Value within the classification system
database	string	✓	Database name
limit	integer		Max results (default 100)
location	string		Filter by geography/location: that location, plus every location inside it ('US' also matches 'US-WECC'), case-insensitive
max_depth	integer		Max depth from root (1 = direct inputs only)
min_quantity	number		Min scaled quantity threshold
name	string		Filter by activity name
preset	string		Name of a classification preset (from list_presets): expands to its bundled filters. Unioned with any explicit classification / classification_value / classification_mode parameters.
process_id	string	✓	Process ID (activityUUID_productUUID format)
substitutions	object[]		Optional what-if supplier substitutions. Each entry: {from: oldSupplierPID, to: newSupplierPID, consumer: consumerPID}. PIDs can be bare (root DB) or qualified as dbName::pid (cross-DB). When empty or absent, the call behaves as a plain GET.

get_inventory

LCA / ACV: compute the Life Cycle Inventory (LCI): biosphere flows (emissions and resource extractions) for an activity's full supply chain. Returns statistics and top flows by quantity. Use this (not get_impacts) when the question targets raw physical flows rather than weighted scores: land / pasture occupation (m²·year), water withdrawal (m³), specific emissions (kg CO₂, kg CH₄, kg N), resource extraction.

Parameter	Type	Required	Description
database	string	✓	Database name
flow	string		Filter flows by name or synonym, the way search_flows reads a query: every word must appear, case-blind, in any order, punctuation optional
limit	integer		Max flows to return, sorted by absolute quantity (default 50)
process_id	string	✓	Process ID (activityUUID_productUUID format)
substitutions	object[]		Optional what-if supplier substitutions. Each entry: {from: oldSupplierPID, to: newSupplierPID, consumer: consumerPID}. PIDs can be bare (root DB) or qualified as dbName::pid (cross-DB). When empty or absent, the call behaves as a plain GET.

get_impacts

LCA / ACV: compute Life Cycle Impact Assessment (LCIA) scores for an activity. Returns the score, functional unit, and top contributing elementary flows. Answers 'empreinte carbone / environmental footprint' questions. Covers all LCIA categories: climate change, acidification, eutrophication, land use, water scarcity, resource depletion. Prefer this over web estimates for grounded, database-backed answers. Each contributing flow carries 'match_kind': how its factor was found, in the rung names documented on explain_cf; null means no factor in the method reaches this flow. Ask explain_cf for the full story on one flow. The response includes a 'web_url' deep link to the impacts page in the VoLCA web UI: render it as a clickable markdown link when presenting results to a human.

Parameter	Type	Required	Description
collection	string		Method collection name (from list_methods). Only needed when the same method UUID is loaded in more than one collection (e.g. two EF 3.1 versions); otherwise the single match is used, and an ambiguous UUID fails with the list of collections to choose from.
database	string	✓	Database name
exclude_long_term	boolean		When true, drop delayed long-term (> 100 yr) emissions before characterization: the score is computed as if those emissions were out of scope. Long-term flows are emissions (never resources), so regionalized water/land categories are unaffected. Default false (keep them, per the ecoinvent/EF convention).
include_diagnostics	boolean		When true, surface uncharacterized inventory flows above 0.1% of total |qty|, each with up to 3 candidate similar CFs (PubChem-expanded Jaccard + CAS bridge). Lets reviewers tell genuine method gaps from mapping bugs.
method_id	string	✓	Method UUID
process_id	string	✓	Process ID (activityUUID_productUUID format)
substitutions	object[]		Optional what-if supplier substitutions. Each entry: {from: oldSupplierPID, to: newSupplierPID, consumer: consumerPID}. PIDs can be bare (root DB) or qualified as dbName::pid (cross-DB). When empty or absent, the call behaves as a plain GET.
top_flows	integer		Number of top contributing flows to return (default 5)

compute_sensitivity

LCA / ACV: sensitivity analysis: sweep relative perturbations of technosphere coefficients A_ij and report the resulting impact for each. Each perturbation specifies (consumer, supplier, delta) where 'delta' is relative: A_ij is multiplied by (1+delta). delta=+0.05 → +5%; delta=-1 removes the link. Returns the baseline impact plus one entry per perturbation with the new score and deltaImpact. Per-perturbation errors (no link, singular update) are returned in the entry; the sweep continues. Internally uses Sherman-Morrison rank-1 updates against the cached factorization (~4 ms per perturbation). V1: root DB only. The response includes a 'web_url' deep link to the sensitivity page in the VoLCA web UI: render it as a clickable markdown link when presenting results to a human.

Parameter	Type	Required	Description
collection	string		Method collection name (from list_methods). Only needed when the same method UUID is loaded in more than one collection (e.g. two EF 3.1 versions); otherwise the single match is used, and an ambiguous UUID fails with the list of collections to choose from.
database	string	✓	Database name
method_id	string	✓	Method UUID
perturbations	string[]	✓	Array of perturbations to apply in parallel. Each entry is an object {consumer: ProcessId, supplier: ProcessId, delta: number, label?: string}. 'delta' is RELATIVE: the technosphere coefficient A_ij is multiplied by (1+delta). Use +0.05 for +5%, -1 to remove a link. 'consumer' is the activity that consumes the input; 'supplier' is the activity that produces it. Both must live in the root database (V1 limitation). 'label' is optional and echoed in the response for correlation.
process_id	string	✓	Process ID (activityUUID_productUUID format)

list_methods

LCA / ACV: list all loaded LCIA methods (impact assessment methods like climate change, acidification, eutrophication, land use, water scarcity).

get_flow_mapping

LCA / ACV: get the mapping between a method's characterization factors and database flows, showing match coverage.

Parameter	Type	Required	Description
collection	string		Method collection name (from list_methods). Only needed when the same method UUID is loaded in more than one collection (e.g. two EF 3.1 versions); otherwise the single match is used, and an ambiguous UUID fails with the list of collections to choose from.
database	string	✓	Database name
max_unmatched	integer		Cap on each unmatched list (default 50)
method_id	string	✓	Method UUID
process_id	string		Required for the unmatched_db_flows ranking: ranks unmatched flows by their share of this process's inventory.
verbose	boolean		When true, return per-CF and per-flow detail beyond the coverage stats: an unmatched_cfs list (CFs with no DB flow), and an unmatched_db_flows list ranked by inventory contribution to a chosen process when process_id is set.

get_characterization

LCA / ACV: look up characterization factors for a method matched against database flows. Without 'flow' filter, returns top factors by absolute value. With 'flow', searches by name. Shows CF value, direction, matched database flow, and match strategy.

Parameter	Type	Required	Description
collection	string		Method collection name (from list_methods). Only needed when the same method UUID is loaded in more than one collection (e.g. two EF 3.1 versions); otherwise the single match is used, and an ambiguous UUID fails with the list of collections to choose from.
database	string	✓	Database name
flow	string		Filter by flow name (case-insensitive substring, matches both method CF name and database flow name)
limit	integer		Max results (default 20)
method_id	string	✓	Method UUID

explain_cf

LCA / ACV: explain why one elementary flow scores with the characterization factor it does. Answers 'why this factor, and which line of the method was used?'. The 'explanation' field is a list of sentences written by the engine: relay them as they are rather than interpreting the codes yourself. 'outcome' is one of: 'characterized' (a factor applies), 'conversion_refused' (a factor was found but the flow's unit cannot be converted to the factor's basis, so the flow scores nothing), 'no_factor' (nothing in the method reaches this flow). 'match.rung' names how the factor was found: 'flow_id' (the method names this exact flow), 'same_unit_name' (a factor line declared in this flow's own unit), 'exact_name' (name and compartment match), 'compartment_default' (the line the method writes for the whole compartment), 'if_absent' (the method writes nothing for this flow's subcompartment, and a row of the compartment table sends it to another one), 'cas_number' (a factor for the same substance by CAS), 'region_base_name' (the base substance, the name's region suffix being untagged by the method), 'energy_content' (what the method charges for a unit of energy, applied to the content the flow's own name states), 'ore_base_element' (the base element of a graded ore). 'steps_tried' lists the rungs tried before that one. 'match.unitConversion' names the bridge that carried the amount onto the factor's basis: 'same_unit', 'unknown_unit' (the flow's unit is not in the unit table, so the amount passed as declared), 'unit_converted', 'normalized_to_base_unit' (the factor is written as a result expression like 'kg CO2 eq', so the amount was brought to the flow's base unit), 'energy_content' (carried across dimensions by the flow's energy density). 'match.refusal' names why no bridge could: 'different_dimensions', 'no_base_unit', 'energy_bridge_failed'. The response includes a 'web_url' deep link to the explain-cf page in the VoLCA web UI: render it as a clickable markdown link when presenting results to a human.

Parameter	Type	Required	Description
collection	string		Method collection name (from list_methods). Only needed when the same method UUID is loaded in more than one collection (e.g. two EF 3.1 versions); otherwise the single match is used, and an ambiguous UUID fails with the list of collections to choose from.
database	string	✓	Database name
flow_id	string	✓	Database flow UUID, as returned by search_flows or in the flow_id field of get_contributing_flows
method_id	string	✓	Method UUID

get_contributing_flows

LCA / ACV: identify which elementary flows (emissions/resources) contribute most to a specific impact category. Answers 'which emissions drive my climate change score?'. Each flow carries 'match_kind': how its factor was found, in the rung names documented on explain_cf; null means no factor in the method reaches this flow. Ask explain_cf for the full story on one flow. The response includes a 'web_url' deep link to the contributing-flows page in the VoLCA web UI: render it as a clickable markdown link when presenting results to a human.

Parameter	Type	Required	Description
collection	string		Method collection name (from list_methods). Only needed when the same method UUID is loaded in more than one collection (e.g. two EF 3.1 versions); otherwise the single match is used, and an ambiguous UUID fails with the list of collections to choose from.
database	string	✓	Database name
exclude_long_term	boolean		When true, drop delayed long-term (> 100 yr) emissions before characterization: the score is computed as if those emissions were out of scope. Long-term flows are emissions (never resources), so regionalized water/land categories are unaffected. Default false (keep them, per the ecoinvent/EF convention).
include_diagnostics	boolean		When true, surface uncharacterized inventory flows above 0.1% of total |qty|, each with up to 3 candidate similar CFs (PubChem-expanded Jaccard + CAS bridge).
limit	integer		Max flows to return, sorted by contribution (default 20)
method_id	string	✓	Method UUID for the impact category
process_id	string	✓	Process ID (activityUUID_productUUID format)

get_contributing_activities

LCA / ACV: identify which upstream activities contribute most to a specific impact category. Answers 'which suppliers drive my climate change score?' Uses exact matrix-based computation, valid even for cyclic supply chains. Each contributing activity carries a 'web_url' deep link to its page in the VoLCA web UI: render these as clickable markdown links when presenting results to a human so they can drill into a specific supplier.

Parameter	Type	Required	Description
collection	string		Method collection name (from list_methods). Only needed when the same method UUID is loaded in more than one collection (e.g. two EF 3.1 versions); otherwise the single match is used, and an ambiguous UUID fails with the list of collections to choose from.
database	string	✓	Database name
exclude_long_term	boolean		When true, drop delayed long-term (> 100 yr) emissions before characterization: the score is computed as if those emissions were out of scope. Long-term flows are emissions (never resources), so regionalized water/land categories are unaffected. Default false (keep them, per the ecoinvent/EF convention).
limit	integer		Max processes to return, sorted by contribution (default 10)
method_id	string	✓	Method UUID for the impact category
process_id	string	✓	Process ID (activityUUID_productUUID format)

list_geographies

LCA / ACV: list all geography codes present in a database, with display names and parent regions. Use the 'geo' value as the geography filter in search_activities.

Parameter	Type	Required	Description
database	string	✓	Database name

list_classifications

LCA / ACV: list classification systems in a database. Without 'system': returns system names and activity counts only (lightweight). With 'system': returns all values for that system. Add 'filter' to narrow values by substring.

Parameter	Type	Required	Description
database	string	✓	Database name
filter	string		Substring filter applied to values when a system is specified (case-insensitive).
system	string		Classification system name to inspect (e.g. 'ISIC rev.4 ecoinvent'). If omitted, returns only system names and counts.

get_path_to

LCA / ACV: find the shortest supply chain path from a process to the first upstream activity whose name matches a pattern. Each step includes cumulative_quantity, scaling_factor, and local_step_ratio (upstream ÷ downstream scaling factors). total_ratio is the product of all local_step_ratio values: the end-to-end conversion factor.

Parameter	Type	Required	Description
database	string	✓	Database name
process_id	string	✓	Process ID (activityUUID_productUUID format)
target	string	✓	Case-insensitive name substring to stop at

get_consumers

LCA / ACV: find all activities that transitively consume (depend on) a given supplier. Returns a flat list, each with a crDepth field: 1 = direct consumer, 2 = consumer of consumer, etc. Useful for tracing downstream use of a raw material, e.g. finding transformed food products in Agribalyse that use a raw ingredient.

Parameter	Type	Required	Description
classification	string		Classification system name (e.g. 'ISIC rev.4 ecoinvent')
classification_value	string		Classification value substring to match
database	string	✓	Database name
include_edges	boolean		When true, the response carries every technosphere edge whose endpoints are both reachable from the supplier. Lets callers reconstruct supplier→consumer paths without a second get_path_to call.
limit	integer		Max results (default 1000)
location	string		Filter by geography/location (e.g. 'FR', 'DE'): that location, plus every location inside it ('RER' also matches 'FR'), case-insensitive
max_depth	integer		Max hops from supplier (1 = direct consumers only)
name	string		Filter by name (case-insensitive substring)
preset	string		Name of a classification preset (from list_presets): expands to its bundled filters
process_id	string	✓	Process ID of the supplier (activityUUID_productUUID format)
product	string		Filter by product name (case-insensitive substring)

count_search_matches

LCA / ACV: how many processes, products and flows one query matches in a database, in a single call. The three are disjoint and together cover the database: a process is an activity row (what you search, get and score), a product is a technosphere flow one activity makes and another consumes, a flow is what is exchanged with nature or discarded. Use it to tell which of the three a query is really about before listing any of them: a term matching 2 processes and 300 flows is a substance name, not a product.

Parameter	Type	Required	Description
database	string	✓	Database name
query	string	✓	The search term to count matches for

compare_impacts

LCA / ACV audit: score the same logical activity on two (database, method) pairs and return the per-impact-category delta plus a per-flow drill-down. Built for cross-database mapping audits: e.g. compare BAFU + EF3.1 vs SimaPro + EF3.1 to surface flows whose contributions diverge because of mapping gaps, not because of underlying chemistry. Headline field is delta.relative_pct: the metric to drive down by adding synonym pairs to data/flows.csv or by regenerating the chem_synonyms snapshot.

Parameter	Type	Required	Description
collection_a	string		Method collection for the A side; needed only when method_id_a is loaded in more than one collection.
collection_b	string		Method collection for the B side; needed only when method_id_b is loaded in more than one collection.
database_a	string	✓	First database name
database_b	string	✓	Second database name
method_id_a	string	✓	Method UUID for the A side
method_id_b	string	✓	Method UUID for the B side
process_id_a	string	✓	Process ID in database_a (activityUUID_productUUID format)
process_id_b	string	✓	Process ID in database_b (activityUUID_productUUID format)
top_flows	integer		Per-side flow drill-down depth (default 10)

compare_activities

LCA / ACV: compare two activities exchange by exchange: the lines one has and the other does not, and the lines whose amount or unit differ. The other activity may sit in another loaded database (other_database), which is how an adapted copy is held against the dataset it was adapted from. Lines pair on the flow identifier and role first, then on the flow name (case and a trailing ' {GEO}' aside), compartment and role, and a changed line says which in 'match' ('SameFlow' or 'SameFlowName'). The role is part of a line: a flow moving from input to coproduct is one line removed and one added. The lines of one flow in one unit are summed, so a supplier swapped at an equal total does not show; one flow written in several units on a side is listed under 'uncompared' rather than summed. Amounts are equal within a relative 1e-9, and units compare by name. 'summary' lists the activity name, location, product name and allocation share where they differ; the product's amount is reported by its reference line. Nothing listed means the two say the same thing.

Parameter	Type	Required	Description
database	string	✓	Database name
other_database	string		Loaded database holding that activity, when it is not this one
other_process_id	string	✓	Process ID of the activity to compare against (activityUUID_productUUID format)
process_id	string	✓	Process ID (activityUUID_productUUID format)

compare_databases

LCA / ACV: compare two loaded databases, typically two versions of one: the activities added, removed and changed, each changed one with the exchange-level detail compare_activities gives. Activities pair in a cascade, each rung seeing only what the rungs before it left unpaired: 'SameProcessId' (the same activityUUID_productUUID), then 'SameNames' (the same activity and product names, case and a trailing ' {GEO}' aside, at the same location), then 'SameProduct' (the same reference product flow at the same location, from the same kind of activity, so the market for a product never pairs with its production). Each changed activity says the rung that paired it. A key several activities answer to, on either side, pairs none of them: they are listed under 'ambiguous' and not compared. 'database' is the base, usually the older version. The counts always cover the full lists and limit truncates each list: pass a limit when calling from a conversation, since two versions of a large database differ by thousands of activities.

Parameter	Type	Required	Description
database	string	✓	Database name
limit	integer		Max entries per list (added, removed, changed, ambiguous), in name order (default: all). The counts always cover the full lists.
other_database	string	✓	Loaded database to compare against, usually the newer version

score_activity

LCA / ACV: compute the full LCIA panel + every configured scoring set for an activity in one call. Returns per-method impact scores, per-scoring-set aggregate scores, per-scoring-set indicator breakdown (one entry per scoring variable), display units, and a 'web_url' to the matching view. Use this when you would otherwise call get_impacts N times across every method of a collection: replaces N round-trips with one batched solve. Discover available scoring sets with list_scoring_sets. Render the 'web_url' as a clickable markdown link when presenting results to a human.

Parameter	Type	Required	Description
collection	string	✓	Method collection name (use list_methods to discover)
database	string	✓	Database name
exclude_long_term	boolean		When true, drop delayed long-term (> 100 yr) emissions before characterization: the score is computed as if those emissions were out of scope. Long-term flows are emissions (never resources), so regionalized water/land categories are unaffected. Default false (keep them, per the ecoinvent/EF convention).
process_id	string	✓	Process ID (activityUUID_productUUID format)
scoring_sets	string[]		For score_activity: restricts the response's scoringResults / scoringUnits / scoringIndicators to these scoring set names. For score_activities: selects the single scoring set the columnar response is projected against; pass one name. Auto-picked when the collection has exactly one configured set. Use list_scoring_sets to discover the configured names. An unknown name fails the call with the list of available names.
substitutions	object[]		Optional what-if supplier substitutions. Each entry: {from: oldSupplierPID, to: newSupplierPID, consumer: consumerPID}. PIDs can be bare (root DB) or qualified as dbName::pid (cross-DB). When empty or absent, the call behaves as a plain GET.

score_activities

LCA / ACV: rank N activities against one scoring set in one call. Returns a columnar JSON shape: {scoring_set, scoring_unit, functional_unit?, columns, rows, not_found, invalid}. 'columns' is the header (['name', 'process_id', 'web_url', 'total', <indicator keys...>]) and 'rows' is a 2D array of scalars: one row per resolved activity. Hoisting the constant metadata once and packing each activity as a flat array of scalars makes this shape ~6× smaller than a row-shaped JSON for batches of 24+ activities. The top-level 'functional_unit' is only emitted when every resolved row shares the same one; otherwise it is dropped and 'functional_unit' appears as a per-row column instead (the 'columns' header reflects which shape was emitted). Per-method scores are NOT included: call score_activity on a specific process_id for that drill-down. Unresolved process IDs land in not_found / invalid. The chosen scoring set must be unambiguous: pass scoring_sets: ["<one>"] when the collection has more than one scoring set configured. The 'web_url' column on each row is a deep link to the activity's impacts page in the VoLCA web UI: render it as a clickable markdown link when presenting results to a human.

Parameter	Type	Required	Description
collection	string	✓	Method collection name
database	string	✓	Database name
exclude_long_term	boolean		When true, drop delayed long-term (> 100 yr) emissions before characterization: the score is computed as if those emissions were out of scope. Long-term flows are emissions (never resources), so regionalized water/land categories are unaffected. Default false (keep them, per the ecoinvent/EF convention).
process_ids	string[]	✓	Process IDs to score (activityUUID_productUUID). All resolved in one multi-RHS solve.
scoring_sets	string[]		For score_activity: restricts the response's scoringResults / scoringUnits / scoringIndicators to these scoring set names. For score_activities: selects the single scoring set the columnar response is projected against; pass one name. Auto-picked when the collection has exactly one configured set. Use list_scoring_sets to discover the configured names. An unknown name fails the call with the list of available names.
summary_only	boolean		When true, score_activities replaces the per-indicator columns with a single 'dominant_indicator' column whose cells are objects {key, share_pct} (e.g. {"key": "ldu", "share_pct": 82.3}): the indicator with the largest absolute share of each activity's total. Use this when ranking large batches before drilling into a single PID with score_activity. Default false.

list_scoring_sets

LCA / ACV: list formula-based scoring sets defined in loaded method collections. A scoring set is a configured aggregation of LCIA category scores into one or more weighted/normalized 'score' values (e.g. an overall single score plus per-area-of-protection sub-scores). For each set returns: name, display unit, variables referenced (with the impact category each binds to), computed intermediates, display labels (variable → human-readable indicator name shown in score breakdowns), normalization and weighting factors, and the score formulas. Use the returned set names as keys when interpreting score_activity / score_activities responses.

Parameter	Type	Required	Description
collection	string		Method collection name. If omitted, returns scoring sets across all loaded collections, grouped by collection.

get_gap_report

LCA / ACV: supplier-gap report of a database: every input demand still unsupplied after internal resolution and cross-database linking, aggregated per (product, supplier activity the input named, location, unit) and ranked by demanding edges. Each gap carries every reason it was blocked for, the number of consumer edges and distinct consumers, the total demanded amount, and the top consuming processes. Answers 'what is missing to switch or complete this database's background dependency?': typically read right after a relink.

Parameter	Type	Required	Description
database	string	✓	Database name
limit	integer		Max gap entries to return, biggest first (default: all). The header counts always cover the full report, so a truncated list stays countable.

get_quality_report

LCA / ACV: dataset-soundness report of a database, for the people who build or repair one: the structural defects a score cannot reveal. All checks run on staged and loaded databases alike: entries without exactly one reference exchange, coproduct allocation percentages that don't sum to 100% (or blocks where only some coproducts carry one), entries duplicated outright (same name, location and reference product), non-finite amounts or a zero reference amount, missing metadata (description, classification, location, units absent from the registry), geography the source never declared, read off the dataset name (SimaPro writes 'Unspecified' in whole databases) or filled in by the loader; stored amounts that disagree with the formulas documenting them, and formulas the engine could not evaluate (mathematicalRelation, checked at parse time), distinct names that merge under SimaPro's 80-character truncation, exchanges without the pedigree scores their database otherwise carries, reference products nothing in the database consumes (expected for final products), land transformation whose 'to' and 'from' areas don't balance within an activity, oxygen-demand or organic-carbon measures in a physically impossible order (BOD5 above COD, or dissolved above total organic carbon), flow CAS numbers whose check digit does not confirm them, and individual allocation percentages outside the 0-100% range. Each finding carries a severity (danger, warning, info), the activity it was found on, and a readable detail. Answers 'is this dataset well formed?': the complement of the supplier-gap report, which answers 'what is this database missing?'

Parameter	Type	Required	Description
database	string	✓	Database name
limit	integer		Max findings to return per check, worst first (default: all). Each check's offenderCount always covers its full list, so a truncated list stays countable.

get_computed_quality_report

LCA / ACV: computed-checks report of a LOADED database: what the data computes, judged against the catalogue's own norms. Scores every (activity, product) entry against one method collection (the single loaded one, or the 'collection' parameter) and reports: per-category score outliers, judged on a log scale within (category, reference-unit) groups by median/MAD: a mg-read-as-kg unit slip lands three orders of magnitude out; entries whose every category score is zero (empty or uncharacterized inventory); and negative category scores (info: legitimate where avoided-production credits or waste treatment dominate). Complements get_quality_report, which checks what the database STORES and runs on staged databases too; this one needs the matrices and a loaded method collection. Same finding shape: severity, the entry, a readable detail.

Parameter	Type	Required	Description
collection	string		Method collection to score the catalogue against. Defaults to the single loaded collection; required when several are loaded.
database	string	✓	Database name
limit	integer		Max findings to return per check, worst first (default: all). Each check's offenderCount always covers its full list, so a truncated list stays countable.

get_characterization_coverage

LCA / ACV: characterization-coverage report of a database against the loaded LCIA method collections, for the people who maintain databases. Surfaces the flows a method scores ONLY through a name bridge: VoLCA matches a factor to a flow that carries a different name for the same substance (via synonym or CAS number), so the flow is characterized here, but a tool that matches factors by their exact name has no such bridge and scores it as zero, silently. Each bridged flow is grouped under the name the method itself uses (its rename target). One entry per loaded collection, so two method versions can be compared side by side. Optionally filtered to a single collection. Answers 'which of this database's flow names would an exact-name tool fail to characterize?'

Parameter	Type	Required	Description
collection	string		Restrict the report to one loaded method collection (from list_methods). If omitted, every loaded collection is reported, so two method versions can be compared side by side.
database	string	✓	Database name
limit	integer		Max bridge groups to return per collection (default: all). Each collection's bridgeGroupCount always covers its full list, so a truncated list stays countable.

edit_exchanges

LCA / ACV: change what one activity consumes and emits, keeping the activity itself. The only tool that writes data. Use it to adjust an imported dataset to the study at hand: drop a substance the scope excludes, correct an amount, add a supplier the dataset is missing. Everything the edit does not name stays as it is (classification, synonyms, parameters, pedigree, coproducts), which is why this exists rather than rewriting the activity. Only the inventory side is addressable: an input by its provider's process_id, a waste output by its treatment's process_id, a biosphere line by its flow id (from get_activity). The reference product and any coproduct are not reachable, because changing those changes what the activity IS. A selector that matches nothing is refused rather than silently doing nothing, and one that matches several lines edits all of them and says how many. Refused outright on a database the engine reads from its configuration: copy it first (that background data is shared with everyone). If the answer says transient, the edit is in memory only and an unload undoes it.

Parameter	Type	Required	Description
add_biosphere	object[]		Biosphere lines to add. Each is {direction, amount} plus either flow (an existing flow id) or name + compartment + unit, which reach the flow the database declares under them and introduce one only when nothing does.
add_inputs	object[]		Technosphere inputs to add. Each is {provider, amount} plus optional unit and comment. The flow follows from the provider.
add_waste_outputs	object[]		Waste outputs to add. Each is {provider, amount} plus optional unit and comment, where the provider is the treatment process.
database	string	✓	Database name
process_id	string	✓	Process ID (activityUUID_productUUID format)
remove	object[]		Lines to drop. Each is {kind, provider|flow}: kind "input" or "waste" with the provider's process_id, or kind "biosphere" with the flow id.
set_amounts	object[]		Lines to restate. Each is {select: {kind, provider|flow}, amount}.