api

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 key behaviors: the unit engine converts to the factor basis (with example conversions: MWh→kWh, tonne→kg, gallon→litre, mile→km) and returns the emissions with the working, GHG Protocol scope, and source. This goes beyond the raw schema and gives concrete insight into the tool's output and conversion logic, though it does not mention failure modes or validation behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences, each earning its place: the first states the purpose and formula, the second gives the input instructions and output highlights, and the third points to companion lookup tools. It is front-loaded with the core purpose and has no redundant or filler content.

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

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

Given the tool has no annotations and no output schema, the description covers the essential context: what it does, how inputs are transformed, what the response includes, and where to find factor keys. It is complete enough for an agent to select and invoke the tool correctly. The only gap is the lack of explicit mentions of error conditions or unsupported units, but the description still provides strong operational guidance.

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 meaning beyond the schema by explaining the unit conversion behavior ('the unit engine converts to the factor basis') and providing examples of supported unit mappings. It also advises how to find the factor_key via search_factors/lookup_factor, giving practical context for that parameter. This raises it to a 4, though it does not fully detail every edge case for the activity object's value.

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 opens with a clear statement: 'Turn activity data into greenhouse-gas emissions: emissions = activity × factor.' This names the specific verb ('turn'/'calculate'), the resource ('greenhouse-gas emissions'), and the exact formula. It distinguishes from the specialized siblings (calculate_electricity, calculate_freight, etc.) by positioning itself as the generic activity calculator, and it points to search_factors/lookup_factor for factor keys, reinforcing its role.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides usage instructions: 'Give an amount + unit and a factor key' and advises using search_factors/lookup_factor to find the factor key. However, it does not explicitly state when to prefer this tool over the sibling calculate_* tools or when not to use it. The guidance is implied (generic vs. specialized) but lacks explicit exclusions or alternative selection criteria.

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

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

With no annotations, the description carries the burden. It discloses the calculation formula, unit flexibility (km/mi via distance object), and radiational forcing variants. Does not cover output format or edge cases, but sufficient for a pure calculation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two efficient sentences: the first states purpose and formula, the second gives factor sourcing guidance. No wasted words, front-loaded with the most critical information.

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

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

The description covers the calculation method, factor usage, and unit flexibility, which is adequate for a simple calculator. It does not explicitly state the return value format, but that is inferable from the formula and tool nature.

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 covers all parameters with descriptions (100% coverage). The description adds value by explaining the formula and clarifying that factor_key is per-passenger-km with RF variants, going beyond the schema's minimal description.

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: calculating business travel emissions (Scope 3 Cat 6) using the distance method, with an explicit formula. This distinguishes it from sibling calculate_* tools that handle other emission categories.

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 explicit guidance on how to obtain factor keys via search_factors and notes the with_rf/without_rf variant distinction. Does not explicitly contrast with other calculate tools, but the name and context make the use case clear enough.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It transparently states that location-based emissions are always returned and market-based emissions are conditional on providing a contractual factor or a residual-mix key, including an example (REC = 0).

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 concise sentences: the first identifies the core function, the second explains the conditional logic and points to the key-lookup tool. Every phrase adds value with no redundancy or filler.

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 lack of output schema and annotations, the description adequately covers the tool's behavior, conditional logic, and prerequisite key lookup. It does not describe the return structure, but for a calculation tool with schema-documented parameters, the description is sufficiently complete for correct invocation.

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 meaning by clarifying that supplier_factor represents a contractual factor (e.g., green tariff/REC) and market_factor_key represents a residual mix, which helps agents understand the purpose of each optional parameter beyond field 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 states the tool calculates GHG Protocol Scope 2 emissions for purchased electricity, explicitly supporting both location-based and market-based methods. This clear resource scope and calculation purpose distinguish it from sibling tools like calculate_freight and calculate_business_travel.

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 clearly explains when market-based emissions are included (when a supplier_factor or market_factor_key is supplied) and directs users to search_factors for finding grid keys. It does not explicitly state when not to use the tool, but the electricity-specific focus and sibling list make the differentiation obvious.

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

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

