Sourced greenhouse-gas emission factors and audit-traced carbon calculations, as an MCP server. Every value comes back with its exact source cell and a pinned data version — so an agent hands back a number a person can cite and a machine can reproduce, instead of a guess.
Probably not. The server is remote, and if your client speaks remote MCP you should point it straight at the URL — nothing to install, nothing to update:
{
"mcpServers": {
"greencalculus": {
"url": "https://mcp.greencalculus.com",
"headers": { "Authorization": "Bearer YOUR_KEY" }
}
}
}This package exists for the clients that can only spawn a local stdio process, and for docker run installs. It is a thin bridge: it forwards each JSON-RPC message to the remote server and returns the reply verbatim. No method is special-cased, so new tools appear here without a release.
Related MCP server: DCL Evaluator
{
"mcpServers": {
"greencalculus": {
"command": "npx",
"args": ["-y", "greencalculus-mcp"],
"env": { "GREENCALCULUS_API_KEY": "YOUR_KEY" }
}
}
}Or with Docker — -i is required and -t must be omitted, because the container's stdin/stdout are the transport and a TTY corrupts the stream:
{
"mcpServers": {
"greencalculus": {
"command": "docker",
"args": ["run", "-i", "--rm", "-e", "GREENCALCULUS_API_KEY", "greencalculus/mcp"],
"env": { "GREENCALCULUS_API_KEY": "YOUR_KEY" }
}
}
}Get a free key at https://greencalculus.com/developers — no card. Discovery (initialize, tools/list) works without one; calling a tool needs it.
Tool | What it does |
| Fetch one emission factor by key, with its source and version |
| Search the corpus by free text |
| Map a messy real-world description to the best-matching factor |
| Say why a factor does not exist, rather than returning nothing |
| Activity → emissions, with unit conversion and GHG Protocol scope |
| Location-based and market-based electricity |
| Embodied carbon (EN 15978), explicit about missing lifecycle stages |
| PCAF financed emissions, with the audit trail |
| Freight by mode, distance and load |
| Spend-based EEIO |
| Business travel across modes |
Variable | Default | Meaning |
| — | Your API key. |
|
| Override the endpoint. |
|
| Per-request timeout. |
Diagnostics go to stderr. Nothing but JSON-RPC is ever written to stdout — a stray byte there corrupts the session.
npm test # unit tests, no network
node bin/greencalculus-mcp.js # reads JSON-RPC on stdin
docker build -t greencalculus/mcp .REST API and docs — https://greencalculus.com/developers
Client SDKs (Python, JS/TS) — https://github.com/jeremiahsay/greencalculus-sdk
Official MCP registry — com.greencalculus/api
MIT — see LICENSE. The licence covers this bridge. Emission-factor data returned by the API carries the licence of its underlying source, which is named in every response.
Turn activity data into greenhouse-gas emissions: emissions = activity × factor. Give an amount + unit and a factor key; the unit engine converts to the factor basis (MWh→kWh, tonne→kg, gallon→litre, mile→km) and returns the emissions with the working, the GHG Protocol scope, and the source. Use search_factors / lookup_factor to find the factor key.
| Name | Required | Description | Default |
|---|---|---|---|
| activity | Yes | { "value": <number>, "unit": "<unit e.g. kWh, MWh, litres, tonne, km>" }. | |
| factor_key | Yes | Canonical emission-factor key. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the unit conversion behavior (MWh→kWh, tonne→kg, gallon→litre, mile→km) and the output structure (emissions with working, GHG Protocol scope, source). This is transparent for a calculation tool with no side effects. It does not mention error handling or rate limits, but that is not critical here.
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 purpose and formula. It packs essential details (unit conversions, output, factor lookup) without redundancy. Every sentence earns its place, and it is highly scannable.
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 (2 params, no output schema), the description fully covers what an agent needs: what it does, how to provide inputs, unit conversion logic, and what it returns. It also includes a prerequisite step (find factor key) and directs to appropriate tools. Without an output schema, it adequately explains return values.
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% (both parameters described), so baseline is 3. The description adds extra meaning by explaining the unit handling (converting to factor basis) and the output fields, which goes beyond just listing parameter names. It clarifies that activity is an object with value and unit, and factor_key is canonical, complementing 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 its purpose: converting activity data into greenhouse-gas emissions using the formula emissions = activity × factor. It also details the unit conversion and what is returned (working, scope, source), distinguishing it from generic tools. The mention of finding factor keys via search_factors/lookup_factor differentiates it from specific calculation tools like calculate_electricity or calculate_freight.
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?
It provides clear usage guidance: give an amount + unit and a factor key, and explicitly instructs to use search_factors or lookup_factor to find the key. It implies this is the generic activity calculator, but does not explicitly exclude specialized alternatives like calculate_electricity or calculate_freight. Still, the workflow is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Business travel emissions (Scope 3 Cat 6), distance method: emissions = km × passengers × factor. Air factors come in with_rf / without_rf (radiative forcing) variants. Find factors via search_factors (section "business_travel").
| Name | Required | Description | Default |
|---|---|---|---|
| distance | Yes | { "value": <number>, "unit": "km|mi" }. | |
| factor_key | Yes | Per-passenger-km travel factor key. | |
| passengers | No | Optional, defaults to 1. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey behavior. It mentions the formula, factor variants (with_rf/without_rf), and dependency on search_factors, but does not disclose output format, potential errors, or any side effects. It's a read-only calculation implied, but not stated, and edge cases like missing factors are not addressed.
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, each earning its place. The first sentence states purpose and formula; the second gives critical factor-context and lookup guidance. No filler or 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 calculation tool with full schema coverage, the description covers the core formula, factor sourcing, and scope. It lacks explicit output details, but given no output schema and that the result is an emissions estimate, the description is sufficiently complete for a competent agent.
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%, providing baseline 3. The description adds value by explaining factor_key variants (with_rf/without_rf) and directing users to search_factors for valid keys, which goes beyond schema basics. It also clarifies the distance unit combinations via the formula.
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: calculating business travel emissions (Scope 3 Cat 6) using the distance method, including the formula. It distinguishes itself from sibling tools by naming the specific category and method, making it unambiguous which tool to choose.
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 context by naming the distance method and pointing to search_factors for factor lookups, but it doesn't explicitly state when to avoid this tool or mention alternatives for other categories. It provides clear context but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GHG Protocol Scope 2 for purchased electricity, both methods. Always returns location-based (grid-average) emissions; also returns market-based when you supply a contractual supplier_factor (e.g. a green tariff / REC = 0) or a market_factor_key (residual mix). Find grid keys via search_factors (section "grid").
| Name | Required | Description | Default |
|---|---|---|---|
| consumption | Yes | { "value": <number>, "unit": "kWh|MWh|GWh" }. | |
| supplier_factor | No | Optional contractual factor { value, unit } (wins over market_factor_key). | |
| market_factor_key | No | Optional: residual-mix / supplier grid factor key. | |
| location_factor_key | Yes | Grid-average factor key, e.g. grid.gbr.electricity.location_based. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It transparently discloses that location-based is always returned and market-based is conditional, and even gives an example (green tariff/REC=0). However, it doesn't explicitly state precedence behavior (supplier_factor wins over market_factor_key), which is only in the schema description.
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, front-loaded with the core purpose, then covering behavior, alternatives, and a pointer to a related tool. Every sentence adds value with no 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?
The tool has 4 parameters, no output schema, and no annotations; the description covers the purpose, behavior, and how to source factor keys. It lacks explicit details about output format, but that isn't required given the absence of an output schema. It adequately addresses the complexity of the 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 adds meaningful context by explaining that location_factor_key is grid-average, market_factor_key is residual-mix, and supplier_factor can be a contractual value like a green tariff/REC=0. This goes beyond simply repeating parameter names.
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 GHG Protocol Scope 2 for purchased electricity and explicitly identifies both methods (location-based and market-based). It distinguishes itself from sibling tools like calculate_activity and calculate_embodied by specifying the exact resource and metric.
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 gives explicit guidance on when market-based results are available (when supplier_factor or market_factor_key is supplied) and clarifies that location-based is always returned. It also directs users to search_factors for finding grid keys, providing a clear path to obtaining necessary inputs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Whole-life embodied carbon for materials, per EN 15978. Give a material key + quantity (+ optional boundary A1-A3 / A1-A4 / A1-A5 / A1-C); it assembles the declared lifecycle modules (A1-A3, B, C1-C4, D) into stages, totals the boundary, reports module D separately, and flags any missing stage as not-assessed (never zero). Find material keys via search_factors (section "materials").
| Name | Required | Description | Default |
|---|---|---|---|
| materials | Yes | Each: { material_key, quantity:{value,unit e.g. m3/kg/tonne/m2}, boundary? }. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses key behavioral traits: assembles lifecycle modules, reports module D separately, and flags missing stages as 'not-assessed' (never zero). It does not mention side effects or authentication, but for a calculation tool these are likely negligible and the core behavior is well explained.
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-loads the purpose, and packs necessary details (modules, boundary, missing-stage behavior, key lookup) without redundancy. Every sentence earns its place.
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 single-parameter tool with a well-documented schema and no output schema, the description covers the behavior, output logic, and usage thoroughly. It explains what the tool does with inputs and its output conventions (e.g., module D separately, missing stages flagged), making it complete for an agent.
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 schema already describes the materials array structure fully (100% coverage), but the description adds the boundary options and directs the agent to search_factors for valid material keys—useful context beyond the schema. This meaningfully aids correct invocation.
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 whole-life embodied carbon for materials per EN 15978, with specific details on module assembly and boundary handling. It implicitly distinguishes itself from siblings like calculate_pcaf by focusing on materials and using the EN standard.
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 concrete usage guidance: tells the agent to find material keys via search_factors, and lists optional boundary choices (A1-A3, A1-A4, etc.). It does not explicitly state when not to use this tool, but the material-specific framing and reference to search_factors give adequate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Freight & logistics emissions (Scope 3 Cat 4 & 9), GLEC tonne-km method: emissions = tonnes × km × factor. Find mode factors via search_factors (section "freight" or "freight_detailed"), e.g. freight.road_hgv.tonne_km.
| Name | Required | Description | Default |
|---|---|---|---|
| mass | Yes | { "value": <number>, "unit": "tonne|kg|lb" }. | |
| distance | Yes | { "value": <number>, "unit": "km|mi|nmi" }. | |
| factor_key | Yes | Per-tonne-km freight factor key. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. It transparently reveals the calculation model (emissions = tonnes × km × factor), the GLEC methodology, and the dependency on factor_key lookup. It does not describe output units or error behavior, but the formula is the core behavioral trait for this calculator.
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 purpose, and no filler. The formula and factor-lookup guidance are packed efficiently into a compact description.
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 and no annotations, so the description must cover both inputs and behavior. It explains the input semantics via the formula and points to the factor source, but it stops short of explicitly stating the output emission unit or result format. Overall, it is complete enough for a straightforward calculator 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 the baseline is 3. The description adds value by showing how mass, distance, and factor combine in the formula and by giving a concrete factor_key example (freight.road_hgv.tonne_km), which clarifies the expected key format 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 specifies a clear verb and resource: calculate freight/logistics emissions using the GLEC tonne-km method. It also narrows scope to Scope 3 Categories 4 & 9, which distinguishes it from sibling calculators like calculate_activity and calculate_spend.
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 gives clear context for when to use this tool: freight & logistics emissions via tonne-km. It proactively directs users to search_factors for factor lookup with a concrete section and example, but it does not explicitly state when not to use this tool versus other calculate_* siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compute PCAF Part A financed emissions for a portfolio. Returns each holding's attribution factor and financed emissions, the portfolio total, the outstanding-weighted data-quality score, and the audit trail (formula + PCAF source).
| Name | Required | Description | Default |
|---|---|---|---|
| holdings | Yes | Each: { outstanding_amount, denominator:{type:"evic"|"equity_plus_debt", value}, company_emissions:{value,unit?} OR estimate_from_spend:{amount_usd, sector_key}, data_quality_score? }. | |
| asset_class | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It mentions outputs (attribution factors, data quality score, audit trail) but does not state if there are side effects, authentication needs, or limitations. It doesn't clarify whether it mutates data or just reads. Given no annotations, this is insufficient.
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 a single sentence that efficiently conveys the tool's purpose and outputs without unnecessary verbosity.
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 provides context about PCAF Part A and outputs, but lacks details on prerequisites, when to use vs other PCAF tools, or any limitations. Given no annotations, it leaves some context to guesswork.
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 'holdings' parameter has a description outlining the structure (outstanding_amount, denominator, emissions or spend data), but the 'asset_class' parameter is undocumented. Schema coverage is only 50%, so some parameters lack clear semantics.
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 verb ('Compute'), resource ('PCAF Part A financed emissions'), and output details (attribution factor, portfolio total, data-quality score, audit trail). It distinguishes from sibling tools like calculate_embodied or calculate_spend by focusing on the PCAF Part A standard.
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 PCAF Part A financed emissions calculation, but it doesn't explicitly state when to use this over alternative calculation tools (e.g., calculate_spend) or provide exclusion criteria. It gives some context but lacks explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Spend-based (EEIO) Scope 3 screening: emissions = spend × economic-intensity factor. Spend must be in the factor's own currency/year (no FX). Find sector factors via search_factors (section "spend_based"), e.g. spend_based.us.naics6.541511.custom_computer_programming_services.
| Name | Required | Description | Default |
|---|---|---|---|
| spend | Yes | { "value": <number>, "currency": "USD|GBP|EUR|SGD" }. | |
| factor_key | Yes | Spend-based (EEIO) sector factor key. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It mentions the input constraint (currency/year) but does not explicitly state whether the tool has side effects or read-only status. As a calculation, it's likely safe, but this is not confirmed.
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, two sentences that pack the formula, the constraint, and a reference to search_factors. No unnecessary details, well-structured for quick comprehension.
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 there is no output schema, the description adequately explains the calculation context, including the EEIO methodology and how to obtain factor keys. The output (emissions) is implied by the formula, so it's sufficient.
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 schema provides basic descriptions, but the tool description adds significant meaning by explaining the spend format requirement and giving an example factor key. This enriches the understanding of both 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?
The description clearly states the tool's purpose: calculating emissions using spend and economic-intensity factor, with the formula explicitly provided. This distinguishes it from sibling tools like calculate_activity or calculate_embodied.
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?
It explains the spend-based approach, emphasizes the currency/year constraint, and directs users to search_factors for finding factor keys. While it doesn't explicitly contrast with alternatives, the specific method and constraints make usage clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ask why a factor is NOT in the corpus. The reasoned counterpart to coverage: where a country reports zero rows for an inventory family, this says whether that is the world's limit or our backlog. Five classifications: "structural" (no publisher issues this anywhere — stop looking, and do not silently substitute another country), "not_yet_sourced" (a publisher exists and is named; it is our backlog), "refused" (we found it and declined — the reason is stated), "held_not_counted" (we DO hold it — see we_hold for the key), "coupled" (empty only because another family is empty). Each record names the publisher checked, the route tried, a confidence and a review date, and reports stale:true once past review. These are authored judgements about what the world publishes, not values derived from our data. Call this before concluding that a gap is permanent, and before telling a user to look elsewhere.
| Name | Required | Description | Default |
|---|---|---|---|
| family | No | Inventory family, e.g. "water", "wtt", "travel", "spend", "heat". | |
| country | No | ISO-3166 alpha-3 code, e.g. "can". | |
| classification | No | Filter: structural | not_yet_sourced | refused | held_not_counted | coupled. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears the full burden. It transparently discloses that results are 'authored judgements' not derived data, mentions the stale flag, and details the output fields (publisher, route, confidence, review date). This goes beyond surface-level description.
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 verbose, with several sentences repeating the same idea (e.g., 'reasoned counterpart to coverage' and 'authored judgements'). It could be tightened while preserving key details, unlike concise equivalents like the high-scoring example.
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 verbosity, it is thoroughly complete: explains the purpose, every classification, the output structure, the nature of the data (judgements vs. derived), and the appropriate timing for use. Nothing essential is missing.
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 schema already covers all parameters with descriptions. The tool description adds depth to the 'classification' parameter by explaining each enum value in detail, but does not significantly enhance understanding of the other parameters. Baseline 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's purpose: to explain why a factor is not in the corpus, with detailed classifications. It distinguishes itself by being the 'reasoned counterpart to coverage' and provides specific use cases, making it distinguishable from sibling tools like lookup_factor.
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 gives explicit guidance on when to use the tool ('Call this before concluding that a gap is permanent...'), but it does not explicitly name alternative tools or state when not to use it. The guidance is implied rather than directly contrasting with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up a single greenhouse-gas emission factor by its canonical key. Returns the value plus an audit envelope: provenance (publisher, exact source cell, retrieval date, LICENCE and whether it may be redistributed, with the attribution the licence requires) and verification (whether the per-gas components sum to the headline, the GWP set, and the source note stating what the publisher did NOT provide). If the key does not exist you get candidate keys back rather than a dead end. Use search_factors first if you do not know the key.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Canonical factor key, e.g. "grid.gbr.electricity.location_based". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so thoroughly. It discloses what is returned (value plus audit envelope), details provenance and verification fields, and explains the missing-key fallback behavior with candidate keys.
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: operation, return envelope details, and usage guidance. The most important information is front-loaded in the first sentence, and the detail is dense but not bloated.
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 and no annotations, the description is complete for a single-parameter lookup tool. It explains the return shape, provenance and verification details, error behavior, and when to use the sibling tool, leaving no critical ambiguity.
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 single 'key' parameter, including an example. The description reinforces that the lookup is by 'canonical key' but does not add substantial parameter semantics beyond the schema, so the baseline 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 uses a specific verb and resource: 'Look up a single greenhouse-gas emission factor by its canonical key.' It also distinguishes itself from siblings by explicitly directing users to search_factors when the key is unknown, and describes the narrow lookup scope versus broader search/calculation 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?
Explicit guidance is provided: 'Use search_factors first if you do not know the key.' This clearly states when this tool is appropriate and names the alternative, which is exactly the kind of usage guidance expected.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find the best emission-factor key(s) for a plain-language description — the hardest step is picking the right key out of ~16,000. Returns ranked candidates; feed the chosen key to a calculate_* tool or lookup_factor. Prefer this over guessing a key. PUT THE COUNTRY IN THE DESCRIPTION. Geography is read from the description text itself, not from a separate field — "diesel per litre" and "diesel per litre France" resolve differently, and omitting the country will quietly return a factor from somewhere else marked "geo_match":"proxy". ACT ON THE LABEL. Every candidate carries label: "accept" or "review", plus "why". "accept" means confidence >= 0.85 and no demotion applied — right about nine times in ten. "review" means the answer may be usable but something is off (low confidence, only one term matched, a proxy country, or a gate demoted it); confirm it before adopting the number rather than using it silently. Roughly half of CORRECT answers are also flagged "review" — that is the intended trade, so treat "review" as "check this", not "discard this". A MISS MAY EXPLAIN ITSELF. When nothing matches, or the only matches are from the wrong country, the response may carry an "absence" object saying WHY. classification "structural" means no publisher issues this anywhere — STOP, do not retry with reworded queries and do not substitute a different country without saying so. "not_yet_sourced" means a publisher exists and we have not ingested it (the publisher is named). "refused" means we found the data and declined it, with the reason. "coupled" means this reads empty only because a related family is empty. Use explain_absence to ask the same question directly.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Optional, default 5. | |
| section | No | Optional section filter, e.g. "fuels", "grid", "freight". | |
| description | Yes | What you need a factor for, INCLUDING the country if it matters, e.g. "UK grid electricity", "diesel per litre France", "hotel stay Japan". Geography is parsed from this string. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Extensively explains return labels, absence types, geography handling, and proxy 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?
Description is very verbose and repetitive, could be condensed.
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 all key aspects: output candidates, labels, absence handling, and next steps.
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 already describes parameters; tool description adds some clarification but not much 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 it finds the best emission-factor key for a plain-language description, distinguishes from lookup/calculate 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?
Gives guidance on when to use (prefer over guessing) and how to include country, but could be more explicit vs other search tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find emission-factor keys by section, key prefix, or free text. Returns matching keys, names, and sections (values are redacted here — call lookup_factor for the value).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 20). | |
| query | No | Free-text search over factor names/keys. | |
| section | No | Restrict to a section, e.g. "grid", "fuels", "freight". | |
| key_prefix | No | Restrict to keys starting with this prefix. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosure. It explicitly notes that values are redacted, which is a key behavioral trait, and lists the returned fields (keys, names, sections). It implies a read-only operation without side effects, which is reasonable for a search tool. It doesn't mention error handling or rate limits, but these are not critical for a simple search.
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 the action and search modes. The second sentence clarifies the return format and redaction, plus directs to lookup_factor for values. No wasted words, excellent structure.
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 search tool with no output schema, the description adequately conveys what the tool does and what it returns (keys, names, sections, and that values are redacted). It covers the essential information for an agent to know whether and how to use it, though it doesn't discuss edge cases like empty results or pagination beyond the limit parameter. Overall, it's complete enough for its simplicity.
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 has 100% coverage with each parameter well-described (limit, query, section, key_prefix). The description adds minimal extra meaning by mentioning the three search modes (section, key prefix, free text), but this essentially restates what the schema already says. Baseline of 3 is appropriate as the description doesn't significantly expand on 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 function: finding emission-factor keys by section, key prefix, or free text. It specifies the resource and search modes, and distinguishes itself from lookup_factor by noting that values are redacted and calling lookup_factor is needed for the value.
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 guides when to use this tool vs. lookup_factor by stating 'call lookup_factor for the value,' which indicates that this is for searching and lookup_factor for getting actual values. However, it doesn't mention other sibling tools like resolve_factor or calculate_* tools, so it provides clear but not exhaustive alternative context.
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.
v0.1.0calculate_activitycalculate_business_travelcalculate_electricitycalculate_embodiedcalculate_freightcalculate_pcafcalculate_spendexplain_absencelookup_factorresolve_factorsearch_factorsScored across 11 tools
The factor-discovery tools form a clear progression (exact lookup, structured search, semantic resolution, absence explanation), and the calculate_* family is cleanly separated by scope and method. However, search_factors and resolve_factor both return candidate factor keys from user-supplied text, so there is some risk of an agent selecting the wrong discovery tool.
Every tool follows a consistent snake_case verb_noun pattern: lookup_factor, calculate_activity, search_factors, resolve_factor, explain_absence, and the calculate_* family. There are no mixed conventions, vague verbs, or inconsistent casing.
11 tools is well within the ideal range for an emissions-factor library: three discovery tools, seven calculation tools covering distinct protocols and scopes, and one gap-explanation tool. The count feels purposeful rather than padded.
The core workflow of discovering factors, looking them up, calculating emissions, and explaining missing data is well covered, and generic calculate_activity fills gaps left by specialized calculators. However, explain_absence references a 'we_hold' tool that does not exist in the tool list, creating a potential dead end for the 'held_not_counted' classification.
Sourced carbon emission factors + audit-traced calculations an AI can cite.
Verified CO2e for any transaction, activity, flight, shipment or CBAM import. 200+ countries.
Deterministic Scope 1/2/3 GHG inventories with bundled factors and audit hashes.
Natural-language queries over a verified emissions knowledge graph, plus standards validation