With no annotations, the description fully discloses behavior: it assembles lifecycle modules (A1-A3, B, C1-C4, D) into stages, totals the boundary, reports module D separately, and flags missing stages as not-assessed (never zero). This goes beyond basic input/output and sets accurate expectations.

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 dense but every sentence earns its place: purpose, usage, behavior, and key lookup are all covered in three sentences. It is front-loaded with the core function and avoids 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?

For a complex calculation tool with no output schema and minimal annotations, the description covers purpose, input structure, boundary options, calculation behavior, and how to find valid keys. It is sufficiently self-contained for an agent to invoke correctly.

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 has 100% coverage but is minimal; the description adds significant meaning by specifying the accepted boundary values (A1-A3, A1-A4, A1-A5, A1-C) and giving example units for quantity. This helps the agent construct correct inputs.

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, using a specific verb and resource. It distinguishes from sibling calculation tools (electricity, freight, etc.) and lookup tools via its material focus and reference to search_factors for keys.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage context: give a material key and quantity, optionally specify a boundary range, and find keys via search_factors. It does not explicitly state when not to use this tool compared to alternatives, but the material focus and boundaries make the intended use clear.

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

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

With no annotations, the description carries the transparency burden; it discloses the calculation method ('emissions = tonnes × km × factor') and the factor-key source. It doesn't cover error handling or output details, but the formula fully specifies the core behavior of a calculation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences convey scope, method, formula, and factor lookup; no filler or repetition of schema fields.

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 3-parameter calculation tool with no output schema, the description provides the formula, factor lookup route, and example, which is sufficient for basic invocation. It leaves minor ambiguity about output format and invalid-factor behavior, but these are lower-stakes for a deterministic calculator.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already documents all three parameters (100% coverage), but the description adds meaning by expressing the formula that connects mass and distance to the factor, and by giving a concrete factor_key example ('freight.road_hgv.tonne_km') plus a lookup path via search_factors.

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 specifically identifies the tool as calculating 'Freight & logistics emissions (Scope 3 Cat 4 & 9)' and gives the exact GLEC tonne-km formula, clearly distinguishing it from sibling calculate_* tools for other emission categories.

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 concrete usage context by stating the GLEC method and instructing users to 'Find mode factors via search_factors', with an example key. It doesn't explicitly say when not to use it or mention alternatives like calculate_activity, but the freight/logistics framing makes the intended scenario clear.

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

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 the return structure (attribution factor, financed emissions, total, DQ score, audit trail) and mentions PCAF source, which gives insight into the computation. It does not mention side effects or prerequisites, but 'Compute' implies a read-only operation.

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 an actionable verb, and every clause adds value—listing specific outputs and the audit trail. There is no redundant or vague phrasing.

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 complexity (multiple outputs, no output schema), the description covers the main return values and relevant context (PCAF source, outstanding-weighted score). It lacks error-handling or input-format details, but for a calculation tool this is nearly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 50% (holdings has a description, asset_class does not). The description does not elaborate on either parameter, adding no semantic value beyond the schema. It doesn't explain how holdings should be structured or what asset_class values are accepted, leaving a gap for the undocumented parameter.

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 ('Compute') and resource ('PCAF Part A financed emissions for a portfolio'), clearly stating the tool's function. It distinguishes itself from sibling calculation tools by naming distinct outputs (attribution factor, portfolio total, data-quality score, audit trail), making its purpose unique.

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 usage is implied: an agent would invoke this when asked for PCAF Part A financed emissions. However, there is no explicit when-to-use guidance or mention of alternatives (e.g., calculate_spend) or exclusions, leaving the choice to the agent's inference.

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

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

With no annotations, the description carries the burden. It discloses the calculation formula, the requirement that spend must be in the factor's currency/year, and explicitly states no FX conversion is applied. It could additionally mention the output format or unit, but the behavior is adequately conveyed.

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 formula, and includes a practical example. Every sentence earns its place; 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 tool with nested parameters and no output schema, the description provides a clear formula, an example, and a retrieval path. It is nearly complete, though it would benefit from stating the output unit (e.g., kg CO2e) to avoid 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%, but the description adds meaning by explaining the spend must match the factor's currency/year and giving an example factor key. It also directs the user to search_factors, enriching the factor_key parameter beyond the schema's terse description.

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 Scope 3 emissions using a spend-based EEIO methodology with the formula emissions = spend × factor. It distinguishes itself from siblings by specifying 'spend-based' and references the factor retrieval process, making the purpose unambiguous.

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 context for when to use the tool (with spend data and an EEIO factor) and instructs the user to find sector factors via search_factors. It does not explicitly exclude other calculation tools, but the 'spend-based' label and the mention of 'no FX' serve as implied usage boundaries.

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

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 that the tool returns the value with full provenance (source id, exact source cell, data version), which is useful. However, it does not mention error behavior (e.g., what happens if the key is invalid) or explicitly confirm read-only nature, though it is implied. The transparency is adequate but not comprehensive.

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 and front-loaded: the first sentence states the purpose and output, and the second sentence provides a usage hint. Every word earns its place, with no redundancy.

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

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

For a simple single-parameter lookup tool, the description covers what the tool does, what it returns, and when to use an alternative. It could mention edge cases like not-found behavior, but given the low complexity and schema richness, the description is sufficiently complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description covers the 'key' parameter fully with an example. The tool description adds 'canonical key' as context but doesn't significantly enhance understanding beyond the schema. With 100% schema coverage, 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 clearly states the tool's function: 'Look up a single greenhouse-gas emission factor by its canonical key.' It identifies the specific verb (look up), resource (emission factor), and method (canonical key). It also distinguishes itself from sibling tools by explicitly referencing search_factors as the alternative for unknown keys.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides direct usage guidance: 'Use search_factors first if you do not know the key.' This clearly specifies when to use this tool versus an alternative, satisfying the need for contextual direction.

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

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

No annotations are provided, so the description carries the behavioral transparency burden. It discloses that the tool returns ranked candidates with a confidence score and notes the difficulty of picking the right key. Yet it does not explain failure modes, output structure details, or whether the operation is read-only, leaving room for more transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no filler, and the purpose is front-loaded. It effectively conveys the tool's core function, why it exists, and what to do with the result.

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, yet the description covers the essential workflow: returns ranked candidates with confidence scores, and the result feeds into calculate_* or lookup_factor. It could be more detailed about the exact output format or edge-case behavior, but for a 3-parameter resolution tool it is largely complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the input schema already explains all three parameters. The description adds minor value by framing `description` as a 'plain-language description' and referencing the 'hardest step', but does not meaningfully extend understanding of `limit` or `section` beyond their schema descriptions.

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+resource pattern: 'Find the best emission-factor key(s) for a plain-language description.' It distinguishes itself from sibling tools by emphasizing ranked candidates with confidence scores and the context of ~13,000 keys, making it clear this is a resolution tool rather than a direct lookup or calculation tool.

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: use it when you have a plain-language description and need a key. It explicitly provides workflow guidance ('feed the chosen key to a calculate_* tool or lookup_factor') and advises 'Prefer this over guessing a key.' However, it does not explicitly exclude alternative tools like search_factors, so it lacks full when-not guidance.

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

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

With no annotations, the description carries the behavioral disclosure burden. It discloses the return payload (matching keys, names, and sections) and the key limitation (values are redacted). This goes beyond the schema, which omits return info, and is honest about a critical usage constraint. It does not cover pagination or error behavior, but the most important traits are surfaced.

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?

Exactly two sentences, no wasted words. The lead sentence states the action and resource; the second discloses the output limitation and directs to the alternative. Front-loaded and 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?

For a search tool with no output schema, the description adequately explains what is returned and what is not, and points to the companion lookup tool. It does not describe ordering or exact matching semantics, but the essential information for using this tool correctly is present. The lack of explicit connection to calculation workflows is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents the three search dimensions (query, section, key_prefix) and limit. The description mentions these dimensions in natural language but adds no new detail beyond the schema. Therefore the 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 opens with a specific verb and resource: 'Find emission-factor keys by section, key prefix, or free text.' It clearly indicates the searchable dimensions and contrasts with the sibling lookup_factor by noting that values are redacted and that lookup_factor provides them, effectively distinguishing the tool's realm.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly names an alternative (lookup_factor) and specifies a clear when-not scenario: 'values are redacted here — call lookup_factor for the value.' However, it does not explicitly state when to use this tool relative to the calculation siblings (e.g., to discover keys before calling calculate_*), though that is implied by the search purpose.

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